Skip to content

Go v2: Align item integration with Rust ABI #27461

Description

Context

PR #27336 incrementally adds the public Go v2 surface for ReadItem and CreateItem. Those operations intentionally remain unwired and return errNotImplemented; completing the native vertical slice is outside that PR's scope.

Before the operations can be connected to the Rust driver, the Go binding must align with the current native ABI and prove its ownership/lifetime behavior. This issue tracks three related integration workstreams.

Related work:

Required work

1. Synchronize LatestCommitted read consistency — upstream ABI complete

The upstream C ABI gap is resolved. Azure/azure-sdk-for-rust#5139 merged on 2026-08-26 and:

  • appended LatestCommitted = 5 without renumbering GlobalStrong = 4;
  • mapped the host value to the Rust driver's ReadConsistencyStrategy::LatestCommitted;
  • regenerated the checked-in C header; and
  • added Rust and C validation coverage.

The original cross-SDK gap, #27351, is closed. No further Rust ABI work is required for this item. When the Go cgo binding lands, its normal option conversion must expose the already-available value while preserving Unset as the Go zero value and ABI inherit sentinel.

2. Consume the current typed completion-header ABI

The current native completion carries response metadata through the typed headers / headers_len collection. The Go binding must not rely on earlier fixed completion fields such as request_charge, activity_id, etag, session_token, sub_status, or retry_after_ms.

Implement completion translation that:

  • iterates the typed native header collection;
  • maps request charge, activity ID, ETag, session token, substatus, continuation, and retry-after into the appropriate Go response/error fields;
  • copies every borrowed string and body buffer into Go-owned memory before freeing the native completion;
  • applies documented missing-header defaults;
  • preserves unknown additive headers without failing the completion;
  • frees every native completion exactly once on success, error, and cancellation paths.

3. Add native lifetime, cancellation, and memory tests

The existing RWMutex tests prove that Client.Close waits for a held Go operation lease, but they do not exercise a real native operation or completion.

Add integration tests proving that:

  • a submitted operation is correlated with exactly one completion;
  • context cancellation calls native cancellation and still waits for/drains the real completion before releasing the client lifetime lease;
  • cancellation racing with success returns the actual successful result when success wins;
  • Client.Close cannot free Rust-owned driver/queue/container resources while an operation is still active;
  • callers are released when shutdown races with an outstanding operation;
  • completion bodies, strings, headers, handles, and registry entries are released exactly once;
  • repeated and concurrent Close calls remain safe;
  • tests pass under Go's race detector where supported.

Use deterministic native test hooks or an in-process test driver where possible; the core ownership tests should not depend on live Azure timing.

Acceptance criteria

  • The native C ABI exposes LatestCommitted without renumbering existing discriminants (Expose latest committed through C ABI azure-sdk-for-rust#5139).
  • The Go binding round-trips the already-available LatestCommitted value into the Rust driver.
  • ReadItem and CreateItem responses/errors are populated from the current typed completion-header model.
  • No Go response or error retains pointers into freed Rust memory.
  • Cancellation and shutdown preserve the one-submit/one-completion and exactly-once-free invariants.
  • Native integration tests cover success, service error, client-side error, cancellation, and close races.
  • The implementation is exercised with go test -race on supported native targets.

Non-goals

  • Changing the public ReadItem or CreateItem API introduced by azcosmos: add ReadItem and CreateItem #27336.
  • Requiring a live Azure account for the deterministic lifetime/ownership suite.
  • Expanding the operation set beyond what is needed to validate the initial item-operation vertical slice.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ClientThis issue points to a problem in the data-plane of the library.Cosmos

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions