This document provides the specification for RUSS.
The goal of RUSS is to expose a collection of services addressable in a hierarchical namespace, each of which establish zero or more I/O streams for communication, and a means for providing an exit status when a service terminates. A service is called with an operation, a service path, an ordered list of zero or more strings, and an unordered map of zero or more key-value pairs. The fundamental client function is modelled after the
RUSS is targeted to UNIX and UNIX-like systems which support domain sockets.
Credentials uniquely identify a principal (e.g., user) on a host. Credentials are not transferable to non-local hosts.
A deadline is a fixed point in time local to a host. The time specified by a deadline does not change. This is in contrast to a timeout which is defined relative to a base time. A deadline is not transferable to non-local hosts.
An integer value in the range 0-255. The exit status is typically used to indicate success (0) or failure/non-success (non-0).
A service supports one or more operations (e.g., list, execute).
Ordered Argument List
A list of strings whose order is significant.
All services are identified by a /-separated list of strings comprising a service path. The service path is prefixed with a socket address, after which the path components are interpreted by a server in search of a matching service.
Service Path Component
A component in the service path consisting of a string of characters except for "/".
Service Path Name
A string of characters in the service path component identifying the name of a service in the service tree.
Service Path Options
An unordered map of key-value pairs taken from a service path component. Service path options are specified after the service path name. Each service path option is specified in the service path component with a "?"-prefix (which is not included in the key name). Service path option information is ignored for the purposes of matching service names with service handlers.
The access point for all services is a domain socket address. It may be dedicated to a server which provides a collection of services or as an indirect access point to one or more such servers.
An object for uni or bidirectional communication. Unless otherwise stated, all services provide and communicate over stdin, stdout, and stderr I/O streams. Additional streams may be provided.
A collection of key-value pairs (strings) whose order is not significant.
Wait Return Value
The value returned by an API wait call that is performed to get an exit status. The value may indicate success, failure, or some other status.
|Some future time that will never arrive given the local host clock calls.|
|126||Dial call failure.|
|127||System failure, e.g., no exit value returned.|
A common set of messages are used to indicate an noteworthy condition as sent over the stderr connection file descriptor:
|Bad or missing arguments for service call.|
|Unexpected connection event.|
|Could not dial service.|
|No exit status.|
|Service list not available.|
|Service request not handled.|
|Service could not switch user.|
|Invalid service path.|
|0||Should never be this for an accepted request.|
|1||If operation string is unrecognized. Useful for future operations.|
|2||execute||Execute a service at a given service path.|
|3||help||Provide server or service-specific help as text.|
|4||id||Provide identifying information about the the server.|
|6||list||Provide a newline separated list of services available below a given service path.|
Additional operations may be defined in the future.
Wait Return Values
|1||Unset; should not occur.|
|-2||Exit fd is closed/invalid.|
|-3||Wait call timed out.|
The service path is formatted as:
Service path options were added in v7.
Data structures that are fundamental to RUSS. They are presented as C
The following describes the protocol corresponding to the protocol string (
Comprises all that is required to establish a viable connection between client and server which amounts to a set of stream descriptors sent by the server and received by the client.
Once the socket connection has served its purpose, it is no longer used. However, the I/O streams and exit descriptors are a part of the RUSS connection and remain available until closed by either of the sides.
The request is sent over the socket.
size is the total number of bytes of the request excluding the
Note: The client credentials are not part of the request message but obtained from the socket.
The response is sent over the socket.
Exiting comprises all that is required to inform the client that the service has completed along with the completion status.
The status of the non-exit streams is not defined. I.e., it is left to the service to deal with the streams, such as to leave them open or to close them.
The exit value is sent over the exit stream.