Hyperlocal

https://docs.rs/hyperlocal/0.9.1
Admin
Hyperlocal is a Rust crate that provides Hyper bindings for Unix domain sockets, enabling HTTP...
Tokens:8,443
Snippets:91
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Serving HTTP on a Unix Socket

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/trait.UnixListenerExt.html

Demonstrates how to bind a UnixListener to a path and use the serve method from UnixListenerExt to handle incoming HTTP requests. The provided closure generates a simple 'Hello, world!' response.

```rust
use hyper::Response;
use hyperlocal::UnixListenerExt;
use tokio::net::UnixListener;

let future = async move {
    let listener = UnixListener::bind("/tmp/hyperlocal.sock").expect("parsed unix path");

    listener
        .serve(|| {
            |_request| async {
                Ok::<_, hyper::Error>(Response::new("Hello, world.".to_string()))
            }
        })
        .await
        .expect("failed to serve a connection")
};

```

--------------------------------

### Construct a hyper::Client with UnixConnector

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixConnector.html

Use UnixConnector to build a hyper::Client for Unix domain sockets. This example demonstrates the basic setup required.

```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::{client::legacy::Client, rt::TokioExecutor};
use hyperlocal::UnixConnector;

let connector = UnixConnector;
let client: Client<UnixConnector, Full<Bytes>> =
    Client::builder(TokioExecutor::new()).build(connector);
```

--------------------------------

### UnixConnector Usage Example

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixConnector.html

This example shows how to create a hyper::Client using UnixConnector to communicate over a Unix domain socket.

```APIDOC
## Example
```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::{client::legacy::Client, rt::TokioExecutor};
use hyperlocal::UnixConnector;

let connector = UnixConnector;
let client: Client<UnixConnector, Full<Bytes>> = 
    Client::builder(TokioExecutor::new()).build(connector);
```
```

--------------------------------

### Create and Convert Uri to hyper::Uri

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.Uri.html

Demonstrates creating a hyperlocal Uri for a Unix Domain Socket and converting it into a hyper::Uri. Ensure the path is absolute.

```rust
use hyper::Uri as HyperUri;
use hyperlocal::Uri;

let uri: HyperUri = Uri::new("/tmp/hyperlocal.sock", "/").into();
```

--------------------------------

### Construct Unix Domain Socket Client

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/trait.UnixClientExt.html

Use the `unix()` method to create a hyper HTTP client that communicates over a Unix domain socket. This is useful for local inter-process communication.

```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::client::legacy::Client;
use hyperlocal::{UnixClientExt, UnixConnector};

let client: Client<UnixConnector, Full<Bytes>> = Client::unix();
```

--------------------------------

### Uri Conversion to hyper::Uri

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.Uri.html

Demonstrates how to convert a hyperlocal Uri into a hyper::Uri.

```APIDOC
## Example
```rust
use hyper::Uri as HyperUri;
use hyperlocal::Uri;

let uri: HyperUri = Uri::new("/tmp/hyperlocal.sock", "/").into();
```

### Description
This example shows the usage of `Uri::new` and the `Into<hyper::Uri>` trait implementation to create a `hyper::Uri` from a `hyperlocal::Uri`.
```

--------------------------------

### Connection Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides methods for retrieving connection metadata.

```APIDOC
### impl Connection for UnixStream

#### fn connected

Return metadata describing the connection.

```rust
fn connected(&self) -> Connected
```
```

--------------------------------

### Uri::new

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.Uri.html

Creates a new Uri from a socket path and a URI path. Panics if the path is not absolute or is malformed.

```APIDOC
## pub fn new(socket: impl AsRef<Path>, path: &str) -> Self

### Description
Create a new `[Uri]` from a socket address and a path

### Parameters
#### Path Parameters
- **socket** (impl AsRef<Path>) - Required - The socket address.
- **path** (&str) - Required - The URI path.

### Panics
Will panic if path is not absolute and/or a malformed path string.
```

--------------------------------

### UnixStream::connect

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Establishes a connection to a Unix domain socket at the specified path.

```APIDOC
## UnixStream::connect

### Description
Connects to a Unix domain socket specified by a path.

### Method Signature
`async fn connect(path: impl AsRef<Path>) -> io::Result<Self>`

### Parameters
* `path` (`impl AsRef<Path>`): The path to the Unix domain socket file.
```

--------------------------------

### UnixListenerExt::serve

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/server.rs.html

Indefinitely accept and respond to connections over a Unix domain socket. This method takes a factory function that generates a response function for each connection, enabling a Hyper server to be run on a Unix socket.

```APIDOC
## UnixListenerExt::serve

### Description
Indefinitely accept and respond to connections.

Pass a function which will generate the function which responds to
all requests for an individual connection.

### Method
`serve<MakeResponseFn, ResponseFn, ResponseFuture, B, E>(self, f: MakeResponseFn)`

### Parameters
- `f` (MakeResponseFn): A function that returns a `ResponseFn`. `MakeResponseFn: Fn() -> ResponseFn`
- `ResponseFn`: A function that takes a `Request<Incoming>` and returns a `ResponseFuture`. `ResponseFn: Fn(Request<Incoming>) -> ResponseFuture`
- `ResponseFuture`: A future that resolves to a `Result<Response<B>, E>`. `ResponseFuture: Future<Output = Result<Response<B>, E>>`
- `B`: The type of the response body, must implement `hyper::body::Body` and `'static`.
- `E`: The error type for the response, must implement `std::error::Error + Send + Sync + 'static`.

### Returns
A future that resolves to `Result<(), Box<dyn std::error::Error + Send + Sync>>` upon completion or error.

### Example
```rust
use hyper::Response;
use hyperlocal::UnixListenerExt;
use tokio::net::UnixListener;

let future = async move {
    let listener = UnixListener::bind("/tmp/hyperlocal.sock").expect("parsed unix path");

    listener
        .serve(|| {
            |_request| async {
                Ok::<_, hyper::Error>(Response::new("Hello, world.".to_string()))
            }
        })
        .await
        .expect("failed to serve a connection")
};
```
```

--------------------------------

### Serve Hyper HTTP Server over Unix Socket

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/server.rs.html

Extends `UnixListener` to serve hyper HTTP connections. Pass a function that generates a response function for each connection. Note: keep_alive is set to false on OSX to prevent connection errors.

```rust
use hyper::{
    body::{Body, Incoming},
    service::service_fn,
    Request, Response,
};
use hyper_util::rt::TokioIo;
use std::future::Future;
use tokio::net::UnixListener;

/// Extension trait for provisioning a hyper HTTP server over a Unix domain
/// socket.
///
/// # Example
///
/// ```rust
/// use hyper::Response;
/// use hyperlocal::UnixListenerExt;
/// use tokio::net::UnixListener;
///
/// let future = async move {
///     let listener = UnixListener::bind("/tmp/hyperlocal.sock").expect("parsed unix path");
///
///     listener
///         .serve(|| {
///             |_request| async {
///                 Ok::<_, hyper::Error>(Response::new("Hello, world.".to_string()))
///             }
///         })
///         .await
///         .expect("failed to serve a connection")
/// };
/// ```
pub trait UnixListenerExt {
    /// Indefinitely accept and respond to connections.
    ///
    /// Pass a function which will generate the function which responds to
    /// all requests for an individual connection.
    fn serve<MakeResponseFn, ResponseFn, ResponseFuture, B, E>(
        self,
        f: MakeResponseFn,
    ) -> impl Future<Output = Result<(), Box<dyn std::error::Error + Send + Sync>>>
    where
        MakeResponseFn: Fn() -> ResponseFn,
        ResponseFn: Fn(Request<Incoming>) -> ResponseFuture,
        ResponseFuture: Future<Output = Result<Response<B>, E>>,
        B: Body + 'static,
        <B as Body>::Error: std::error::Error + Send + Sync,
        E: std::error::Error + Send + Sync + 'static;
}

impl UnixListenerExt for UnixListener {
    fn serve<MakeServiceFn, ResponseFn, ResponseFuture, B, E>(
        self,
        f: MakeServiceFn,
    ) -> impl Future<Output = Result<(), Box<dyn std::error::Error + Send + Sync>>>
    where
        MakeServiceFn: Fn() -> ResponseFn,
        ResponseFn: Fn(Request<Incoming>) -> ResponseFuture,
        ResponseFuture: Future<Output = Result<Response<B>, E>>,
        B: Body + 'static,
        <B as Body>::Error: std::error::Error + Send + Sync,
        E: std::error::Error + Send + Sync + 'static,
    {
        async move {
            loop {
                let (stream, _) = self.accept().await?;
                let io = TokioIo::new(stream);

                let svc_fn = service_fn(f());

                hyper::server::conn::http1::Builder::new()
                    // On OSX, disabling keep alive prevents serve_connection from
                    // blocking and later returning an Err derived from E_NOTCONN.
                    .keep_alive(false)
                    .serve_connection(io, svc_fn)
                    .await?;
            }
        }
    }
}
```

--------------------------------

### UnixConnector for Hyper Client

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Provides a `UnixConnector` that can be used to construct a `hyper::Client` capable of communicating over Unix domain sockets. This is useful when you need direct access to the `hyper::Client` builder.

```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::{client::legacy::Client, rt::TokioExecutor};
use hyperlocal::UnixConnector;

let connector = UnixConnector;
let client: Client<UnixConnector, Full<Bytes>> = 
    Client::builder(TokioExecutor::new()).build(connector);
```

--------------------------------

### Create Unix Domain Socket URI

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/uri.rs.html

Use `Uri::new` to construct a `hyperlocal::Uri` from a socket path and a request path. This type can then be converted into a `hyper::Uri`.

```rust
use hyper::Uri as HyperUri;
use std::path::Path;

/// A convenience type that can be used to construct Unix Domain Socket URIs
///
/// This type implements `Into<hyper::Uri>`.
///
/// # Example
/// ```
/// use hyper::Uri as HyperUri;
/// use hyperlocal::Uri;
///
/// let uri: HyperUri = Uri::new("/tmp/hyperlocal.sock", "/").into();
/// ```
#[derive(Debug, Clone)]
pub struct Uri {
    hyper_uri: HyperUri,
}

impl Uri {
    /// Create a new `[Uri]` from a socket address and a path
    ///
    /// # Panics
    /// Will panic if path is not absolute and/or a malformed path string.
    pub fn new(
        socket: impl AsRef<Path>,
        path: &str,
    ) -> Self {
        let host = hex::encode(socket.as_ref().to_string_lossy().as_bytes());
        let host_str = format!("unix://{{host}}:0{{path}}");
        let hyper_uri: HyperUri = host_str.parse().unwrap();

        Self { hyper_uri }
    }
}

impl From<Uri> for HyperUri {
    fn from(uri: Uri) -> Self {
        uri.hyper_uri
    }
}
```

--------------------------------

### Write Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides synchronous writing capabilities for the UnixStream.

```APIDOC
### impl Write for UnixStream

#### fn poll_write

Attempt to write bytes from `buf` into the destination.

```rust
fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>
```

#### fn poll_flush

Attempts to flush the object.

```rust
fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>
```

#### fn poll_shutdown

Attempts to shut down this writer.

```rust
fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>
```

#### fn is_write_vectored

Returns whether this writer has an efficient `poll_write_vectored` implementation.

```rust
fn is_write_vectored(&self) -> bool
```

#### fn poll_write_vectored

Like `poll_write`, except that it writes from a slice of buffers.

```rust
fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>
```
```

--------------------------------

### Server Functionality

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/lib.rs.html

Enables the server extension trait for Unix domain sockets.

```APIDOC
## Server Module

### Description
Provides traits for configuring and managing servers using Unix domain sockets.

### Traits
- `UnixListenerExt`: Extension trait for server listener functionality.
```

--------------------------------

### UnixConnector Service Implementation

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `Service<Uri>` trait for `UnixConnector`, enabling it to handle requests for `Uri`s and return a `UnixStream` as the response. It parses the socket path from the URI.

```rust
impl Service<Uri> for UnixConnector {
    type Response = UnixStream;
    type Error = io::Error;
    #[allow(clippy::type_complexity)]
    type Future =
        Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send + 'static>>;

    fn call(
        &mut self,
        req: Uri,
    ) -> Self::Future {
        let fut = async move {
            let path = parse_socket_path(&req)?;
            UnixStream::connect(path).await
        };

        Box::pin(fut)
    }

    fn poll_ready(
        &mut self,
        _cx: &mut Context<'_>,
    ) -> Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }
}
```

--------------------------------

### Client Functionality

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/lib.rs.html

Enables the client extension trait and connector for Unix domain sockets.

```APIDOC
## Client Module

### Description
Provides traits and types for establishing client connections over Unix domain sockets.

### Types
- `UnixClientExt`: Extension trait for client functionality.
- `UnixConnector`: Connector for Unix domain socket clients.
- `UnixStream`: Represents a Unix domain socket stream.
```

--------------------------------

### UnixStream Connection

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Establishes a connection to a Unix domain socket at the specified path. This is a fundamental operation for the hyperlocal client.

```rust
impl UnixStream {
    async fn connect(path: impl AsRef<Path>) -> io::Result<Self> {
        let unix_stream = tokio::net::UnixStream::connect(path).await?;
        Ok(Self { unix_stream })
    }
}
```

--------------------------------

### UnixListenerExt::serve

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/trait.UnixListenerExt.html

Indefinitely accept and respond to connections on a Unix domain socket. This method takes a factory function that generates a request handler function. The request handler function is responsible for processing incoming requests and returning a future that resolves to a response.

```APIDOC
## fn serve<MakeResponseFn, ResponseFn, ResponseFuture, B, E>( self, f: MakeResponseFn, ) -> impl Future<Output = Result<(), Box<dyn Error + Send + Sync>>>
where MakeResponseFn: Fn() -> ResponseFn,
      ResponseFn: Fn(Request<Incoming>) -> ResponseFuture,
      ResponseFuture: Future<Output = Result<Response<B>, E>>,
      B: Body + 'static,
      <B as Body>::Error: Error + Send + Sync,
      E: Error + Send + Sync + 'static,

### Description
Indefinitely accept and respond to connections.
Pass a function which will generate the function which responds to all requests for an individual connection.

### Parameters
- **f** (MakeResponseFn) - A function that returns a request handler function.

### Returns
A future that resolves to a Result indicating success or an error.
```

--------------------------------

### UnixClientExt::unix

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/trait.UnixClientExt.html

Constructs a client that speaks HTTP over a Unix domain socket.

```APIDOC
## fn unix() -> Client<UnixConnector, B>

### Description
Construct a client which speaks HTTP over a Unix domain socket

### Example
```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::client::legacy::Client;
use hyperlocal::{UnixClientExt, UnixConnector};

let client: Client<UnixConnector, Full<Bytes>> = Client::unix();
```
```

--------------------------------

### with_subscriber

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixConnector.html

Attaches a provided Subscriber to the UnixConnector, returning a WithDispatch wrapper.

```APIDOC
## fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>

### Description
Attaches the provided `Subscriber` to this type, returning a `WithDispatch` wrapper.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```rust
// Example usage (assuming UnixConnector and Dispatch are defined)
// let connector = UnixConnector::new();
// let subscriber = SomeSubscriber::new(); // Replace with actual subscriber type
// let with_dispatch = connector.with_subscriber(subscriber);
```

### Response
#### Success Response
- Returns a `WithDispatch<Self>` wrapper.

#### Response Example
```rust
// The WithDispatch struct would contain the original UnixConnector and the attached subscriber.
// Example structure (not actual code):
// struct WithDispatch<T> {
//     inner: T,
//     subscriber: Dispatch,
// }
```
```

--------------------------------

### Uri::new

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/uri.rs.html

Constructs a new `Uri` from a socket path and a URI path. This type implements `Into<hyper::Uri>`.

```APIDOC
## Uri::new

### Description
Create a new `[Uri]` from a socket address and a path.

### Method
`pub fn new(socket: impl AsRef<Path>, path: &str) -> Self`

### Parameters
#### Path Parameters
- **socket** (impl AsRef<Path>) - Required - The path to the Unix domain socket.
- **path** (&str) - Required - The URI path.

### Panics
Will panic if path is not absolute and/or a malformed path string.

### Example
```rust
use hyper::Uri as HyperUri;
use hyperlocal::Uri;

let uri: HyperUri = Uri::new("/tmp/hyperlocal.sock", "/").into();
```
```

--------------------------------

### Test Unix URI Conversion

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/uri.rs.html

Verifies that a `hyperlocal::Uri` constructed from a socket path and root path correctly converts to the expected `hyper::Uri` format.

```rust
#[cfg(test)]
mod tests {
    use super::Uri;
    use hyper::Uri as HyperUri;

    #[test]
    fn test_unix_uri_into_hyper_uri() {
        let unix: HyperUri = Uri::new("foo.sock", "/").into();
        let expected: HyperUri = "unix://666f6f2e736f636b:0/".parse().unwrap();
        assert_eq!(unix, expected);
    }
}
```

--------------------------------

### AsyncRead Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides asynchronous reading capabilities for the UnixStream.

```APIDOC
### impl AsyncRead for UnixStream

#### fn poll_read

Attempts to read from the `AsyncRead` into `buf`.

```rust
fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>
```
```

--------------------------------

### UnixClientExt::unix

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Constructs a Hyper client that speaks HTTP over a Unix domain socket.

```APIDOC
## UnixClientExt::unix

### Description
Constructs a client which speaks HTTP over a Unix domain socket.

### Method
`unix()`

### Parameters
None

### Request Body
None

### Response
- Returns a `Client<UnixConnector, B>` where `B` is a `Body` type.

### Example
```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::client::legacy::Client;
use hyperlocal::{UnixClientExt, UnixConnector};

let client: Client<UnixConnector, Full<Bytes>> = Client::unix();
```
```

--------------------------------

### Read Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides synchronous reading capabilities for the UnixStream.

```APIDOC
### impl Read for UnixStream

#### fn poll_read

Attempts to read bytes into the `buf`.

```rust
fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: ReadBufCursor<'_>, ) -> Poll<Result<(), Error>>
```
```

--------------------------------

### From<Uri> for HyperUri

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/uri.rs.html

Provides conversion from `hyperlocal::Uri` to `hyper::Uri`.

```APIDOC
## From<Uri> for HyperUri

### Description
Implements the `From` trait to allow seamless conversion of a `hyperlocal::Uri` into a `hyper::Uri`.

### Method
`impl From<Uri> for HyperUri`

### Example
```rust
use hyper::Uri as HyperUri;
use hyperlocal::Uri;

let hyperlocal_uri = Uri::new("/tmp/my.sock", "/api");
let hyper_uri: HyperUri = hyperlocal_uri.into();
```
```

--------------------------------

### UnixConnector

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

The `UnixConnector` can be used to construct a `hyper::Client` which can speak to a Unix domain socket. It implements the `Service<Uri>` trait, allowing it to be used with hyper's client builder.

```APIDOC
## UnixConnector

### Description
The `UnixConnector` can be used to construct a `hyper::Client` which can speak to a unix domain socket.

### Example
```rust
use http_body_util::Full;
use hyper::body::Bytes;
use hyper_util::{client::legacy::Client, rt::TokioExecutor};
use hyperlocal::UnixConnector;

let connector = UnixConnector;
let client: Client<UnixConnector, Full<Bytes>> = 
    Client::builder(TokioExecutor::new()).build(connector);
```

### Note
If you don't need access to the low-level `[hyper::Client]` builder interface, consider using the `[UnixClientExt]` trait instead.
```

--------------------------------

### AsyncWrite Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides asynchronous writing capabilities for the UnixStream.

```APIDOC
### impl AsyncWrite for UnixStream

#### fn poll_write

Attempt to write bytes from `buf` into the object.

```rust
fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>
```

#### fn poll_flush

Attempts to flush the object, ensuring that any buffered data reach their destination.

```rust
fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>
```

#### fn poll_shutdown

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

```rust
fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>
```

#### fn poll_write_vectored

Like `poll_write`, except that it writes from a slice of buffers.

```rust
fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>
```

#### fn is_write_vectored

Determines if this writer has an efficient `poll_write_vectored` implementation.

```rust
fn is_write_vectored(&self) -> bool
```
```

--------------------------------

### UnixListenerExt Trait Definition

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/trait.UnixListenerExt.html

Defines the serve method for Unix domain socket listeners, enabling them to act as hyper HTTP servers. This method accepts a factory function that generates request handlers.

```rust
pub trait UnixListenerExt {
    // Required method
    fn serve<MakeResponseFn, ResponseFn, ResponseFuture, B, E>(
        self,
        f: MakeResponseFn,
    ) -> impl Future<Output = Result<(), Box<dyn Error + Send + Sync>>>
       where MakeResponseFn: Fn() -> ResponseFn,
             ResponseFn: Fn(Request<Incoming>) -> ResponseFuture,
             ResponseFuture: Future<Output = Result<Response<B>, E>>,
             B: Body + 'static,
             <B as Body>::Error: Error + Send + Sync,
             E: Error + Send + Sync + 'static;
}
```

--------------------------------

### Rust Crate Configuration

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/lib.rs.html

Defines linting rules and feature flags for the hyperlocal crate. Features 'client' and 'server' are conditionally compiled and exported.

```rust
#![deny(
    missing_debug_implementations,
    unreachable_pub,
    rust_2018_idioms,
    missing_docs
)]
#![warn(clippy::all, clippy::pedantic)]

//! `hyperlocal` provides [Hyper](http://github.com/hyperium/hyper) bindings
//! for [Unix domain sockets](https://github.com/tokio-rs/tokio/tree/master/tokio-net/src/uds/).
//!
//! See the examples for how to configure a client or a server.
//!
//! # Features
//!
//! - Client- enables the client extension trait and connector. *Enabled by
//!   default*.
//!
//! - Server- enables the server extension trait. *Enabled by default*.

#[cfg(feature = "client")]
mod client;
#[cfg(feature = "client")]
pub use client::{UnixClientExt, UnixConnector, UnixStream};

#[cfg(feature = "server")]
mod server;
#[cfg(feature = "server")]
pub use server::UnixListenerExt;

mod uri;

pub use uri::Uri;

```

--------------------------------

### Debug Implementation

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Provides debugging capabilities for the UnixStream.

```APIDOC
### impl Debug for UnixStream

#### fn fmt

Formats the value using the given formatter.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```
```

--------------------------------

### Convert `hyperlocal::Uri` to `hyper::Uri`

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/uri.rs.html

The `hyperlocal::Uri` struct implements `From<Uri>` for `hyper::Uri`, allowing for seamless conversion.

```rust
impl From<Uri> for HyperUri {
    fn from(uri: Uri) -> Self {
        uri.hyper_uri
    }
}
```

--------------------------------

### UnixStream Connection Information

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `Connection` trait for `UnixStream`, providing connection information. This is typically used by `hyper` to understand the nature of the established connection.

```rust
impl Connection for UnixStream {
    fn connected(&self) -> Connected {
        Connected::new()
    }
}
```

--------------------------------

### URI Handling

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/lib.rs.html

Provides functionality for handling URIs specific to Unix domain sockets.

```APIDOC
## URI Module

### Description
Handles Uniform Resource Identifiers (URIs) for Unix domain socket connections.

### Types
- `Uri`: Represents a URI that can be used with Unix domain sockets.
```

--------------------------------

### UnixStream AsyncWrite Implementation

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `AsyncWrite` trait for `UnixStream`, allowing it to be used with asynchronous writing operations. It delegates calls to the underlying `tokio::net::UnixStream`.

```rust
impl AsyncWrite for UnixStream {
    fn poll_write(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &[u8],
    ) -> Poll<Result<usize, io::Error>> {
        self.project().unix_stream.poll_write(cx, buf)
    }

    fn poll_flush(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), io::Error>> {
        self.project().unix_stream.poll_flush(cx)
    }

    fn poll_shutdown(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), io::Error>> {
        self.project().unix_stream.poll_shutdown(cx)
    }

    fn poll_write_vectored(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        bufs: &[io::IoSlice<'_>],
    ) -> Poll<Result<usize, Error>> {
        self.project().unix_stream.poll_write_vectored(cx, bufs)
    }

    fn is_write_vectored(&self) -> bool {
        self.unix_stream.is_write_vectored()
    }
}
```

--------------------------------

### UnixStream AsyncRead Implementation

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `AsyncRead` trait for `UnixStream`, allowing asynchronous reading of data from the Unix domain socket. It forwards the polling to the underlying `tokio::net::UnixStream`.

```rust
impl AsyncRead for UnixStream {
    fn poll_read(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &mut ReadBuf<'_>,
    ) -> Poll<io::Result<()>> {
        self.project().unix_stream.poll_read(cx, buf)
    }
}
```

--------------------------------

### Parse Unix Socket Path from URI

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Parses a `Uri` to extract the socket path, expecting the scheme to be 'unix'. Returns an `io::Error` if the scheme is invalid or missing.

```rust
fn parse_socket_path(uri: &Uri) -> Result<PathBuf, io::Error> {
    if uri.scheme_str() != Some("unix") {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,

```

--------------------------------

### with_subscriber

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Attaches a provided Subscriber to the UnixStream instance. This method returns a `WithDispatch` wrapper, allowing for further operations with the attached subscriber.

```APIDOC
## fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>

### Description
Attaches the provided `Subscriber` to this type, returning a `WithDispatch` wrapper.

### Parameters
#### Path Parameters
- **subscriber** (S) - Required - The subscriber to attach. Must implement `Into<Dispatch>`.
```

--------------------------------

### UnixStream Struct

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

The UnixStream struct is a wrapper around tokio::net::UnixStream, providing an abstraction for Unix domain socket streams.

```APIDOC
## Struct UnixStream

Wrapper around `tokio::net::UnixStream`.

```rust
pub struct UnixStream { /* private fields */ }
```
```

--------------------------------

### UnixStream Hyper Read Implementation

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `hyper::rt::Read` trait for `UnixStream`, enabling it to be used with `hyper` for reading data from the Unix domain socket. It wraps the `tokio::net::UnixStream` with `TokioIo`.

```rust
impl hyper::rt::Read for UnixStream {
    fn poll_read(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: ReadBufCursor<'_>,
    ) -> Poll<Result<(), Error>> {
        let mut t = TokioIo::new(self.project().unix_stream);
        Pin::new(&mut t).poll_read(cx, buf)
    }
}
```

--------------------------------

### UnixStream Hyper Write Implementation

Source: https://docs.rs/hyperlocal/0.9.1/src/hyperlocal/client.rs.html

Implements the `hyper::rt::Write` trait for `UnixStream`, enabling it to be used within the `hyper` ecosystem for writing data over the socket.

```rust
impl hyper::rt::Write for UnixStream {
    fn poll_write(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &[u8],
    ) -> Poll<Result<usize, Error>> {
        self.project().unix_stream.poll_write(cx, buf)
    }

    fn poll_flush(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), Error>> {
        self.project().unix_stream.poll_flush(cx)
    }

    fn poll_shutdown(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), Error>> {
        self.project().unix_stream.poll_shutdown(cx)
    }
}
```

--------------------------------

### with_current_subscriber

Source: https://docs.rs/hyperlocal/0.9.1/hyperlocal/struct.UnixStream.html

Attaches the current default Subscriber to the UnixStream instance. This method returns a `WithDispatch` wrapper, making the current default subscriber available for subsequent operations.

```APIDOC
## fn with_current_subscriber(self) -> WithDispatch<Self>

### Description
Attaches the current default `Subscriber` to this type, returning a `WithDispatch` wrapper.

### Parameters
This method does not take any explicit parameters.
```
Tokens:
Raw