Closed analogrelay closed 3 weeks ago
Drafting while I add method_options
to our options
Re-un-drafting. I've added a method_options: azure_core::ClientMethodOptions
field to every method options type. Since that type carries an optional Context
, I've also changed all our methods to use that Context
as the base context we add our ResourceLink
value to.
This realizes some recent changes to guidelines regarding options and service method parameters. Specifically:
impl Into
andimpl AsRef
parametersThe options changes were easy and deleted a bunch of unnecessary boilerplate, my favorite! Avoiding the use of
impl
s led to the following exceptions (which I mentioned when we were chatting about the guidelines earlier but will detail again here):impl Into<Query>
is used for APIs that accept a query. Cosmos queries are made up of a query text, and a parameter. Other SDKs, such as the Go SDK, encode the parameters in the options, but I don't feel like that's an accurate modelling. Query parameters appear in the body, and having to merge a parameter with an option to create the body doesn't feel right. We want to support callingcontainer_client.query_items("SELECT * FROM c", ...)
andcontainer_client.query_items(Query::from("SELECT * FROM c WHERE c.id = @id").with_parameter("@id", id), ...)
, so we useimpl Into<Query>
here, and implementFrom<&'static str>
andFrom<String>
onQuery
.impl Into<PartitionKey>
is used on APIs for item CRUD, which require a partition key be specified. Cosmos allows multiple types as partition keys (strings, numbers, booleans) and allows up to 3 levels of hierarchical keys. We want to be able to callcontainer_client.read_item(item_id, "partition1", ...)
, andcontainer_client.read_item(item_id, ("parent_partition", 42, "grandchild_partition"), ...)
. So, we acceptimpl Into<PartitionKey>
and have several implementations (insdk/data/cosmos/azure_data_cosmos/partition_key.rs
) ofFrom
forPartitionKey
Finally,
impl Into<QueryPartitionStrategy>
is used on APIs that query items. Cosmos supports single-partition queries, where the partition key must be specified independent of the query, and cross-partition queries (where no partition key is specified). The Cosmos Rust SDK does not support cross-partition queries at this time but may add that support later. So, we useQueryPartitionStrategy
as an enum that currently only has a single variant (QueryPartitionStrategy::SinglePartition(PartitionKey)
) and haveimpl<T: Into<PartitionKey>> From<T> for QueryPartitionStrategy
which allows the API to accept the same arguments as the CRUD APIs, and a futureQueryPartitionStrategy::CrossPartition
marker to indicate a cross-partition query.I left all those cases above alone, though we can absolutely continue discussions there.
cc @heaths @JeffreyRichter @RickWinter (as FYI for the exceptions pointed out above, though I'm sure we'll do some more formal API reviewing later)