service-binding

提供了一种方式，允许服务器和客户端以结构化格式描述它们的服务绑定和客户端端点。

此 Crates 自动解析和绑定到 TCP 套接字、Unix 套接字和 Windows 命名管道。

设计上，此 Crates 非常精简，主要依赖于 std 中的内容（除 macOS launchd 服务绑定外）。

URI 方案绑定深受 Docker Engine 指定方案的影响。

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
    }
}

支持的方案

^[1] 绑定到第一个成功的地址（见 TcpListener::bind） [^2] 目前在Windows上通过 std 不可用（见 #271 和 #56533） [^3] 等同于 fd:// 但如果传递了更多套接字则会失败 [^4] 仅为监听器 [^5] 转换为 \\.\pipe\test

示例

以下示例使用 clap 和 actix-web，并使其能够使用Unix域套接字（包括systemd套接字激活）和绑定到TCP端口的常规TCP套接字组合运行服务器

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 套接字激活

此crate还支持systemd的 套接字激活。如果要解析的参数是 fd://，则返回的 Listener 对象将是一个包含systemd提供的监听器的 Unix 变体。

例如以下文件定义了一个套接字单元：~/.config/systemd/user/app.socket

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

[Install]
WantedBy=sockets.target

当启用时，它将在 $XDG_RUNTIME_DIR 目录中创建一个新的套接字文件。当此套接字连接到systemd时，将启动服务；fd:// 读取正确的systemd环境变量并返回Unix域套接字。

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

<?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>