Struct wasmcloud_host::Host

pub struct Host { /* fields omitted */ }

A wasmCloud host is a secure runtime responsible for scheduling actors and capability providers, configuring the links between them, and facilitating secure function call dispatch between actors and capabilities.

Implementations

impl Host

pub async fn start(&self) -> Result<()>

Starts the host’s actor system. This call is non-blocking, so it is up to the consumer to provide some form of parking or waiting (e.g. wait for a Ctrl-C signal).

Examples

match host.start().await {
   Ok(_) => {    
    // Await a ctrl-c, e.g. actix_rt::signal::ctrl_c().await.unwrap();
    info!("Ctrl-C received, shutting down");
    host.stop().await;
   }
   Err(e) => {
    error!("Failed to start host: {}", e);
   }
}

pub async fn stop(&self)

Stops a running host. Be aware that this function may terminate before the host has finished disposing of all of its resources.

pub fn id(&self) -> String

Returns the unique public key (a 56-character upppercase string beginning with the letter N) of this host. The host’s private key is used to securely sign invocations so that remote hosts can perform anti-forgery checks. For more information on the PKI used by wasmCloud, see the documentation for the nkeys crate.

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

Starts a native capability provider and preps it for execution in the host.

pub async fn start_capability_from_registry(
    &self,
    cap_ref: &str,
    link_name: Option<String>
) -> Result<()>

Instructs the host to download a capability provider from an OCI registry and start it. The wasmCloud host caches binary images retrieved from OCI registries (because images are assumed to be immutable this kind of caching is acceptable). If you need to purge the OCI image cache, remove the wasmcloudcache and wasmcloud_ocicache directories from the appropriate root folder (which defaults to the environment’s TEMP directory).

Arguments

• cap_ref - The OCI reference URL of the capability provider.
• link_name - The link name to be used for this capability provider.

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

Instructs the runtime host to start an actor. Note that starting an actor can trigger a provider initialization if a link definition for this actor already exists in the lattice cache.

pub async fn start_actor_from_registry(&self, actor_ref: &str) -> Result<()>

Instructs the runtime host to download the actor from the indicated OCI registry and start the actor. This call will fail if the host cannot communicate with, fails to authenticate against, or cannot finish downloading the indicated OCI image.

pub async fn stop_actor(&self, actor_ref: &str) -> Result<()>

Stops a running actor in the host. This call is assumed to be idempotent and as such will not fail if you attempt to stop an actor that is not running (though this may result in errors or warnings in log output).

• actor_ref - Either the public key or the OCI reference URL of the actor to stop.

pub async fn update_actor(
    &self,
    actor_id: &str,
    new_oci_ref: Option<String>,
    bytes: &[u8]
) -> Result<()>

Updates a running actor with the bytes from a new actor module. Invoking this method will cause all pending messages inbound to the actor to block while the update is performed. It can take a few seconds depending on the size of the actor and the underlying engine you’re using (e.g. JIT vs. interpreter).

Arguments

• actor_id - The public key of the actor to update.
• new_oci_ref - If applicable, a new OCI reference URL that corresponds to the new version.
• bytes - The raw bytes containing the new WebAssembly module.

⚠️ Caveats

• Take care when supplying a value for the new_oci_ref parameter. You should be consistent in how you supply this value. Updating actors that were started from OCI references should continue to have OCI references, while those started from non-OCI sources should not be given new, arbitrary OCI references. Failing to keep this consistent could cause unforeseen failed attempts at subsequent updates.
• If the new version of the actor is actually in an OCI registry, then the preferred method of performing a live update is to do so through the lattice control interface and specifying the OCI URL. This method is less error-prone and can cause less confusion over time.

pub async fn stop_provider(
    &self,
    provider_ref: &str,
    contract_id: &str,
    link: Option<String>
) -> Result<()>

Stops a running capability provider. This call will not fail if the indicated provider is not currently running. This call is non-blocking and does not wait for the provider to finish cleaning up its resources before returning.

Arguments

• provider_ref - The capability provider’s public key or OCI reference URL
• contract_id - The contract ID of the provider to stop
• link - The link name used by the instance of the capability provider

pub async fn actors(&self) -> Result<Vec<String>>

Retrieves the list of all actors within this host. This function call does not include any actors remotely running in a connected lattice.

pub async fn providers(&self) -> Result<Vec<(String, String, String)>>

Retrieves the list of the uniquely identifying information about all capability providers running in the host. This function does not include any capability providers that may be remotely running in a connected lattice. The return value is a vector of 3-tuples (provider_public_key, contract_id, link_name)

pub async fn get_actor_identity(
    &self,
    actor_id: &str
) -> Result<(Option<String>, String, i32)>

Retrieves human-friendly identity information for a provider Return value is (image_reference, name, revision)

Arguments

• actor_id - The public key of the actor.

pub async fn get_provider_identity(
    &self,
    provider_id: &str,
    link_name: Option<String>
) -> Result<(Option<String>, String, i32)>

Retrieves human-friendly identity information for a provider Return value is (image_reference, name, revision)

Arguments

• provider_id - The public key of the provider.
• link_name - The link name used by the instance of the capability provider. If no link_name is provided, the value “default” will be used

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

Perform a raw waPC-style invocation on the given actor by supplying an operation string and a payload of raw bytes, resulting in a payload of raw response bytes. It is entirely up to the actor as to how it responds to unrecognized operations. This operation will also be checked against the authorization system if a custom authorization plugin has been supplied to this host. This call will fail if you attempt to invoke a non-existent actor or call alias or the target actor cannot be reached.

Arguments

• actor - The public key of the actor or its call alias if applicable.
• operation - The name of the operation to perform
• msg - The raw bytes containing the payload pertaining to this operation.

pub async fn set_link(
    &self,
    actor: &str,
    contract_id: &str,
    link_name: Option<String>,
    provider_id: String,
    values: HashMap<String, String>
) -> Result<()>

Links are a first-class, durable entity within a lattice and host runtime. A link defines a set of configuration values that apply to an actor and a capability provider that is uniquely keyed by the provider’s contract ID, public key, and link name.

You can set a link before or after either the actor or provider are started. Links are automatically established when both parties are present in a lattice, and re-established if a party temporarily leaves the lattice and rejoins (which can happen during a crash or a network partition event). The resiliency and reliability of link definitions within a lattice are inherited from your choice of lattice cache provider.

Arguments

• actor - Can either be the actor’s public key or an OCI reference URL.
• contract_id - The contract ID of the link, e.g. wasmcloud:httpserver.
• link_name - The link name of the capability provider when it was loaded.
• provider_id - The public key of the capability provider (e.g. Vxxxx)
• values - The set of configuration values to give to the capability provider for this link definition.

pub async fn remove_link(
    &self,
    actor: &str,
    contract_id: &str,
    link_name: Option<String>
) -> Result<()>

Removes a link definition from the host (and accompanying lattice if connected). This will remove the link definition from the lattice cache and it will also invoke the “remove actor” operation on all affected capability providers, giving those providers an opportunity to clean up resources and terminate any child processes associated with the actor. This call does not wait for all providers to finish cleaning up associated resources.

Arguments

• actor - The public key of the actor. You cannot supply an OCI reference when removing a link.
• contract_id - The contract ID of the capability in question.
• link_name - The name of the link used by the capability provider for which the link is to be removed.

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

Apply a number of declarations from a manifest file to the runtime host. A manifest file can contain a list of actors, capability providers, custom labels, and link definitions that will be added to a host upon application. Manifest application is not idempotent, so repeated application of multiple manifests will almost certainly not result in the same host state.

pub async fn actor_claims(&self) -> Result<Vec<Claims<Actor>>>

Retrieves the list of all actor claims known to this host. Note that this list is essentially a grow-only map maintained by the distributed lattice cache. As a result, the return value of this function contains a list of all claims as seen since the lattice began. It is quite likely that this list can contain references to actors that are no longer in the lattice. When the host is operating in single-player mode, this list naturally only indicates actors that have been started since the host was initialized.

pub async fn labels(&self) -> HashMap<String, String>

Retrieves the list of host labels. Some of these labels are automatically populated by the host at start-time, such as OS family and CPU, and others are manually supplied to the host at build-time or through a manifest to define custom scheduling rules.

pub async fn link_definitions(&self) -> Result<Vec<LinkDefinition>>

Retrieves the list of link definitions as known by the distributed lattice cache. If the host is in single-player mode, this cache is limited to just that host. In lattice mode, this cache reflects all of the current link definitions.

pub async fn oci_references(&self) -> Result<HashMap<String, String>>

Obtains the list of all known OCI references. As with other lattice cache data, this can be thought of as a grow-only map that can contain references for actors or providers that may no longer be present within a lattice or host. The returned map’s key is the OCI reference URL of the entity, and the value is the public key of that entity, where Mxxx are actors and Vxxx are capability providers.