Skip to main content

ModuleHandle

Struct ModuleHandle 

Source
pub struct ModuleHandle { /* private fields */ }
Expand description

Cloneable handle for module-originated control RPCs on channel 0.

Implementations§

Source§

impl ModuleHandle

Source

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

Source

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

Source

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

Source

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

Source

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.

Source

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.

Source

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

Source

pub async fn route_authorize( &self, principal: Principal, scope: RouteAuthorizeScope, target: String, expected: RouteAuthorizeExpected, ) -> Result<RouteAuthorizeResponse, ScopeCallError>

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

Source

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn is_closed(&self) -> bool

Whether this module’s connection to the daemon has closed.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn live_roots(&self) -> Result<LiveRootsSnapshot, CatalogUpdateError>

Snapshot the roots served by this module’s routable endpoint.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

pub async fn push( &self, handle: &RouteHandle, body: Vec<u8>, admission_class: Option<AdmissionClass>, ) -> Result<(), SubcModuleError>

Emit an uncorrelated Push on a live route.

Source

pub fn dropped_route_frames(&self) -> u64

Number of unknown or stale route frames silently dropped by endpoint validation.

Trait Implementations§

Source§

impl Clone for ModuleHandle

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more