Struct wasmcloud_control_interface::Client

pub struct Client { /* private fields */ }

Lattice control interface client

Implementations

impl Client

pub fn new( nc: Client, ns_prefix: Option<String>, timeout: Duration, auction_timeout: Duration ) -> Self

👎Deprecated since 0.23.0: please use the client builder instead

Creates a new lattice control interface client. You should use ClientBuilder::new instead. This function will also not attempt to communicate with a key-value store containing the lattice metadata and will only ever use the deprecated methods of host/lattice interaction

pub fn new_with_topic_prefix( nc: Client, topic_prefix: &str, ns_prefix: Option<String>, timeout: Duration, auction_timeout: Duration ) -> Self

👎Deprecated since 0.23.0: please use the client builder instead

Creates a new lattice control interface client with a control interface topic prefix. You should use ClientBuilder::new instead. This function will also not attempt to communicate with a key-value store containing the lattice metadata and will only ever use the deprecated methods of host/lattice interaction

pub async fn get_hosts(&self) -> Result<Vec<Host>, Box<dyn Error + Send + Sync>>

Queries the lattice for all responsive hosts, waiting for the full period specified by timeout.

pub async fn get_host_inventory( &self, host_id: &str ) -> Result<HostInventory, Box<dyn Error + Send + Sync>>

Retrieves the contents of a running host

pub async fn get_claims( &self ) -> Result<GetClaimsResponse, Box<dyn Error + Send + Sync>>

Retrieves the full set of all cached claims in the lattice. If a suitable key-value bucket for metadata was discovered at client creation time, then that bucket will be queried directly for the claims. If not, then the claims will be queried by issuing a request on a queue-subscribed topic to the listening hosts.

pub async fn perform_actor_auction( &self, actor_ref: &str, constraints: HashMap<String, String> ) -> Result<Vec<ActorAuctionAck>, Box<dyn Error + Send + Sync>>

Performs an actor auction within the lattice, publishing a set of constraints and the metadata for the actor in question. This will always wait for the full period specified by duration, and then return the set of gathered results. It is then up to the client to choose from among the “auction winners” to issue the appropriate command to start an actor. Clients cannot assume that auctions will always return at least one result.

pub async fn perform_provider_auction( &self, provider_ref: &str, link_name: &str, constraints: HashMap<String, String> ) -> Result<Vec<ProviderAuctionAck>, Box<dyn Error + Send + Sync>>

Performs a provider auction within the lattice, publishing a set of constraints and the metadata for the provider in question. This will always wait for the full period specified by duration, and then return the set of gathered results. It is then up to the client to choose from among the “auction winners” and issue the appropriate command to start a provider. Clients cannot assume that auctions will always return at least one result.

pub async fn start_actor( &self, host_id: &str, actor_ref: &str, count: u16, annotations: Option<HashMap<String, String>> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Sends a request to the given host to start a given actor by its OCI reference. This returns an acknowledgement of receipt of the command, not a confirmation that the actor started. An acknowledgement will either indicate some form of validation failure, or, if no failure occurs, the receipt of the command. To avoid blocking consumers, wasmCloud hosts will acknowledge the start actor command prior to fetching the actor’s OCI bytes. If a client needs deterministic results as to whether the actor completed its startup process, the client will have to monitor the appropriate event in the control event stream

pub async fn scale_actor( &self, host_id: &str, actor_ref: &str, actor_id: &str, count: u16, annotations: Option<HashMap<String, String>> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Sends a request to the given host to scale a given actor. This returns an acknowledgement of receipt of the command, not a confirmation that the actor scaled. An acknowledgement will either indicate some form of validation failure, or, if no failure occurs, the receipt of the command. To avoid blocking consumers, wasmCloud hosts will acknowledge the scale actor command prior to fetching the actor’s OCI bytes. If a client needs deterministic results as to whether the actor completed its startup process, the client will have to monitor the appropriate event in the control event stream

pub async fn put_registries( &self, registries: RegistryCredentialMap ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes a registry credential map to the control interface of the lattice. All hosts will be listening and all will overwrite their registry credential map with the new information. It is highly recommended you use TLS connections with NATS and isolate the control interface credentials when using this function in production as the data contains secrets

pub async fn advertise_link( &self, actor_id: &str, provider_id: &str, contract_id: &str, link_name: &str, values: HashMap<String, String> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

If a key-value bucket was discovered at client construction time, then the link data will be written directly to the bucket and interested parties will be notified indirectly by virtue of key subscription/monitoring. If no bucket was discovered, then the “old” behavior will be performed of publishing the link data on the appropriate topic.

pub async fn remove_link( &self, actor_id: &str, contract_id: &str, link_name: &str ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

If a key-value bucket is being used, then the link definition will be removed from that bucket directly. If not, then this function will fall back to publishing a link definition removal request on the right lattice control interface topic.

pub async fn query_links( &self ) -> Result<LinkDefinitionList, Box<dyn Error + Send + Sync>>

Retrieves the list of link definitions stored in the lattice metadata key-value bucket. If no such bucket was discovered at client creation time, then it will issue a “legacy” request on the appropriate topic to request link definitions from the first host that answers that request.

pub async fn update_actor( &self, host_id: &str, existing_actor_id: &str, new_actor_ref: &str, annotations: Option<HashMap<String, String>> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Issue a command to a host instructing that it replace an existing actor (indicated by its public key) with a new actor indicated by an OCI image reference. The host will acknowledge this request as soon as it verifies that the target actor is running. This acknowledgement occurs before the new bytes are downloaded. Live-updating an actor can take a long time and control clients cannot block waiting for a reply that could come several seconds later. If you need to verify that the actor has been updated, you will want to set up a listener for the appropriate PublishedEvent which will be published on the control events channel in JSON

pub async fn start_provider( &self, host_id: &str, provider_ref: &str, link_name: Option<String>, annotations: Option<HashMap<String, String>>, provider_configuration: Option<String> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Issues a command to a host to start a provider with a given OCI reference using the specified link name (or “default” if none is specified). The target wasmCloud host will acknowledge the receipt of this command before downloading the provider’s bytes from the OCI registry, indicating either a validation failure or success. If a client needs deterministic guarantees that the provider has completed its startup process, such a client needs to monitor the control event stream for the appropriate event. If a host ID is not supplied (empty string), then this function will return an early acknowledgement, go find a host, and then submit the start request to a target host.

pub async fn stop_provider( &self, host_id: &str, provider_ref: &str, link_name: &str, contract_id: &str, annotations: Option<HashMap<String, String>> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Issues a command to a host to stop a provider for the given OCI reference, link name, and contract ID. The target wasmCloud host will acknowledge the receipt of this command, and will not supply a discrete confirmation that a provider has terminated. For that kind of information, the client must also monitor the control event stream

pub async fn stop_actor( &self, host_id: &str, actor_ref: &str, count: u16, annotations: Option<HashMap<String, String>> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Issues a command to a host to stop an actor for the given OCI reference. The target wasmCloud host will acknowledge the receipt of this command, and will not supply a discrete confirmation that the actor has terminated. For that kind of information, the client must also monitor the control event stream

pub async fn stop_host( &self, host_id: &str, timeout_ms: Option<u64> ) -> Result<CtlOperationAck, Box<dyn Error + Send + Sync>>

Issues a command to a specific host to perform a graceful termination. The target host will acknowledge receipt of the command before it attempts a shutdown. To deterministically verify that the host is down, a client should monitor for the “host stopped” event or passively detect the host down by way of a lack of heartbeat receipts

pub async fn events_receiver( &self ) -> Result<Receiver<Event>, Box<dyn Error + Send + Sync>>

Returns the receiver end of a channel that subscribes to the lattice control event stream. Any Events that are published after this channel is created will be added to the receiver channel’s buffer, which can be observed or handled if needed. See the example for how you could use this receiver to handle events.

Example

use wasmcloud_control_interface::{Client, ClientBuilder};
async {
  let nc = async_nats::connect("127.0.0.1:4222").await.unwrap();
  let client = ClientBuilder::new(nc)
                .rpc_timeout(std::time::Duration::from_millis(1000))
                .auction_timeout(std::time::Duration::from_millis(1000))
                .build().await.unwrap();
  let mut receiver = client.events_receiver().await.unwrap();
  tokio::spawn( async move {
      while let Some(evt) = receiver.recv().await {
          println!("Event received: {:?}", evt);
      }
  });
  // perform other operations on client
  client.get_host_inventory("NAEXHW...").await.unwrap();
};

Once you’re finished with the event receiver, be sure to call drop with the receiver as an argument. This closes the channel and will prevent the sender from endlessly sending messages into the channel buffer.

Example

use wasmcloud_control_interface::{Client, ClientBuilder};
async {
  let nc = async_nats::connect("0.0.0.0:4222").await.unwrap();
  let client = ClientBuilder::new(nc)
                .rpc_timeout(std::time::Duration::from_millis(1000))
                .auction_timeout(std::time::Duration::from_millis(1000))
                .build().await.unwrap();    
  let mut receiver = client.events_receiver().await.unwrap();
  // read the docs for flume receiver. You can use it in either sync or async code
  // The receiver can be cloned() as needed.
  // If you drop the receiver. The subscriber will exit
  // If the nats connection ic closed, the loop below will exit.
  while let Some(evt) = receiver.recv().await {
      println!("Event received: {:?}", evt);
  }
};

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.