Skip to main content

Crate blazingly_contract

Crate blazingly_contract 

Source
Expand description

§blazingly-contract

Runtime-neutral, canonical API contracts for Blazingly.

The crate owns the semantic source of truth shared by HTTP, MCP, AI documentation, internal RPC, and future mesh tooling:

  • versioned canonical encoding independent of declaration order;
  • model, input, output, typed-error, dependency, and security metadata;
  • aliases, nested validation, and stable custom-validator identities;
  • pull-based streaming request-body inputs without a runtime dependency;
  • MCP discovery and agent risk, confirmation, and idempotency policies;
  • SHA-256 contract fingerprints;
  • semantic compatibility reports.

It intentionally does not depend on Tokio, an HTTP server, an MCP transport, proc macros, or runtime dependency injection. The default std feature can be disabled for no_std + alloc consumers.

use blazingly_contract::{Compatibility, OperationContract};

fn verify_upgrade(previous: &OperationContract, current: &OperationContract) {
    let report = Compatibility::compare(previous, current);
    assert!(report.is_backward_compatible());
    println!("{}", current.fingerprint());
}

The Rust API follows Semantic Versioning. Canonical bytes and fingerprints are additionally versioned by CURRENT_CONTRACT_FORMAT_VERSION; changing the crate version does not silently change a contract fingerprint.

Version 0.4 uses canonical format 1.3, which carries value-type constraints on TypeDescriptor, including collection items and nested values, while preserving deterministic ordering and compatibility classification. Every operation fingerprint changes across the 1.2 to 1.3 move, so recorded compatibility baselines have to be recaptured. The new public constraints field breaks a struct literal that names every TypeDescriptor field: use TypeDescriptor::scalar/model/new, or add constraints: Vec::new().

§Install

[dependencies]
blazingly-contract = "0.4"

Licensed under the MIT License.

Structs§

AgentPolicy
Protocol-neutral metadata used by MCP and other agent transports.
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.
DependencyDescriptor
A typed dependency declared by an operation handler.
FieldDescriptor
One field in an API model.
FieldViolation
One typed model-validation failure.
InputDescriptor
One typed operation argument and its HTTP extraction source.
InvalidOperationId
An invalid operation identity.
McpToolDescriptor
MCP tool semantics declared alongside an operation.
ModelDescriptor
A complete model used by validation, OpenAPI, MCP, and Markdown.
OperationContract
The protocol-neutral semantic contract for one operation.
OperationFailure
A typed domain failure shared by HTTP and MCP projections.
OperationId
A stable, human-readable operation identity such as users.create.
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.
TypeDescriptor
The type identity and schema captured by the Rust frontend.
ValidationErrors
All model-validation failures collected in one pass.

Enums§

CompatibilityImpact
Compatibility impact of one semantic contract change.
Confirmation
Whether an agent must ask for confirmation before invoking an operation.
InputSource
The transport-neutral source of one operation argument.
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.

Traits§

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.