Crate blazingly

Expand description

§Blazingly

Blazingly is an operation-first Rust API framework: handler signatures and Rust models define extraction, validation, typed responses, OpenAPI, and generated documentation — and the same operation model natively defines MCP tools, resources, and prompts, not a reconstruction from OpenAPI.

This crate is the facade. cargo add blazingly re-exports the framework crates under one name and one prelude; each underlying crate (blazingly-core, blazingly-openapi, blazingly-mcp, and the rest) is an ordinary library usable on its own, and the facade adds the curated surface, the feature wiring, and the macros. MSRV is Rust 1.88. tokio, hyper, and axum are banned from the dependency graph at any depth and CI enforces it.

§What you get

FastAPI-style handlers: #[get]/#[post]/… on plain functions, #[api_model] validated models, #[api_error] stable typed errors;
compiled dependency injection (#[provider], Depends<T>, with Path/Query/Header/Cookie inputs beside them) and nested, mountable Plugin scopes with lifecycle hooks;
custom extraction through Extract<T> over the public FromInvocation trait, and Extract<RequestParts> for the request line and peer address;
runtime-neutral Request, Response, compiled Router, and an in-memory TestApp;
deterministic OpenAPI 3.1 / JSON Schema 2020-12 with precompiled /openapi.json and Scalar/Swagger UI mounts;
native MCP: the same typed operations served over JSON-RPC, Streamable HTTP, and supervised stdio, with confirmation and output-exposure policy;
generated API/AI Markdown bundles, project scaffolds, deployment files, and versioned operation contracts with compatibility reports;
middleware (CORS, compression, rate limits, trusted host/proxy), security verifiers (JWT, OAuth2 bearer, API key, signed sessions), and observability (request IDs, W3C trace context, tracing, Prometheus);
an opt-in Tokio-free Compio native HTTP/1 server with rustls TLS, SSE, and WebSocket upgrades.

New in 0.2: request-aware providers (a #[provider] takes Path/Query/ Header/Cookie inputs, folded into the consuming operation’s contract exactly once), Plugin::mount("/v1") and with_id_namespace("v1") for serving one module under two prefixes with distinct operation identities, custom extraction through Extract<T> over the public FromInvocation trait, and value-type constraints that survive nesting — a #[min_length] on a newtype now reaches the items schema of a Vec<T> that uses it, at any depth. The full list is in the changelog.

One caveat worth knowing early: a synchronous handler runs inline on the worker that accepted the request and is never moved to the blocking pool. Anything that genuinely blocks must call run_blocking.

§Features

deploy, docs, mcp, middleware, observability, openapi, realtime, security, and validation are enabled by default. Opt-in: native, native-tls, native-http2 (experimental), mcp-stdio, database, queue, templates, and observability-otel. cargo check -p blazingly --no-default-features verifies the minimal surface: contract, core, DI, executor, HTTP, macros, and blazingly-json. It does not drop the OpenAPI projection from the build — blazingly-http serves /openapi.json and depends on blazingly-openapi unconditionally, so the openapi feature gates the re-export rather than the compilation.

§Example

use blazingly::prelude::*;

#[api_model]
struct CreateUser {
    #[email]
    email: String,
}

#[api_model]
struct UserView {
    id: u64,
    email: String,
}

#[post("/users", id = "users.create", summary = "Create a user")]
#[mcp::tool(name = "create_user", risk = "write")]
async fn create_user(Json(input): Json<CreateUser>) -> Created<UserView> {
    Created(UserView {
        id: 1,
        email: input.email,
    })
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = ExecutableApp::new(routes![create_user])?;

    // The same typed operation, projected without a server:
    let openapi = blazingly::openapi::to_value(app.definition());
    let agent_docs = blazingly::docs::mcp_markdown(app.definition());
    println!("{openapi}\n{agent_docs}");
    Ok(())
}

TestApp exercises the same application entirely in memory; the opt-in native feature serves it over the Tokio-free HTTP/1 socket server.

§Links

Getting started — install, a first application, validation, DI, OpenAPI, and MCP
API documentation
Changelog
Stability and SemVer — what pre-1.0 does and does not promise
Repository — the framework-internal documentation lives in docs/

Re-exports§

pub use blazingly_database as database;
pub use blazingly_deploy as deploy;
pub use blazingly_docs as docs;
pub use blazingly_http as http;
pub use blazingly_json as json;
pub use blazingly_middleware as middleware;
pub use blazingly_observability as observability;
pub use blazingly_openapi as openapi;
pub use blazingly_queue as queue;
pub use blazingly_realtime as realtime;
pub use blazingly_security as security_runtime;
pub use blazingly_templates as templates;
pub use blazingly_validation as validation;

Modules§

mcp
native
prelude

Macros§

descriptors
routes: Collects annotated handlers into the operation list an application is built from.

Structs§

Accepted: A successful HTTP 202 response.
AgentPolicy: Protocol-neutral metadata used by MCP and other agent transports.
App: Builder for an application description.
AppDefinition: A validated, deterministic application description.
Background: A typed response carrying work that starts after its wire body is sent.
BackgroundTask: One runtime-neutral task that begins after the response body is written.
BackgroundTaskError: A failure produced by work scheduled after an HTTP response is sent.
BlockingFuture: Future resolved by a bounded blocking worker.
BlockingPool: A bounded process-wide pool used only by explicitly synchronous handlers.
BlockingPoolConfig: Capacity and worker count for synchronous blocking handlers.
BodyStreamError: One failure produced while an HTTP response body is being streamed.
CancellationToken: Runtime-neutral cooperative cancellation shared by adapters and operation execution.
Compatibility: Entry point for semantic contract comparison.
CompatibilityChange: One deterministic compatibility finding.
CompatibilityReport: Semantic compatibility report between two versions of one operation.
ConnectionInfo: Normalized transport values readable by a handler extractor.
ContractFingerprint: Stable SHA-256 identity of one canonical operation contract.
ContractFormatVersion: Version of the canonical Blazingly contract format.
Cookie: A typed HTTP cookie argument.
Created: A successful HTTP 201 response.
DependencyDescriptor: A typed dependency declared by an operation handler.
DependencyKey: Runtime identity of a typed dependency.
DependencyRequest: A dependency required by one operation handler.
Depends: A resolved typed dependency passed to a handler or provider.
ExecutableApp: A validated executable operation graph.
ExecutableOperation: A handler plus the operation descriptor shared by HTTP and MCP.
Extension: Typed request-local value installed by transport middleware.
Extract: Explicitly asks the operation macro to extract T from the invocation.
FieldDescriptor: One field in an API model.
FieldViolation: One typed model-validation failure.
File: A typed uploaded file argument.
Form: A typed application/x-www-form-urlencoded request body.
Header: A typed HTTP header argument.
HookContext: Runtime-neutral metadata passed to compiled plugin hooks.
HookOutcome: A body-free result summary passed to on_response hooks.
HttpApp: An owned, runtime-neutral HTTP application compiled from the operation graph.
HttpBinding: The HTTP projection of a protocol-neutral operation contract.
HttpRequestContext: Mutable, request-local context shared by runtime-neutral HTTP middleware.
HttpUpgrade: A validated HTTP protocol switch plus its post-handshake session handler.
InputDescriptor: One typed operation argument and its HTTP extraction source.
InputRejection: A stable client-visible failure produced while extracting an argument.
InvalidOperationId: An invalid operation identity.
InvocationControl: Adapter-supplied cancellation and timeout signals for one invocation.
Json: A typed JSON request body.
McpToolDescriptor: MCP tool semantics declared alongside an operation.
ModelDescriptor: A complete model used by validation, OpenAPI, MCP, and Markdown.
Multipart: A typed multipart/form-data request body.
MultipartField: One part of a streamed multipart/form-data body.
MultipartPartHeaders: The Content-Disposition metadata of one multipart part.
MultipartStream: A multipart/form-data request body read part by part, chunk by chunk.
NoContent: A successful HTTP 204 response without a body.
OperationContract: The protocol-neutral semantic contract for one operation.
OperationDescriptor: A protocol-neutral operation paired with its HTTP projection.
OperationFailure: A typed domain failure shared by HTTP and MCP projections.
OperationId: A stable, human-readable operation identity such as users.create.
Path: A typed path argument.
Plugin: A lexical provider scope containing operations and nested plugins.
PreparedJson: A JSON response body the operation encoded itself.
Provider: A typed dependency provider registered in a plugin scope.
Query: Typed URL query arguments.
Request: A runtime-neutral HTTP request.
RequestParts: An owned snapshot of the raw request parts, taken before the handler runs.
RequestProvider: A provider together with the request inputs it declared.
ResolvedDependencies: Slot-based dependency values visible to one operation handler.
Response: A runtime-neutral HTTP response.
ResponseBuildError: A response construction failure that must be redacted by transports.
ResponseDescriptor: A single successful or error response declared by an operation.
ResponseHeader: A response header emitted without transport-specific dependencies.
RouteMatch: A compiled route match with its direct operation slot and path captures.
Router: A runtime-neutral router compiled once from the operation graph.
SecurityRequirement: Security scheme and scopes required by one operation.
SecuritySchemeDescriptor: Named security scheme registered by an application.
Status: Overrides the successful status of another typed response.
StreamingBody: Typed streaming HTTP response body.
TestApp: An in-memory borrowed HTTP adapter over the shared executable operation graph.
TestOverrides: Typed provider replacements applied only while compiling a test app.
TypeDescriptor: The type identity and schema captured by the Rust frontend.
UpgradeIoError: A transport error after an HTTP connection has switched protocols.
UploadBody: Pull-based request body with adapter-enforced transport limits.
UploadFile: Runtime-neutral buffered upload metadata.
ValidationErrors: All model-validation failures collected in one pass.
WithHeaders: Adds response headers without changing the typed response body.

Enums§

BlockingError: Failure to schedule or execute a synchronous blocking handler.
BuildError: An invalid application graph.
CollectBodyError: Failure while deliberately buffering an HTTP response stream.
CompatibilityImpact: Compatibility impact of one semantic contract change.
Confirmation: Whether an agent must ask for confirmation before invoking an operation.
DependencyError: A stable request rejection or an internal dependency failure.
DependencyLifetime: The lifetime of a dependency provider.
ExecutableBuildError: An application-definition or dependency-compilation failure.
ExecutionOutcome: The protocol-neutral result of executing one operation.
FieldMetadata: Field metadata carried inside ValidationRule::Custom.
HookOutcomeKind: Stable result classes visible to plugin response hooks.
HttpMethod: HTTP methods supported by the operation frontend.
InputSource: The transport-neutral source of one operation argument.
InvocationAbort: Reason a controlled invocation stopped before completion.
InvocationInput: Transport-neutral values supplied to typed operation extractors.
MultipartError: A failure produced while reading a multipart/form-data request body.
OperationRisk: Agent-visible risk associated with invoking an operation.
OutputExposure: How much operation output may be exposed to an agent.
RouteError: A router miss that distinguishes an unknown path from a wrong method.
SchemaKind: Transport-independent JSON shape.
SecurityLocation: HTTP location used by an API-key security scheme.
SecuritySchemeKind: Transport-independent description of an application security scheme.
ValidationRule: Validation generated as native Rust code by #[api_model].

Constants§

CURRENT_CONTRACT_FORMAT_VERSION: The current canonical contract encoding version.
MAX_MULTIPART_HEADER_BYTES: Largest header block accepted for one multipart/form-data part.
MAX_MULTIPART_PARTS: Largest number of parts accepted in one multipart/form-data body.

Traits§

ApiConstrained: A value type whose field rules are declared once and reused by name.
ApiError: A user-declared operation error with stable transport semantics.
ApiModel: A model that can describe and validate itself without runtime reflection.
ApiSchema: A Rust type that can participate in an operation schema.
BackgroundExt: Ergonomic after-response task decoration.
BodyStream: Runtime-neutral, pull-based response byte stream.
FromInvocation: Decodes one typed handler argument from an invocation.
HttpMiddleware: Synchronous middleware interception points shared by every HTTP adapter.
HttpRequestParts: Borrowed HTTP request values used by the compiled executor.
HttpRequestView: Borrowed request access used by in-memory and native HTTP adapters.
OperationOutput: A typed handler result that can become a shared operation outcome.
ResponseExt: Ergonomic response decoration shared by typed success responses.
UpgradedIo

Functions§

blocking_error_outcome
install_global_blocking_pool: Installs the process-wide blocking pool before the first sync invocation.
merge_field_validation_errors: Records a field validator’s violations under the field it was declared on.
merge_validation_errors: Prefixes nested model violations while preserving stable codes/messages.
record_response_size: Records the encoded size of a body of shape T.
response_size_hint: Returns the capacity to reserve for the next body of shape T.
run_blocking: Schedules owned synchronous work without blocking an async worker.

Type Aliases§

BackgroundFuture
OperationFuture
ProviderInputDecoder: Decodes one provider-declared request input into an erased slot value.
UpgradeFuture
UpgradeHandler
UpgradeReadFuture: Runtime-neutral byte I/O owned after an HTTP protocol upgrade.
UpgradeWriteFuture

Attribute Macros§

api_error: Declares a stable domain error as an enum.
api_model: Declares an API model.
connect: Declares a CONNECT operation. See get for the argument form.
delete: Declares a DELETE operation. See get for the argument form.
get: Declares a GET operation.
head: Declares a HEAD operation. See get for the argument form.
operation: Defines an operation using an explicit HTTP method.
options: Declares an OPTIONS operation. See get for the argument form.
patch: Declares a PATCH operation. See get for the argument form.
post: Declares a POST operation. See get for the argument form.
provider: Turns a typed factory function into a compiled DI provider declaration.
put: Declares a PUT operation. See get for the argument form.
security: Requires a registered security scheme, and optionally scopes, for an operation.
trace: Declares a TRACE operation. See get for the argument form.

Crate blazingly

Crate blazingly Copy item path

§Blazingly

§What you get

§Features

§Example

§Links

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate blazingly