[Tracking Issue] Convert Cosmos to Pipeline Architecture

[rylev]

This is a tracking issue for converting operations over to the pipeline architecture. There are some sub issues for converting individual SDK crates over, but this issue acts as a guide for how to switch to the new architecture.

Overview

Previous to the pipeline architecture, each operation was independently controlled meaning there was no central way to control the way operations were performed.

The pipeline architecture on the other hand allows users of the SDK to create pipelines through which outgoing requests and incoming responses are processed. The pipeline are composed of "policies" which can both change the outgoing request and the incoming response. Policies are usually either on a "per-request" basis (meaning they are called only once per operation) or "per-retry" (meaning they are applied every time an operation is attempted).

Examples of policies are the TelemetryPolicy which adds various telemetry headers to the request and the retry policy which checks whether an incoming response was successful and if it detects a transient failure, retries the request.

Converting to the Architecture

For an example of converting one operation (Cosmos's get_database operation) over to the pipeline architecture, take a look at #286.

The basic steps are:

• Create a new submodule of the operations module where the operation will live. This submodule should be named after the operation (e.g., for get_database it's called get_database).
• Move the "request builder" (e.g., for get_database the GetDatabaseBuilder) to new operation submodule and rename it from Builder to Options (e.g., GetDatabaseBuilder => GetDatabaseOptions`). This now represents the options that can be supplied when performing the operation. Note that many options that were part of the builder are no longer valid options because there will be individual policies that take their place. For instance, previously many operations took an option to set the user agent. This is now done by a policy.
• Change the execute method to a decorate_request method that instead of performing the request, simply mutates a request parameter with any of the options supplied.
• Move the associated response type (e.g., for get_database the GetDatabaseResponse type from the responses submodule to the operation submodule. Previously a std::convert::TryFrom implementation was used to convert from an http::Response<Bytes> object. This should now be a plain associated async function called try_from that converts from the new Response type. See the example for how this should be done.
• Finally, convert the appropriate method on the appropriate client (e.g., for get_database this was the DatabaseClient::get_database) to use the new options and response types with the pipeline. Again, see the example for how this should be done.

Todos

• Attachments
  • delete_attachment
  • get_attachment
  • list_attachments
• Collections
  • create_collection
  • delete_collection
  • get_collection
  • list_collections
  • replace_collection
• Databases
  • create_database
  • delete_database
  • list_databases
  • get_database
• Documents
  • create_document
  • delete_document
  • get_document
  • replace_document
  • list_documents
  • query_documents
• Partition Key Ranges
  • get_partition_key_ranges
• Permissions
  • create_permission
  • delete_permission
  • get_permission
  • replace_permission
  • list_permissions
• Reference Attachments
  • create_reference_attachment
  • replace_reference_attachment
• Slug Attachments
  • create_slug_attachment
  • create_stored_procedure
  • delete_stored_procedure
  • execute_stored_procedure
  • replace_stored_procedure
• Stored Prodedures
  • list_stored_procedures
• Triggers
  • create_trigger
  • delete_trigger
  • list_triggers
• Users
  • create_user
  • delete_user
  • get_user
  • replace_user
• User Defined Functions
  • create_user_defined_function
  • delete_user_defined_function
  • list_user_defined_functions
  • list_users

[yoshuawuyts]

• delete_document has been started in [Cosmos] Change delete_document to pipeline architecture #322
• delete_user and list_users has been started in Move delete_user and list_users to pipeline architecture #346

[JoshGendein]

I'll pick up create_permission, get_permission, replace_permission, and delete_permission

[eholk]

I've started working on get_document at https://github.com/eholk/azure-sdk-for-rust/tree/cosmos-get-document.

[nalshihabi]

I have started working on create_stored_procedure delete_stored_procedure execute_stored_procedure. Also, I think some of these stored procedures related methods are incorrectly listed under Slug Attachments.

[JoshGendein]

I'll start on get_collection and delete_collection.

EDIT: Also replace_collection which it looks like isn't in the list above.

[jddarby]

I have started get_attachment in #375. First time contributing so let me know if I've missed anything.

[thovoll]

@rylev is this issue meant for CosmosDB only?

[cataggar]

#677 claimed to complete this 🥳