u
Hyper client and server bindings for Unix domain sockets
Hyper is a rock solid Rust HTTP client and server toolkit.
Unix domain sockets provide a mechanism
for host-local interprocess communication. hyperlocal
builds on and complements Hyper's
interfaces for building Unix domain socket HTTP clients.
This is useful for accessing HTTP interfaces exposed via a Unix daemons. Examples of Unix daemons that provide this kind of host local interface include Docker, a process container manager.
Add the following to your Cargo.toml
file
[dependencies]
hyperlocal = "0.9"
A typical server can be built by creating a tokio::net::UnixListener
and accepting connections in a loop using
hyper::service::service_fn
to create a request/response processing function, and connecting the UnixStream
to it
using hyper::server::conn::http1::Builder::new().serve_connection()
.
An example is at examples/server.rs, runnable via cargo run --example server
To test that your server is working you can use an out-of-the-box tool like curl
$ curl --unix-socket /tmp/hyperlocal.sock localhost
It's a Unix system. I know this.
Note that hyperlocal
is not required to build a server, though hyper
and tokio
are both used in the example.
hyperlocal
provides bindings for writing unix domain socket based HTTP clients the Client
interface from the
hyper-utils
crate.
An example is at examples/client.rs, runnable via cargo run --example client
Hyper's client interface makes it easy to send typical HTTP methods like GET
, POST
, DELETE
with factory
methods, get
, post
, delete
, etc. These require an argument that can be tranformed into a hyper::Uri
.
Since Unix domain sockets aren't represented with hostnames that resolve to ip addresses coupled with network ports,
your standard over the counter URL string won't do. Instead, use a hyperlocal::Uri
, which represents both file path to the domain
socket and the resource URI path and query string.
Supports hyper 1.x
by providing a tower
service UnixConnector
and an
extension method hyper_util::client::legacy::Client::unix()
to create a
client.
The server extension method bind_unix
was removed since there is no longer
an equivalent to hyper::Server
.
Supports hyper 0.14
and provided extensions to both hyper's Client
and Server
via traits.
Doug Tangren (softprops) 2015-2020