Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_steel/src/lib.rs

4.6 KiB, 18 runs

created by r1870400018:965, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! A TCP server implementation providing HTTPS, WebSocket and SMTPS support.
2//!
3//! Steel provides both a server implementation and a complete application framework. The server layer
4//! handles TLS certificates, static file serving, WebSocket upgrades and SMTPS connections. The
5//! application layer provides configuration management, development tooling and a shell interface.
6//!
7//! # Building
8//!
9//! Build the Steel server application with:
10//! ```bash
11//! cargo build --release
12//! ```
13//!
14//! This creates the `steel` binary in the target/release directory.
15//!
16//! # Architecture
17//!
18//! The crate is structured into two main modules:
19//! - `srv`: The core server implementation providing HTTPS, WebSocket and SMTPS support
20//! - `app`: The application framework including configuration, development tools and shell interface
21//!
22//! # Features
23//!
24//! - Development mode with hot reloading and automated self-signed certificates
25//! - Production mode with Let's Encrypt certificate automation
26//! - JavaScript/TypeScript bundling and SASS compilation in development
27//! - Configurable static file serving and routing
28//! - WebSocket support with protocol abstractions
29//! - Clean separation between server and application concerns
30//! - Post-quantum cryptography options
31//!
32//! # Shell Interface
33//!
34//! The Steel server operates as an interactive shell, allowing management of:
35//! - TLS certificates
36//! - Server configuration
37//! - Development mode
38//! - File serving
39//! - Encrypted secrets
40//!
41//! # Extending Functionality
42//!
43//! New shell commands can be added by:
44//!
45//! 1. Adding a command to the syntax in app/syntax.rs:
46//! ```rust
47//! let cmd = Cmd::from(CmdConfig {
48//! name: fmt!("mycommand"),
49//! help: Some(fmt!("Description of my command")),
50//! cat: fmt!("Category"),
51//! ..Default::default()
52//! });
53//! s = res!(s.add_cmd(cmd));
54//! ```
55//!
56//! 2. Adding a match arm in app/repl.rs execute() method:
57//! ```rust
58//! match cmd_key.as_str() {
59//! "mycommand" => evals.push(res!(self.my_command(&shell_cfg, Some(cmd)))),
60//! // ... other commands ...
61//! }
62//! ```
63//!
64//! 3. Implementing the command handler in the AppShellContext:
65//! ```rust
66//! impl AppShellContext {
67//! pub fn my_command(
68//! &mut self,
69//! shell_cfg: &ShellConfig,
70//! cmd: Option<&MsgCmd>,
71//! )
72//! -> Outcome<Evaluation>
73//! {
74//! // Command implementation
75//! Ok(Evaluation::Output(fmt!("Command executed")))
76//! }
77//! }
78//! ```
79//!
80//! # Configuration
81//!
82//! On first run, Steel creates a default configuration file config.jdat. This contains settings for:
83//! - Server ports and addresses
84//! - TLS certificate paths
85//! - Static file serving paths
86//! - Development mode options
87//! - Logging configuration
88//!
89//! The configuration can be modified directly or through the shell interface.
90//!
91#![forbid(unsafe_code)]
92pub mod srv;
93pub mod app;
94
95pub mod prelude {
96 pub use crate::app::ext::{
97 AppExtension,
98 NoExtension,
99 };
100 pub use crate::app::server::build_outbound_tls_client;
101 pub use crate::app::tui::{
102 run,
103 run_with_extension,
104 };
105 pub use crate::srv::api::{
106 ApiHandler,
107 ApiHandlerRegistry,
108 };
109 pub use crate::srv::cfg::{
110 ApiRoute,
111 WebhookRoute,
112 };
113 pub use crate::srv::webhook::{
114 WebhookHandler,
115 WebhookRegistry,
116 // Utilities for handler implementations.
117 url_encode,
118 extract_value,
119 extract_top_level_value,
120 extract_json_string,
121 // Stripe webhook signature verification.
122 verify_stripe_signature,
123 STRIPE_SIG_TOLERANCE_SECS,
124 };
125
126 // Request-side HTTP types that handlers need to read incoming
127 // request headers and construct response messages without
128 // depending on `fe2o3_net` directly.
129 pub use oxedyne_fe2o3_net::http::{
130 fields::{
131 HeaderFields,
132 HeaderFieldValue,
133 HeaderName,
134 },
135 header::{
136 HttpHeadline,
137 HttpMethod,
138 },
139 loc::HttpLocator,
140 msg::HttpMessage,
141 status::HttpStatus,
142 };
143
144 // Re-exports from the upstream syntax / TUI crates so that app
145 // extensions can implement `AppExtension` without depending on
146 // them directly.
147 pub use oxedyne_fe2o3_syntax::{
148 Syntax,
149 msg::MsgCmd,
150 cmd::{
151 Cmd,
152 CmdConfig,
153 },
154 arg::{
155 Arg,
156 ArgConfig,
157 },
158 opt::OptionRefVec,
159 };
160 pub use oxedyne_fe2o3_tui::lib_tui::repl::{
161 Evaluation,
162 ShellConfig,
163 };
164}