Struct wasmcloud_control_interface::client::Client
source · pub struct Client {
pub lattice: String,
/* private fields */
}
Expand description
Lattice control interface client
Fields§
§lattice: String
Lattice prefix
Implementations§
source§impl Client
impl Client
sourcepub fn nats_client(&self) -> Client
pub fn nats_client(&self) -> Client
Get a copy of the NATS client in use by this control client
source§impl Client
impl Client
sourcepub fn new(nc: Client) -> Client
pub fn new(nc: Client) -> Client
Convenience method for creating a new client with all default settings. This is the same as
calling ClientBuilder::new(nc).build()
sourcepub async fn get_hosts(
&self
) -> Result<Vec<CtlResponse<Host>>, Box<dyn Error + Send + Sync>>
pub async fn get_hosts( &self ) -> Result<Vec<CtlResponse<Host>>, Box<dyn Error + Send + Sync>>
Queries the lattice for all responsive hosts, waiting for the full period specified by timeout.
sourcepub async fn get_host_inventory(
&self,
host_id: &str
) -> Result<CtlResponse<HostInventory>, Box<dyn Error + Send + Sync>>
pub async fn get_host_inventory( &self, host_id: &str ) -> Result<CtlResponse<HostInventory>, Box<dyn Error + Send + Sync>>
Retrieves the contents of a running host
sourcepub async fn get_claims(
&self
) -> Result<CtlResponse<Vec<HashMap<String, String>>>, Box<dyn Error + Send + Sync>>
pub async fn get_claims( &self ) -> Result<CtlResponse<Vec<HashMap<String, String>>>, Box<dyn Error + Send + Sync>>
Retrieves the full set of all cached claims in the lattice.
sourcepub async fn perform_component_auction(
&self,
component_ref: &str,
component_id: &str,
constraints: HashMap<String, String>
) -> Result<Vec<CtlResponse<ComponentAuctionAck>>, Box<dyn Error + Send + Sync>>
pub async fn perform_component_auction( &self, component_ref: &str, component_id: &str, constraints: HashMap<String, String> ) -> Result<Vec<CtlResponse<ComponentAuctionAck>>, Box<dyn Error + Send + Sync>>
Performs an component auction within the lattice, publishing a set of constraints and the metadata for the component 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 component. Clients cannot assume that auctions will always return at least one result.
sourcepub async fn perform_provider_auction(
&self,
provider_ref: &str,
provider_id: &str,
constraints: HashMap<String, String>
) -> Result<Vec<CtlResponse<ProviderAuctionAck>>, Box<dyn Error + Send + Sync>>
pub async fn perform_provider_auction( &self, provider_ref: &str, provider_id: &str, constraints: HashMap<String, String> ) -> Result<Vec<CtlResponse<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.
sourcepub async fn scale_component(
&self,
host_id: &str,
component_ref: &str,
component_id: &str,
max_instances: u32,
annotations: Option<HashMap<String, String>>,
config: Vec<String>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn scale_component( &self, host_id: &str, component_ref: &str, component_id: &str, max_instances: u32, annotations: Option<HashMap<String, String>>, config: Vec<String> ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Sends a request to the given host to scale a given component. This returns an acknowledgement of receipt of the command, not a confirmation that the component 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 component command prior to fetching the component’s OCI bytes. If a client needs deterministic results as to whether the component completed its startup process, the client will have to monitor the appropriate event in the control event stream
§Arguments
host_id
: The ID of the host to scale the component on
component_ref
: The OCI reference of the component to scale
max_instances
: The maximum number of instances this component can run concurrently. Specifying 0
will stop the component.
annotations
: Optional annotations to apply to the component
sourcepub async fn put_registries(
&self,
registries: HashMap<String, RegistryCredential>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn put_registries( &self, registries: HashMap<String, RegistryCredential> ) -> Result<CtlResponse<()>, 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
§Arguments
registries
: A map of registry names to their credentials to be used for fetching from specific registries
sourcepub async fn put_link(
&self,
link: InterfaceLinkDefinition
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn put_link( &self, link: InterfaceLinkDefinition ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Puts a link into the lattice. Returns an error if it was unable to put the link
sourcepub async fn delete_link(
&self,
source_id: &str,
link_name: &str,
wit_namespace: &str,
wit_package: &str
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn delete_link( &self, source_id: &str, link_name: &str, wit_namespace: &str, wit_package: &str ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Deletes a link from the lattice metadata keyvalue bucket. Returns an error if it was unable to delete. This is an idempotent operation.
sourcepub async fn get_links(
&self
) -> Result<CtlResponse<Vec<InterfaceLinkDefinition>>, Box<dyn Error + Send + Sync>>
pub async fn get_links( &self ) -> Result<CtlResponse<Vec<InterfaceLinkDefinition>>, Box<dyn Error + Send + Sync>>
Retrieves the list of link definitions stored in the lattice metadata key-value bucket. If the client was created with caching, this will return the cached list of links. Otherwise, it will query the bucket for the list of links.
sourcepub async fn put_config(
&self,
config_name: &str,
config: impl Into<HashMap<String, String>>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn put_config( &self, config_name: &str, config: impl Into<HashMap<String, String>> ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Puts a named config, replacing any data that is already present.
Config names must be valid NATS subject strings and not contain any .
or >
characters.
sourcepub async fn delete_config(
&self,
config_name: &str
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn delete_config( &self, config_name: &str ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Delete the named config item.
Config names must be valid NATS subject strings and not contain any .
or >
characters.
sourcepub async fn get_config(
&self,
config_name: &str
) -> Result<CtlResponse<HashMap<String, String>>, Box<dyn Error + Send + Sync>>
pub async fn get_config( &self, config_name: &str ) -> Result<CtlResponse<HashMap<String, String>>, Box<dyn Error + Send + Sync>>
Get the named config item.
§Arguments
config_name
: The name of the config to fetch. Config names must be valid NATS subject strings and not contain any.
or>
characters.
§Returns
A map of key-value pairs representing the contents of the config item. This response is wrapped in the CtlResponse type. If
the config item does not exist, the host will return a CtlResponse with a success
field set to true
and a response
field
set to Option::None. If the config item exists, the host will return a CtlResponse with a success
field set to true
and a
response
field set to Option::Some containing the key-value pairs of the config item.
§Example Usage
let client = wasmcloud_control_interface::Client::new(async_nats::connect("127.0.0.1:4222")).await.unwrap("should connect to NATS");
client.put_config("foo", HashMap::from_iter(vec![("key".to_string(), "value".to_string())])).await.expect("should be able to put config");
let config = client.get_config("foo").await.expect("should be able to get config");
assert!(config.success);
assert_eq!(config.response, Some(HashMap::from_iter(vec![("key".to_string(), "value".to_string())]))
// Note that the host will return a success response even if the config item does not exist.
// Errors are reserved for communication problems with the host or with the config store.
let absent_config = client.get_config("bar").await.expect("should be able to get config");
assert!(absent_config.success);
assert_eq!(absent_config.response, None);
sourcepub async fn put_label(
&self,
host_id: &str,
key: &str,
value: &str
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn put_label( &self, host_id: &str, key: &str, value: &str ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Put a new (or update an existing) label on the given host.
§Errors
Will return an error if there is a communication problem with the host
sourcepub async fn delete_label(
&self,
host_id: &str,
key: &str
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn delete_label( &self, host_id: &str, key: &str ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Removes a label from the given host.
§Errors
Will return an error if there is a communication problem with the host
sourcepub async fn update_component(
&self,
host_id: &str,
existing_component_id: &str,
new_component_ref: &str,
annotations: Option<HashMap<String, String>>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn update_component( &self, host_id: &str, existing_component_id: &str, new_component_ref: &str, annotations: Option<HashMap<String, String>> ) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
Issue a command to a host instructing that it replace an existing component (indicated by its public key) with a new component indicated by an OCI image reference. The host will acknowledge this request as soon as it verifies that the target component is running. This acknowledgement occurs before the new bytes are downloaded. Live-updating an component 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 component 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
sourcepub async fn start_provider(
&self,
host_id: &str,
provider_ref: &str,
provider_id: &str,
annotations: Option<HashMap<String, String>>,
provider_configuration: Vec<String>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn start_provider( &self, host_id: &str, provider_ref: &str, provider_id: &str, annotations: Option<HashMap<String, String>>, provider_configuration: Vec<String> ) -> Result<CtlResponse<()>, 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.
The provider_configuration
parameter is a list of named configs to use for this provider. It is not required to specify a config.
sourcepub async fn stop_provider(
&self,
host_id: &str,
provider_id: &str
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn stop_provider( &self, host_id: &str, provider_id: &str ) -> Result<CtlResponse<()>, 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
sourcepub async fn stop_host(
&self,
host_id: &str,
timeout_ms: Option<u64>
) -> Result<CtlResponse<()>, Box<dyn Error + Send + Sync>>
pub async fn stop_host( &self, host_id: &str, timeout_ms: Option<u64> ) -> Result<CtlResponse<()>, 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
sourcepub async fn events_receiver(
&self,
event_types: Vec<String>
) -> Result<Receiver<Event>, Box<dyn Error + Send + Sync>>
pub async fn events_receiver( &self, event_types: Vec<String> ) -> Result<Receiver<Event>, Box<dyn Error + Send + Sync>>
Returns the receiver end of a channel that subscribes to the lattice event stream.
Any Event
s 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)
.timeout(std::time::Duration::from_millis(1000))
.auction_timeout(std::time::Duration::from_millis(1000))
.build();
let mut receiver = client.events_receiver(vec!["component_scaled".to_string()]).await.unwrap();
while let Some(evt) = receiver.recv().await {
println!("Event received: {:?}", evt);
}
};