🏗️ Elegant & Highly Performant Async Gemini Server Framework for the Modern Age
async
framework
gemini-protocol
protocol
gemini
rust
docs(examples): create a readme with details
+148
-10
+138
examples/README.md
+138
examples/README.md
···
1
+
# Examples
2
+
3
+
## [Async Stateful Module](./async_stateful_module.rs)
4
+
5
+
`cargo run --example async_stateful_module --features response-macros`
6
+
7
+
Demonstrates use of the `AsyncModule` trait by implementing the module
8
+
`Clicker` which tracks the global number of visits to the capsule.
9
+
10
+
This can easily be adapted to contain a hashmap of routes which are individually
11
+
tracked for clicks.
12
+
13
+
## [Async](./async.rs)
14
+
15
+
`cargo run --example async --features response-macros`
16
+
17
+
Demonstrates use of async routes through an async response macro and
18
+
implementing a click tracker using a shared variable through an thread-safe,
19
+
async mutex.
20
+
21
+
## [Binary](./binary.rs)
22
+
23
+
`cargo run --example binary --features response-macros`
24
+
25
+
Demonstrates the binary response functionality by using both manual
26
+
and automatic mime resolution (`--features auto-deduce-mime`).
27
+
28
+
## [Callbacks](./callbacks.rs)
29
+
30
+
`cargo run --example callbacks`
31
+
32
+
Demonstrates use of the pre and post-route callback handlers.
33
+
34
+
## [Certificate](./certificate.rs)
35
+
36
+
`cargo run --example certificate --features response-macros`
37
+
38
+
Demonstrate the various certificate related responses as well as
39
+
reading the client certificate to give conditional access.
40
+
41
+
## [Default Logger](./default_logger.rs)
42
+
43
+
`cargo run --example default_logger --features logger,response-macros`
44
+
45
+
A simple example showing the use of the default default logger implementation.
46
+
47
+
## [Empty](./empty.rs)
48
+
49
+
`cargo run --example empty`
50
+
51
+
An empty example which starts up a server but has no mounted routes.
52
+
53
+
## [Error Handler](./error_handler.rs)
54
+
55
+
`cargo run --example error_handler`
56
+
57
+
Creates an intentional error within a route, invoking the error handler.
58
+
59
+
## [Fix Path](./fix_path.rs)
60
+
61
+
`cargo run --example fix_path --features response-macros`
62
+
63
+
A simple example which demonstrates use of the path fixer that attempts to resolve the closest match of a route when an invalid route is visited.
64
+
65
+
This feature is limited to simple resolution patches such as resolving
66
+
trailing and missing trailing slashes. If your capsule requires a more sophisticated path fixer, please use any of the provided mechanisms to do so before your routes execute.
67
+
68
+
## [Input](./input.rs)
69
+
70
+
`cargo run --example input`
71
+
72
+
Demonstrates how to accept and inspect both standard and sensitive input.
73
+
74
+
## [MIME](./mime.rs)
75
+
76
+
`cargo run --example mime`
77
+
78
+
Demonstrate how to modify the MIME of a response before use.
79
+
80
+
## [Parameters](./parameters.rs)
81
+
82
+
`cargo run --example parameters --features response-macros`
83
+
84
+
Demonstrate the use of route parameters (not URL queries).
85
+
86
+
## [Partial](./partial.rs)
87
+
88
+
`cargo run --example partial`
89
+
90
+
Demonstrates use of appending headers and footers to routes, globally.
91
+
92
+
If you would like to conditionally append headers and footers based on route, please look into using a templating framework.
93
+
94
+
## [Query](./query.rs)
95
+
96
+
`cargo run --example input --features response-macros`
97
+
98
+
Demonstrates the inspection of URL queries parameters.
99
+
100
+
## [Responses](./responses.rs)
101
+
102
+
`cargo run --example responses --features response-macros`
103
+
104
+
Demonstrates the use of a wide variety of responses, additionally exposing the flexibility of response bodies types.
105
+
106
+
## [Simple `async-std`](./simple_async_std.rs)
107
+
108
+
`cargo run --example simple_async_std --features async-std`
109
+
110
+
Demonstrates how to explicitly specify Windmark to use the [`async-std`](https://github.com/async-rs/async-std) runtime.
111
+
112
+
If the `async-std` feature is NOT enabled, Windmark will default to using Tokio as the async runtime.
113
+
114
+
## [Simple Tokio](./simple_tokio.rs)
115
+
116
+
`cargo run --example simple_async_std --features async-std`
117
+
118
+
Demonstrates how to explicitly specify Windmark to use the [Tokio](https://github.com/tokio-rs/tokio) runtime.
119
+
120
+
## [Stateful Module](./stateful_module.rs)
121
+
122
+
`cargo run --example stateful_module --features response-macros`
123
+
124
+
Demonstrates use of `Module`s by implementing a click tracker
125
+
126
+
Identical in functionality to the Async Stateful Module example, just not asynchronous.
127
+
128
+
## [Stateless Module](./stateless_module.rs)
129
+
130
+
`cargo run --example stateless_module`
131
+
132
+
Demonstrates use of a stateless module.
133
+
134
+
Unlike a `Module`, a stateless module is not encapsulated into a `struct`, but is a simple function which is used to perform operations.
135
+
136
+
Stateless modules are able to emulate stateful modules employing `static` variables. The earliest Windmark modules (add-ons) were made this way.
137
+
138
+
The only requirement of a module is to implement the signature of a stateless module: `FnMut(&mut Router) -> ()`.
+1
-1
examples/async.rs
+1
-1
examples/async.rs
···
15
15
// Copyright (C) 2022-2023 Fuwn <contact@fuwn.me>
16
16
// SPDX-License-Identifier: GPL-3.0-only
17
17
18
-
//! `cargo run --example async`
18
+
//! `cargo run --example async --features response-macros`
19
19
20
20
#[windmark::main]
21
21
async fn main() -> Result<(), Box<dyn std::error::Error>> {
+1
-1
examples/async_stateful_module.rs
+1
-1
examples/async_stateful_module.rs
+1
-1
examples/binary.rs
+1
-1
examples/binary.rs
···
15
15
// Copyright (C) 2022-2023 Fuwn <contact@fuwn.me>
16
16
// SPDX-License-Identifier: GPL-3.0-only
17
17
18
-
//! `cargo run --example binary`
18
+
//! `cargo run --example binary --features response-macros`
19
19
//!
20
20
//! Optionally, you can run this example with the `auto-deduce-mime` feature
21
21
//! enabled.
+1
-1
examples/certificate.rs
+1
-1
examples/certificate.rs
+1
-1
examples/default_logger.rs
+1
-1
examples/default_logger.rs
···
15
15
// Copyright (C) 2022-2023 Fuwn <contact@fuwn.me>
16
16
// SPDX-License-Identifier: GPL-3.0-only
17
17
18
-
//! `cargo run --example default_logger --features logger`
18
+
//! `cargo run --example default_logger --features logger,response-macros`
19
19
20
20
#[windmark::main]
21
21
async fn main() -> Result<(), Box<dyn std::error::Error>> {
+1
-1
examples/fix_path.rs
+1
-1
examples/fix_path.rs
···
15
15
// Copyright (C) 2022-2023 Fuwn <contact@fuwn.me>
16
16
// SPDX-License-Identifier: GPL-3.0-only
17
17
18
-
//! `cargo run --example fix_path`
18
+
//! `cargo run --example fix_path --features response-macros`
19
19
20
20
#[windmark::main]
21
21
async fn main() -> Result<(), Box<dyn std::error::Error>> {
+1
-1
examples/parameters.rs
+1
-1
examples/parameters.rs
+1
-1
examples/query.rs
+1
-1
examples/query.rs
···
15
15
// Copyright (C) 2022-2023 Fuwn <contact@fuwn.me>
16
16
// SPDX-License-Identifier: GPL-3.0-only
17
17
18
-
//! `cargo run --example input`
18
+
//! `cargo run --example input --features response-macros`
19
19
20
20
#[windmark::main]
21
21
async fn main() -> Result<(), Box<dyn std::error::Error>> {
+1
-1
examples/responses.rs
+1
-1
examples/responses.rs
+1
-1
examples/stateful_module.rs
+1
-1
examples/stateful_module.rs