pub struct ModuleHandle { /* private fields */ }Expand description
Cloneable handle for module-originated control RPCs on channel 0.
Implementations§
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub async fn record_activity(
&self,
request: ActivityRecordRequest,
) -> Result<ActivityRecordResponse, ActivityRecordError>
pub async fn record_activity( &self, request: ActivityRecordRequest, ) -> Result<ActivityRecordResponse, ActivityRecordError>
Append one event through the module connection, after checking the negotiated capability. The daemon verifies citations and stamps the actor. Use ids in summaries and details, never secret values. A successful reply is durable; timeout and connection loss must not be retried blindly.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub async fn agent_commands(
&self,
started: Vec<AgentCommandRoot>,
finished: Vec<AgentCommandFinished>,
known: Option<Vec<AgentCommandRoot>>,
) -> Result<(), AgentCommandsError>
pub async fn agent_commands( &self, started: Vec<AgentCommandRoot>, finished: Vec<AgentCommandFinished>, known: Option<Vec<AgentCommandRoot>>, ) -> Result<(), AgentCommandsError>
Attribute commands to agents rather than to this module. Start times must
come from subc_os::process_start_time_ms. known replaces the whole live
set; omitting it only applies starts and finishes. An older daemon returns
AgentCommandsError::Unsupported, which callers may safely ignore.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub async fn scope_watch(
&self,
scopes: Vec<ScopeWatchSelector>,
) -> Result<ScopeSubscription, ScopeCallError>
pub async fn scope_watch( &self, scopes: Vec<ScopeWatchSelector>, ) -> Result<ScopeSubscription, ScopeCallError>
Watch scope epochs on this registered connection. The initial snapshot closes the gap for endings before open; subsequent events are terminal for each selector. Drop or unsubscribe, then reopen to replace the set. A lost connection ends the feed; open a new watch after registering again.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub async fn scope_served_by(
&self,
scope_ref: String,
scope_epoch: u64,
module_id: String,
) -> Result<ScopeServedByReply, ScopeCallError>
pub async fn scope_served_by( &self, scope_ref: String, scope_epoch: u64, module_id: String, ) -> Result<ScopeServedByReply, ScopeCallError>
Read acknowledged-bind history for an epoch owned by this module.
Only Served is affirmative. Ended or absent epochs are Unknown, as are
epochs not yet re-registered after a daemon restart.
Without scope-served-by/v1 in HELLO_ACK, nothing is sent.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub async fn consumer(
&self,
path: &Path,
options: ConsumerOptions,
) -> Result<Arc<SubcConsumer>, ConsumerError>
pub async fn consumer( &self, path: &Path, options: ConsumerOptions, ) -> Result<Arc<SubcConsumer>, ConsumerError>
Open or reuse a self-bound TCP consumer. The pool belongs to this spawn’s registration binding; keys compare the exact path and every option. It holds only weak references: dropping the last Arc closes the connection. Await or spawn the serve future before calling this method.
Sourcepub async fn consumer_local(
&self,
path: &Path,
options: ConsumerOptions,
) -> Result<Arc<SubcConsumer>, ConsumerError>
pub async fn consumer_local( &self, path: &Path, options: ConsumerOptions, ) -> Result<Arc<SubcConsumer>, ConsumerError>
Like Self::consumer, but local-only. Local and TCP connections never
share a pool entry, even when their connection file and options match.
Sourcepub async fn helper_claim_handoff(
&self,
) -> Result<HelperClaimHandoff, ClaimError>
pub async fn helper_claim_handoff( &self, ) -> Result<HelperClaimHandoff, ClaimError>
Pass a helper-purpose claim through subc-os’s one-read pipe. The helper acts for the module, but its calls are attested as delegated, not its own. No self claim or launch nonce is ever put into the child’s environment or argv. On Unix, install this handoff last on the helper’s Command. On Windows, configure the Command before spawning, then serve the handoff with the live child’s PID on a blocking thread, retaining the child.
Source§impl ModuleHandle
impl ModuleHandle
Ask whether principal may still open target using the stored scope
and its expected claim (route.authorize). Requires a registered module
connection: the daemon permits only its configured federated owner with
route-authorize/v1 in that module’s registration.
Judgments about the route, including refusal outcomes such as
NotAuthorized, are values in the Ok response. Daemon Error frames
instead refuse the call itself and return ScopeCallError::Refused,
preserving their code and message. In particular,
route_authorize_not_permitted means the asking module may not use this
operation, not that the route is unauthorized. Transport, timeout,
unsupported operation, and malformed or unexpected replies are also call
errors. Without route.authorize in HELLO_ACK’s subc_ops, nothing is sent.
This is a point-in-time judgment, not a reservation: a later route open may still be refused.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub fn request_pool_snapshots(&self) -> Vec<RequestPoolSnapshot>
pub fn request_pool_snapshots(&self) -> Vec<RequestPoolSnapshot>
Figures for each handler-slot pool of this connection, the default
pool first, then the long-held pool when the module declared one in
ModuleHandler::request_pools.
Source§impl ModuleHandle
impl ModuleHandle
Sourcepub fn machine_id(&self) -> Option<&MachineId>
pub fn machine_id(&self) -> Option<&MachineId>
The daemon’s machine id, as delivered on HELLO_ACK.
None means the daemon did not send one (it predates the machine id, or
was embedded without one) or sent a malformed value. Read that as “the
daemon has not named this machine”, never as “no machine”, and never mint
a substitute. The id is a name, never an authority: see MachineId.
Sourcepub fn daemon_capabilities(&self) -> &[String]
pub fn daemon_capabilities(&self) -> &[String]
The daemon capability identifiers delivered in this connection’s HELLO_ACK.
The list preserves the daemon’s order and unknown capability identifiers.
Sourcepub fn daemon_supports(&self, capability: &str) -> bool
pub fn daemon_supports(&self, capability: &str) -> bool
Whether this daemon advertised capability in this connection’s HELLO_ACK.
Scope owners should check
daemon_supports(subc_protocol::manifest::CAP_SCOPE_BIND_PROOF_V1)
before setting ScopeRecord.bind_proof_sha256 on records sent over
this connection.
Sourcepub fn closed(&self) -> impl Future<Output = ()> + Send + 'static
pub fn closed(&self) -> impl Future<Output = ()> + Send + 'static
Resolves once this module’s connection to the daemon has closed: after a channel-0 GOODBYE, EOF, or a connection error. A module ends its own background work on it, so nothing outlives the connection.
Sourcepub async fn catalog_update(
&self,
provides: Vec<ProviderRole>,
) -> Result<(), CatalogUpdateError>
pub async fn catalog_update( &self, provides: Vec<ProviderRole>, ) -> Result<(), CatalogUpdateError>
Ask the daemon to replace this module’s advertised provider roles in place.
The returned result resolves when the daemon ACKs the update, rejects it with a typed channel-0 Error frame, the request times out, or the connection dies.
Sourcepub async fn update_role_declarations(
&self,
role_declarations: BTreeMap<String, Map<String, Value>>,
) -> Result<(), CatalogUpdateError>
pub async fn update_role_declarations( &self, role_declarations: BTreeMap<String, Map<String, Value>>, ) -> Result<(), CatalogUpdateError>
Replace this module’s complete registered role-declaration map in place.
An empty map ({} on the wire) clears all declarations. Requires
subc-daemon 0.44.9 or later; returns CatalogUpdateError::NotSupported
without sending when HELLO_ACK does not advertise the operation. Invalid
declarations are refused by the daemon as CatalogUpdateError::Rejected,
preserving the previous map and the refusal’s code and reason.
Sourcepub async fn catalog_update_with_capabilities(
&self,
provides: Vec<ProviderRole>,
capabilities: CapabilityDeclarations,
) -> Result<(), CatalogUpdateError>
pub async fn catalog_update_with_capabilities( &self, provides: Vec<ProviderRole>, capabilities: CapabilityDeclarations, ) -> Result<(), CatalogUpdateError>
Replace provider roles and attest a new static capability declaration.
The declaration must be the same static metadata emitted by the module’s current manifest; this update exists so the daemon can reconcile live routes when that attested metadata changes.
Sourcepub async fn set_ready(&self, ready: bool) -> Result<(), CatalogUpdateError>
pub async fn set_ready(&self, ready: bool) -> Result<(), CatalogUpdateError>
Change readiness without changing provider roles or capability declarations.
Register with ready(false), start polling the serving future immediately,
and do slow startup work on another task before calling set_ready(true).
Setting readiness to false refuses new binds but leaves existing routes up.
Requires subc-daemon 0.20.3 or later (including subc-daemon 0.38.x).
Returns CatalogUpdateError::Protocol without sending if the current roles
are unknown: a catalog replacement is still in flight, or an earlier update
timed out, was cancelled or had an undecodable reply. After an uncertain result, a successful
explicit catalog replacement establishes the roles again.
Sourcepub async fn live_roots(&self) -> Result<LiveRootsSnapshot, CatalogUpdateError>
pub async fn live_roots(&self) -> Result<LiveRootsSnapshot, CatalogUpdateError>
Snapshot the roots served by this module’s routable endpoint.
Sourcepub async fn scope_sync(
&self,
generation: u64,
scopes: Vec<ScopeRecord>,
) -> Result<ScopeSyncReply, ScopeCallError>
pub async fn scope_sync( &self, generation: u64, scopes: Vec<ScopeRecord>, ) -> Result<ScopeSyncReply, ScopeCallError>
Register this module’s full scope set with the daemon (scope.sync).
Owners can set ScopeRecord::workdir and ScopeRecord::project_id with
the record builders after discovering scope-workdir/v1. These fields
attribute the session and grant no authority.
The owner is this module; nothing in the request names it. scopes is
the whole set: a live scope left out ends. generation must be larger
than the last one the daemon accepted from this owner’s sync authority,
or the sync is refused with scope_sync_stale.
A refusal of the whole sync comes back as ScopeCallError::Refused
carrying the daemon’s code (see subc_protocol::error_codes, e.g.
SCOPE_SYNC_STALE, SCOPE_SYNC_NOT_AUTHORITY), and nothing changed.
Only a module the daemon itself launched can hold sync authority.
Sourcepub async fn scope_apply(
&self,
generation: u64,
upsert: Vec<ScopeRecord>,
end: Vec<ScopeEnd>,
) -> Result<ScopeApplyReply, ScopeCallError>
pub async fn scope_apply( &self, generation: u64, upsert: Vec<ScopeRecord>, end: Vec<ScopeEnd>, ) -> Result<ScopeApplyReply, ScopeCallError>
Apply a delta to this module’s scope set (scope.apply).
This connection must first have established sync authority through an
accepted Self::scope_sync. generation shares the full-sync sequence
and must exceed the last accepted generation. Unnamed scopes stay live;
end ends only the named ref at the named epoch.
Whole-call refusals return ScopeCallError::Refused without changing
the set or generation. Per-record refusals and not_live ends remain in
the reply. Without scope.apply in HELLO_ACK, nothing is sent.
Sourcepub async fn scope_describe(
&self,
owner: Principal,
scope_ref: String,
) -> Result<ScopeDescribeReply, ScopeCallError>
pub async fn scope_describe( &self, owner: Principal, scope_ref: String, ) -> Result<ScopeDescribeReply, ScopeCallError>
Read one scope’s current state (scope.describe). Any registered
module may read any owner’s scope.
An unknown ref is not an error: the daemon answers it with status
not_live. owner_synced says whether the owner has synced since this
daemon started (if so, the scope is gone), and owner_configured whether
the owner is a module the daemon supervises (if not, it never will sync).
Sourcepub async fn confirm_operator(
&self,
summary: &str,
caller_route: &RouteHandle,
) -> Result<(), OperatorConfirmError>
pub async fn confirm_operator( &self, summary: &str, caller_route: &RouteHandle, ) -> Result<(), OperatorConfirmError>
Ask the operator to authorise one in-flight, unchanged write.
Every error means the module must refuse the write. Ok(()) authorises
only the write this call was made for; it must never be cached or reused.
The daemon checks the summary and whether this module may ask for the
caller’s route. No failure is retried.
A consumer call that may trigger confirmation must set
CallOptions::timeout to at least 300 seconds. This helper waits up to
290 seconds, including egress backpressure, and dropping it withdraws an
accepted request.
Sourcepub async fn confirm_operation(
&self,
summary: &str,
caller_route: &RouteHandle,
operation: &str,
) -> Result<(), OperatorConfirmError>
pub async fn confirm_operation( &self, summary: &str, caller_route: &RouteHandle, operation: &str, ) -> Result<(), OperatorConfirmError>
Ask the operator to authorise one in-flight, unchanged write for a named management operation.
This sends the same operator.confirm request as Self::confirm_operator,
with kind set to "operation" and operation set to the given name.
It shares the same deadline, withdrawal-on-drop and error mapping: every
error means the module must refuse the write, and Ok(()) authorises
only the write this call was made for; it must never be cached or reused.
A later daemon may answer without a prompt only when the name is listed
in this module’s manifest confirm_operations; the daemon decides.
Naming an operation the module did not declare still prompts; it is not
refused.
An empty name is refused locally as
OperatorConfirmError::OperationInvalid without sending anything.
A consumer call that may trigger confirmation must set
CallOptions::timeout to at least 300 seconds. This helper waits up to
290 seconds, including egress backpressure, and dropping it withdraws an
accepted request.
Sourcepub async fn confirm_enrollment(
&self,
summary: &str,
caller_route: &RouteHandle,
) -> Result<(), OperatorConfirmError>
pub async fn confirm_enrollment( &self, summary: &str, caller_route: &RouteHandle, ) -> Result<(), OperatorConfirmError>
Ask the operator to authorise pairing or enrolling a device or credential.
This sends the same operator.confirm request as Self::confirm_operator,
with kind set to "enrollment". It shares the same deadline,
withdrawal-on-drop and error mapping: every error means the module must
refuse the enrollment, and Ok(()) authorises only the enrollment this
call was made for; it must never be cached or reused.
The daemon never approves an enrollment without an operator prompt; it
may still refuse one before prompting, as for any confirmation. A
daemon built against subc-protocol before 0.33.5 ignores the kind and
treats the request as Self::confirm_operator does.
A consumer call that may trigger confirmation must set
CallOptions::timeout to at least 300 seconds. This helper waits up to
290 seconds, including egress backpressure, and dropping it withdraws an
accepted request.
Sourcepub async fn push(
&self,
handle: &RouteHandle,
body: Vec<u8>,
admission_class: Option<AdmissionClass>,
) -> Result<(), SubcModuleError>
pub async fn push( &self, handle: &RouteHandle, body: Vec<u8>, admission_class: Option<AdmissionClass>, ) -> Result<(), SubcModuleError>
Emit an uncorrelated Push on a live route.
Sourcepub fn dropped_route_frames(&self) -> u64
pub fn dropped_route_frames(&self) -> u64
Number of unknown or stale route frames silently dropped by endpoint validation.