cosmosdb

package
v1.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 38 Imported by: 0

README

Azure Cosmos DB

Parity grade: B · SDK azure-sdk-for-go/sdk/data/azcosmos@v1.5.0 · last audited 2026-10-18 (19af2a18c)

Coverage

Metric Value
PARITY entries audited 18 (18 ok)
Feature families 16 (14 ok, 2 partial)
Known gaps 9
Deferred items 0
Resource leaks clean
Known gaps
  • Throughput: provisioned throughput, autoscale, serverless limits and 429 throttling do not exist; x-ms-request-charge is reported but never limited, and the offers/throughput APIs are not served
  • IndexingPolicy: stored and echoed on containers but never enforced; queries always scan the container, so index-dependent behaviors (composite-index-required ORDER BY, excluded paths, EnableScanInQuery) are not reproduced
  • MultiRegion: one fixed region (South Central US) with a single writable location; failover, multi-write, preferred regions and consistency levels other than a static session token are not modeled
  • RequestCharge: an approximation of documented costs, not a metering of index and storage work
  • Continuation: a query is re-executed for every page, so results can shift if the container changes between pages
  • SQL: user-defined functions, spatial functions (ST_*), the remaining date and conversion built-ins, regex modifier x, and ORDER BY combined with GROUP BY are not implemented; unsupported functions are a 400 parse error
  • ItemOperations: PATCH, transactional batch, bulk, change feed, stored procedures, triggers and conflict-resolution policy are not served
  • Containers: unique-key policy and the geospatial/vector/computed-property settings are not stored or enforced; database and container ETags are static
  • TableAPI: $batch (multipart changesets) is not implemented, and Table API responses carry no per-operation request charge or continuation beyond what pkgs/odatatable provides

More

Documentation

Overview

Package cosmosdb emulates Azure Cosmos DB over its REST+JSON gateway protocol: the Core (SQL) API (databases, containers with hierarchical partition keys and TTL, documents, a SQL query engine with joins, subqueries, aggregates and built-ins, continuation tokens, request-unit accounting) and the Table API. Master-key auth and TLS are opt-in. See PARITY.md for scope and known gaps.

Index

Constants

View Source
const DefaultMasterKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="

DefaultMasterKey is the real Cosmos DB Local Emulator's well-known, publicly documented fixed master key. Accepting it by default (like services/azureblob's/azurequeue's/azuretable's fixed devstoreaccount1 key) means unmodified SDK configuration pointed at the real emulator's documented connection string works out of the box against gopherstack too. See masterkey.go and AZURE.md section 5.

View Source
const DefaultPort = 8081

DefaultPort is the real Cosmos DB Local Emulator's own fixed, protocol-conventional TCP port (8081). Unlike services/azureblob's 10000, services/azurequeue's 10001, and services/azuretable's 10002 -- all of which mirror Azurite's own port convention -- 8081 mirrors the real Cosmos DB Emulator's own published default instead, since Cosmos's emulator (unlike Azurite) is a single-service, single-port tool with no analogous three-port split to imitate. This deliberately sits OUTSIDE --port-range-start/--port-range-end's own default range (10000-10100), exactly like services/iot's MQTT broker default (1883) -- see AZURE.md section 4 and handler.go's StartWorker for the synchronous-bind, no-fallback-pool rationale this follows.

Variables

View Source
var (
	// ErrMissingAuthorization is returned when validation is on and a request carries no Authorization header.
	ErrMissingAuthorization = errors.New("cosmosdb: missing Authorization header")
	// ErrMissingDate is returned when neither x-ms-date nor Date is present.
	ErrMissingDate = errors.New("cosmosdb: missing x-ms-date header")
	// ErrDateSkew is returned when the request date is outside maxAuthClockSkew of server time.
	ErrDateSkew = errors.New("cosmosdb: x-ms-date outside the allowed clock skew")
	// ErrBadSignature is returned when the signature does not match.
	ErrBadSignature = errors.New("cosmosdb: signature mismatch")
)
View Source
var (
	ErrDatabaseNotFound       = errors.New("cosmosdb: database not found")
	ErrDatabaseAlreadyExists  = errors.New("cosmosdb: database already exists")
	ErrContainerNotFound      = errors.New("cosmosdb: container not found")
	ErrContainerAlreadyExists = errors.New("cosmosdb: container already exists")
	ErrDocumentNotFound       = errors.New("cosmosdb: document not found")
	ErrDocumentAlreadyExists  = errors.New("cosmosdb: document already exists")
	ErrETagMismatch           = errors.New("cosmosdb: etag mismatch")

	// ErrInvalidDocument is returned when a document body is not a JSON
	// object, or its "id" field is present but not a non-empty string.
	ErrInvalidDocument = errors.New("cosmosdb: invalid document body")

	// ErrInvalidPartitionKeyPath is returned for a container partition key definition that is empty, unprefixed,
	// duplicated, or has more than three (hierarchical) paths.
	ErrInvalidPartitionKeyPath = errors.New(
		"cosmosdb: partitionKey.paths must contain between one and three distinct \"/\"-prefixed paths",
	)

	// ErrInvalidDefaultTTL is returned for a container defaultTtl that is neither -1 nor a positive integer.
	ErrInvalidDefaultTTL = errors.New("cosmosdb: defaultTtl must be -1 or a positive integer")

	// ErrPartitionKeyImmutable is returned when a container replace tries to change the partition key.
	ErrPartitionKeyImmutable = errors.New("cosmosdb: the partition key of an existing container cannot be changed")

	// ErrInvalidContinuation is returned for a malformed x-ms-continuation token.
	ErrInvalidContinuation = errors.New("cosmosdb: invalid continuation token")

	// ErrQueryParse and ErrQueryTooDeep are returned by ParseQuery. A parse
	// error always surfaces as 400 BadRequest, never a panic -- see
	// document_ops.go's handleQuery.
	ErrQueryParse   = errors.New("cosmosdb: query parse error")
	ErrQueryTooDeep = errors.New("cosmosdb: query expression nested too deeply")

	// ErrSnapshotNull* are returned by Restore when a snapshot's nested map
	// holds a JSON null entry, which decodes to a nil pointer that would
	// panic on first dereference if stored as-is. See persistence.go.
	ErrSnapshotDatabaseNull  = errors.New("cosmosdb: restore snapshot: database is null")
	ErrSnapshotContainerNull = errors.New("cosmosdb: restore snapshot: container is null")
	ErrSnapshotDocumentNull  = errors.New("cosmosdb: restore snapshot: document is null")

	// ErrPartitionKeyMismatch is returned by ReplaceDocument when the
	// replacement body's own partition-key-path field is present but
	// disagrees with the caller-supplied partition key (the
	// x-ms-documentdb-partitionkey header value, canonicalized). Without
	// this check, a document keyed under partition "a" could be silently
	// rewritten to claim partition "b" in its own body while remaining
	// stored (and only ever findable) under "a" -- an internally
	// inconsistent document real Cosmos DB never allows to exist.
	ErrPartitionKeyMismatch = errors.New(
		"cosmosdb: replacement body's partition key does not match the request's partition key",
	)

	// ErrSnapshotDocumentNullBody is returned by storedDocument.UnmarshalJSON
	// when a persisted document's "Body" field is itself JSON null.
	// encoding/json decodes a null-into-map with no error (it just sets the
	// map to nil), so without this explicit check a document with a null
	// Body would silently restore as an empty document, discarding every
	// field it used to have -- not a decode failure, so nothing would ever
	// surface the data loss.
	ErrSnapshotDocumentNullBody = errors.New("cosmosdb: restore snapshot: document body is null")

	// ErrUnexpectedTrailingJSON is returned by rejectTrailingJSON when a
	// second decode off the same stream succeeds instead of hitting EOF,
	// meaning the input carried more than the one JSON value callers
	// require.
	ErrUnexpectedTrailingJSON = errors.New("cosmosdb: unexpected additional JSON value")
)

Sentinel errors for Azure Cosmos DB (Core/SQL API) operations.

View Source
var ErrMalformedAuthorization = errors.New("cosmosdb: malformed Authorization header")

ErrMalformedAuthorization is returned by VerifyMasterKey when the request's Authorization header cannot be parsed.

View Source
var ErrNilAppContext = errors.New("cosmosdb: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

Functions

func ExecuteQuery

func ExecuteQuery(query string, params []QueryParameter, docs []DocumentInfo) ([]any, error)

ExecuteQuery parses and runs query against docs. It never panics.

func VerifyMasterKey

func VerifyMasterKey(masterKey string, r *http.Request) (bool, error)

VerifyMasterKey recomputes the master-key signature for r using masterKey, and reports whether it matches the signature the client sent. This is an explicit, opt-in check: nothing in this package calls it implicitly -- see auth.go's authorize, which only calls this when Settings.ValidateAuth is true, mirroring pkgs/azureauth.VerifySharedKey's identical opt-in stance.

Types

type ConfigProvider

type ConfigProvider interface {
	GetCosmosDBSettings() Settings
}

ConfigProvider is a private interface to extract CosmosDB configuration from the abstract AppContext Config, mirroring services/azuretable.ConfigProvider.

type ContainerInfo

type ContainerInfo struct {
	DefaultTTL        *int
	ID                string
	RID               string
	PartitionKeyPath  string
	PartitionKeyPaths []string
	IndexingPolicy    json.RawMessage
}

ContainerInfo is a read-only snapshot of a container, returned by the StorageBackend container accessors.

type ContainerSpec

type ContainerSpec struct {
	DefaultTTL        *int
	ID                string
	PartitionKeyPath  string
	PartitionKeyPaths []string
	IndexingPolicy    json.RawMessage
}

ContainerSpec is the caller-supplied shape for creating or replacing a container. PartitionKeyPaths (up to three, hierarchical) takes precedence over the single PartitionKeyPath. DefaultTTL nil leaves TTL disabled.

type DatabaseInfo

type DatabaseInfo struct {
	ID  string
	RID string
}

DatabaseInfo is a read-only snapshot of a database, returned by the StorageBackend database accessors.

type DocumentInfo

type DocumentInfo struct {
	Timestamp        time.Time
	Body             map[string]any
	ID               string
	RID              string
	Self             string
	ETag             string
	PartitionKeyJSON string
}

DocumentInfo is a read-only snapshot of a document, returned by the StorageBackend document accessors. Body holds the document's user-defined fields only (never the system properties, which callers -- handler.go's encodeDocument -- overlay from the other fields at response-encode time, mirroring services/azuretable's EntityInfo/encodeEntity split).

type Handler

type Handler struct {
	Backend      StorageBackend
	TableBackend *odatatable.InMemoryBackend

	MasterKey string

	TLSHosts      []string
	Port          int
	SweepInterval time.Duration
	ValidateAuth  bool
	TLS           bool
	// contains filtered or unexported fields
}

Handler is the Echo HTTP handler for Azure Cosmos DB (Core/SQL API) operations.

func NewHandler

func NewHandler(backend StorageBackend) *Handler

NewHandler creates a new Cosmos DB Handler. Port/MasterKey default to DefaultPort/DefaultMasterKey; callers (typically provider.go) override them from Settings.

func (*Handler) ExtractOperation

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation extracts the Cosmos DB operation name from the request, for metrics labeling.

func (*Handler) ExtractResource

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource extracts the resource path, for metrics labeling.

func (*Handler) GetSupportedOperations

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations returns the list of supported Cosmos DB operations, Core/SQL and Table API combined.

func (*Handler) Handler

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler function for Cosmos DB operations.

func (*Handler) MatchPriority

func (h *Handler) MatchPriority() int

MatchPriority returns the routing priority for the CosmosDB handler. Irrelevant in practice since RouteMatcher never matches; 0 (lowest) is the safe default.

func (*Handler) Name

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset

func (h *Handler) Reset()

Reset clears all in-memory state, Core/SQL and Table API alike.

func (*Handler) Restore

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher exists only to satisfy service.Registerable's interface contract -- see provider.go's Provider doc comment. CosmosDB never matches on the shared AWS single-port Router; it runs on its own dedicated listener started by StartWorker.

func (*Handler) Shutdown

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the dedicated Cosmos DB listener.

func (*Handler) SignRequest

func (h *Handler) SignRequest(r *http.Request) error

SignRequest adds x-ms-date and a master-key Authorization header to r using the handler's key. It lets in-process callers (the dashboard proxy) satisfy ValidateAuth.

func (*Handler) Snapshot

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated Cosmos DB listener (optionally TLS) and starts the TTL janitor. The bind is synchronous so a port conflict is returned to the caller.

func (*Handler) TLSCertPEM

func (h *Handler) TLSCertPEM() []byte

TLSCertPEM returns the self-signed certificate (PEM) the TLS listener serves, for clients to trust; nil unless TLS is enabled and the worker started.

type InMemoryBackend

type InMemoryBackend struct {
	// contains filtered or unexported fields
}

InMemoryBackend implements StorageBackend using an in-memory map guarded by a single RWMutex. Shaped after services/azuretable's InMemoryBackend.

func NewInMemoryBackend

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates a new empty InMemoryBackend.

func (*InMemoryBackend) AttachTableAPI

func (b *InMemoryBackend) AttachTableAPI(t tableSnapshotter)

AttachTableAPI includes t in this backend's Snapshot/Restore/Reset.

func (*InMemoryBackend) CreateContainer

func (b *InMemoryBackend) CreateContainer(dbID string, spec ContainerSpec) (ContainerInfo, error)

CreateContainer creates a new, empty container within dbID. Returns ErrDatabaseNotFound if dbID doesn't exist, or ErrContainerAlreadyExists if a container with the same ID already exists in it.

func (*InMemoryBackend) CreateDatabase

func (b *InMemoryBackend) CreateDatabase(id string) (DatabaseInfo, error)

CreateDatabase creates a new, empty database. Returns ErrDatabaseAlreadyExists if a database with the same ID already exists.

func (*InMemoryBackend) CreateDocument

func (b *InMemoryBackend) CreateDocument(
	dbID, containerID string, body map[string]any, upsert bool,
) (DocumentInfo, error)

CreateDocument creates (or, if upsert, inserts-or-replaces) a document. See StorageBackend's doc comment.

func (*InMemoryBackend) DeleteContainer

func (b *InMemoryBackend) DeleteContainer(dbID, containerID string) error

DeleteContainer removes a container and all of its documents.

func (*InMemoryBackend) DeleteDatabase

func (b *InMemoryBackend) DeleteDatabase(id string) error

DeleteDatabase removes a database and all of its containers/documents. Returns ErrDatabaseNotFound if absent.

func (*InMemoryBackend) DeleteDocument

func (b *InMemoryBackend) DeleteDocument(dbID, containerID, partitionKey, id, ifMatch string) error

DeleteDocument removes a document after verifying ifMatch.

func (*InMemoryBackend) GetContainer

func (b *InMemoryBackend) GetContainer(dbID, containerID string) (ContainerInfo, error)

GetContainer retrieves a single container.

func (*InMemoryBackend) GetDatabase

func (b *InMemoryBackend) GetDatabase(id string) (DatabaseInfo, error)

GetDatabase retrieves a single database. Returns ErrDatabaseNotFound if absent.

func (*InMemoryBackend) GetDocument

func (b *InMemoryBackend) GetDocument(dbID, containerID, partitionKey, id string) (DocumentInfo, error)

GetDocument retrieves a single document by partition key and ID.

func (*InMemoryBackend) ListContainers

func (b *InMemoryBackend) ListContainers(dbID string) ([]ContainerInfo, error)

ListContainers returns a snapshot of all containers in dbID, sorted by ID.

func (*InMemoryBackend) ListDatabases

func (b *InMemoryBackend) ListDatabases() []DatabaseInfo

ListDatabases returns a snapshot of all databases, sorted by ID.

func (*InMemoryBackend) ListDocuments

func (b *InMemoryBackend) ListDocuments(dbID, containerID string) ([]DocumentInfo, error)

ListDocuments returns every live document in containerID, ordered by ID.

func (*InMemoryBackend) ListDocumentsPaged

func (b *InMemoryBackend) ListDocumentsPaged(
	dbID, containerID, token string, limit int,
) (page.Page[DocumentInfo], error)

ListDocumentsPaged returns one page of live documents; token and limit follow pkgs/page (limit <= 0 is unbounded).

func (*InMemoryBackend) QueryDocuments

func (b *InMemoryBackend) QueryDocuments(
	dbID, containerID, query string, params []QueryParameter,
) ([]any, error)

QueryDocuments runs a Cosmos SQL query against containerID. Result values share nested data with stored documents and must be treated as read-only.

func (*InMemoryBackend) ReplaceContainer

func (b *InMemoryBackend) ReplaceContainer(dbID string, spec ContainerSpec) (ContainerInfo, error)

ReplaceContainer updates a container's defaultTtl and indexing policy. The partition key is immutable.

func (*InMemoryBackend) ReplaceDocument

func (b *InMemoryBackend) ReplaceDocument(
	dbID, containerID, partitionKey, id string, body map[string]any, ifMatch string,
) (DocumentInfo, error)

ReplaceDocument fully replaces an existing document's body (its "id" and partition key value are fixed by the path/header and cannot be changed by the replacement body's own "id"/partition key field -- consistent with real Cosmos DB, which rejects a partition-key-changing Replace outright; this emulator instead just always keys off the caller-supplied partitionKey/id).

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset clears all in-memory state.

func (*InMemoryBackend) Restore

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a JSON snapshot. It implements persistence.Persistable. A snapshot's "databases" map, or any database's "Containers" map, or any container's "Documents" map, may legally be JSON null (a nil Go map after decode) rather than absent -- this is tolerated by initializing each to an empty map rather than leaving it nil, since a nil map is safe to range/read but panics on insertion (this was a real M2 bug in services/azuretable's Restore -- see AZURE.md's process rules).

func (*InMemoryBackend) RunQuery

func (b *InMemoryBackend) RunQuery(
	dbID, containerID, query string, params []QueryParameter, partitionKey string,
) (QueryResult, error)

RunQuery is QueryDocuments scoped to partitionKey (canonical JSON; empty means cross-partition), also reporting how many rows were scanned.

func (*InMemoryBackend) Snapshot

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises the backend state to JSON. It implements persistence.Persistable.

func (*InMemoryBackend) SweepExpired

func (b *InMemoryBackend) SweepExpired() int

SweepExpired physically removes expired documents and returns how many were removed.

type Provider

type Provider struct{}

Provider implements service.Provider for the Azure Cosmos DB service. It registers no RouteMatcher on the shared single-port Router: the returned Handler is a service.BackgroundWorker serving its own listener on the fixed Cosmos emulator port (8081), and also runs the TTL sweeper.

func (*Provider) Init

Init initializes the CosmosDB service backend and handler. The configured port (Settings.Port, default DefaultPort) is only recorded here; the actual TCP bind happens synchronously in Handler.StartWorker, so a port-in-use failure is returned to the caller directly instead of being discovered later from a background goroutine.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the service provider name.

type QueryParameter

type QueryParameter struct {
	Value any    `json:"value"`
	Name  string `json:"name"`
}

QueryParameter is one "@name"/value binding from a query request body.

type QueryResult

type QueryResult struct {
	Rows    []any
	Scanned int
}

QueryResult is the output of one query execution; Scanned counts container rows examined.

type Settings

type Settings struct {
	// MasterKey is the base64-encoded master key authorize verifies request
	// signatures against when ValidateAuth is true. Defaults to the real
	// emulator's own well-known key (DefaultMasterKey).
	MasterKey string `` //nolint:lll // config struct tags are intentionally verbose
	/* 248-byte string literal not displayed */
	// Port is the fixed TCP port for the dedicated Cosmos DB listener. See
	// handler.go's StartWorker for what happens when it's unavailable
	// (fails fast; no fallback pool, matching services/azureblob,
	// services/azurequeue, and services/azuretable).
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 172-byte string literal not displayed */
	// ValidateAuth opts into cryptographic master-key signature
	// verification of the Authorization header (opt-in, off by default --
	// mirrors services/s3's WithPresignValidation and pkgs/azureauth's
	// VerifySharedKey opt-in pattern). See masterkey.go.
	ValidateAuth bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 169-byte string literal not displayed */
}

Settings holds service-level configuration for the Cosmos DB backend. Fields are picked up by the Kong CLI parser when this struct is embedded in the root CLI command (see cli.go's CLI.CosmosDB field), mirroring services/azuretable's Settings pattern.

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings returns the default Settings. Used when no ConfigProvider is available at init time (e.g. tests constructing a Provider directly).

type StorageBackend

type StorageBackend interface {
	CreateDatabase(id string) (DatabaseInfo, error)
	GetDatabase(id string) (DatabaseInfo, error)
	ListDatabases() []DatabaseInfo
	DeleteDatabase(id string) error

	CreateContainer(dbID string, spec ContainerSpec) (ContainerInfo, error)
	GetContainer(dbID, containerID string) (ContainerInfo, error)
	ListContainers(dbID string) ([]ContainerInfo, error)
	DeleteContainer(dbID, containerID string) error

	// CreateDocument creates (or, if upsert, inserts-or-replaces) a document
	// in containerID. The document's partition key value is derived from
	// body per the container's declared partition key path; body's "id"
	// field is used verbatim if present (a non-string "id" is rejected), or
	// generated if absent.
	CreateDocument(dbID, containerID string, body map[string]any, upsert bool) (DocumentInfo, error)
	GetDocument(dbID, containerID, partitionKey, id string) (DocumentInfo, error)
	ReplaceDocument(
		dbID, containerID, partitionKey, id string, body map[string]any, ifMatch string,
	) (DocumentInfo, error)
	DeleteDocument(dbID, containerID, partitionKey, id, ifMatch string) error
	// ListDocuments returns every document in containerID, ordered by ID,
	// for both the read-feed (GET .../docs) and the SQL query engine's FROM
	// clause. Cross-partition: it is not filtered by partition key.
	ListDocuments(dbID, containerID string) ([]DocumentInfo, error)

	// Reset clears all in-memory state. Used by the
	// POST /_gopherstack/reset endpoint for CI pipelines and rapid local development.
	Reset()
}

StorageBackend defines the interface for an Azure Cosmos DB (Core/SQL API) backend. Shaped after services/azuretable's StorageBackend: a narrow, testable seam between the wire handler and storage, so handler tests can substitute a fake.

ifMatch on ReplaceDocument/DeleteDocument threads through the same If-Match states services/azuretable's StorageBackend documents:

  • "" (no If-Match header): unconditional mutation.
  • any other string: the document must exist AND its current ETag must equal this value, else ErrETagMismatch.

partitionKey parameters are the caller-supplied partition key value's canonical JSON encoding (see canonicalPartitionKeyJSON), extracted from the mandatory x-ms-documentdb-partitionkey header on every point operation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL