Crate kubos_service

A collection of structures and functions used to create hardware services in the Kubos Linux ecosystem.

Use

The basic use of the kubos_service crate is through the Service structure. This structure provides an interface for creating a new service instance, configuring it with a hardware subsystem and Juniper Query/Mutation objects. It also provides a starting entry point and basic configuration file parsing.

In Services

Services should only link to the kubos_service crate if they have a hardware device they want to expose over the service interface (currently GraphQL/HTTP).

Configuration

Services which use this crate have the option of using a local configuration file or falling back on default config values. The service will search for the configuration file at this location /etc/kubos-config.toml unless otherwise specified with the -c flag at run time.

The service configuration file uses the Toml format and is expected to use the following layout:

[service-name]
config-key = "value"
config-key2 = 123

[service-name.addr]
ip = "127.0.0.1"
port = 8082

The [service-name.addr] section is required for all services and is used to set the ip/port on which the service will listen for messages. Any service specific configuration values can be specified directly under the [service-name] section. Note - the service-name used in the sections must match the name used when creating the Config instance inside your service.

Examples

Creating and starting a simple service.

use kubos_service::{Config, Service};
use model::Subsystem;
use schema::{MutationRoot, QueryRoot};

Service::new(
    Config::new("service-name").unwrap(),
    Subsystem::new(),
    QueryRoot,
    MutationRoot,
).start();

Using the service config info to configure the subsystem.

use kubos_service::{Config, Service};
use model::Subsystem;
use schema::{MutationRoot, QueryRoot};

let config = Config::new("example-service").unwrap();
let subsystem = Subsystem { bus: config["bus"] };
Service::new(
    config,
    subsystem,
    QueryRoot,
    MutationRoot,
).start();

Running a service with the default config file (/etc/kubos-config.toml).

$ ./example-service

Running a service with a custom config file.

$ ./example-service -c config.toml

Modules

Logger

Common structure and functions for setting up service logging

Macros

process_errors

Iterate through a failure::Error and concatenate the error and all its causes into a single string

push_err

Convenience macro to push an error string onto the master errors vector

run

Execute a function and return Result<func_data, String> Optionally: Add the error string to the master error string for later consumption, prefixed with the name of the function being called

Structs

Config

KubOS config used by either Apps or Services. KubOS config files use the TOML format, and can may contain multiple named Categories. Typically each category corresponds to an App or Service name. This allows one config file to store configuration for multiple Apps / Services at a time.

Context

Context struct used by a service to provide Juniper context, subsystem access and persistent storage.

Service

This structure represents a hardware service.