Crate socle 

socle

Opinionated axum service bootstrap: telemetry, database, rate limiting, and shutdown in one builder. Public open-source facade extracted from an internal service kit.

Recommended middleware ordering

RequestIdLayer → auth (placeholder) → OrgIsolationLayer → rate-limit → audit → handler

use socle::{ServiceBootstrap, BootstrapCtx, Result};
use axum::{Router, routing::get};

ServiceBootstrap::new("billing-service")
    .with_telemetry()
    .with_database("postgres://localhost/billing")
    .with_router(|_ctx: &BootstrapCtx| Router::new().route("/health", get(|| async { "ok" })))
    .serve("0.0.0.0:8080")
    .await

Re-exports

pub use audit::AuditAnnotation;

pub use audit::AuditAnnotationSlot;

pub use audit::AuditEvent;

pub use audit::AuditFilter;

pub use audit::AuditLayer;

pub use audit::AuditService;

pub use audit::AuditSink;

pub use audit::AuditSinkError;

pub use audit::TracingAuditSink;

pub use etag::check_if_match;

pub use etag::etag_from_updated_at;

pub use org_isolation::OrgContextExtractor;

pub use org_isolation::OrgContextSource;

pub use org_isolation::OrgIsolationLayer;

pub use org_isolation::OrgIsolationService;

pub use org_policy::AncestryOrgPolicy;

pub use org_policy::OrgPolicy;

pub use extract::Valid;

pub use ports::auth::AuthProvider;

pub use ports::health::ReadinessCheckFn;

pub use ports::rate_limit::RateLimitProvider;

pub use ports::telemetry::BasicTelemetryProvider;

pub use ports::telemetry::TelemetryProvider;

Modules

audit

Audit capture Tower layer with pluggable sinks.

etag

ETag / conditional-request helpers.

extract

Axum extractors provided by socle.

org_isolation

Org isolation extractor and enforcement middleware.

org_policy

Org-scoped access policy trait and default ancestry implementation.

pagination

Re-exports of api-bones pagination and query types.

ports

Ports — trait definitions the bootstrap application depends on.

reexports

Re-exports of the underlying crates.

testing

Test helpers shared across services built on socle.

Macros

assert_span

Assert that at least one span in $spans has the given name.

Structs

ApiError

RFC 9457 Problem Details error response.

ApiResponse

Generic API response envelope.

ApiResponseBuilder

Builder for ApiResponse.

AuditInfo

Audit metadata embedded in API resource structs.

BootstrapConfig

Layered configuration consumed by crate::ServiceBootstrap::from_config.

BootstrapCtx

Context handed to the user’s router builder closure.

BulkRequest

A batch of items to be processed in a single API call.

BulkResponse

The response to a BulkRequest, containing per-item results.

CorrelationId

An opaque cross-service correlation identifier, transported via X-Correlation-Id.

CorsConfig

Structured CORS configuration.

Cursor

URL-safe base64 cursor codec.

CursorPaginatedResponse

Cursor-based paginated response envelope (PLATFORM-003).

CursorPagination

Cursor-based pagination metadata (PLATFORM-003).

CursorPaginationParams

Query parameters for cursor-based list endpoints.

ETag

An HTTP entity tag as defined by RFC 7232 §2.3.

HandlerError

Error type for axum handlers. Wraps ApiError and implements IntoResponse.

IdempotencyKey

A validated idempotency key for safe POST/PATCH retry semantics.

KeysetPaginatedResponse

A page of results from a keyset-paginated endpoint.

KeysetPaginationParams

Query parameters for keyset (seek-based) pagination.

Link

A single HATEOAS link with a relation type, target URL, and optional HTTP method hint.

Links

An ordered collection of Link values.

OrgId

A UUID v4 tenant identifier, typically propagated via the X-Org-Id HTTP header.

OrgPath

An ordered org-path (root to self, inclusive), transported via X-Org-Path.

OrganizationContext

Platform context bundle — org, principal, request-id, roles, org-path, attestation.

PaginatedResponse

Offset-based paginated response envelope with a flat shape.

PaginationParams

Query parameters for offset-based list endpoints.

ProblemJson

RFC 7807 / 9457 Problem Details response body with optional extension members.

RateLimitBackend

In-process GCRA rate limiter configuration.

RateLimitConfig

Rate-limiting configuration for BootstrapConfig.

RateLimitInfo

Structured rate-limit metadata matching X-RateLimit-* headers.

RequestId

A UUID v4 request identifier, typically propagated via the X-Request-Id HTTP header.

ResponseMeta

Metadata attached to every ApiResponse.

ServiceBootstrap

Builder for a microservice runtime.

Slug

A validated, URL-friendly identifier.

SortParams

Query parameters for sorting a collection endpoint.

UnconstrainedResponse

Explicit opt-out from RFC-oriented response enforcement.

ValidationError

A single field-level validation error, used in ApiError::errors.

Enums

BulkItemResult

The outcome of processing a single item in a BulkRequest.

CorrelationIdError

Error returned when constructing a CorrelationId from a string fails.

CursorError

Error returned when a cursor cannot be decoded or its signature is invalid.

Error

Errors that can occur while bootstrapping or running a service.

ErrorCode

Machine-readable error code included in every API error response.

IdempotencyKeyError

Errors that can occur when constructing an IdempotencyKey.

IfMatch

Models the If-Match conditional request header (RFC 7232 §3.1).

IfNoneMatch

Models the If-None-Match conditional request header (RFC 7232 §3.2).

LogFormat

Logging output format.

RateLimitExtractor

Determines what gets rate-limited.

RateLimitKind

Backend store selection for RateLimitConfig.

SlugError

Errors that can occur when constructing a Slug.

SortDirection

Sort order for list endpoints.

Functions

created

created_at

created_under

etagged

listed

listed_page

Paginate a fully-loaded Vec<T>, map each item to U, and return a HandlerListResponse.

ok

Type Aliases

CreatedAtResponse

Return type for handlers that create a resource with a Location header (201 Created).

CreatedResponse

Return type for handlers that create a resource (201 Created).

EtaggedHandlerResponse

Return type for read/update handlers that carry an ETag response header (200 OK).

HandlerListResponse

Return type for handlers that return a paginated collection (200 OK).

HandlerResponse

Return type for handlers that return a single resource (200 OK).

RequestIdParseError

Backwards-compatible alias — prefer RequestIdError.

ResourceId

RFC 4122 UUID v4 resource identifier.

Result

Result alias used throughout socle.

ShutdownHookFn

Async drain callback registered via ServiceBootstrap::with_shutdown_hook.

Timestamp

RFC 3339 timestamp alias for API responses.