axum_listener/lib.rs
1//! # Axum Listener Extensions
2//!
3//! This crate provides enhanced listeners for the [Axum](https://github.com/tokio-rs/axum) web framework,
4//! enabling unified handling of TCP and Unix Domain Socket (UDS) connections.
5//!
6//! ## Features
7//!
8//! - **DualListener**: A unified listener that can bind to either TCP or Unix Domain Socket addresses
9//! - **MultiListener**: A listener that can simultaneously accept connections from multiple underlying listeners
10//! - **Cross-platform support**: Works on Unix-like systems with UDS support and all platforms for TCP
11//! - **Axum integration**: Implements the `axum::serve::Listener` trait for seamless integration
12//!
13//! ## Cargo Features
14//!
15//! - `http1` (default): Enables HTTP/1 support in axum
16//! - `http2`: Enables HTTP/2 support in axum
17//! - `remove-on-drop` (default): Automatically removes UDS socket files when the address is dropped
18//!
19//! ## Quick Start
20//!
21//! ### Using DualListener for a single address
22//!
23//! ```rust,no_run
24//! # tokio_test::block_on(async {
25//! use axum::{Router, routing::get};
26//! use axum_listener::listener::DualListener;
27//!
28//! let router = Router::new().route("/", get(|| async { "Hello, World!" }));
29//!
30//! // Bind to a TCP address
31//! let listener = DualListener::bind("localhost:8080").await.unwrap();
32//! axum::serve(listener, router.clone()).await.unwrap();
33//!
34//! // Or bind to a Unix Domain Socket (on Unix systems)
35//! # #[cfg(unix)] {
36//! let listener = DualListener::bind("unix:/tmp/app.sock").await.unwrap();
37//! axum::serve(listener, router).await.unwrap();
38//! # }
39//! # });
40//! ```
41//!
42//! ### Using MultiListener for multiple addresses
43//!
44//! ```rust,no_run
45//! # tokio_test::block_on(async {
46//! use axum::{Router, routing::get};
47//! use axum_listener::multi::MultiListener;
48//!
49//! let router = Router::new().route("/", get(|| async { "Hello, World!" }));
50//!
51//! // Bind to multiple TCP and UDS simultaneously
52//! let addresses = ["localhost:8080", "localhost:9090", "unix:/tmp/app.sock"];
53//! let multi_listener = MultiListener::bind(addresses).await.unwrap();
54//! axum::serve(multi_listener, router).await.unwrap();
55//! # });
56//! ```
57//!
58//! ## Address Formats
59//!
60//! The following address formats are supported:
61//!
62//! - **TCP addresses**: `"localhost:8080"`, `"127.0.0.1:3000"`, `"[::1]:8080"`
63//! - **Unix Domain Sockets** (Unix only): `"/path/to/socket"`, `"unix:/path/to/socket"`
64//!
65//! ## Platform Support
66//!
67//! - TCP listeners work on all platforms
68//! - Unix Domain Socket listeners are only available on Unix-like systems (Linux, macOS, BSD, etc.)
69//! - The crate gracefully handles platform differences with conditional compilation
70pub mod dual;
71pub mod multi;
72#[doc(inline)]
73pub use dual::*;
74#[doc(inline)]
75pub use multi::*;