Struct CollaborationManager 

pub struct CollaborationManager { /* private fields */ }

Implementations

impl CollaborationManager

pub fn for_agent_route_with_identity( app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, agent_id: impl Into<String>, identity: CertifiedEndpointIdentity, ) -> Result<CollaborationManager, NotAvailable>

Self::for_agent_route over the inherited service descriptor, but joining with identity instead of the launcher’s identity service: a task agent presents the task delegation its desktop signed and proves it holds the task key, which also signs its writes.

Errors

Returns [runtime_portal::NotAvailable] when the collaboration service is unavailable or the broker refuses the join.

impl CollaborationManager

pub fn for_service( app_id: impl Into<String>, cluster_id: Uuid, ) -> Result<CollaborationManager, NotAvailable>

Connect a headless service of app_id in cluster_id that holds no document of its own: it publishes actions and answers them. It never asks the broker for a committed document, which a workspace holds only for apps that declare resource kinds; asking would fail the connection.

Errors

Returns [runtime_portal::NotAvailable] when the launcher did not hand down a collab service connection.

pub fn for_route_fd( fd: i32, app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, handle: Option<String>, ) -> Result<CollaborationManager, NotAvailable>

Explicit typed endpoint for in-process and headless transport harnesses. Takes ownership of fd. It uses an ephemeral signer; a production broker rejects the uncertified join, so this cannot bypass workspace admission.

Errors

Returns [runtime_portal::NotAvailable] when fd does not bootstrap a working collab service connection.

pub fn for_route_fd_with_identity( fd: i32, app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, handle: Option<String>, identity: CertifiedEndpointIdentity, ) -> Result<CollaborationManager, NotAvailable>

Connect to an explicit endpoint with a certified device presentation. This is the headless equivalent of the launcher-provided identity path.

Errors

Returns [runtime_portal::NotAvailable] when fd cannot bootstrap a collaboration service connection.

pub fn switch_native_record( &mut self, checkout: &RecordCheckout, ) -> Result<(), String>

pub fn for_native_launch( kind: &RecordKind, connection: NativeConnection, ) -> Result<CollaborationManager, NativeLaunchError>

The window’s manager for a native launch, joined: connected to its route, or disabled where no service was configured. Waits on the calling thread for the broker’s answer, however long it takes. A live window starts the join with Self::join_native instead and goes on while it runs.

Errors

As Self::join_native, and the broker’s refusal of the route, or why the connection ended before it answered.

pub fn join_native( kind: &RecordKind, connection: NativeConnection, ) -> Result<CollaborationManager, NativeLaunchError>

The window’s manager for a native launch, joining its route in the background, or disabled where no service was configured. The manager reports super::CollaborationState::Connecting until the broker answers; Self::poll takes the answer as an event, as it does for every other app, or Self::finish_join waits for it. No clock decides the join: the broker’s answer, its refusal or the connection’s end does.

Call it on the thread, and in the wake scope, of the app the manager is for: its worker wakes that app at each step of the join.

Errors

crate::NativeLaunchError::Operation where a configured service is unavailable or this device’s identity cannot be loaded.

pub fn join_instance( kind: &RecordKind, connection: OwnedFd, identity: BorrowedFd<'_>, route: RouteSpec, handle: Option<String>, ) -> Result<CollaborationManager, NativeLaunchError>

The manager of one app instance a tilolang host runs, joining route in the background on connection, as the person whose identity the identity-service connection identity holds.

The session opened both connections for that app’s launch and handed them to the host (runtime_portal::tilolang_host): the broker attests connection against the session’s launch record of the instance, never against what the host says, and refuses a hello for another app or workspace. Nothing is read from the process’s environment, which is the host’s, not the app’s. identity must outlive the manager.

pub fn finish_join(self) -> Result<CollaborationManager, NotAvailable>

This manager, once the primary route it is joining is joined: waits on the calling thread for the broker’s answer, for as long as it takes, and fails with the broker’s reason or the connection’s end. A manager with nothing to join is returned as it is.

pub fn for_agent_route( app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, agent_id: impl Into<String>, ) -> Result<CollaborationManager, NotAvailable>

Connect a headless participant as a first-class workspace agent. Its friendly id is both the visible handle and the principal whose scoped capabilities the broker evaluates.

Errors

Returns [runtime_portal::NotAvailable] when the collaboration service or certified join identity is unavailable.

pub fn for_agent_route_fd( fd: i32, app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, agent_id: impl Into<String>, ) -> Result<CollaborationManager, NotAvailable>

Explicit-socket counterpart to Self::for_agent_route. Production still requires a certified endpoint identity; this method merely preserves the agent principal kind for diagnostic transports.

Errors

Returns [runtime_portal::NotAvailable] when the socket cannot be joined or the route identity cannot be established.

pub fn for_agent_route_fd_with_identity( fd: i32, app_id: impl Into<String>, cluster_id: Uuid, record: Option<String>, agent_id: impl Into<String>, identity: CertifiedEndpointIdentity, ) -> Result<CollaborationManager, NotAvailable>

Certified explicit-socket agent connection used by out-of-process runtimes that do not inherit the launcher’s service descriptor.

Errors

Returns [runtime_portal::NotAvailable] when the socket or certified route join fails.

pub fn for_route_host_in_background( connector: HostSessionConnector, route: RouteSpec, record_kind: Option<String>, ) -> CollaborationManager

A manager on route, reached through the host’s connector as an app it launched, connecting in the background: the manager reports super::CollaborationState::Connecting until the broker acknowledges the route. For a host showing an app inside its own process.

impl CollaborationManager

pub fn with_transport( transport: Box<dyn CollabTransport>, ) -> CollaborationManager

Speak to an explicitly supplied transport.

The manager announces nothing on its own: send a CollabRequest::Hello to name the primary route. The route becomes Self::primary_route only once the transport reports the remote end’s acknowledgement through CollabTransport::take_primary_route_result, observed by Self::poll. The transport is handed a wake callback that schedules this owner’s next frame.

pub fn set_transport_wake(&mut self, wake: Box<dyn Fn() + Send + Sync>)

Hand the transport the callback that schedules this owner’s next frame (CollabTransport::set_wake): what a transport answered outside a drain of its own calls instead of waiting for one.

pub fn new() -> CollaborationManager

Connects to the launcher-inherited collaboration service when this build has one, entering Disabled mode when it is unavailable.

Returns at once: the connection is made in the background and its progress is reported by Self::state. Nothing here waits on the service, so this is safe to call on a UI thread before the first frame.

Both modes auto-send Hello announcing no record (one document per (app, workspace)); use Self::for_record for apps that have adopted records.

pub fn has_native_committed_primary(&self) -> bool

pub fn prepare_native_record( &mut self, checkout: &RecordCheckout, ) -> Option<CommittedDocument>

Join through the existing worker; never take the inherited RPC fd twice.

impl CollaborationManager

pub fn for_record(checkout: &RecordCheckout) -> CollaborationManager

A manager scoped to one record — one document, one change graph, one channel — so two people editing different files in one workspace don’t get handed each other’s state. A process with several records open holds several managers; tilo_ui::App swaps its manager on checkout change.

pub fn require_document_authorization(&mut self)

pub fn with_peer_transport( transport: impl PeerTransport + 'static, ) -> CollaborationManager

Inject a host-owned ordinary authenticated peer transport. Joins remain pending until the adapter supplies the broker’s matching acknowledgement.

pub fn disabled() -> CollaborationManager

Explicitly disconnected construction: no identity, service or worker discovery.

pub fn state(&self) -> CollaborationState

Where the connection stands. Cheap; call it every frame.

pub fn is_joining(&self) -> bool

Whether the manager is joining its primary route in the background: it has a connection, and the broker has not answered the route yet.

pub fn join_hold(&self) -> Option<JoinHold>

What holds up the primary route this manager is joining, as the broker reports it: the workspace is not ready on this device yet, or the broker cannot be reached. None while nothing is reported, and once the route is joined or refused. Each change wakes the owner.

pub fn join_refusal(&self) -> Option<&str>

Why the broker refused the primary route this manager was joining in the background, with the broker’s own reason. The manager is offline from then on; the app keeps its local replica.

pub fn sync_lost(&self) -> bool

Whether changes were meant to reach peers and currently do not: the manager had a collaboration service and has lost it. A document that never had one (local, outside any workspace) is not offline, and one still connecting has not lost anything yet.

pub fn action_of( &self, workspace: &str, change: &[u8; 32], ) -> Option<CommitHistory>

The whole action the change change was part of, when this endpoint’s transport keeps the index of actions it carries in workspace: every unit the action wrote, which is what one undo takes back. None for a manager with no such index.

pub fn take_state_change(&mut self) -> Option<CollaborationState>

The current state when it differs from the one this method last returned (initially, the state the manager was constructed in). Lets an owner run connect-time work once, when the manager becomes ready.

pub fn requested_primary_route(&self) -> Option<&RouteSpec>

The primary route most recently announced by a Hello, acknowledged or not.

pub fn retarget_join(&mut self, checkout: &RecordCheckout) -> Result<(), String>

Join checkout’s route in place of the primary route this manager is still joining, without waiting: the broker’s answer to the new route arrives as the last one would have (Self::poll).

pub fn primary_route(&self) -> Option<&PrimaryRouteWitness>

True when connected to a live broker — used by the event loop to keep ticking so the stream drains promptly.

pub fn private_window_instance(&self) -> Option<u64>

pub fn is_connected(&self) -> bool

Whether requests currently reach peers: Self::state is CollaborationState::Ready.

pub fn send(&mut self, req: CollabRequest) -> bool

Fire-and-forget and non-blocking on every backend. Presence may be shed under saturation; any other durable command is accepted and waits for the transport’s queue to have workspace, so a burst is backpressure, never a disconnect. Document mutations never disconnect: see Self::try_send for why one was not sent.

While the manager is CollaborationState::Connecting only a Hello is accepted: there is no acknowledged primary route to carry anything else, so other requests return false exactly as they do offline. Owners re-publish their state once the manager is ready.

pub fn try_send(&mut self, req: CollabRequest) -> Result<(), CollabSendError>

Self::send with the reason a request was not handed off. A document mutation larger than one signed frame is split into signed segments by the transport; one above [collab_types::MAX_DOCUMENT_TRANSFER_BYTES] is refused with CollabSendError::TooLarge and nothing is sent.

Errors

Returns CollabSendError when the request was not queued, and CollabSendError::Unavailable for anything but a Hello while the manager is still connecting.

pub fn report_local_document_action( &mut self, request_id: u64, capture: CapturedAction, ) -> Result<(), String>

Submit an exact capture without querying or rebasing its directory revision. The caller drains only its route’s local-input queue and retains errors for presentation; queue acceptance alone is not admission or signed publication. Replies arrive as CollabEvent::LocalDocumentActionReported.

pub fn report_local_document_action_to_route( &mut self, route: RouteSpec, request_id: u64, capture: CapturedAction, ) -> Result<(), LocalDocumentActionError>

Report a capture on an explicitly retained shared or local document route. The route must own the captured input and published directory revision. Queueing and admission supply neither execution proof nor publication authority. Replies arrive as CollabEvent::LocalDocumentActionReported.

pub fn begin_document_publication_barrier( &mut self, ) -> Result<DocumentPublicationReceipt, DocumentPublicationError>

Ask the transport for a completion receipt covering every document mutation submitted before this call. The receipt reports that the transport finished publishing them, not that peers applied them.

Errors

Returns DocumentPublicationError::Unavailable without a transport, or the transport’s own refusal (including DocumentPublicationError::Unsupported).

pub fn publish_action_directory(&mut self, app_id: impl Into<String>)

Register the UI-owned pull directory on the primary broker route. Re-registering is harmless: the broker atomically replaces the old capability for this live connection.

pub fn action_directory_observation(&self) -> (bool, Option<(u64, u64)>)

pub fn take_action_directory_requests(&mut self) -> Vec<ActionDirectoryRequest>

Drain requests issued by the transport’s ActionDirectory server. This must be called by [crate::app::App] on its owner thread.

pub fn join_route(&mut self, route: RouteSpec, record_kind: RecordKind)

Join and subscribe to an additional route without publishing traffic. Repeated joins of the same route are idempotent. Join route, whose record holds record_kind. The kind travels with the join so a host that must create the record when this device writes first knows what it holds; joining without it would let the host answer that the app named no kind.

pub fn install_document_encryption( &mut self, route: RouteSpec, group: ChannelGroup, ) -> Result<(), String>

Install an already-provisioned MLS endpoint for route.

From this point the route is fail-closed: locally generated document mutations are encrypted and encrypted inbound envelopes are decrypted before becoming CollabEvent::Document. The channel id must be the deterministic id for the exact app/workspace/record route. Group provisioning and durable secret storage intentionally remain outside the UI process; callers should obtain the group from the workspace identity service and must reinstall it after a process restart.

pub fn send_to_route(&mut self, route: RouteSpec, req: CollabRequest)

Publish on an explicitly named additional route. The route is joined lazily and retained, and its inbound streams feed this manager’s normal Self::poll queue.

Like Self::send, this sends nothing while the manager is still connecting.

pub fn document_route_ready(&self, route: Option<&RouteSpec>) -> bool

Whether the actual route’s original document history has been applied. This is the same transport gate used before document publication. A closed transport never reopens, so its routes stop being ready the moment it closes, before the worker clears their read state.

pub fn route_join_failure(&self, route: &RouteSpec) -> Option<String>

Why the last join of route failed, until a join of it succeeds: a route that never joined (a refused committed read, a record its workspace cannot create) says why here, rather than staying unready.

pub fn document_route_publishable(&self, route: &RouteSpec) -> bool

Whether route takes documents now: joined, and its original history applied.

pub fn try_send_to_route( &mut self, route: RouteSpec, req: CollabRequest, ) -> Result<(), CollabSendError>

Self::send_to_route with the reason a request was not handed off. This is the exact local enqueue outcome: the transport’s later publication barrier still owns durable acknowledgement.

Errors

Returns CollabSendError when the request was not queued.

pub fn document_publication_failed(&self) -> bool

pub fn refused_change(&self) -> Option<String>

The last change the peer answered but would not accept, while nothing later went through. The bridge is still connected: only that change is not accepted, and the owner reconciles its local copy.

pub fn take_action_surface_failed(&mut self) -> bool

Whether the broker refused or failed an action-surface publication since the last call; the caller must republish its surface.

pub fn stop_after_publication_failure(&mut self)

pub fn set_document_owner_routes( &mut self, routes: Vec<RouteSpec>, document_generation: u64, )

pub fn invocation_owner_current(&mut self, id: u64) -> bool

Whether invocation id from the drained batch may still run in the current document; see CollabTransport::invocation_owner_current.

pub fn hosts_surface(&mut self) -> bool

Whether this app is one of the desktop’s own surfaces: what it offers lives with the desktop it speaks to, not in a document of its own.

pub fn finish_event_batch(&mut self)

pub fn connection_snapshot( &self, route: &RouteSpec, ) -> Option<ConnectionSnapshot>

Validated inert provenance for this exact authenticated route.

pub fn poll(&mut self) -> Vec<CollabEvent<SdkCustody>>

Drain every event pending on the current backend. Non-blocking.

Also records a primary-route acknowledgement the transport reported since the last poll.

While the manager is CollaborationState::Connecting, this is also where it settles: a primary-route acknowledgement makes it ready; a refusal or a closed connection takes it offline.

Trait Implementations

impl Default for CollaborationManager

fn default() -> CollaborationManager

Returns the “default value” for a type.