Umbral Socket

Lightweight IPC client and server over Unix sockets.

Umbral Socket uses a small binary framed protocol over Unix stream sockets. Methods are identified by u8, and payloads are raw byte slices.

Installation

cargo add umbral-socket

Client

use std::io;

use umbral_socket::stream::UmbralClient;

fn main() -> io::Result<()> {
    let mut client = UmbralClient::new("/tmp/umbral.sock")?;
    let response = client.send(1, b"{\"user\":\"alan\"}")?;

    println!("response: {}", String::from_utf8_lossy(&response));
    Ok(())
}

Server

Handlers receive shared state and the request payload. They return a static byte slice response.

use std::io;

use umbral_socket::stream::UmbralServer;

struct State;

fn main() -> io::Result<()> {
    UmbralServer::new(State)
        .route(1, |_, payload| {
            println!("request: {}", String::from_utf8_lossy(payload));
            Ok(b"OK")
        })
        .run("/tmp/umbral.sock")
}

Protocol

UmbralClient is synchronous and owns one Unix socket connection. For high performance dispatchers, implement the event loop directly over the protocol.

Request frame:

method: u8
payload_len: u32 big-endian
payload: [u8]

Response frame:

status: u8
payload_len: u32 big-endian
payload: [u8]