pass in Pipeline to ClientBuilder

[cataggar]

I did not make Pipeline settable in #527 because I wasn't sure how it should be done in #510. Should it be added to ClientBuilder and Client like this. Would we expect someone to call new_pipeline and then set the retry policies?

[yoshuawuyts]

That's a good question; given we're on track to convert all endpoints to builders, it might make sense for the client to follow a similar pattern. I was hoping that once we have the endpoints in place, we could take a look at the client builders after. But it seems I wasn't the only one thinking of that (:

What is a pipeline? ¹

A "pipeline" in our SDK is an HTTP backend + corresponding middleware ². It's defined as follows:

#[derive(Debug, Clone)]
pub struct Pipeline {
    http_client: Arc<dyn HttpClient>,
    pipeline: Vec<Arc<dyn Policy>>,
}

Pipeline::new creates a new pipeline and sets up default policies. For now this is "telemetry", and "custom headers injector". And depending on the build mode, we can switch out to a "recorder" HTTP backend.

What would usage of our clients look like with this PR?

Policies on the pipeline currently cannot be modified or extended, which is what the PR under discussion attempts to address. Taking CosmosClient as an example again, assuming we would implement this PR as-is, using it to extend the pipeline with a custom policy would be as follows:

let account = std::env::var("COSMOS_ACCOUNT").unwrap();
let master_key = std::env::var("COSMOS_MASTER_KEY").unwrap();
let auth = AuthorizationToken::primary_from_base64(&master_key)?;

// Create a new Cosmos client with a custom policy
let options = CosmosOptions::default();
let mut pipeline = Pipeline::new(
    option_env!("CARGO_PKG_NAME"),
    option_env!("CARGO_PKG_VERSION"),
    ClientOptions::default(),
    vec![],                               // per-call policies
    vec![Arc::new(ExamplePolicy::new())], // per-retry policies
);
let client = CosmosClient::new(account, auth, options, pipeline);

This PR moves the construction of Pipeline into the customer's code, requiring them to handle pipelines in every SDK. The Pipeline::new_pipeline constructor simplifies this somewhat (not shown here; it doesn't take any parameters) -- but when a customer desires to add a custom policy, it definitely is a lot to take in.

An alternative interface for constructing clients

I see the "pipeline" and "options" parameters as mirrors to the interface issues we faced with "context" and "options" in our endpoint constructors. And I believe we should be able to address these in a similar manner. I'd like to propose we consider constructing clients using an API along these lines instead:

let account = std::env::var("COSMOS_ACCOUNT").unwrap();
let master_key = std::env::var("COSMOS_MASTER_KEY").unwrap();
let auth = AuthorizationToken::primary_from_base64(&master_key)?;

// Create a new Cosmos client with a custom policy
let client = CosmosClient::new(account, auth)
    .retry_policy(ExamplePolicy::new());

This would move all CosmosClientOptions optional parameters into a builder, and add two new methods: retry_policy and call_policy which take an impl Policy each. I feel like this would be a more ergonomic experience, with the benefit of having the flexibility to be able to extend the policies.

Footnotes

1. I'm writing this down in part for myself as well, since I haven't really gone through the pipeline code until now. I'm trying to keep this section brief tho (: ↩

2. In the surf http client this would correspond to a Client instance. ↩

[cataggar]

This requires further discussion, so I opened:

• How do we set Pipelines options to a Client? #591.