oxedyne/fe2o3/fe2o3_net/src/lib.rs
4.4 KiB, 59 runs
created by r1870400018:589, 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 networking library providing foundational components for building network applications. |
| 2 | //! |
| 3 | //! This crate implements core networking protocols and utilities, with a focus on robust |
| 4 | //! error handling and type safety. It provides strongly-typed abstractions for common |
| 5 | //! networking concepts and protocols. |
| 6 | //! |
| 7 | //! # Key Features |
| 8 | //! |
| 9 | //! ## HTTP/HTTPS Protocol |
| 10 | //! - Complete header field handling with strongly typed values |
| 11 | //! - Status code management with descriptive messages |
| 12 | //! - Content type system supporting common web formats |
| 13 | //! - Request and response message parsing |
| 14 | //! - Cookie and session handling |
| 15 | //! - Support for HTTP/1.1, HTTP/2 and HTTP/3 |
| 16 | //! - Forwarding-header policy for a proxy hop (`http::fwd`), deciding which peers |
| 17 | //! may be believed when they speak `X-Forwarded-For` and its companions |
| 18 | //! |
| 19 | //! ## WebSocket Protocol |
| 20 | //! - Secure handshake implementation |
| 21 | //! - Binary and text message support |
| 22 | //! - Frame-level control with customisable chunk sizes |
| 23 | //! - Ping/pong heartbeat mechanism |
| 24 | //! - Connection upgrade handling |
| 25 | //! - Built-in latency tracking |
| 26 | //! |
| 27 | //! ## SMTP Email |
| 28 | //! - Message composition and parsing |
| 29 | //! - Command implementation (HELO, MAIL FROM, RCPT TO, etc.) |
| 30 | //! - Header field processing |
| 31 | //! - Multi-part content support |
| 32 | //! - Response code handling |
| 33 | //! |
| 34 | //! ## SSDP Discovery and UPnP |
| 35 | //! - The three UPnP discovery messages: search, answer and announcement |
| 36 | //! - Parsing forgiving enough for the devices actually on a network |
| 37 | //! - A multicast responder for 239.255.255.250:1900, async or blocking |
| 38 | //! - Device and service description documents, SOAP actions, and DIDL-Lite |
| 39 | //! |
| 40 | //! ## DNS and Addressing |
| 41 | //! - FQDN (Fully Qualified Domain Name) validation |
| 42 | //! - Email address parsing and validation |
| 43 | //! - Phone number handling with country codes |
| 44 | //! - Generic contact address abstraction |
| 45 | //! |
| 46 | //! ## Presentations |
| 47 | //! - A relying party's challenge to a browser session, and the verification of the |
| 48 | //! signed answer: a public name under Ed25519, or a pseudonym and linking tag |
| 49 | //! proved by a ring signature over a whole member set (`presentation`) |
| 50 | //! - Shapes that compile to wasm32 with the default features off |
| 51 | //! |
| 52 | //! ## Content Management |
| 53 | //! - Comprehensive media type system |
| 54 | //! - Character set handling for major encodings |
| 55 | //! - Content disposition control |
| 56 | //! - File type detection |
| 57 | //! |
| 58 | //! # Example |
| 59 | //! |
| 60 | //! ```rust |
| 61 | //! use oxedyne_fe2o3_core::prelude::*; |
| 62 | //! use oxedyne_fe2o3_net::{ |
| 63 | //! dns::Fqdn, |
| 64 | //! http::msg::HttpMessage, |
| 65 | //! }; |
| 66 | //! |
| 67 | //! # fn main() -> Outcome<()> { |
| 68 | //! // Create a simple HTTP response |
| 69 | //! let response = HttpMessage::ok_respond_with_text("Hello, world!"); |
| 70 | //! |
| 71 | //! // Validate a domain name |
| 72 | //! let domain = res!(Fqdn::new("example.com")); |
| 73 | //! # Ok(()) |
| 74 | //! # } |
| 75 | //! ``` |
| 76 | //! |
| 77 | //! # Error Handling |
| 78 | //! |
| 79 | //! The crate uses the Hematite error handling system with tagged errors for precise |
| 80 | //! error identification and chaining. All operations return an `Outcome<T>` which |
| 81 | //! provides context and categorisation of errors. |
| 82 | //! |
| 83 | //! # Async Support |
| 84 | //! |
| 85 | //! Network operations are implemented using Tokio for asynchronous I/O. The crate |
| 86 | //! provides both synchronous and asynchronous interfaces where appropriate. |
| 87 | //! |
| 88 | //! # Safety |
| 89 | //! |
| 90 | //! This crate forbids unsafe code and avoids unwrap operations, preferring explicit |
| 91 | //! error handling through the `Outcome` type. |
| 92 | //! |
| 93 | #![forbid(unsafe_code)] |
| 94 | // The `ring` modules. `acme`'s `jose` (JWS/base64url), `cache` and `rfc8555` |
| 95 | // layers are tokio-free and reused by the tokio-free `webauthn` verifier; only |
| 96 | // its tokio/rcgen submodules are gated, inside the module. |
| 97 | #[cfg(feature = "ring")] |
| 98 | pub mod acme; |
| 99 | pub mod addr; |
| 100 | pub mod conc; |
| 101 | pub mod charset; |
| 102 | pub mod constant; |
| 103 | #[cfg(feature = "ring")] |
| 104 | pub mod dkim; |
| 105 | pub mod dns; |
| 106 | pub mod dns_resolver; |
| 107 | #[cfg(feature = "ring")] |
| 108 | pub mod ecdsa; |
| 109 | pub mod email; |
| 110 | pub mod file; |
| 111 | pub mod guard; |
| 112 | #[cfg(feature = "ring")] |
| 113 | pub mod hmac; |
| 114 | pub mod http; |
| 115 | pub mod id; |
| 116 | #[cfg(feature = "async")] |
| 117 | pub mod imap; |
| 118 | #[cfg(feature = "async")] |
| 119 | pub mod llm; |
| 120 | pub mod mail; |
| 121 | pub mod media; |
| 122 | pub mod presentation; |
| 123 | pub mod search; |
| 124 | pub mod sms; |
| 125 | pub mod smtp; |
| 126 | #[cfg(feature = "async")] |
| 127 | pub mod ssdp; |
| 128 | pub mod time; |
| 129 | #[cfg(feature = "async")] |
| 130 | pub mod tls; |
| 131 | // UPnP device/service description sits on top of the (tokio-driven) SSDP |
| 132 | // discovery responder and its `Target` type, so it goes behind the same gate. |
| 133 | #[cfg(feature = "async")] |
| 134 | pub mod upnp; |
| 135 | #[cfg(feature = "ring")] |
| 136 | pub mod webauthn; |
| 137 | pub mod ws; |
| 138 | |
| 139 | #[cfg(feature = "async")] |
| 140 | pub use ws::core::WebSocket; |