Skip to main content

ModuleHandler

Trait ModuleHandler 

Source
pub trait ModuleHandler:
    Send
    + Sync
    + 'static {
Show 17 methods // Required method fn handle<'life0, 'async_trait>( &'life0 self, ctx: RequestCtx, body: Vec<u8>, ) -> Pin<Box<dyn Future<Output = HandlerOutcome> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait; // Provided methods fn on_hello_ack<'life0, 'life1, 'async_trait>( &'life0 self, _ack: &'life1 ModuleHelloAckBody, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn control_ops(&self) -> Vec<String> { ... } fn on_control_request<'life0, 'life1, 'async_trait>( &'life0 self, _op: &'life1 str, _body: Value, _cancel: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<Value, ErrorBody>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn config_declaration(&self) -> Option<ConfigDeclareRequest> { ... } fn config_review<'life0, 'async_trait>( &'life0 self, _request: ConfigReviewRequest, ) -> Pin<Box<dyn Future<Output = ConfigReviewReply> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn config_apply<'life0, 'async_trait>( &'life0 self, _view: ConfigView, ) -> Pin<Box<dyn Future<Output = Result<(), Vec<String>>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn config_files<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn on_config_state<'life0, 'async_trait>( &'life0 self, _state: ConfigState, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn on_config_error<'life0, 'async_trait>( &'life0 self, error: ConfigError, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn on_bind<'life0, 'life1, 'async_trait>( &'life0 self, _req: &'life1 RouteBindRequest, ) -> Pin<Box<dyn Future<Output = BindDecision> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn on_bound<'life0, 'life1, 'async_trait>( &'life0 self, _handle: &'life1 RouteHandle, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn health<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = HealthReport> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn on_route_gone<'life0, 'life1, 'async_trait>( &'life0 self, _handle: &'life1 RouteHandle, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn request_pools(&self) -> RequestPools { ... } fn on_draining<'life0, 'async_trait>( &'life0 self, _reason: RouteCloseReason, _deadline: SystemTime, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... } fn on_connection_end<'life0, 'async_trait>( &'life0 self, _end: ConnectionEnd, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait { ... }
}
Expand description

Trait implemented by a module for its business logic. The serve functions in this crate own all wire-protocol plumbing.

§Stopping cleanly: drains

Before the daemon stops a module (restart, reload, disable, swap, or its own shutdown) it closes route admission, tells the module with ModuleHandler::on_draining, waits for the module’s in-flight requests to finish, and only then sends GOODBYE and closes the connection. The wait ends at the drain deadline whether or not the work is done.

Requests the daemon forwarded are counted by the daemon itself. Work it cannot see (a job a request started in the background, a batch being flushed) holds the drain open only if the module says so. The module does that with a counter it reports in its health answer (a “health gauge”), and a manifest entry telling the daemon that the counter means “busy”: a Busy self-signal anchored to those health gauges. Declare it, and report those gauges in ModuleHandler::health’s metrics above zero until the work has finished. During a drain the daemon probes health and waits until every declared gauge reads 0 (or the deadline passes); a declared gauge missing from the report counts as busy. The manifest entry, as built by the echo-module example in this crate:

use subc_protocol::manifest::{
    ModuleManifest, SelfSignalDeclaration, SelfSignalEffect, SelfSignalKind, SignalAnchor,
};

let manifest = ModuleManifest::builder("my-module", "1.0.0")
    .self_signals(Some(vec![SelfSignalDeclaration {
        name: "background_work".to_string(),
        kind: SelfSignalKind::Busy,
        effect: SelfSignalEffect::Observe,
        anchored_to: SignalAnchor::HealthGauges {
            gauges: vec!["background_jobs".to_string()],
        },
        cadence: None,
        domain: None,
        note: None,
    }]))
    .build();

and health then reports {"background_jobs": <count>} in metrics. Count only work whose result would still be delivered if it finished during the drain; see SelfSignalDeclaration::kind.

Required Methods§

Source

fn handle<'life0, 'async_trait>( &'life0 self, ctx: RequestCtx, body: Vec<u8>, ) -> Pin<Box<dyn Future<Output = HandlerOutcome> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Handle a data-plane request on a route channel. Return a unary response, a typed error, or stream interim events via RequestCtx::emit and return HandlerOutcome::Streamed. Each request runs in its own task so one slow handler cannot head-of-line-block another route.

Provided Methods§

Source

fn on_hello_ack<'life0, 'life1, 'async_trait>( &'life0 self, _ack: &'life1 ModuleHelloAckBody, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called once after HELLO_ACK so the module can inspect the ack body for negotiated capabilities and any storage descriptor supplied by the daemon.

Source

fn control_ops(&self) -> Vec<String>

Extra daemon-to-module operations served on channel 0, such as consent/v1. Read and validated once before HELLO: names must be nonempty ASCII names using letters, digits, ., _, - or /, with no empty segments. Duplicates and SDK-owned health.check, config.review and route.bind are refused with SubcModuleError::InvalidControlOp before advertising.

Source

fn on_control_request<'life0, 'life1, 'async_trait>( &'life0 self, _op: &'life1 str, _body: Value, _cancel: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<Value, ErrorBody>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Handle a declared control op with its entire decoded JSON request body. The control name is the body’s op string; for a protocol-tagged request with no op, such as consent/v1, it is the body’s protocol string. Return a JSON RESPONSE body or an ErrorBody carrying a wire error code and message. Runs off the reader, independently of routes, health and config review, with at most 16 concurrent calls per connection and no queue; overload returns resource_exhausted. There is no SDK time limit.

CANCEL for this request’s correlation, or disconnect, signals cancel. A reply produced after cancellation is discarded. Cooperate with the signal to release resources promptly; a cancelled call still holds its slot until it returns, and connection teardown eventually aborts it.

Source

fn config_declaration(&self) -> Option<ConfigDeclareRequest>

Opt in once per connection. The SDK advertises config.review, declares these locations, and fetches immutable views before calling config_apply. Returning None leaves the existing module wire and file reader unchanged.

Source

fn config_review<'life0, 'async_trait>( &'life0 self, _request: ConfigReviewRequest, ) -> Pin<Box<dyn Future<Output = ConfigReviewReply> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Pure review of supplied snapshots and base. Do not read mutable files, environment, network or secrets here. Runs off the connection reader.

Source

fn config_apply<'life0, 'async_trait>( &'life0 self, _view: ConfigView, ) -> Pin<Box<dyn Future<Output = Result<(), Vec<String>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Atomically apply a complete view, or leave the previous view intact and return secret-free NACK reasons. Readiness is included in a successful return. Runs off the reader; health and drain hooks remain independent.

Source

fn config_files<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Use the module’s existing file reader. Called only for an opted-in module whose HELLO_ACK lacks config.gate, never after a gate refusal.

Source

fn on_config_state<'life0, 'async_trait>( &'life0 self, _state: ConfigState, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Observe wire status and refusals without ending the serving connection.

Source

fn on_config_error<'life0, 'async_trait>( &'life0 self, error: ConfigError, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Observe transport, malformed-reply and other config errors. These never authorize a file fallback or end the module connection.

Source

fn on_bind<'life0, 'life1, 'async_trait>( &'life0 self, _req: &'life1 RouteBindRequest, ) -> Pin<Box<dyn Future<Output = BindDecision> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Decide a route.bind. This hook is decision-only and must not emit route traffic.

Source

fn on_bound<'life0, 'life1, 'async_trait>( &'life0 self, _handle: &'life1 RouteHandle, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called after an accepted bind ACK is queued and the handle is installed.

Source

fn health<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = HealthReport> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return cheap in-memory health for the module.

The default reports Ok with the detail “no health implementation; inherited default”. The detail lets an operator reading ck health <module> tell “measured, nothing wrong” from “nobody measured”, but the daemon decides on the status alone and never parses the detail, so to the daemon the default looks like a module that checked itself and found nothing wrong. It stays a default because health is optional: a module that advertises no health capability is never probed, so the value is never read. A module that does advertise health and keeps this default can report no fault beyond the serve helper’s own saturation check.

The serve helper calls this when the daemon sends health.check, on a task of its own rather than in a handler-slot pool, so a health check never waits behind the requests it reports on. It then folds in dispatch saturation: if every slot of a pool is in use and a request has waited more than two seconds for one, an Ok reply becomes Degraded, and the pool’s slot count and oldest wait are prepended to detail (naming the pool when the module declared a long-held pool in ModuleHandler::request_pools). A Degraded or Failing status, the module’s own detail and its metrics are kept.

An implementation must not block: no blocking lock, no disk access and no subprocess on this path. Derive the status from signals the dispatch path already records in memory, such as a monotonic heartbeat or the age of the oldest queued item. A health reply that waits on a slow shared resource stalls under exactly the conditions it is meant to report, because that resource is what degrades first.

Source

fn on_route_gone<'life0, 'life1, 'async_trait>( &'life0 self, _handle: &'life1 RouteHandle, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

A route was torn down, rejected, or abandoned before its bind ACK was queued.

Source

fn request_pools(&self) -> RequestPools

How this module’s data requests share handler slots. Called once per connection, before the serve loop reads its first frame after HELLO_ACK.

Each data request waits for a slot before ModuleHandler::handle runs and holds it until handle returns. The default is one pool of 64 slots for every request, waited for in arrival order. A module whose requests can be held for minutes should declare a long-held pool for them, so they cannot take every slot and leave short requests queued behind them where the daemon cannot see:

use subc_client_rs::{RequestClass, RequestPools};

fn request_pools() -> RequestPools {
    RequestPools::new().with_long_held(16, |body| {
        if body.starts_with(br#"{"op":"research.run""#) {
            RequestClass::long_held().with_op("research.run")
        } else {
            RequestClass::default_pool()
        }
    })
}

A request that waits two seconds for a slot is logged once at WARN while it is still waiting. While the connection is open, a request cancelled while waiting is answered cancelled at once; when the connection ends, waiting requests end without a reply, as before. ModuleHandle::request_pool_snapshots reports each pool’s figures. Health checks never use a pool.

Source

fn on_draining<'life0, 'async_trait>( &'life0 self, _reason: RouteCloseReason, _deadline: SystemTime, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

The daemon has started draining this module: it will stop it for reason (a restart, reload, disable, or the daemon’s own shutdown), and has already stopped admitting new routes to it. Stop taking new work here and finish or hand off what is in flight; see the trait docs for how to keep the drain open while background work finishes.

deadline is the wall-clock time by which the module must be done. It is “no later than”, never a grant of that much time: the daemon enforces its own ceiling on a monotonic clock and tears the connection down when that runs out, and after the host sleeps the ceiling can fall before this wall-clock time does. Aim to finish early.

Called once for each drain notice the daemon sends, on its own task, so a slow hook never holds up pings, requests, or the GOODBYE that ends the drain. It is started before that GOODBYE is handled (and before ModuleHandler::on_connection_end). Connection teardown aborts hooks that have not finished within the drain budget.

Source

fn on_connection_end<'life0, 'async_trait>( &'life0 self, _end: ConnectionEnd, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

The connection ended orderly: a daemon GOODBYE is a planned stop, EOF or Reset means the daemon went away without one, and Closed is a module stop. Called once, after request tasks have finished or been cancelled. A module that wants a different exit code for an unannounced end can decide here. Not called for handler or protocol failures. A later, unexpected writer failure can still make serving return an error.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§