Struct wascc_host::Host

pub struct Host { /* fields omitted */ }

Represents an instance of a waSCC host runtime

Implementations

impl Host

pub fn new() -> Self

Creates a new runtime host using all of the default values. Use the host builder if you want to provide more customization options

pub fn add_actor(&self, actor: Actor) -> Result<()>

Adds an actor to the host. This will provision resources (such as a handler thread) for the actor. Actors will not be able to make use of capability providers unless bindings are added (or existed prior to the actor being added to a host, which is possible in lattice mode)

pub fn add_actor_from_registry(&self, image: &str) -> Result<()>

Adds an actor to the host by attempting to retrieve it from an OCI registry. This function takes an image reference as an argument, e.g. myregistry.mycloud.io/actor:v1 If OCI credentials are supplied in environment variables, those will be used.

pub fn add_capability(
    &self,
    actor: Actor,
    binding: Option<&str>,
    wasi: WasiParams
) -> Result<()>

Adds a portable capability provider (e.g. a WASI actor) to the waSCC host. Portable capability providers adhere to the same contract as native capability providers, but they are implemented as "high-privilege WASM" modules via WASI. Today, there is very little a WASI-based capability provider can do, but in the near future when WASI gets a standardized networking stack, more providers can be written as portable modules.

pub fn remove_actor(&self, pk: &str) -> Result<()>

Removes an actor from the host. Notifies the actor's processing thread to terminate, which will in turn attempt to unbind that actor from all previously bound capability providers (in lattice mode, this unbinding only takes place if the actor is the last instance of its kind in the lattice)

pub fn replace_actor(&self, new_actor: Actor) -> Result<()>

Replaces one running actor with another live actor with no message loss. Note that the time it takes to perform this replacement can cause pending messages from capability providers (e.g. messages from subscriptions or HTTP requests) to build up in a backlog, so make sure the new actor can handle this stream of these delayed messages. Also ensure that the underlying WebAssembly driver (chosen via feature flag) supports hot-swapping module bytes.

pub fn add_middleware(&self, mid: impl Middleware)

Adds a middleware item to the middleware processing pipeline

pub fn add_native_capability(&self, capability: NativeCapability) -> Result<()>

Adds a native capability provider plugin to the host runtime. If running in lattice mode, and at least one other instance of this same capability provider is running with previous bindings, then the provider being added to this host will automatically reconstitute the binding configuration. Note that because these capabilities are native, cross-platform support is not always guaranteed.

pub fn add_native_capability_from_registry(
    &self,
    image_ref: &str,
    binding_name: Option<String>
) -> Result<()>

Adds a native capability provider plugin to the host runtime by pulling the library from a provider archive stored in an OCI-compliant registry. This file will be stored in the operating system's designated temporary directory after being downloaded.

pub fn remove_native_capability(
    &self,
    capability_id: &str,
    binding_name: Option<String>
) -> Result<()>

Removes a native capability provider plugin from the waSCC runtime

pub fn remove_binding(
    &self,
    actor: &str,
    capid: &str,
    binding_name: Option<String>
) -> Result<()>

Removes a binding between an actor and the indicated capability provider. In lattice mode, this operation has a lattice global scope, and so all running instances of the indicated capability provider will be asked to dispose of any resources provisioned for the given actor.

pub fn set_binding(
    &self,
    actor: &str,
    capid: &str,
    binding_name: Option<String>,
    config: HashMap<String, String>
) -> Result<()>

Binds an actor to a capability provider with a given configuration. If the binding name is None then the default binding name will be used (default). An actor can only have one named binding per capability provider. In lattice mode, the call to this function has a lattice global scope, and so all running instances of the indicated provider will be notified and provision resources accordingly. For example, if you create a binding between an actor and an HTTP server provider, and there are four instances of that provider running in the lattice, each of those four hosts will start an HTTP server on the indicated port.

pub fn call_actor(
    &self,
    actor: &str,
    operation: &str,
    msg: &[u8]
) -> Result<Vec<u8>>

Invoke an operation handler on an actor directly. The caller is responsible for knowing ahead of time if the given actor supports the specified operation. In lattice mode, this call will still only attempt a local invocation on the host and will not make a lattice-wide call. If you want to make lattice-wide invocations, please use the lattice client library.

pub fn claims_for_actor(&self, pk: &str) -> Option<Claims<Actor>>

Returns the full set of JWT claims for a given actor, if that actor is running in the host. This call will not query other hosts in the lattice if lattice mode is enabled.

pub fn apply_manifest(&self, manifest: HostManifest) -> Result<()>

Applies a manifest JSON or YAML file to set up a host's actors, capability providers, and actor bindings

pub fn actors(&self) -> Vec<SubjectClaimsPair>

Returns the list of actors registered in the host. Even if lattice mode is enabled, this function will only return the list of actors in this specific host

pub fn capabilities(&self) -> HashMap<(String, String), CapabilityDescriptor>

Returns the list of capability providers registered in the host. The key is a tuple of (binding, capability ID)

pub fn actors_by_tag(&self, tags: &[&str]) -> Vec<String>

Returns the list of actors in the host that contain all of the tags in the supplied parameter. This function will not make a lattice-wide tag query

pub fn shutdown(&self) -> Result<()>

Attempts to perform a graceful shutdown of the host by removing all actors in the host and then removing all capability providers. This function is not guaranteed to block and wait for the shutdown to finish

pub fn id(&self) -> String

Returns the public key of the host

Trait Implementations

impl Clone for Host

fn clone(&self) -> Host

Returns a copy of the value.

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

Performs copy-assignment from source.