$ show opensearch-project/opensearch-go
The OpenSearch Go client (`opensearch-go/v5`) is a production-grade, community-driven SDK that provides typed, idiomatic Go bindings for the OpenSearch REST API. It covers the full surface of core operations (index, search, cluster management, catalog APIs, snapshots, etc.) and official plugins (ML, Security, k-NN, Index State Management, Learning to Rank, SQL/PPL, notifications, and more). The client is not just a thin HTTP wrapper—it includes a sophisticated transport layer with adaptive connection pooling, node discovery, retry policies, shard-aware routing, and pluggable observability (Prometheus, OpenTelemetry) via an observer pattern. Additionally, it ships a code generator (`cmd/osgen`) that produces all typed request/response structs and tests from the OpenSearch OpenAPI specification, and a migration linter (`cmd/osapilint`) to automate major-version upgrades (v2→v5). Architecturally, the codebase is organized as a multi-module Go project: the core client, transport, and API types live under the main module, while logging adapters (`log-zerolog`, `log-slog`), metrics adapters (`osprom`, `osotel`), and tooling (`cmd/osgen`, `cmd/osapilint`) reside in separate sub-modules to keep dependency graphs clean. The primary entry points are `opensearch.NewClient()` / `opensearchapi.NewClient()` for the core API, and plugin-specific constructors (e.g., `ml.NewClient(osClient)`) for extended capabilities. Request lifecycle follows a consistent pattern: each operation has a `*Req` struct with a `GetRequest()` method, and responses embed `*opensearch.Response` with `Inspect()` and `RawBody()` accessors. Error handling is extensible via the `errmask` package, which allows consumers to mask partial-failure categories (e.g., bulk item errors) from surfacing as Go errors. Data flows through the client’s layered pipeline: user constructs a typed request → internal `build.Request()` and `params.Encode()` produce an `*http.Request` → the transport applies policies (connection selection, retry, node discovery) → performs the HTTP call → the response is deserialized into a typed struct. The transport uses garbage-avoiding patterns (sync.Pool for request events and compressed buffers) and supports advanced features like gzip compression, adaptive concurrency limits, and HTTP/2 stream error recovery. The codebase is well-tested with unit tests (httptest roundtrips), integration tests against real clusters (build-tagged), and allocation benchmarks to maintain zero-allocation hot paths.
The LLM identified 3 files worth highlighting for reuse:
A lock-free TTL cache implementation using `sync.Pool` and time-based expiration via unix timestamps. It avoids mutex contention by storing entries in a concurrent-safe map with lazy expiration checks. The cache supports variable TTLs per entry and a callback for eviction. This component is isolated (only depends on standard library) and demonstrates a non-trivial lock-free design that can be extracted into any Go project needing a lightweight, expiration-aware cache without external dependencies.
Defines a bitfield-based error masking system (`ErrorMask`) that allows consumers to selectively suppress specific error categories (e.g., bulk item failures, search shard failures) from bubbling up as Go errors. It provides a clean interface (`Add`, `Remove`, `IsSet`) and integrates with the SDK’s error detection via `resolveErrorMask` which reads the `OPENSEARCH_GO_ERROR_MASK` environment variable. The pattern is isolated and reusable for any Go library that needs fine-grained control over which error types are exposed to the caller, without importing the rest of the SDK.
Defines the `ConnectionObserver` and `BaseConnectionObserver` interfaces and types for observing connection lifecycle events (connect, disconnect, error) and request/response events (succeeded, failure, status codes). The observer uses a pooled event pipeline (`sync.Pool` for event objects, non-blocking channel dispatch) to minimize allocations on hot paths. This pattern is the foundation for the `osprom` and `osotel` metric adapters, which implement these observers to emit Prometheus histograms or OpenTelemetry traces. The observer interface is clean and standalone—any Go project needing pluggable instrumentation of an HTTP client or connection pool could adopt it by providing their own observer implementation.