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§
Sourcefn 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,
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§
Sourcefn 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 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.
Sourcefn control_ops(&self) -> Vec<String>
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.
Sourcefn 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 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.
Sourcefn config_declaration(&self) -> Option<ConfigDeclareRequest>
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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn config_files<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = ()> + 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,
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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn 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 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.
Sourcefn health<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = HealthReport> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: '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,
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.
Sourcefn 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 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.
Sourcefn request_pools(&self) -> RequestPools
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.
Sourcefn 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_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.
Sourcefn 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,
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".