trillium_smol/
lib.rs

1#![deny(
2    clippy::dbg_macro,
3    missing_copy_implementations,
4    rustdoc::missing_crate_level_docs,
5    missing_debug_implementations,
6    missing_docs,
7    nonstandard_style,
8    unused_qualifications
9)]
10
11//! # Trillium adapter using smol and async-global-executor
12//!
13//! ## Default / 12-factor applications
14//!
15//! ```rust,no_run
16//! trillium_smol::run(|conn: trillium::Conn| async move { conn.ok("hello smol") });
17//! ```
18//!
19//! ## Server configuration
20//!
21//! For more details, see [trillium_smol::config](crate::config).
22//!
23//! ```rust
24//! let swansong = trillium_smol::Swansong::new();
25//! # swansong.shut_down(); // stoppping the server immediately for the test
26//! trillium_smol::config()
27//!     .with_port(0)
28//!     .with_host("127.0.0.1")
29//!     .without_signals()
30//!     .with_nodelay()
31//!     .with_acceptor(()) // see [`trillium_rustls`] and [`trillium_native_tls`]
32//!     .with_swansong(swansong)
33//!     .run(|conn: trillium::Conn| async move { conn.ok("hello smol") });
34//! ```
35//!
36//! ## Client
37//!
38//! ```rust
39//! # #[cfg(feature = "smol")]
40//! trillium_testing::with_server("ok", |url| async move {
41//!     use trillium_client::{Client, Conn};
42//!     use trillium_smol::TcpConnector;
43//!     let mut conn = Conn::<TcpConnector>::get(url.clone()).execute().await?;
44//!     assert_eq!(conn.response_body().read_string().await?, "ok");
45//!
46//!     let client = Client::<TcpConnector>::new();
47//!     let mut conn = client.get(url);
48//!     conn.send().await?;
49//!     assert_eq!(conn.response_body().read_string().await?, "ok");
50//!     Ok(())
51//! });
52//! ```
53
54#[cfg(test)]
55#[doc = include_str!("../README.md")]
56mod readme {}
57
58use trillium::Handler;
59pub use trillium_server_common::{Binding, Connector, Runtime, RuntimeTrait, Swansong};
60
61mod client;
62pub use client::ClientConfig;
63
64mod server;
65use server::Config;
66
67mod transport;
68pub use async_global_executor;
69pub use async_io;
70pub use async_net;
71pub use transport::SmolTransport;
72
73mod runtime;
74pub use runtime::SmolRuntime;
75
76mod udp;
77pub use udp::SmolUdpSocket;
78
79/// # Runs a trillium handler in a sync context with default config
80///
81/// Runs a trillium handler on the async-global-executor runtime with
82/// default configuration. See [`crate::config`] for what the defaults are
83/// and how to override them
84///
85///
86/// This function will block the current thread until the server shuts
87/// down
88pub fn run(handler: impl Handler) {
89    config().run(handler)
90}
91
92/// # Runs a trillium handler in an async context with default config
93///
94/// Run the provided trillium handler on an already-running async-executor
95/// with default settings. The defaults are the same as [`crate::run`]. To
96/// customize these settings, see [`crate::config`].
97///
98/// This function will poll pending until the server shuts down.
99pub async fn run_async(handler: impl Handler) {
100    config().run_async(handler).await
101}
102
103/// # Configures a server before running it
104///
105/// ## Defaults
106///
107/// The default configuration is as follows:
108///
109/// port: the contents of the `PORT` env var or else 8080
110/// host: the contents of the `HOST` env var or else "localhost"
111/// signals handling and graceful shutdown: enabled on cfg(unix) systems
112/// tcp nodelay: disabled
113/// tls acceptor: none
114///
115/// ## Usage
116///
117/// ```rust
118/// let swansong = trillium_smol::Swansong::new();
119/// # swansong.shut_down(); // stoppping the server immediately for the test
120/// trillium_smol::config()
121///     .with_port(0)
122///     .with_host("127.0.0.1")
123///     .without_signals()
124///     .with_nodelay()
125///     .with_acceptor(()) // see [`trillium_rustls`] and [`trillium_native_tls`]
126///     .with_swansong(swansong)
127///     .run(|conn: trillium::Conn| async move { conn.ok("hello smol") });
128/// ```
129///
130/// See [`trillium_server_common::Config`] for more details
131pub fn config() -> Config<()> {
132    Config::new()
133}
trillium_smol/lib.rs

trillium_smol/
lib.rs
