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

trillium_smol/
lib.rs
