Struct Client

pub struct Client<C, M, R = Standard> { /* private fields */ }

An ergonomic service client for DocktorApi.

This client allows ergonomic access to a DocktorApi-shaped service. Each method corresponds to an endpoint defined in the service’s Smithy model, and the request and response shapes are auto-generated from that same model.

Constructing a Client

To construct a client, you need a few different things:

• A Config that specifies additional configuration required by the service.
• A connector (C) that specifies how HTTP requests are translated into HTTP responses. This will typically be an HTTP client (like hyper), though you can also substitute in your own, like a mock mock connector for testing.
• A “middleware” (M) that modifies requests prior to them being sent to the request. Most commonly, middleware will decide what endpoint the requests should be sent to, as well as perform authentication and authorization of requests (such as SigV4). You can also have middleware that performs request/response tracing, throttling, or other middleware-like tasks.
• A retry policy (R) that dictates the behavior for requests that fail and should (potentially) be retried. The default type is generally what you want, as it implements a well-vetted retry policy implemented in RetryMode::Standard.

To construct a client, you will generally want to call Client::with_config, which takes a aws_smithy_client::Client (a Smithy client that isn’t specialized to a particular service), and a Config. Both of these are constructed using the builder pattern where you first construct a Builder type, then configure it with the necessary parameters, and then call build to construct the finalized output type. The aws_smithy_client::Client builder is re-exported in this crate as Builder for convenience.

In most circumstances, you will want to use the following pattern to construct a client:

use docktor_api_client::{Builder, Client, Config};
let raw_client =
    Builder::dyn_https()
      .middleware(/* discussed below */)
      .build();
let config = Config::builder().build();
let client = Client::with_config(raw_client, config);

For the middleware, you’ll want to use whatever matches the routing, authentication and authorization required by the target service. For example, for the standard AWS SDK which uses SigV4-signed requests, the middleware looks like this:

use aws_endpoint::AwsEndpointStage;
use aws_http::user_agent::UserAgentStage;
use aws_sig_auth::middleware::SigV4SigningStage;
use aws_sig_auth::signer::SigV4Signer;
use aws_smithy_http_tower::map_request::MapRequestLayer;
use tower::layer::util::Stack;
use tower::ServiceBuilder;

type AwsMiddlewareStack =
    Stack<MapRequestLayer<SigV4SigningStage>,
        Stack<MapRequestLayer<UserAgentStage>,
            MapRequestLayer<AwsEndpointStage>>>,

#[derive(Debug, Default)]
pub struct AwsMiddleware;
impl<S> tower::Layer<S> for AwsMiddleware {
    type Service = <AwsMiddlewareStack as tower::Layer<S>>::Service;

    fn layer(&self, inner: S) -> Self::Service {
        let signer = MapRequestLayer::for_mapper(SigV4SigningStage::new(SigV4Signer::new())); _signer: MapRequestLaye
        let endpoint_resolver = MapRequestLayer::for_mapper(AwsEndpointStage); _endpoint_resolver: MapRequestLayer<Aw
        let user_agent = MapRequestLayer::for_mapper(UserAgentStage::new()); _user_agent: MapRequestLayer<UserAgentSt
        // These layers can be considered as occurring in order, that is:
        // 1. Resolve an endpoint
        // 2. Add a user agent
        // 3. Sign
        // (4. Dispatch over the wire)
        ServiceBuilder::new() _ServiceBuilder<Identity>
            .layer(endpoint_resolver) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
            .layer(user_agent) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
            .layer(signer) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
            .service(inner)
    }
}

Using a Client

Once you have a client set up, you can access the service’s endpoints by calling the appropriate method on Client. Each such method returns a request builder for that endpoint, with methods for setting the various fields of the request. Once your request is complete, use the send method to send the request. send returns a future, which you then have to .await to get the service’s response.

Implementations

impl<C, M, R> Client<C, M, R>

pub fn with_config(client: Client<C, M, R>, conf: Config) -> Self

Creates a client with the given service configuration.

pub fn conf(&self) -> &Config

Returns the client’s configuration.

impl<C, M, R> Client<C, M, R>

where C: SmithyConnector, M: SmithyMiddleware<C>, R: NewRequestPolicy,

pub fn healthcheck_operation(&self) -> HealthcheckOperation<C, M, R>

Constructs a fluent builder for the HealthcheckOperation operation.

• The fluent builder takes no input, just send it.
• On success, responds with HealthcheckOperationOutput with field(s):
  • message(Option<String>): (undocumented)
• On failure, responds with SdkError<HealthcheckOperationError>

pub fn list_operation(&self) -> ListOperation<C, M, R>

Constructs a fluent builder for the ListOperation operation.

• The fluent builder takes no input, just send it.
• On success, responds with ListOperationOutput with field(s):
  • primary(Option<String>): Is primary?
  • host(Option<Host>): Host info.
  • resources(Option<Resources>): Host resources.
  • services(Option<Vec<Service>>): List of available services.
  • checksum(Option<String>): Service checksum.
  • available_services(Option<Vec<String>>): List of services runnable by this host
  • peers(Option<HashMap<String, ListOutput>>): Map of peers configurations
• On failure, responds with SdkError<ListOperationError>

pub fn prometheus_target_operation(&self) -> PrometheusTargetOperation<C, M, R>

Constructs a fluent builder for the PrometheusTargetOperation operation.

• The fluent builder takes no input, just send it.
• On success, responds with PrometheusTargetOperationOutput with field(s):
  • targets(Option<Vec<PrometheusTarget>>): List of Prometheus targets.
• On failure, responds with SdkError<PrometheusTargetOperationError>

pub fn restart_operation(&self) -> RestartOperation<C, M, R>

Constructs a fluent builder for the RestartOperation operation.

• The fluent builder is configurable:
  • services(Vec<String>) / set_services(Option<Vec<String>>): Service name.
  • hostname(impl Into<String>) / set_hostname(Option<String>): Hostname.
• On success, responds with RestartOperationOutput with field(s):
  • inner(Option<Vec<SystemdOutputInner>>): Systemd output list.
• On failure, responds with SdkError<RestartOperationError>

pub fn start_operation(&self) -> StartOperation<C, M, R>

Constructs a fluent builder for the StartOperation operation.

• The fluent builder is configurable:
  • services(Vec<String>) / set_services(Option<Vec<String>>): Service name.
  • hostname(impl Into<String>) / set_hostname(Option<String>): Hostname.
• On success, responds with StartOperationOutput with field(s):
  • inner(Option<Vec<SystemdOutputInner>>): Systemd output list.
• On failure, responds with SdkError<StartOperationError>

pub fn stop_operation(&self) -> StopOperation<C, M, R>

Constructs a fluent builder for the StopOperation operation.

• The fluent builder is configurable:
  • services(Vec<String>) / set_services(Option<Vec<String>>): Service name.
  • hostname(impl Into<String>) / set_hostname(Option<String>): Hostname.
• On success, responds with StopOperationOutput with field(s):
  • inner(Option<Vec<SystemdOutputInner>>): Systemd output list.
• On failure, responds with SdkError<StopOperationError>

Trait Implementations

impl<C, M, R> Clone for Client<C, M, R>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Debug, M: Debug, R: Debug> Debug for Client<C, M, R>

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

Formats the value using the given formatter.

impl<C, M, R> From<Client<C, M, R>> for Client<C, M, R>

fn from(client: Client<C, M, R>) -> Self

Converts to this type from the input type.