service-binding

Crates.ioservice-binding
lib.rsservice-binding
version3.0.0
sourcesrc
created_at2022-04-22 10:13:48.974414
updated_at2024-05-07 09:33:53.045755
descriptionAutomates parsing and binding to TCP, Unix sockets and Windows Named Pipes
homepage
repositoryhttps://github.com/wiktor-k/service-binding
max_upload_size
id572092
size46,975
David Runge (dvzrv)

documentation

README

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

Commit count: 112

cargo fmt