trillium_async_std/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(
3    clippy::dbg_macro,
4    missing_copy_implementations,
5    rustdoc::missing_crate_level_docs,
6    missing_debug_implementations,
7    missing_docs,
8    nonstandard_style,
9    unused_qualifications
10)]
11
12//! # Trillium server adapter for async-std
13//!
14//! ```rust,no_run
15//! # #[allow(clippy::needless_doctest_main)]
16//! fn main() {
17//!     trillium_async_std::run(|conn: trillium::Conn| async move { conn.ok("hello async-std") });
18//! }
19//! ```
20//!
21//! ```rust,no_run
22//! # #[allow(clippy::needless_doctest_main)]
23//! #[async_std::main]
24//! async fn main() {
25//!     trillium_async_std::run_async(
26//!         |conn: trillium::Conn| async move { conn.ok("hello async-std") },
27//!     )
28//!     .await;
29//! }
30//! ```
31//!
32//! For advanced binding — several listeners on one server, fallible binds you
33//! can recover from, or adopting an already-bound socket — call `.listeners()`
34//! on a [`config()`](crate::config) to get a
35//! [`ListenerConfig`].
36
37#[cfg(test)]
38#[doc = include_str!("../README.md")]
39mod readme {}
40
41use trillium::Handler;
42pub use trillium_server_common::{Binding, IntoListenAddr, ListenerConfig, Swansong};
43
44mod client;
45pub use client::ClientConfig;
46
47mod server;
48pub use async_std;
49use server::Config;
50
51mod transport;
52pub use transport::AsyncStdTransport;
53
54/// # Runs a trillium handler in a sync context with default config
55///
56/// Runs a trillium handler on the async-std runtime with default
57/// configuration. See [`crate::config`] for what the defaults are and how
58/// to override them
59///
60///
61/// This function will block the current thread until the server shuts
62/// down
63pub fn run(handler: impl Handler) {
64    config().run(handler)
65}
66
67/// # Runs a trillium handler in an async context with default config
68///
69/// Run the provided trillium handler on an already-running async-std
70/// runtime with default settings. the defaults are the same as
71/// [`crate::run`]. To customize these settings, see [`crate::config`].
72///
73/// This function will poll pending until the server shuts down.
74pub async fn run_async(handler: impl Handler) {
75    config().run_async(handler).await
76}
77/// # Configures a server before running it
78///
79/// ## Defaults
80///
81/// The default configuration is as follows:
82///
83/// port: the contents of the `PORT` env var or else 8080
84/// host: the contents of the `HOST` env var or else "localhost"
85/// signals handling and graceful shutdown: enabled on cfg(unix) systems
86/// tcp nodelay: disabled
87/// tls acceptor: none
88///
89/// ## Usage
90///
91/// ```rust
92/// let swansong = trillium_async_std::Swansong::new();
93/// # swansong.shut_down(); // stoppping the server immediately for the test
94/// trillium_async_std::config()
95///     .with_port(0)
96///     .with_host("127.0.0.1")
97///     .without_signals()
98///     .with_nodelay()
99///     .with_acceptor(()) // see [`trillium_rustls`], [`trillium_native_tls`], and [`trillium_openssl`]
100///     .with_swansong(swansong)
101///     .run(|conn: trillium::Conn| async move { conn.ok("hello async-std") });
102/// ```
103///
104/// See [`trillium_server_common::Config`] for more details
105pub fn config() -> Config<()> {
106    Config::new()
107}
108
109mod runtime;
110pub use runtime::AsyncStdRuntime;
111
112mod udp;
113pub use udp::AsyncStdUdpSocket;
trillium_async_std/lib.rs

trillium_async_std/
lib.rs
