Zinit OpenRPC Client

This module provides a V language client for interacting with Zinit process manager using the OpenRPC protocol over a Unix socket.

Overview

Zinit is a process manager that allows you to manage services on a system. This client provides a way to interact with Zinit using its JSON-RPC API, which follows the OpenRPC specification.

Features

• Full implementation of the Zinit OpenRPC API
• Type-safe request and response handling
• Support for all Zinit operations:
• Service management (start, stop, monitor, forget)
• Service status and statistics
• System operations (shutdown, reboot)
• Log retrieval
• Service configuration management

Usage

Basic Usage

import freeflowuniverse.herolib.osal.zinit

fn main() {
    // Create a new Zinit client with the default socket path
    mut zinit_client := zinit.new_stateless()!

    // List all services
    service_list := zinit_client.client.list()!
    println('Services:')
    for name, state in service_list {
        println('- ${name}: ${state}')
    }

    // Start a service
    zinit_client.client.start('my_service')!

    // Get service status
    status := zinit_client.client.status('my_service')!
    println('Service state: ${status.state}')
}

Creating a New Service

import freeflowuniverse.herolib.osal.zinit

fn main() {
    mut zinit_client := zinit.new_stateless()!

    // Define service configuration
    service_config := zinit.ServiceConfig{
        exec: '/usr/bin/my-program --option value'
        oneshot: false
        after: ['dependency1', 'dependency2']
        log: 'stdout'
        env: {
            'ENV_VAR1': 'value1'
            'ENV_VAR2': 'value2'
        }
        shutdown_timeout: 30
    }

    // Create the service
    zinit_client.client.create_service('my_service', service_config)!

    // Monitor and start the service
    zinit_client.client.monitor('my_service')!
    zinit_client.client.start('my_service')!
}

Getting Service Statistics

import freeflowuniverse.herolib.osal.zinit

fn main() {
    mut zinit_client := zinit.new_stateless()!

    // Get service stats
    stats := zinit_client.client.stats('my_service')!

    println('Memory usage: ${stats.memory_usage} bytes')
    println('CPU usage: ${stats.cpu_usage}%')

    // Print child process stats
    for child in stats.children {
        println('Child PID: ${child.pid}, Memory: ${child.memory_usage} bytes')
    }
}

Retrieving Logs

import freeflowuniverse.herolib.osal.zinit

fn main() {
    mut zinit_client := zinit.new_stateless()!

    // Get logs for a specific service
    logs := zinit_client.client.get_logs('my_service')!
    for log in logs {
        println(log)
    }

    // Get all logs
    all_logs := zinit_client.client.get_all_logs()!
    for log in all_logs {
        println(log)
    }
}

API Reference

Client Methods

• discover() - Returns the OpenRPC specification for the API
• list() - Returns a map of service names to their current states
• status(name string) - Returns detailed status information for a specific service
• start(name string) - Starts a service
• stop(name string) - Stops a service
• monitor(name string) - Starts monitoring a service
• forget(name string) - Stops monitoring a service
• kill(name string, signal string) - Sends a signal to a running service
• shutdown() - Stops all services and powers off the system
• reboot() - Stops all services and reboots the system
• stats(name string) - Returns memory and CPU usage statistics for a service
• get_logs(name string) - Returns current logs from a specific service
• get_all_logs() - Returns all current logs from zinit and monitored services
• create_service(name string, config ServiceConfig) - Creates a new service configuration file
• delete_service(name string) - Deletes a service configuration file
• get_service(name string) - Gets a service configuration file
• start_http_server(address string) - Starts an HTTP/RPC server at the specified address
• stop_http_server() - Stops the HTTP/RPC server if running

Data Structures

• ServiceStatus - Detailed status information for a service
• ServiceStats - Memory and CPU usage statistics for a service
• ServiceConfig - Configuration for creating a new service

OpenRPC Specification

The full OpenRPC specification for the Zinit API is available in the openrpc.json file. This specification defines all the methods, parameters, and return types for the API.

Example

See the examples/osal/zinit/zinit_openrpc_example.v file for a complete example of using the Zinit OpenRPC client.

fn check() bool

fn destroy() !

remove all know services to zinit

fn new() !&Zinit

fn new_client(socket_path string) ZinitClient

new_client creates a new Zinit OpenRPC client Parameters:- socket_path: Path to the Zinit Unix socket (default: /tmp/zinit.sock)Returns:- A new ZinitClient instance

fn new_rpc_client(args ZinitClientArgs) Client

fn new_stateless(z ZinitConfig) !ZinitStateless

enum StartupManagerType {
	unknown
	zinit
	systemd
	screen
}

enum ZProcessStatus {
	unknown
	init
	ok
	killed
	error
	blocked
	spawned
}

struct ChildProcessStats {
pub:
	pid          int
	memory_usage i64
	cpu_usage    f64
}

ChildProcessStats represents statistics for a child process

struct Client {
	socket_path string = '/var/run/zinit.sock'
}

these need to be all private (non pub)

struct CreateServiceParams {
pub:
	name    string
	content ServiceConfig
}

CreateServiceParams represents the parameters for the create_service method

struct EmptyResponse {}

EmptyResponse represents an empty response from the API

struct KillParams {
pub:
	name   string
	signal string
}

KillParams represents the parameters for the kill method

struct OpenRPCInfo {
pub:
	version     string
	title       string
	description string
}

OpenRPCInfo represents the info section of the OpenRPC specification

struct OpenRPCMethod {
pub:
	name        string
	description string
}

OpenRPCMethod represents a method in the OpenRPC specification

struct OpenRPCSpec {
pub:
	openrpc string
	info    OpenRPCInfo
	methods []OpenRPCMethod
}

OpenRPCSpec represents the OpenRPC specification

struct ServiceConfig {
pub:
	exec             string
	oneshot          bool
	after            []string
	log              string
	env              map[string]string
	shutdown_timeout int
}

ServiceConfig represents the configuration for a service

struct ServiceConfigResponse {
pub:
	exec             string
	oneshot          bool
	after            []string
	log              string
	env              map[string]string
	shutdown_timeout int
}

ServiceConfigResponse represents the response from get_service

struct ServiceStats {
pub:
	name         string
	pid          int
	memory_usage i64
	cpu_usage    f64
	children     []ChildProcessStats
}

ServiceStats represents memory and CPU usage statistics for a service

struct ServiceStatus {
pub:
	name   string
	pid    int
	state  string
	target string
	after  map[string]string
}

ServiceStatus represents the detailed status of a service

struct ZProcess {
pub:
	name string = 'default'
pub mut:
	cmd         string // command to start
	cmd_stop    string // command to stop (optional)
	cmd_test    string // command line to test service is running
	workdir     string // where to execute the commands
	status      ZProcessStatus
	pid         int
	after       []string // list of service we depend on
	env         map[string]string
	oneshot     bool
	start       bool = true
	restart     bool = true // whether the process should be restarted on failure
	description string // not used in zinit
}

fn (mut zp ZProcess) check() !

will check that process is running

fn (zp ZProcess) cmd() !string

fn (zp ZProcess) cmdstop() !string

fn (zp ZProcess) cmdtest() !string

fn (mut zp ZProcess) destroy() !

fn (mut zp ZProcess) isrunning() !bool

will check that process is running

fn (mut zp ZProcess) load() !

fn (zp ZProcess) log() !string

check if process is running if yes return the log

fn (mut zp ZProcess) output_wait(c_ string, timeoutsec int) !

how long to wait till the specified output shows up, timeout in sec

fn (zp ZProcess) start() !

fn (mut zp ZProcess) status() !ZProcessStatus

return status of process

 enum ZProcessStatus {
    unknown
    init
    ok
    error
    blocked
    spawned
 killed
 }

fn (mut zp ZProcess) stop() !

struct ZProcessNewArgs {
pub mut:
	name        string @[required]
	cmd         string @[required]
	cmd_stop    string   // command to stop (optional)
	cmd_test    string   // command line to test service is running
	workdir     string   // where to execute the commands
	after       []string // list of service we depend on
	env         map[string]string
	oneshot     bool
	start       bool = true
	restart     bool = true // whether the process should be restarted on failure
	description string // not used in zinit
	startuptype StartupManagerType
}

struct Zinit {
pub mut:
	processes map[string]ZProcess
	path      pathlib.Path
	pathcmds  pathlib.Path
}

fn (mut zinit Zinit) new(args_ ZProcessNewArgs) !ZProcess

will delete the process if it exists while starting

fn (mut zinit Zinit) get(name_ string) !ZProcess

fn (mut zinit Zinit) exists(name_ string) bool

fn (mut zinit Zinit) stop(name string) !

fn (mut zinit Zinit) start(name string) !

fn (mut zinit Zinit) delete(name string) !

fn (mut self Zinit) load() !

fn (mut self Zinit) names() []string

struct ZinitClient {
pub mut:
	rpc_client &jsonrpc.Client
}

ZinitClient is a unified client for interacting with Zinit using OpenRPC

fn (mut c ZinitClient) discover() !string

discover returns the OpenRPC specification for the API Returns:- A string representation of the OpenRPC specification

fn (mut c ZinitClient) list() !map[string]string

list returns a map of service names to their current states Returns:- A map where keys are service names and values are their states

fn (mut c ZinitClient) status(name string) !ServiceStatus

status returns detailed status information for a specific service Parameters:- name: The name of the service to get status forReturns:- A ServiceStatus struct containing detailed status information

fn (mut c ZinitClient) start(name string) !

start starts a service Parameters:- name: The name of the service to start

fn (mut c ZinitClient) stop(name string) !

stop stops a service Parameters:- name: The name of the service to stop

fn (mut c ZinitClient) monitor(name string) !

monitor starts monitoring a service Parameters:- name: The name of the service to monitor

fn (mut c ZinitClient) forget(name string) !

forget stops monitoring a service Parameters:- name: The name of the service to forget

fn (mut c ZinitClient) kill(name string, signal string) !

kill sends a signal to a running service Parameters:- name: The name of the service to send the signal to

• signal: The signal to send (e.g., SIGTERM, SIGKILL)

fn (mut c ZinitClient) shutdown() !

shutdown stops all services and powers off the system

fn (mut c ZinitClient) reboot() !

reboot stops all services and reboots the system

fn (mut c ZinitClient) stats(name string) !ServiceStats

stats returns memory and CPU usage statistics for a service Parameters:- name: The name of the service to get stats forReturns:- A ServiceStats struct containing memory and CPU usage statistics

fn (mut c ZinitClient) get_logs(name string) ![]string

get_logs returns current logs from a specific service Parameters:- name: The name of the service to get logs forReturns:- An array of log strings

fn (mut c ZinitClient) get_all_logs() ![]string

get_all_logs returns all current logs from zinit and monitored services Returns:- An array of log strings

fn (mut c ZinitClient) create_service(name string, config ServiceConfig) !string

create_service creates a new service configuration file Parameters:- name: The name of the service to create

• config: The service configurationReturns:- A string indicating the result of the operation

fn (mut c ZinitClient) delete_service(name string) !string

delete_service deletes a service configuration file Parameters:- name: The name of the service to deleteReturns:- A string indicating the result of the operation

fn (mut c ZinitClient) get_service(name string) !ServiceConfigResponse

get_service gets a service configuration file Parameters:- name: The name of the service to getReturns:- The service configuration

fn (mut c ZinitClient) start_http_server(address string) !string

start_http_server starts an HTTP/RPC server at the specified address Parameters:- address: The network address to bind the server to (e.g., '127.0.0.1:8080')Returns:- A string indicating the result of the operation

fn (mut c ZinitClient) stop_http_server() !

stop_http_server stops the HTTP/RPC server if running

struct ZinitConfig {
	path        string = '/etc/zinit'
	pathcmds    string = '/etc/zinit/cmds'
	socket_path string = default_socket_path
}

struct ZinitStateless {
pub mut:
	client   ZinitClient
	path     pathlib.Path
	pathcmds pathlib.Path
}

fn (mut zinit ZinitStateless) new(args_ ZProcessNewArgs) !ZProcess

will delete the process if it exists while starting

fn (mut zinit ZinitStateless) exists(name string) !bool

fn (mut zinit ZinitStateless) stop(name string) !

fn (mut zinit ZinitStateless) start(name string) !

fn (mut zinit ZinitStateless) running(name string) !bool

fn (mut zinit ZinitStateless) delete(name string) !

fn (mut self ZinitStateless) names() ![]string