Crate dcontext_dactor 

dcontext-dactor

Automatic dcontext propagation through dactor actor messages.

This crate bridges dcontext (distributed context propagation) with dactor (actor framework) by providing interceptors that automatically carry context across actor message boundaries — no boilerplate needed in handlers.

How It Works

Context propagation is a two-stage interceptor pipeline:

1. Outbound interceptor (sender side) — ContextOutboundInterceptor captures the current dcontext and attaches it as message headers.

   • Local targets → ContextSnapshotHeader (preserves local-only values)
   • Remote targets → ContextHeader (serialized wire bytes)

2. Inbound interceptor (receiver side) — ContextInboundInterceptor performs two actions:

   • on_receive: normalizes headers — deserializes wire bytes into a ContextSnapshotHeader if needed.
   • wrap_handler: wraps the handler future with dcontext::async_ctx::with_context, restoring the propagated snapshot into the async task-local scope automatically.

This uses dactor 0.3’s wrap_handler feature to wrap the handler future with a task-local context scope. dcontext::async_ctx::get_context / dcontext::async_ctx::set_context work transparently inside the handler.

Error Handling

Both interceptors accept an ErrorPolicy that controls behavior when serialization or deserialization fails:

• ErrorPolicy::LogAndContinue (default) — log a warning, deliver the message without context.
• ErrorPolicy::Reject — reject the message via Disposition::Reject.

Local vs. Remote

• Local (same process): Context is propagated via ContextSnapshot, preserving local-only values that cannot be serialized. No serialization is performed.

• Remote (cross-process): Context is serialized to bytes via dcontext::async_ctx::serialize_context and transmitted as a wire header. Local-only values are excluded.

Quick Start

use dcontext_dactor::{ContextOutboundInterceptor, ContextInboundInterceptor};

// Register interceptors on your runtime — that's it!
runtime.add_outbound_interceptor(Box::new(ContextOutboundInterceptor::default()));
runtime.add_inbound_interceptor(Box::new(ContextInboundInterceptor::default()));

// Handlers automatically have dcontext available — no boilerplate
#[async_trait]
impl Handler<MyMessage> for MyActor {
    async fn handle(&mut self, msg: MyMessage, ctx: &mut ActorContext) -> () {
        // dcontext is automatically restored by the interceptor's wrap_handler
        let rid: RequestId = dcontext::async_ctx::get_context("request_id").unwrap();
        // ... handle message with context available ...
    }
}

Manual Extraction

For advanced use cases (e.g., spawning sub-tasks that need context), extract_context is still available to pull the snapshot from headers. with_propagated_context is retained for backward compatibility but is no longer needed when using the interceptor pipeline.

Structs

ContextHeader

Header carrying serialized context bytes for wire transport.

ContextInboundInterceptor

Inbound interceptor that propagates dcontext automatically through actor message handlers.

ContextOutboundInterceptor

Outbound interceptor that captures the current dcontext and attaches it to outgoing actor messages as headers.

ContextSnapshotHeader

Header carrying a ContextSnapshot for in-process (local) propagation.

Enums

ErrorPolicy

Controls how interceptors behave when serialization or deserialization fails.

Functions

extract_context

Extract the propagated context snapshot from actor message headers.

register_context_headers

Register dcontext header deserializers with a dactor HeaderRegistry.

with_propagated_contextDeprecated

Run an async handler body with the propagated dcontext from actor headers.