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.

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 etag::check_if_match;

pub use etag::etag_from_updated_at;

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

etag

ETag / conditional-request helpers.

extract

Axum extractors provided by socle.

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.

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.

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

Build the success value for a CreatedResponse handler (201 Created).

listed

Build the success value for a HandlerListResponse handler.

ok

Build the success value for a HandlerResponse handler (200 OK).

Type Aliases

CreatedResponse

Return type for handlers that create a resource and return it with a 201 status.

EtaggedHandlerResponse

Return type for read/update handlers that carry an ETag response header.

HandlerListResponse

Return type for handlers that return a paginated collection wrapped in the platform envelope.

HandlerResponse

Return type for handlers that return a single resource wrapped in the platform envelope.

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.