recourse 0.0.1-rc.3

Versioned failure contracts for Rust services
Documentation

recourse

recourse is the framework-neutral core for versioned failure contracts in Rust services.

[dependencies]
recourse = "=0.0.1-rc.3"

It provides:

  • permanent catalog codes and type URIs;
  • typed, schema-governed public evidence;
  • strict RFC 9457 Problem construction and HTTP policy headers;
  • structurally separate public Problems and private reports;
  • durable operation diagnostics and health findings;
  • bounded tolerant client decoding;
  • append-only catalog locks and conservative compatibility classification.

Applications register declarations explicitly with Catalog::builder(). The core crate has no async runtime or application-framework dependency. Framework adapters consume its concrete response parts at the edge.

This minimal program declares one permanent diagnostic and encodes its canonical HTTP Problem without a server framework:

use recourse::{
    catalog::{Catalog, CatalogSpec, CodeNumber},
    diagnostic::{DiagnosticType, NoEvidence},
    http::{CorrelationId, Fixed, HttpProblemType, ProblemOccurrence},
};

enum ServiceCatalog {}

impl CatalogSpec for ServiceCatalog {
    const NAME: &'static str = "example-service";
    const PREFIX: &'static str = "EXM";
    const TYPE_BASE: &'static str = "https://example.invalid/problems/";
}

enum ResourceMissing {}

impl DiagnosticType for ResourceMissing {
    type Catalog = ServiceCatalog;
    type Evidence = NoEvidence;

    const NUMBER: CodeNumber = CodeNumber::new(1001);
    const TITLE: &'static str = "Resource missing";
    const DETAIL: &'static str = "The requested resource does not exist.";
    const SUGGESTIONS: &'static [&'static str] = &["Check the resource identifier."];
    const DOCS: &'static str = "Verify the identifier before retrying.";
}

impl HttpProblemType for ResourceMissing {
    type Policy = Fixed<404>;
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let catalog = Catalog::<ServiceCatalog>::builder()
        .problem::<ResourceMissing>()
        .build()?;
    let occurrence = ProblemOccurrence::new(
        CorrelationId::new("request-01")?,
        "/problem-occurrences/request-01",
    )?;
    let encoded = catalog
        .try_problem::<ResourceMissing>(occurrence, NoEvidence)?
        .try_encode()?;

    assert_eq!(encoded.status().as_u16(), 404);
    assert_eq!(encoded.headers()["content-type"], "application/problem+json");
    Ok(())
}

The catalog owns the status, headers, JSON shape, code, and type URI. Public evidence must explicitly implement PublicEvidence; private source errors use the structurally separate PrivateReport type.

The evidence-schema profile treats retained string format keywords as runtime assertions and rejects unknown formats during catalog construction. Fixed-width numeric formats require their exact JSON type and receive complete representation bounds. Platform-sized and 128-bit integer formats are rejected because the protocol's intermediate JSON representation cannot guarantee their portable, lossless encoding. Runtime numeric evidence must use Rust primitive integers or finite floats. serde_json::Number and numeric serde_json::Value variants are intentionally unsupported because their serializer-private raw tokens bypass that governed emitter domain. The exact vocabularies are exposed as catalog::SUPPORTED_SCHEMA_FORMATS and catalog::SUPPORTED_SCHEMA_NUMERIC_FORMATS. Catalog construction also rejects declared minimum sizes, required members, fixed values, and provably mandatory nesting that cannot fit the default diagnostic wire profile.

See the repository for the Dispatch reference implementation, executable conformance fixtures, and the canonical verification gate for the workspace and publishable package artifacts.