Control Interface

The lattice control interface provides a way for clients to interact with the lattice to issue control commands and queries. This interface is a message broker protocol that supports functionality like starting and stopping actors and providers, declaring link definitions, performing function calls on actors, monitoring lattice events, holding auctions to determine scheduling compatibility, and much more.

The core message broker protocol can be used by any client capable of connecting to NATS. There is also a Rust crate that provides a convenient API for accessing the control interface. Please see the Rust documentation for the crate on how to use the Rust API.

The following is a list of the operations supported by the control interface.

NATS Control Interface

All of the control interface messages published on NATS topics use a standard prefix. This prefix is wasmbus.ctl.{namespace} where namespace is a string used to differentiate one lattice from another. Note that this namespace must correspond to the namespace prefix of the lattice you intend to control.

⚠️ You must ensure that your namespace prefix is alphanumeric and does not the contain / or . or > characters, as those have special meaning to the NATS message broker.

All control interface messages are serialized as message pack payloads that conform to the schema found in the wasmcloud-control-interface repository.

TopicTypeDescription
{pre}.auction.providerReqHold an auction for starting a provider
{pre}.auction.actorReqHold an auction for starting an actor
{pre}.cmd.{host}.laReqTell a host to start (launch) an actor
{pre}.cmd.{host}.saReqTell a host to stop an actor
{pre}.cmd.{host}.lpReqTell host to launch provider
{pre}.cmd.{host}.spReqTell host to stop provider
{pre}.cmd.{host}.updReqTell host to live-update actor
{pre}.get.linksReqQuery link definition list
{pre}.get.claimsReqQuery claims cache
{pre}.get.{host}.invReqQuery host running inventory
{pre}.get.hostsCollCollect list of all running hosts

Operations of type Sub are subscribe-only. A lattice control interface client may subscribe to this event stream, but should never publish to it. A good security scenario is to have a different set of lattice connection credentials for the wasmcloud host than you use for the control client. This allows you to prevent the control client from publishing to potentially dangerous topics.

Operations of type Req are requests that receive replies. These replies may be simple acknowledgements and may not directly indicate completion of work.

Operations of type Coll are collect or scatter-gather operations that issue a request on a subject and then wait for some given period of time to collect responses. Use caution with collect/gather operations because if you do not wait long enough, you may receive incomplete responses.

Lattice Events

As of v0.19.x, lattice events will be published on the stream wasmbus.evt.{namespace} where namespace is the lattice namespace prefix. Unlike control messages, lattice events are published as JSON for convenience and ease of monitoring. For a list of all of the enum variants for lattice events, refer to the events module in the wasmcloud-control-interface crate.