skyzen 0.2.1

A fast, ergonomic HTTP framework that works everywhere
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

//! Skyzen — an HTTP framework for Rust whose infrastructure is portable, not just its handlers.
//!
//! A handler asks for [`Kv`], [`Storage`], [`Queue`] or [`Db`] and gets a *capability*, not a
//! vendor SDK. The same function body runs against Redis and Postgres on a server, Cloudflare KV
//! and D1 at the edge, `DynamoDB` and SQS on AWS, Cosmos DB and Blob Storage on Azure — and against
//! in-process fakes from `skyzen-test` in a plain `cargo test`, with no sockets and no emulator.
//! Those types live in [`skyzen_services`](https://docs.rs/skyzen-services).
//!
//! The HTTP layer is portable in the same way: one `#[skyzen::main]` serves a native Tokio/Hyper
//! server, an AWS Lambda, an Azure Functions custom handler, and a Cloudflare Worker, chosen by
//! what the process finds in its environment rather than by anything in the application.
//!
//! [`Kv`]: https://docs.rs/skyzen-services/latest/skyzen_services/struct.Kv.html
//! [`Storage`]: https://docs.rs/skyzen-services/latest/skyzen_services/struct.Storage.html
//! [`Queue`]: https://docs.rs/skyzen-services/latest/skyzen_services/struct.Queue.html
//! [`Db`]: https://docs.rs/skyzen-services/latest/skyzen_services/struct.Db.html
//!
//! # Key Modules
//!
//! - [`routing`] — Tree-based routing with path parameters, HTTP method matching, custom 404/405
//!   handlers, and `nest`ing of an already-built [`Router`](routing::Router)
//! - [`extract`] — Extract typed data from requests: [`Json<T>`](utils::Json),
//!   [`Query<T>`](extract::Query), [`Path<T>`](extract::Path),
//!   [`TypedHeader<H>`](extract::TypedHeader), [`HeaderMap`](header::HeaderMap), and the body as
//!   `Bytes` or `String`
//! - [`responder`] — Convert types into HTTP responses: [`Json<T>`](utils::Json), `String`,
//!   [`StatusCode`], [`Sse`](responder::Sse), and tuples such as `(StatusCode, Json<T>)`
//! - [`handler`] — Async functions with extractors as arguments become endpoints automatically
//! - [`middleware`] — `&self` middleware, [`from_fn`](middleware::from_fn), and the shipped
//!   [`Cors`](middleware::Cors), [`BodyLimit`](middleware::BodyLimit) and compression layers
//! - [`utils`] — Common utilities including [`Json<T>`](utils::Json),
//!   [`Redirect`](utils::Redirect), [`Html<T>`](utils::Html) and [`CookieJar`](utils::CookieJar)
//! - [`mod@openapi`] — Automatic `OpenAPI` documentation from annotated handlers
//! - [`runtime`] — Runtime primitives for `#[skyzen::main]`, including the platform detection above
//! - [`static_files`] — Streamed file serving with `ETag`, `Range` and SPA fallback (requires
//!   `static-files`)
//! - [`websocket`] — Unified WebSocket API across native and WASM (requires `ws` feature)
//!
//! # Safe by default
//!
//! - A `5xx` response body is redacted to `"Internal server error"`; the real message and its whole
//!   `source()` chain go to the log. A `4xx` message is returned verbatim, because it is about the
//!   caller's request.
//! - Request bodies are capped at [`RequestBodyLimit::DEFAULT`] (2 MiB) with no configuration,
//!   enforced from `Content-Length` *and* mid-stream.
//!
//! # Getting Started
//!
//! ```rust,ignore
//! use skyzen::routing::{CreateRouteNode, Route, Router};
//!
//! #[skyzen::main]
//! fn main() -> Router {
//!     Route::new((
//!         "/".at(|| async { "Hello, World!" }),
//!     ))
//!     .build()
//! }
//! ```

extern crate self as skyzen;

#[macro_use]
mod macros;

pub mod handler;

pub mod routing;

/// Durable Object abstraction for stateful edge computing.
pub mod durable;

/// OpenAPI helpers.
pub mod openapi;

/// Portable event payloads.
pub mod events;

/// Utilities.
pub mod utils;

/// Runtime primitives leveraged by `#[skyzen::main]`.
pub mod runtime;

/// Attribute & derive macros exported by Skyzen.
pub use skyzen_macros::{
    durable_object, email, embed_migrations, error, import_config, main, openapi, queue, scheduled,
    sql, tail, test, Column, FromRow, HttpError,
};

/// Static asset helpers for building file servers.
#[cfg(feature = "static-files")]
pub mod static_files;
#[cfg(feature = "static-files")]
pub use static_files::EmbeddedStaticDir;
#[cfg(all(feature = "static-files", not(target_arch = "wasm32")))]
pub use static_files::StaticDir;

/// Re-exported so the [`embed_dir!`] macro expansion can resolve `include_dir::` types.
#[doc(hidden)]
#[cfg(feature = "static-files")]
pub use include_dir;

#[doc(hidden)]
pub use http_kit;
#[doc(inline)]
pub use http_kit::{
    header, Body, BodyError, Endpoint, HttpError, Method, Request, Response, StatusCode, Uri,
};
/// Service types used by macro expansions.
///
/// Keeping this path behind the root crate means applications using manifest-driven wiring do
/// not need to declare Skyzen's implementation dependency themselves.
#[doc(hidden)]
pub use skyzen_services as __services;

/// RFC-typed headers, for use with [`TypedHeader`](crate::extract::TypedHeader).
///
/// This is the [`headers`](https://docs.rs/headers) crate; `skyzen::header` beside it is the raw
/// `HeaderName`/`HeaderValue` vocabulary from `http`.
#[cfg(feature = "typed-header")]
pub use headers;
#[cfg(target_arch = "wasm32")]
#[doc(hidden)]
pub use js_sys;
#[doc(inline)]
pub use middleware::Middleware;
#[doc(inline)]
pub use routing::{CreateRouteNode, Route};
pub use skyzen_core::error::*;
pub use skyzen_core::Server;
pub use skyzen_core::{error_response, log_endpoint_error, ErrorChain, RequestBodyLimit};
#[cfg(target_arch = "wasm32")]
#[doc(hidden)]
pub use wasm_bindgen;
#[cfg(target_arch = "wasm32")]
#[doc(hidden)]
pub use wasm_bindgen_futures;

/// Hyper-based server backend.
#[cfg(all(feature = "hyper", not(target_arch = "wasm32")))]
pub use skyzen_hyper as hyper;

#[doc(inline)]
pub use openapi::{IgnoreOpenApi, OpenApi, OpenApiOperation};

pub use utoipa::{PartialSchema, ToSchema};

/// Extract strong-typed object from your request.
pub mod extract;

/// Authentication and authorization utilities.
#[cfg(feature = "auth")]
pub mod auth;

pub mod responder;
pub use responder::Responder;

pub mod middleware;

#[doc(hidden)]
pub mod __private {
    use crate::{
        middleware::{layer, Layered, Middleware},
        Endpoint,
    };

    /// Wrap the endpoint `#[skyzen::main]` produced with one service injector.
    ///
    /// Applied outside `Route::build`, so the services declared in `Skyzen.toml` reach every
    /// request without the route tree having to know about them.
    pub fn with_middleware<E, M>(endpoint: E, middleware: M) -> Layered<E>
    where
        E: Endpoint + Clone + Send + Sync + 'static,
        M: Middleware,
    {
        layer(endpoint, middleware)
    }
}

#[cfg(feature = "ws")]
pub mod websocket;
#[cfg(feature = "ws")]
pub use websocket::{
    WebSocket, WebSocketMessage, WebSocketReceiver, WebSocketSender, WebSocketUpgrade,
};