Crate wasmcloud_host[−][src]

wasmCloud Host

wasmCloud is a platform for writing portable business logic that can run anywhere from the edge to the cloud, that boasts a secure-by-default, boilerplate-free developer experience with rapid feedback loop.

The wasmCloud team believes that we can not only change the way developers build software for the better, but make it easier to secure, deploy, maintain, observe, and upgrade that software as well–all while reducing the amount of boilerplate we have to copy and paste.

wasmCloud is designed around the following core tenets:

Productivity - Developer and Operations
Enterprise-grade Security
Cost Savings
Portability
Performance

You should not have to change your design, architecture, or your programming environment as you move from concept to production. wasmCloud aims to bring joy to distributed systems development without sacrificing enterprise-grade features.

Actors

wasmCloud’s actors are designed in the spirit of the actor model, though some of the implementation details may differ from what people might expect from certain actor runtimes. A wasmCloud actor is a single-threaded, portable unit of compute and deployment.

Our actors also contain cryptographically signed JSON Web Tokens (JWT) that assert via claims the list of capabilities to which any given actor has been granted access. For more information, check out our security documentation.

Capabilities

Actors, by virtue of being freestanding (non-WASI) WebAssembly modules, cannot interact with the operating system nor can they perform I/O of any kind. As such, if an actor wants to do anything other than perform pure calculations, it must do so by virtue of a capability provider, a dynamic plugin loaded by the wasmCloud host runtime that is made available for secure dispatch to and from an actor.

Using the Host API

This crate provides the primary API for interacting with the host runtime. If you are purely interested in using a “stock” binary to run your actor workloads and communicate with capability providers using standard features, then you should use the wasmCloud binary available for installation.

If, on the other hand, you are interested in providing a custom host runtime of your own that utilizes the wasmCloud host API as a platform, then this crate is what you’ll need.

To start a runtime, simply build a host and then add actors, capabilities, and link definitions to it. For more information, take a look at the documentation and tutorials at wasmcloud.dev.

Host API Example

The following example creates a new wasmCloud host in the default standalone (no lattice/single-player) mode. It then loads an actor that echoes back incoming HTTP requests as a JSON object in the body of the outbound HTTP response.

The HTTP server capability provider is loaded so that the actor can receive web requests. A link definition is required between the HTTP server capability provider and the actor in order to verify actor privileges and supply configuration values (such as the port on which to listen). This link definition can be established before or after the actor and capability provider have been started, as link definitions are first-class data cached throughout a lattice.

use wasmcloud_host::{HostBuilder, Actor, NativeCapability};
use std::collections::HashMap;
use std::error::Error;
use std::time::Duration;
use actix_rt::time::sleep;
use reqwest;

const WEB_PORT: u32 = 8080;

#[actix_rt::main]
async fn main() -> Result<(), Box<dyn Error + Sync +Send>> {
    let h = HostBuilder::new().build();
    h.start().await?;
    let echo = Actor::from_file("../../tests/modules/echo.wasm")?;
    let actor_id = echo.public_key();
    h.start_actor(echo).await?;

    // Read a cross-platform provider archive file
    let arc = par_from_file("../../tests/modules/httpserver.par.gz")?;
    let websrv = NativeCapability::from_archive(&arc, None)?;
    let websrv_id = websrv.id();

    let mut webvalues: HashMap<String, String> = HashMap::new();
    webvalues.insert("PORT".to_string(), format!("{}", WEB_PORT));
     
    // Establish a link between the actor and a capability provider
    h.set_link(
        &actor_id,
        "wasmcloud:httpserver",
        None,
        websrv_id,
        webvalues,
    )
    .await?;
    // Start the web server provider (which auto-establishes the link)
    h.start_native_capability(websrv).await?;
    // Let the web server start
    sleep(Duration::from_millis(500)).await;
    let url = format!("http://localhost:{}/demo?test=kthxbye", WEB_PORT);

    let resp = reqwest::get(&url).await?;
    assert!(resp.status().is_success());
    let v: serde_json::Value = serde_json::from_slice(&resp.bytes().await?)?;
    assert_eq!("test=kthxbye", v["query_string"].as_str().unwrap());

    Ok(())
}

Structs

Host	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.
HostBuilder	A host builder provides a convenient, fluid syntax for setting initial configuration and tuning parameters for a wasmCloud host
HostManifest	A host manifest contains a declarative profile of the host’s desired state. The manifest can specify custom labels, a list of actors, a list of capability providers, and a list of link definitions. Environment substitution syntax can optionally be used within a manifest file so that information that may change across environments (like public keys) can change without requiring the manifest file to change.
NativeCapability	Represents a native capability provider compiled as a shared object library. These plugins are OS- and architecture-specific, so they will be `.so` files on Linux, `.dylib` files on macOS, `.dll` files on Windows, etc.
WasmCloudActor	An actor is a WebAssembly module that conforms to the wasmCloud protocols and can securely consume capabilities exposed by capability providers.

Traits

Authorizer

An authorizer is responsible for determining whether an actor can be loaded as well as whether an actor can invoke another entity. For invocation checks, the authorizer is only ever invoked after an initial capability attestation check has been performed and passed. This has the net effect of making it impossible to override the base behavior of checking that an actor’s embedded JWT contains the right capability attestations.

Type Definitions

Actor	Type alias used to disambiguate between wasmCloud actors and Actix actors
Result	Result type used for function calls within this library

Crate wasmcloud_host⎘[−][src]

Crate wasmcloud_host[−][src]