Crate blazingly_core

Expand description

§blazingly-core

The runtime-neutral operation model of the Blazingly framework.

This crate defines the data the rest of the framework acts on: the typed extractor and response wrappers handlers use (Json, Path, Query, Header, Cookie, Form, Multipart, File; Created, Accepted, NoContent, Status, WithHeaders), streaming, upgrade, upload, and background-task primitives, a pull-based multipart/form-data reader, the HTTP projection of a protocol-neutral operation (HttpMethod, HttpBinding, OperationDescriptor), and the App builder that validates routes into a deterministic AppDefinition. It re-exports the contract vocabulary of blazingly-contract. There is no server, no async runtime, and no macro in this crate.

It is an ordinary library and usable standalone: blazingly-executor, blazingly-http, the native server, and the OpenAPI, docs, and MCP crates all consume it, and custom adapters or tooling over the operation model can depend on it directly. The blazingly facade re-exports this crate at its root and adds the attribute macros and the executor that turn plain functions into operations.

§Direct use

use blazingly_core::{App, HttpMethod, OperationDescriptor, ResponseDescriptor};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let health = OperationDescriptor::new(
        HttpMethod::Get,
        "/health",
        "health.read",
        "Liveness probe",
        None,
        vec![ResponseDescriptor::success(200, None)],
    )?;

    let definition = App::new().route(health).build()?;
    assert_eq!(definition.operations().len(), 1);
    Ok(())
}

build rejects duplicate operation ids and duplicate or ambiguous HTTP bindings, so an AppDefinition that exists is one every adapter can trust.

§Links

Macros§

descriptors

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.
BodyStreamError: One failure produced while an HTTP response body is being streamed.
Compatibility: Entry point for semantic contract comparison.
CompatibilityChange: One deterministic compatibility finding.
CompatibilityReport: Semantic compatibility report between two versions of one operation.
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.
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.
HttpBinding: The HTTP projection of a protocol-neutral operation contract.
HttpUpgrade: A validated HTTP protocol switch plus its post-handshake session handler.
InputDescriptor: One typed operation argument and its HTTP extraction source.
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.
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.
PreparedJson: A JSON response body the operation encoded itself.
Query: Typed URL query arguments.
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.
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.
TypeDescriptor: The type identity and schema captured by the Rust frontend.
UpgradeIoError: A transport error after an HTTP connection has switched protocols.
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§

BuildError: An invalid application graph.
CompatibilityImpact: Compatibility impact of one semantic contract change.
Confirmation: Whether an agent must ask for confirmation before invoking an operation.
FieldMetadata: Field metadata carried inside ValidationRule::Custom.
HttpMethod: HTTP methods supported by the operation frontend.
InputSource: The transport-neutral source of one operation argument.
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.
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.
ResponseExt: Ergonomic response decoration shared by typed success responses.
UpgradedIo

Functions§

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.

Type Aliases§

BackgroundFuture
UpgradeFuture
UpgradeHandler
UpgradeReadFuture: Runtime-neutral byte I/O owned after an HTTP protocol upgrade.
UpgradeWriteFuture