/service-binding

Automates parsing and binding to TCP and Unix sockets

Primary LanguageRustOtherNOASSERTION

service-binding

CI Crates.io

Provides a way for servers and clients to describe their service bindings and client endpoints in a structured format.

This crate automates parsing and binding to TCP sockets, Unix sockets and Windows Named Pipes.

By design this crate is very lean and mostly relies on what is in std (with an exception of macOS launchd service binding).

The URI scheme bindings have been heavily inspired by how Docker Engine specifies them.

use service_binding::{Binding, Listener};

let host = "tcp://127.0.0.1:8080"; // or "unix:///tmp/socket"

// parse the URI into a Binding
let binding: Binding = host.parse().unwrap();

// convert the binding into a Listener
match binding.try_into().unwrap() {
    #[cfg(unix)]
    Listener::Unix(listener) => {
        // bind to a unix domain socket
    },
    Listener::Tcp(listener) => {
        // bind to a TCP socket
    }
    Listener::NamedPipe(pipe) => {
        // bind to a Windows Named Pipe
    }
}

Supported schemes

URI format Example Description Binding Listener / Stream
tcp://ip:port tcp://127.0.0.1:8080 TCP IP address Sockets Tcp
tcp://address:port tcp://localhost:8080 Hostname with address resolution 1 Sockets Tcp
unix://path unix:///run/user/1000/test.sock Unix domain sockets 2 FilePath Unix
fd:// fd:// systemd first socket activation 34 FileDescriptor Unix
fd://<number> fd://3 exact number file descriptor FileDescriptor Unix
fd://<socket-name> fd://http socket activation by name 4 FileDescriptor Unix
npipe://<name> npipe://agent Windows Named Pipe 5 NamedPipe NamedPipe

Example

The following example uses clap and actix-web and makes it possible to run the server using any combination of Unix domain sockets (including systemd socket activation) and regular TCP socket bound to a TCP port:

use actix_web::{web, App, HttpServer, Responder};
use clap::Parser;
use service_binding::{Binding, Listener};

#[derive(Parser, Debug)]
struct Args {
    #[clap(
        env = "HOST",
        short = 'H',
        long,
        default_value = "tcp://127.0.0.1:8080"
    )]
    host: Binding,
}

async fn greet() -> impl Responder {
    "Hello!"
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let server = HttpServer::new(move || {
        App::new().route("/", web::get().to(greet))
    });

    match Args::parse().host.try_into()? {
        #[cfg(unix)]
        Listener::Unix(listener) => server.listen_uds(listener),
        Listener::Tcp(listener) => server.listen(listener),
        _ => Err(std::io::Error::other("Unsupported listener type")),
    }?.run().await
}

systemd Socket Activation

This crate also supports systemd's Socket Activation. If the argument to be parsed is fd:// the Listener object returned will be a Unix variant containing the listener provided by systemd.

For example the following file defines a socket unit: ~/.config/systemd/user/app.socket:

[Socket]
ListenStream=%t/app.sock
FileDescriptorName=service-name

[Install]
WantedBy=sockets.target

When enabled it will create a new socket file in $XDG_RUNTIME_DIR directory. When this socket is connected to systemd will start the service; fd:// reads the correct systemd environment variable and returns the Unix domain socket.

The service unit file ~/.config/systemd/user/app.service:

[Service]
ExecStart=/usr/bin/app -H fd://

Since the socket is named (FileDescriptorName=service-name) it can also be selected using its explicit name: fd://service-name.

launchd Socket Activation

On macOS launchd socket activation is also available although the socket needs to be explicitly named through the fd://socket-name syntax.

The corresponding plist file (which can be placed in ~/Library/LaunchAgents and loaded via launchctl load ~/Library/LaunchAgents/service.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>EnvironmentVariables</key>
	<dict>
		<key>RUST_LOG</key>
		<string>debug</string>
	</dict>
	<key>KeepAlive</key>
	<true/>
	<key>Label</key>
	<string>com.example.service</string>
	<key>OnDemand</key>
	<true/>
	<key>ProgramArguments</key>
	<array>
		<string>/path/to/service</string>
		<string>-H</string>
		<string>fd://socket-name</string> <!-- activate socket by name -->
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>Sockets</key>
	<dict>
		<key>socket-name</key> <!-- the socket name here -->
		<dict>
			<key>SockPathName</key>
			<string>/path/to/socket</string>
			<key>SockFamily</key>
			<string>Unix</string>
		</dict>
	</dict>
	<key>StandardErrorPath</key>
	<string>/Users/test/Library/Logs/service/stderr.log</string>
	<key>StandardOutPath</key>
	<string>/Users/test/Library/Logs/service/stdout.log</string>
</dict>
</plist>

License

This project is licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Footnotes

  1. binds to the first address that succeeds (see TcpListener::bind) ↩

  2. not available on Windows through the std right now (see #271 and #56533) ↩

  3. equivalent of fd://3 but fails if more sockets have been passed ↩

  4. listener only ↩ ↩2

  5. translates to \\.\pipe\test ↩