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/*!
13# Trillium server adapter for async-std
14
15```rust,no_run
16# #[allow(clippy::needless_doctest_main)]
17fn main() {
18 trillium_async_std::run(|conn: trillium::Conn| async move {
19 conn.ok("hello async-std")
20 });
21}
22```
23
24```rust,no_run
25# #[allow(clippy::needless_doctest_main)]
26#[async_std::main]
27async fn main() {
28 trillium_async_std::run_async(|conn: trillium::Conn| async move {
29 conn.ok("hello async-std")
30 }).await;
31}
32```
33*/
34
35use std::future::Future;
36
37use trillium::Handler;
38pub use trillium_server_common::{Binding, CloneCounterObserver, Stopper};
39
40mod client;
41pub use client::ClientConfig;
42
43mod server;
44use server::Config;
45
46pub use async_std;
47
48mod transport;
49pub use transport::AsyncStdTransport;
50
51/**
52# Runs a trillium handler in a sync context with default config
53
54Runs a trillium handler on the async-std runtime with default
55configuration. See [`crate::config`] for what the defaults are and how
56to override them
57
58
59This function will block the current thread until the server shuts
60down
61*/
62
63pub fn run(handler: impl Handler) {
64 config().run(handler)
65}
66
67/**
68# Runs a trillium handler in an async context with default config
69
70Run the provided trillium handler on an already-running async-std
71runtime with default settings. the defaults are the same as
72[`crate::run`]. To customize these settings, see [`crate::config`].
73
74This function will poll pending until the server shuts down.
75*/
76pub async fn run_async(handler: impl Handler) {
77 config().run_async(handler).await
78}
79/**
80# Configures a server before running it
81
82## Defaults
83
84The default configuration is as follows:
85
86* port: the contents of the `PORT` env var or else 8080
87* host: the contents of the `HOST` env var or else "localhost"
88* signals handling and graceful shutdown: enabled on cfg(unix) systems
89* tcp nodelay: disabled
90* tls acceptor: none
91
92## Usage
93
94```rust
95let stopper = trillium_async_std::Stopper::new();
96# stopper.stop(); // stoppping the server immediately for the test
97trillium_async_std::config()
98 .with_port(0)
99 .with_host("127.0.0.1")
100 .without_signals()
101 .with_nodelay()
102 .with_acceptor(()) // see [`trillium_rustls`] and [`trillium_native_tls`]
103 .with_stopper(stopper)
104 .run(|conn: trillium::Conn| async move {
105 conn.ok("hello async-std")
106 });
107```
108
109See [`trillium_server_common::Config`] for more details
110
111*/
112pub fn config() -> Config<()> {
113 Config::new()
114}
115
116/// spawn and detach a Future that returns ()
117pub fn spawn<Fut: Future<Output = ()> + Send + 'static>(future: Fut) {
118 async_std::task::spawn(future);
119}