Module microsvc 

microsvc — Convention-based microservice command handler framework.

Build microservices by registering command and event handlers on typed Routes<D> bundles, then adding those bundles to a deployment-level Service. Each handler receives a Context<D> with access to the input payload, session variables, and its route dependencies.

Quick Start

Dispatch is async — dispatch, handle, and the commit path all return futures and are awaited.

use std::sync::Arc;
use distributed::{microsvc, HashMapRepository};
use serde_json::json;

let routes = microsvc::Routes::new()
    .with_repo(HashMapRepository::new().queued().aggregate::<Order>())
    .command("order.create")
    .handle(|ctx| {
        let input = ctx.input::<CreateOrderInput>();
        async move { Ok(json!({ "id": input?.id })) }
    });
let service = Arc::new(microsvc::Service::new().routes(routes));

// Direct dispatch (async)
let result = service
    .dispatch("order.create", json!({ "id": "o1" }), microsvc::Session::new())
    .await?;

// HTTP transport (requires "http" feature)
// microsvc::serve(service, "0.0.0.0:3000").await?;

Handler Convention

Each handler file follows this convention. handle is async:

// src/handlers/order_create.rs

pub const COMMAND: &str = "order.create";

pub fn guard(ctx: &microsvc::Context<Repo>) -> bool {
    ctx.has_fields(&["id", "product_id"])
}

pub async fn handle(ctx: &microsvc::Context<'_, Repo>) -> Result<Value, microsvc::HandlerError> {
    let input = ctx.input::<CreateOrderInput>()?;
    let mut order = Order::default();
    order.create(input.id)?;
    ctx.repo().commit(&mut order).await?;
    Ok(json!({ "id": order.entity().id() }))
}

Re-exports

pub use crate::bus::Message;

pub use crate::bus::MessageKind;

pub use crate::bus::PayloadDecodeError;

pub use crate::bus::SubscriptionPlan;

Structs

CommandRequest

An inbound command request.

CommandResponse

Response from dispatching a command.

Context

The context passed to every handler.

HandlerSpec

Transport-visible metadata for a registered handler.

ReadModelStoreDependencies

Dependencies for a service that only needs a read-model store.

RepoDependencies

Dependencies for a service that only needs an aggregate repository.

RepoReadModelDependencies

Dependencies for a service that needs both an aggregate repository and a read-model store.

RouteBuilder

Builder returned by Routes::command, Routes::event, Routes::events, and Routes::handler.

Routes

A typed bundle of command/event handlers and the dependency value they use.

Service

A microservice deployment that routes messages to one or more route bundles.

Session

Parsed session variables from the incoming request.

Enums

DeliveryKind

How a handler expects the transport to deliver matching messages.

HandlerError

Error type for command handler operations.

HandlerNames

Static message names attached to a handler spec.

Constants

DEFAULT_MAX_PUBLISH_ATTEMPTS

Default publish-failure ceiling before an outbox row is permanently failed.

DEFAULT_PUBLISH_LEASE

Default lease for an immediate after-commit outbox publish. Short by design: it only needs to cover commit → publish, so a crash before the publish completes hands the row back to the polling worker quickly.

Traits

ConfigurableOutboxPublisher

Dependency capability for repositories whose outbox commits can publish immediately.

HasOutboxStore

Dependency capability for repositories that expose a durable outbox store.

HasReadModelStore

Dependency capability for services that expose a read-model store.

HasRepo

Dependency capability for services that expose an aggregate repository.

Type Aliases

HandlerBuilder

Backwards-compatible type alias for the handler registration builder.