Struct HostContext 

pub struct HostContext { /* private fields */ }

Explicit identity, authority and storage. Apps receive no ambient profile resolver.

Implementations

impl HostContext

pub fn hosted(&self) -> bool

Whether the session’s document host keeps this app’s record: the process holds none of it and reads the readings it publishes over its one connection (docs/architecture/apps.md §8 step 2).

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

The resource address the session’s document host publishes this app’s record at, when it keeps it (Self::hosted): what the app reads its state from and submits its actions against.

pub fn provide_connection<T>(&mut self, connection: T)

where T: 'static,

Supply the connection the app reads the session’s readings over and submits its actions to, in place of the one the launcher made it: what a host that runs the app inside itself (a test’s document host, a capture’s fixture) does, and nothing a launch the session makes needs (docs/designs/app-language/one-app-model.md §4).

pub fn supplied_connection<T>(&self) -> Option<&T>

where T: 'static,

The connection supplied by Self::provide_connection, when a host did; None for a launch, whose connection is the launcher’s.

impl HostContext

pub fn prepare_session_hosted( definition: &ApplicationDefinition, inputs: HostContextInputs, resource: &str, ) -> Result<HostContext, LaunchError>

The context of a launch the session’s document host serves. resource is the address the session publishes the app’s record at: the context names the record kind and the view’s instance, so a view restores what it kept, but its record store holds nothing of it.

Errors

Rejects invalid identifiers, a denied capability, and a record store of another app’s namespace.

impl HostContext

pub fn reopener(&self) -> Reopener

What the component needs to open another record of its app in its window later (Reopener).

pub fn prepare( definition: &ApplicationDefinition, inputs: HostContextInputs, target: &LaunchTarget, ) -> Result<HostContext, LaunchError>

Reserve New or open Existing before the factory, using only supplied identities.

Errors

Rejects denied authority, invalid/foreign namespaces and unavailable records.

pub fn prepare_new_record( definition: &ApplicationDefinition, inputs: HostContextInputs, record_id: RecordId, ) -> Result<HostContext, LaunchError>

Reserve a host-named new record through the same checked construction path. Useful for a workspace’s default document, whose identity must survive a restart even before the first local View has been saved. Existing records are never adopted or reinitialized by this operation.

Errors

Rejects foreign namespaces, denied authority and occupied identities.

pub fn write_as_author(&mut self)

Commit this instance’s edits to its record under an actor of its author’s own (crate::record::author_writer) rather than the record’s writer, which every instance sharing the record’s store writes as. For a host that mounts several authors on one store (a page’s mounts of one profile and device), so history can tell whose edit each change is. The record’s writer, which the store persists, is unchanged, as is everything written outside the instance.

pub fn provide_content(&mut self, store: ContentStore)

Lend the component the host’s content store for this storage scope: opaque bytes addressed by hash that outlive the component and that other components of the same scope read too.

pub fn content(&self) -> Option<&ContentStore>

pub fn provide_open_file(&mut self, file: OpenFile)

Hand the component a file to open. ApplicationDefinition::instantiate refuses the launch unless the definition opens its media type.

pub fn take_open_file(&mut self) -> Option<OpenFile>

The file the host handed over to open, once.

pub fn provide_capture(&mut self, capture: Capture)

Prepare the instance for a screenshot of capture instead of a window someone uses.

pub fn capture(&self) -> Option<&Capture>

The screenshot this instance is prepared for, if it is one.

pub fn provide_launch_arguments(&mut self, arguments: Vec<String>)

Hand the component what its launch named besides a file: the arguments of a command line or an “open with” (paths, URLs), in order. The host has already checked how many the component accepts.

pub fn take_launch_arguments(&mut self) -> Vec<String>

The launch arguments the host handed over, once.

pub fn provide_handoff(&mut self, handoff: PlaybackHandoff)

Hand the component the playback another device or app handed over with the media its launch names.

pub fn take_handoff(&mut self) -> Option<PlaybackHandoff>

The playback handoff the host handed over, once.

pub fn lend<T>(&mut self, service: T)

where T: Any,

Lend the component a service of the host that mounts it in its own process: a connection to the session’s process supervisor for a terminal the shell hosts. The component takes it by type; a host that lends nothing leaves the app on its own services.

pub fn lend_boxed(&mut self, service: Box<dyn Any>)

Lend the component a service already boxed: what a component that showed before its record hands the one that shows it (T stays the service’s own type).

pub fn record_opening(&self) -> Option<RecordOpening>

The record this context opened, while it is still opening off the frame (RecordStore::begin_opening): the component shows before it, and takes it in.

pub fn take_lent(&mut self) -> Vec<Box<dyn Any>>

The services the host lent, once.

pub fn provide_launch_options(&mut self, options: Vec<LaunchOption>)

Hand the component the options of its own that its launch named (--purpose number). The host has already checked that the component takes each of them.

pub fn take_launch_options(&mut self) -> Vec<LaunchOption>

The launch options the host handed over, once.

pub fn provide_private(&mut self)

Prepare the instance as a private window: its profile is thrown away with the process, and nothing it shows reaches the person’s other windows, devices or collaborators.

pub fn is_private(&self) -> bool

Whether the instance is a private window.

pub fn control_domain(&self) -> ControlDomain

Explicit owner-bound producer capability, available before factory work.

pub fn record(&self) -> &RecordCheckout

pub fn records(&self) -> &RecordStore

The store the record is kept in, with the app’s other records of the same workspace: what an app holding records beside its own (the parts of a chain) opens them in, so they sync on the same routes.

pub fn window_records(&self) -> Vec<(RecordId, AutoCommit)>

The per-window records this app’s windows kept in this workspace before it kept one record per workspace, read-only and sorted by id (RecordStore::window_records). Only a context of the workspace’s own record answers: what the app adopts into it when it creates it. Any other context has none.

pub fn app_id(&self) -> &str

The application this context was prepared for.

pub fn author(&self) -> &UserId

pub fn host_person(&self) -> &UserId

The immutable local person supplied at host preparation, not the author currently attributed to an action.

pub fn permissions(&self) -> PermissionContext

A snapshot of the participant’s permissions at this moment.

pub fn restrict_to_reading(&mut self)

The participant’s permissions as they change while the component runs (a role change, a revoked share). Components that present themselves read-only hold this instead of deciding once at launch. Lower this instance to reading: what a window replaying a recording offers whoever holds it. Nothing it shows can be changed through it.

pub fn live_permissions(&self) -> LivePermissions

pub fn action_context(&self) -> &ActionContext

pub fn wake_handle(&self) -> WakeHandle

pub fn services(&self) -> &HostServices

The host services this component was prepared under — the ones crate::host::current resolved when the host prepared it.

pub fn secrets(&self) -> SecretStore

This app’s secrets, in the store its host provides: the system’s (the Secret Service, the Keychain, the browser’s wrapped store) or a host’s own. Other apps’ secrets are out of reach.

pub fn provide_models(&mut self, models: Models)

Bind the model capability authorized by this host’s authenticated session. Nothing is discovered from process globals or another component.

pub fn provide_provider_admin(&mut self, handle: ProviderAdministration)

Loan separately authorized provider administration to this component only.

pub fn provider_admin(&self) -> ProviderAdministration

This component’s administration authority, unavailable unless explicitly loaned.

pub fn models(&self) -> Models

Asynchronous model access, unavailable unless the host explicitly supplied it.

pub fn files(&self) -> AppFiles

This app’s private file areas (data, config, cache, state): the per-user directories natively, the origin-private file system in a page. See crate::storage for what belongs where.

pub fn settings<T>(&self) -> Settings<T>

where T: SettingsSchema,

This app’s typed settings of type T, in the settings document the host gave it (Self::provide_settings); T declares how far they travel.

pub fn storage(&self) -> AppStorage

This app’s files, secrets and settings in one handle, as framework views and surfaces receive them.

pub fn provide_settings(&mut self, document: SettingsDocument)

Give the component this settings document instead of the person’s session document: a test or capture profile’s own.

pub fn provide_files(&mut self, files: AppFiles)

Give the component these file areas instead of the person’s: a test or capture profile’s own, so nothing it writes lands in theirs.

pub fn provide_person_records(&mut self, records: PersonRecords)

Give the component the person’s own records of this app (crate::record::person), kept beside the record it shows.

pub fn provide_workspace_records(&mut self, records: WorkspaceRecords)

Give the component the records every app of its workspace opens (crate::record::workspace), kept beside the record it shows.

pub fn workspace_records(&self) -> Option<&WorkspaceRecords>

The records every app of the workspace opens, when the host keeps them.

pub fn device_id(&self) -> &str

This device, as the host names it: stable across launches of the app on it, distinct on each of the person’s devices.

pub fn person_records(&self) -> Option<&PersonRecords>

The person’s own records of this app, when the host keeps them.

pub fn migrate_record( &self, migrate: impl FnOnce(&mut AutoCommit) -> Result<bool, String>, ) -> Result<bool, String>

Bring the record up to the storage version its app reads, before it is read: migrate makes at most one deterministic housekeeping change (two devices migrating the same document make the same one) and answers whether it changed anything.

pub fn read_record<R>( &self, read: impl FnOnce(&AutoCommit) -> R, ) -> Result<R, RecordOpenError>

Read/project an existing or initialized document. No untracked sync mutation.

Errors

A reserved or missing record cannot be read.

pub fn merge_peer_document(&self, document: Vec<u8>) -> Result<bool, String>

Merge another participant’s copy of the record, as their changes arriving over sync are merged: validated first, attributed to them in history, and never on this participant’s undo stack. Returns whether anything changed.

pub fn initialize_new_record( &mut self, initialize: impl FnOnce(&mut AutoCommit) -> Result<(), String>, ) -> Result<(), RecordOpenError>

The unique owner transition from Reserved to Ready. Existing is never initialized.

Errors

Refuses repeated initialization and preserves the reservation on schema/storage failure.

pub fn initialize_new_record_seeded( &mut self, initialize: impl FnOnce(&mut AutoCommit) -> Result<(), String>, seed: impl FnOnce(&mut AutoCommit) -> Result<(), String>, ) -> Result<(), RecordOpenError>

Self::initialize_new_record, then seed the record as this author on this device. The genesis initialize writes is the same on every device; the seed is what depends on who creates the record or where, and is nobody’s undo step. See RecordReservation::initialize_seeded.

Errors

As Self::initialize_new_record; a failing seed fails it too.

pub fn creation_workspace(&self) -> Option<&CreationWorkspace>

The host-derived original creation scope, absent on every ordinary restore.

Trait Implementations

impl Drop for HostContext

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.