cosmos: Public API Reorganization

[analogrelay]

A pre-API-review tidy pass on azure_data_cosmos. The crate's public surface is reorganized into stable, by-purpose modules (feed, diagnostics, partitioning, response, error, options, models), and the crate root is slimmed to just the names a typical caller is likely to type out (CosmosClient, Query, FeedScope, PartitionKey, TransactionalBatch, …). A handful of long-pending API hygiene items — SafeDebug adoption, fallible-serialization paths returning Result<T>, sharper rustdoc — are folded into the same pass. No behavioral changes; the full lib + doc test suite is green. The 0.35.0 CHANGELOG entry has the canonical per-symbol move map.

Area	Summary
Crate root	Slimmed to the names a customer is likely to type: CosmosClient, CosmosClientBuilder, ContainerClient, DatabaseClient, AccountEndpoint, AccountReference, CosmosCredential, CosmosError, Result, Query, FeedScope, PartitionKey, TransactionalBatch, RoutingStrategy. The pub use options::*; blanket re-export and the three pub use *; blankets inside models/ are replaced with explicit by-symbol lists.
feed (new)	Home for query + feed iteration types. The old query module is removed; Query and FeedScope live here (and remain re-exported at the crate root). FeedPage, QueryFeedPage, QueryItemIterator, QueryPageIterator also live here.
diagnostics (new)	DiagnosticsContext lives here. No longer surfaced via models::*.
partitioning (new)	PartitionKey, PartitionKeyValue, EffectivePartitionKey, PartitionKeyDefinition, PartitionKeyKind, PartitionKeyVersion. Only PartitionKey is re-exported at the crate root.
response (new)	BatchResponse, ItemResponse, ResourceResponse, ResponseBody, ResponseHeaders moved out of models.
error	Now a public module. CosmosStatus and SubStatusCode are reachable here (no longer at the crate root).
options	New home for Region (the regions module is removed), RoutingStrategy (root re-export retained), and the four batch sub-operation *Options types (moved out of transactional_batch). The operation: OperationOptions field on every options type is now pub(crate); callers go through with_operation_options(...).
models	Response wrappers and DiagnosticsContext removed. Module file split into per-type files; mod.rs is a clean re-export shell.
API hygiene	Query::with_text takes impl Into<String>. SafeDebug with #[safe(true)] on ItemResponse, ResourceResponse<T>, BatchResponse, CosmosCredential. Added Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize on ConsistencyLevel and RoutingStrategy (kept hand-written Display). DatabaseProperties::id is now Option<String>.
Error handling	TransactionalBatch::{create_item, upsert_item, replace_item} and TransactionalBatchOperationResult::deserialize_body return azure_data_cosmos::Result<_> (no more raw serde_json::Error). Resource bodies stored as Option<Box<RawValue>> and exposed via resource_body(). read_throughput / begin_replace_throughput no longer panic on a malformed offer — they debug_assert! and return a synthetic CosmosError.
Documentation	Inline doc on TransactionalBatchOperationResult::status_code explaining why it stays u16. Documented on create_database / create_container / replace / begin_replace_throughput that they always return the resource body regardless of ContentResponseOnWrite. CosmosClient rustdoc points at CosmosClient::builder(). README and inline-comment touch-ups.
File organization	feed/mod.rs, models/mod.rs, options/mod.rs split into per-type files. lib.rs, clients/mod.rs, and options/mod.rs reorganized into clearly delimited "Public API" / "Public modules" / "Internal modules" / "Crate-internal re-exports" sections.

[Copilot]

Pull request overview

Reorganizes the azure_data_cosmos crate’s public API into stable, purpose-based modules (e.g., feed, options, partitioning, response, diagnostics), slimming the crate root to a smaller set of common entry points and updating downstream tests/examples/docs to the new paths.

Changes:

• Introduced new public modules (feed, response, diagnostics, partitioning) and moved/re-exported types accordingly.
• Refactored per-request options into options/* submodules and updated call sites (tests/examples) to use azure_data_cosmos::options::....
• Improved API hygiene (e.g., fallible serialization returning crate::Result, SafeDebug adoption, sharper rustdoc) and updated changelog/docs.

Reviewed changes

Copilot reviewed 74 out of 75 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sdk/cosmos/azure_data_cosmos/tests/split_tests/cosmos_split_offers.rs	Updates imports to the new options::CreateContainerOptions path.
sdk/cosmos/azure_data_cosmos/tests/split_tests/cosmos_query_split.rs	Updates query/feed imports to feed::* and options to options::*.
sdk/cosmos/azure_data_cosmos/tests/multi_write_tests/cosmos_multi_write.rs	Migrates Region import to options::Region.
sdk/cosmos/azure_data_cosmos/tests/multi_write_tests/cosmos_multi_write_fault_injection.rs	Moves options imports into options::* module.
sdk/cosmos/azure_data_cosmos/tests/in_memory_emulator_tests/user_agent.rs	Updates Region/UserAgentSuffix imports to options::* and adjusts root imports.
sdk/cosmos/azure_data_cosmos/tests/in_memory_emulator_tests/end_to_end.rs	Updates imports to new module layout and adapts to DatabaseProperties::id: Option<String>.
sdk/cosmos/azure_data_cosmos/tests/framework/test_data.rs	Updates CreateContainerOptions import to options::CreateContainerOptions.
sdk/cosmos/azure_data_cosmos/tests/framework/test_client.rs	Updates imports for FeedScope, Region, ItemResponse, and DiagnosticsContext to new modules; adapts DB id handling.
sdk/cosmos/azure_data_cosmos/tests/framework/mock_account.rs	Updates Region imports to options::Region.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_response_metadata.rs	Switches ResponseHeaders and FeedScope imports to new response/feed modules.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_query.rs	Switches continuation/feed imports to feed::*.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_proxy.rs	Updates Region path to options::Region in routing strategy usage.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_patch.rs	Moves patch options to options and response wrapper import to response.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_offers.rs	Updates CreateContainerOptions import to options.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_items.rs	Moves ItemResponse to response and item/write options to options.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_feed_ranges.rs	Updates CreateContainerOptions import to options.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_databases.rs	Adapts assertions for DatabaseProperties::id: Option<String>.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_containers.rs	Updates PartitionKeyKind import to partitioning and options import to options.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_batch.rs	Moves ContentResponseOnWrite/OperationOptions imports under options.
sdk/cosmos/azure_data_cosmos/src/transactional_batch.rs	Moves batch sub-operation options into options and converts serialization errors to crate::Result.
sdk/cosmos/azure_data_cosmos/src/session_helpers.rs	Updates FeedRange/SessionToken paths and switches status access to error::CosmosStatus.
sdk/cosmos/azure_data_cosmos/src/response/resource_response.rs	Moves response wrappers into new response module and derives SafeDebug.
sdk/cosmos/azure_data_cosmos/src/response/mod.rs	Adds the new response module with public exports and crate-internal bridges.
sdk/cosmos/azure_data_cosmos/src/response/item_response.rs	Moves item response wrapper into response module and derives SafeDebug.
sdk/cosmos/azure_data_cosmos/src/response/headers.rs	Introduces SDK-owned ResponseHeaders wrapper with typed accessors and internal conversion helpers.
sdk/cosmos/azure_data_cosmos/src/response/cosmos_response.rs	Rehomes internal CosmosResponse to the response module and updates doc links.
sdk/cosmos/azure_data_cosmos/src/response/body.rs	Updates intra-doc links to the new response::* paths.
sdk/cosmos/azure_data_cosmos/src/response/batch_response.rs	Moves batch response wrapper into response module and derives SafeDebug.
sdk/cosmos/azure_data_cosmos/src/regions.rs	Removes the deprecated regions module re-export.
sdk/cosmos/azure_data_cosmos/src/region_proximity.rs	Updates Region import to options::Region.
sdk/cosmos/azure_data_cosmos/src/partitioning.rs	Adds partitioning module and re-exports partition key types.
sdk/cosmos/azure_data_cosmos/src/options/throughput.rs	Splits throughput options into a dedicated options submodule with operation now pub(crate).
sdk/cosmos/azure_data_cosmos/src/options/routing_strategy.rs	Updates Region import location and adds equality derives for RoutingStrategy.
sdk/cosmos/azure_data_cosmos/src/options/mod.rs	Refactors options into per-area modules and centralizes public re-exports.
sdk/cosmos/azure_data_cosmos/src/options/item.rs	Adds options submodule for item read/write/patch options with operation now pub(crate).
sdk/cosmos/azure_data_cosmos/src/options/feed.rs	Adds feed/query options module using feed::ContinuationToken.
sdk/cosmos/azure_data_cosmos/src/options/feed_ranges.rs	Adds feed-range routing-map options module with operation now pub(crate).
sdk/cosmos/azure_data_cosmos/src/options/database.rs	Adds database CRUD/query options module with operation now pub(crate).
sdk/cosmos/azure_data_cosmos/src/options/container.rs	Adds container CRUD/query options module with operation now pub(crate).
sdk/cosmos/azure_data_cosmos/src/options/consistency.rs	Adds ConsistencyLevel module and derives common traits + serde support.
sdk/cosmos/azure_data_cosmos/src/options/client.rs	Adds CosmosClientOptions module and keeps client config internal via builder.
sdk/cosmos/azure_data_cosmos/src/options/batch.rs	Adds batch request + sub-operation options module.
sdk/cosmos/azure_data_cosmos/src/models/system_properties.rs	Splits SystemProperties (and timestamp parsing) into its own model file with tests.
sdk/cosmos/azure_data_cosmos/src/models/mod.rs	Refactors models into per-type modules and trims exports to resource models only.
sdk/cosmos/azure_data_cosmos/src/models/database_properties.rs	Extracts DatabaseProperties and models id as Option<String> with wire-model rationale.
sdk/cosmos/azure_data_cosmos/src/models/container_properties.rs	Updates partitioning imports to use new partitioning::PartitionKeyDefinition.
sdk/cosmos/azure_data_cosmos/src/lib.rs	Reorganizes crate root exports and declares new public modules.
sdk/cosmos/azure_data_cosmos/src/feed/query.rs	Updates Query::with_text to accept impl Into<String>.
sdk/cosmos/azure_data_cosmos/src/feed/query_page.rs	Adds dedicated QueryFeedPage type and wires it via SDK response/headers wrappers.
sdk/cosmos/azure_data_cosmos/src/feed/page.rs	Adds dedicated FeedPage type for feed paging results.
sdk/cosmos/azure_data_cosmos/src/feed/mod.rs	Introduces feed module surface and re-exports driver continuation/feed-range types.
sdk/cosmos/azure_data_cosmos/src/feed/iterator.rs	Refactors iterators to use new feed/response modules and updated status paths.
sdk/cosmos/azure_data_cosmos/src/fault_injection/mod.rs	Updates fault-injection module docs and continues driver re-exports.
sdk/cosmos/azure_data_cosmos/src/error.rs	Updates diagnostics import path to new diagnostics module.
sdk/cosmos/azure_data_cosmos/src/driver_bridge.rs	Updates internal response bridge to use response::CosmosResponse.
sdk/cosmos/azure_data_cosmos/src/diagnostics.rs	Adds diagnostics module that re-exports driver DiagnosticsContext.
sdk/cosmos/azure_data_cosmos/src/credential.rs	Derives SafeDebug for credential redaction and adds tests locking down Debug output.
sdk/cosmos/azure_data_cosmos/src/clients/throughput_poller.rs	Updates imports for new response module and diagnostics path; updates status references.
sdk/cosmos/azure_data_cosmos/src/clients/offers_client.rs	Updates imports to new response module and status path; adjusts error construction.
sdk/cosmos/azure_data_cosmos/src/clients/mod.rs	Reorganizes client module exports and internal sectioning.
sdk/cosmos/azure_data_cosmos/src/clients/database_client.rs	Updates imports to new options and response modules; replaces panics with error-return helper for missing _rid.
sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client.rs	Updates docs to emphasize CosmosClient::builder() and adjusts imports to new modules.
sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client_builder.rs	Updates docs/imports to new module paths and fixes doc links to moved types.
sdk/cosmos/azure_data_cosmos/src/clients/container_client.rs	Updates imports and doc links to moved modules; updates status paths.
sdk/cosmos/azure_data_cosmos/src/account_endpoint.rs	Updates status path to error::CosmosStatus.
sdk/cosmos/azure_data_cosmos/README.md	Updates examples/import paths and revises internal feature documentation wording.
sdk/cosmos/azure_data_cosmos/examples/cosmos/upsert.rs	Updates option imports to options::* and keeps core client types at crate root.
sdk/cosmos/azure_data_cosmos/examples/cosmos/replace.rs	Updates option imports to options::* and keeps core client types at crate root.
sdk/cosmos/azure_data_cosmos/examples/cosmos/query.rs	Updates FeedScope import to feed::FeedScope.
sdk/cosmos/azure_data_cosmos/examples/cosmos/create.rs	Updates options and partitioning imports to options::* / partitioning::*.
sdk/cosmos/azure_data_cosmos/examples/cosmos/batch.rs	Updates batch result body display to match RawValue storage (body.get()).
sdk/cosmos/azure_data_cosmos/docs/control-plane-always-returns-body.md	Adds shared doc snippet explaining control-plane operations always return resource bodies.
sdk/cosmos/azure_data_cosmos/CHANGELOG.md	Adds 0.35.0 (Unreleased) changelog content describing the API reorganization and hygiene changes.
sdk/cosmos/azure_data_cosmos/Cargo.toml	Enables serde_json’s raw_value feature for RawValue support.
sdk/cosmos/azure_data_cosmos_driver/README.md	Simplifies driver README positioning and support-model description.

Comments suppressed due to low confidence (1)

sdk/cosmos/azure_data_cosmos/src/options/routing_strategy.rs:23

• RoutingStrategy is described in the changelog as deriving Hash + Serialize/Deserialize, but the enum currently only derives Clone, Debug, PartialEq, Eq. If the intent is to allow equality + hashing and serde round-trips (as with ConsistencyLevel), those derives should be added here (note: Copy is not possible with the PreferredRegions(Vec<Region>) variant).

[simorenoh]

Just a nit on my end, but feel free to ignore me since it's likely entirely personal preference - I see for files the renaming of, for instance, response_body.rs to just body.rs because the file lives in a new directory /response. In that same folder, we also have however item_response.rs.

Similarly, under the /options directory we only have individual names, like batch.rs or client.rs, but under clients we have container_client.rs and offers_client.rs.

All of this to say, personally I'd lean more towards just having complete names on everything so you don't even need the directory to know what you're looking at (batch_options.rs is self-explanatory) and to align file names across the repo. But again, just personal preference. Re-organization in general and new patterns LGTM!

[tvaron3]

LGTM

[FabianMeiswinkel]

LGTM

[kundadebdatta]

PR Deep Review

The reorg itself is clean (no orphaned/over-exposed symbols, explicit re-exports complete, per-type splits preserved impls/tests) and the genuine logic changes are correct (panic→error control flow, SafeDebug credential redaction, serde error mapping, RawValue single-parse, ETag swap, Option<String> id). The 0.36.0 CHANGELOG is accurate. The findings below are documentation/test-hygiene; inline comments cover #2–#6.

🟡 1 · The PR description is out of sync with the merged code

At head 0e97210 the description table claims structure/visibility that does not exist (the CHANGELOG, by contrast, is correct):

• Lists partitioning (new) and response (new) modules — neither exists. Partition types and the response wrappers (BatchResponse/ItemResponse/ResourceResponse/ResponseBody/ResponseHeaders) all stayed in models. lib.rs declares only clients, diagnostics, error, fault_injection, feed, models, options.
• "the operation: OperationOptions field … is now pub(crate)" — it is still pub on every options type (e.g. options/item.rs). with_operation_options(...) exists, but the stated encapsulation guarantee doesn't hold.
• "CosmosStatus and SubStatusCode … no longer at the crate root" — both are still at the crate root (pub use error::{CosmosError, CosmosStatus, Result, SubStatusCode}).
• The body says "The 0.35.0 CHANGELOG entry has the canonical move map," but the entry is 0.36.0 (0.35.0 shipped 2026-06-09).

It looks like the partitioning/response split (and the pub(crate) change) were folded back into models after the earlier review round — the GitHub Copilot bot's file summary still references the now-removed partitioning.rs/response/ files. Since this is a pre-API-review tidy pass, the description is what an API reviewer reads, so please re-sync it (or land the changes it promises).

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}