If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/olivere/elastic shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live olivere/elastic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/olivere/elastic.

What it runs against: a local clone of olivere/elastic — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in olivere/elastic | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch release-branch.v7 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 667 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of olivere/elastic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/olivere/elastic.git
#   cd elastic
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of olivere/elastic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "olivere/elastic(\\.git)?\\b" \\
  && ok "origin remote is olivere/elastic" \\
  || miss "origin remote is not olivere/elastic (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify release-branch.v7 >/dev/null 2>&1 \\
  && ok "default branch release-branch.v7 exists" \\
  || miss "default branch release-branch.v7 no longer exists"

# 4. Critical files exist
test -f "client.go" \\
  && ok "client.go" \\
  || miss "missing critical file: client.go"
test -f "connection.go" \\
  && ok "connection.go" \\
  || miss "missing critical file: connection.go"
test -f "bulk.go" \\
  && ok "bulk.go" \\
  || miss "missing critical file: bulk.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "backoff.go" \\
  && ok "backoff.go" \\
  || miss "missing critical file: backoff.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 667 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~637d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/olivere/elastic"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

olivere/elastic is a Go client library for Elasticsearch (versions 1.x through 7.x) that provides a high-level API for indexing, querying, and managing Elasticsearch clusters. It wraps the Elasticsearch REST API with Go idioms, handling connection pooling, bulk operations, and request/response serialization via easyjson. DEPRECATED: The official Elasticsearch Go client at github.com/elastic/go-elasticsearch is the recommended replacement. Flat package structure with core types and methods in root (client.go, bulk.go, backoff.go, canonicalize.go) and specialized API endpoints as separate files (cat_.go, search.go, etc.). AWS authentication support lives in aws/ and aws/v4/ subdirectories. Bulk operations use easyjson code generation (_easyjson.go files) for JSON marshaling performance. Integration tests suffixed with _integration_test.go are segregated from unit tests.

Go developers building search and analytics applications on Elasticsearch who need a typed client library with builder patterns for complex queries. Commonly used by teams maintaining legacy systems still on elastic/v6 or v7, and by engineers migrating away from this library to the official client.

This library is feature-complete but deprecated as of 2022 in favor of the official Elasticsearch client. The v7 release branch is stable and widely used in production systems, with comprehensive test coverage (unit and integration tests visible in *_test.go files) and CI pipelines (.github/workflows/test-v7.yml, codeql-v7.yml). However, no active development or patches are being added — it is in maintenance-only mode.

High risk for new projects: The library is officially deprecated and the maintainer recommends migrating to github.com/elastic/go-elasticsearch. Dependency on AWS SDK (aws-sdk-go v1.43.21) adds complexity; OpenTelemetry and OpenCensus observability dependencies introduce version churn. Single maintainer (Oliver Eilhard) and no recent commits visible suggest the repo is no longer actively maintained — expect slow or no response to issues.

Active development has halted. The CHANGELOG-7.0.md indicates this branch targets Elasticsearch 7.x. CI workflows (.github/workflows/test-v7.yml, codeql-v7.yml) are configured but likely run only on maintenance branches. No evidence of recent feature work or bug fixes — library is in archival state pending user migration.

git clone https://github.com/olivere/elastic.git
cd elastic
git checkout release-branch.v7  # or use v6/v5 for legacy versions
go mod download
make test  # runs unit tests via Makefile

Note: Requires Go 1.17+ (from go.mod). For new projects, use github.com/elastic/go-elasticsearch instead.

Daily commands:

make test        # Run all unit tests
make test-verbose  # Run with verbose output (if target exists)
# For integration tests against a running ES cluster:
ES_URL=http://localhost:9200 go test -v -run Integration ./...

No dev server—this is a client library. You need a running Elasticsearch instance (7.x for v7 branch) to test against. Docker: docker run -p 9200:9200 docker.elastic.co/elasticsearch/elasticsearch:7.17.0

• client.go — Main Elasticsearch client entry point; all API operations are initiated through this struct and its methods.
• connection.go — Manages HTTP connections to Elasticsearch nodes; handles low-level network communication, retries, and connection pooling.
• bulk.go — Core bulk indexing API; implements the high-throughput batch operation pattern essential for production workloads.
• go.mod — Dependency manifest; defines the Go version requirement (1.17) and critical external dependencies like AWS SDK and OpenTelemetry.
• backoff.go — Implements exponential backoff retry logic; critical for resilience when Elasticsearch is unavailable or overwhelmed.
• errors.go — Defines error types and handling patterns throughout the client; essential for proper error classification and recovery logic.
• doc.go — Package-level documentation; provides the primary API surface overview and usage examples for new contributors.

Add a new Elasticsearch API operation

1. Create a new file following the pattern <operation>.go (e.g., flush.go) (<operation>.go)
2. Define a builder struct with chainable methods matching Elasticsearch query DSL (e.g., type FlushService struct { client *Client }) (<operation>.go)
3. Implement the Do() or Do(ctx context.Context) method that constructs the HTTP request via c.client.client.Do(req) (<operation>.go)
4. Add a factory method to client.go (e.g., func (c *Client) Flush() *FlushService) (client.go)
5. Create unit tests in <operation>_test.go and integration tests if needed in <operation>_integration_test.go (<operation>_test.go)

Add a new request/response type with JSON serialization

1. Define a struct in a new file (e.g., my_request.go) with struct tags for JSON fields (my_request.go)
2. Run go generate ./... if using easyjson annotations, or let the stdlib json marshaler handle it (my_request.go)
3. The build system will auto-generate my_request_easyjson.go for fast serialization (see pattern in bulk_*_request_easyjson.go files) (my_request_easyjson.go)
4. Add unit tests validating serialization round-trips in my_request_test.go (my_request_test.go)

Implement retry and backoff for a flaky operation

1. Import the backoff package and use the existing NewExponentialBackoff() or NewSimpleBackoff() in your operation's Do() method (backoff.go)
2. Wrap your HTTP request in a retry loop using the backoff strategy (see patterns in bulk_processor.go) (<operation>.go)
3. Classify errors using type assertions against error types defined in errors.go to decide retry-worthiness (errors.go)
4. Add test cases in <operation>_test.go using mock servers that simulate transient failures (<operation>_test.go)

Add AWS authentication for secure Elasticsearch

1. Review the AWS signature v4 signer implementation in aws/sign_v4.go (aws/sign_v4.go)
2. Pass the signer to the client via NewClient(elastic.SetHttpClient(awsHttpClient)) (client.go)
3. Reference config examples in config/config.go for recommended setup patterns (config/config.go)

• Go 1.17+ — Lightweight goroutines enable efficient concurrent requests; required by AWS SDK v1.43+ and OpenTelemetry v1.5+
• mailru/easyjson — Code-generated JSON serialization (~10x faster than reflection-based marshaling); critical for bulk operation throughput
• aws-sdk-go — Provides SigV4 signing for AWS-managed Elasticsearch (Amazon OpenSearch); also dependency of smartystreets/go-aws-auth
• opentracing/opentelemetry — Distributed tracing support for observability in microservices; decoupled via interface injection
• pkg/errors — Stack trace capture for debugging; lighter than multi-wrapping approaches

• Synchronous request/response model (no callback/promise chains)

  • Why: Go's goroutine model makes blocking calls lightweight; simpler API surface than callbacks
  • Consequence: Users must manage concurrency via goroutines; no built-in connection pooling limits (must be configured)

• Builder pattern for all operations instead of struct fields

  • Why: Fluent API matches Elasticsearch DSL; enables method chaining and defaults
  • Consequence: More boilerplate per operation; verbose for simple queries; harder to programmatically build complex queries

• Exponential backoff with fixed max retries instead of circuit breaker

  • Why: Simpler; avoids state management; suitable for transient network failures
  • Consequence: Cannot fast-fail against consistently unhealthy nodes; may retry dead nodes longer than necessary

• Deprecated in favor of official go-elasticsearch client

  • Why: Official client has Elastic's full support, native NDJSON streaming, and type-safe query builders
  • Consequence: This library receives minimal maintenance; users are encouraged to migrate; no new major features

• Real-time pub/sub or WebSocket support (polling/long-polling only via standard HTTP)

No setup required for basic usage (connect to any ES URL), but: Integration tests fail silently if Elasticsearch is not running on http://localhost:9200 (no clear error messages). easyjson code generation must be manually re-run (easyjson -all *.go) after modifying struct field tags—changes won't marshal/unmarshal correctly otherwise. AWS auth requires explicit NewSigningClient() call; default client does no auth. Deprecation: All new code should use the official client; this library will not receive updates for newer Elasticsearch features (8.x+). Context handling: Older code may not pass context.Context to requests—migrations to newer Go versions require refactoring. Connection pooling: Default settings may not suit high-concurrency workloads; tune MaxConnections and client.SetMaxRetries().

• Builder Pattern for Query DSL — olivere/elastic uses fluent builder chains (e.g., NewBoolQuery().Must(...).Filter(...)) to construct complex Elasticsearch queries safely; understanding this pattern is essential for using the search API correctly.
• Connection Pooling & HTTP Keep-Alive — The client manages a pool of persistent HTTP connections to Elasticsearch; misconfiguring pool size (MaxConns) can lead to performance degradation or connection exhaustion in high-throughput scenarios.
• Exponential Backoff Retry Strategy — backoff.go implements adaptive retry logic with exponential delays; critical for resilience against transient ES failures (503 Service Unavailable, network blips).
• Code Generation with easyjson — The *_easyjson.go files are auto-generated by the easyjson tool to provide fast, zero-copy JSON marshaling/unmarshaling; understanding this avoids manual serialization bugs and ensures performance.
• AWS Signature Version 4 (SigV4) Request Signing — aws/sign_v4.go implements AWS request signing for authentication to Amazon Elasticsearch Service; required for clusters protected by AWS IAM without explicitly passing credentials.
• Bulk Indexing & Batching — bulk.go and bulk_processor.go implement the Elasticsearch Bulk API, allowing efficient batch operations; understanding flush policies and error handling is crucial for high-volume data ingestion.
• Distributed Tracing with OpenTelemetry — The client integrates go.opentelemetry.io/otel hooks for distributed tracing; understanding span creation and propagation helps debug slow queries across microservices.

• elastic/go-elasticsearch — The official Elasticsearch Go client that olivere/elastic should be migrated to; provides auto-generated APIs for newer Elasticsearch versions with first-party support.
• elastic/elasticsearch-py — Python equivalent client library; useful for understanding Elasticsearch client design patterns across language ecosystems and comparing API philosophies.
• olivere/elastic-aws-request-signer — Standalone AWS request signing utilities that olivere/elastic can integrate with; companion package for AWS Elasticsearch Service authentication.
• go-kit/kit — Provides complementary patterns for service observability, logging, and instrumentation that pair well with this client in production Go services.
• elastic/elastic-transport-go — Low-level transport abstraction used by the official go-elasticsearch client; useful for understanding modern HTTP client patterns as alternative to olivere/elastic.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for AWS signature v4 signing (aws/sign_v4.go)

The AWS signature v4 implementation exists (aws/sign_v4.go, aws/v4/aws_v4.go) with only unit tests (aws/sign_v4_test.go). There are no integration tests validating actual AWS Elasticsearch/OpenSearch requests. New contributors could add integration tests that verify signed requests work against real AWS Elasticsearch instances, catching regressions in authentication flows.

• [ ] Create aws/sign_v4_integration_test.go with test cases for real AWS ES endpoint authentication
• [ ] Reference existing integration test pattern from cat_snapshots_integration_test.go and cat_count_integration_test.go
• [ ] Test both HTTP request signing and response validation against actual AWS credentials
• [ ] Document required AWS_REGION and AWS_ENDPOINT environment variables in CONTRIBUTING.md

Add missing *_integration_test.go files for bulk operations

The bulk operations are core functionality (bulk.go, bulk_processor.go, bulk_*_request.go files) but lack integration tests. Unit tests exist (bulk_test.go, bulk_processor_test.go) but integration tests following the repo's pattern (like cat_snapshots_integration_test.go and cat_count_integration_test.go) are missing. This is critical for a deprecated library to ensure bulk indexing actually works before migration.

• [ ] Create bulk_integration_test.go testing real bulk indexing against running Elasticsearch
• [ ] Create bulk_processor_integration_test.go testing concurrent bulk processing with actual cluster
• [ ] Reference cat_count_integration_test.go and cat_snapshots_integration_test.go for test structure
• [ ] Test error handling, retries, and backoff behavior (backoff.go) in real scenarios

Implement OpenTelemetry span instrumentation for core query operations

The go.mod already includes go.opentelemetry.io/otel v1.5.0 and go.opentelemetry.io/otel/trace dependencies, but the codebase doesn't appear to instrument core operations (search, bulk, etc.) with OpenTelemetry spans. This would help users migrate to the official client with observability context intact. Contributors could add distributed tracing support to critical paths.

• [ ] Add OpenTelemetry span wrapping to Search() method in search.go
• [ ] Add span instrumentation to BulkProcessor.Start() and bulk operations in bulk_processor.go
• [ ] Add span instrumentation to client.Do() in client.go for all requests
• [ ] Create otel_test.go to verify spans are properly created and include relevant attributes (index, query, error details)
• [ ] Update CONTRIBUTING.md with OpenTelemetry instrumentation guidelines for new features

• Add integration tests for cat_ endpoints*: Files like cat_allocation.go, cat_fielddata.go, cat_health.go have unit tests but no _integration_test.go files. Write integration tests that validate responses against a live Elasticsearch 7.x cluster to improve coverage and catch regressions.
• Document bulk processor backpressure patterns: bulk_processor.go lacks examples in comments/README showing how to handle the BulkProcessor response channel and implement custom error handling. Add inline examples and a doc comment explaining how callers should manage backpressure.
• Add missing field tags to struct types for canonicalization: canonicalize.go handles field name canonicalization but many request/response structs may lack 'json' tags or use inconsistent naming. Audit and add proper struct tags to ensure consistent JSON serialization across all types.

• High · Deprecated Library - No Security Updates — Repository root / README.md. The olivere/elastic library is officially deprecated. The repository explicitly states 'Deprecated: Use the official Elasticsearch client for Go at https://github.com/elastic/go-elasticsearch'. Deprecated libraries no longer receive security patches, bug fixes, or updates, leaving applications vulnerable to known and newly discovered security issues. Fix: Migrate to the official Elasticsearch Go client (github.com/elastic/go-elasticsearch) which is actively maintained and receives security updates.
• High · Outdated AWS SDK Dependency — go.mod. The go.mod file specifies 'github.com/aws/aws-sdk-go v1.43.21', which is significantly outdated. AWS SDK v1 has known vulnerabilities and lacks security patches. Current versions are much newer (v1.50+), and AWS recommends using the AWS SDK v2 for new projects. Fix: Update to the latest version of aws-sdk-go v1 (v1.50+) or migrate to aws-sdk-go-v2. Review AWS security advisories for the version currently in use.
• High · Multiple Outdated Transitive Dependencies — go.mod (indirect dependencies). Several indirect dependencies have outdated versions with potential security issues: opentracing-go v1.2.0, go.opencensus.io v0.23.0, and opentelemetry.io/otel v1.5.0 are all significantly behind current versions. Older versions may contain known CVEs. Fix: Update all transitive dependencies to their latest versions. Run 'go get -u ./...' and audit with 'go list -json -m all | nancy sleuth' or similar tools.
• Medium · Disabled Elasticsearch Security in Docker Compose — docker-compose.yml. The docker-compose.yml file disables Elasticsearch X-Pack security with 'xpack.security.enabled=false' and does not configure authentication. This configuration exposes the Elasticsearch cluster to unauthorized access. Fix: Enable X-Pack security (xpack.security.enabled=true), configure authentication credentials, and restrict network access. Use network isolation and authentication for all Elasticsearch instances, even in development.
• Medium · Elasticsearch Exposed on All Interfaces — docker-compose.yml (lines with commented http.host=0.0.0.0). While commented out, the docker-compose.yml shows configuration options that could expose Elasticsearch on 0.0.0.0. The current configuration with 'network.publish_host=127.0.0.1' is safer, but the presence of alternate configurations suggests potential for misconfiguration. Fix: Ensure Elasticsearch is never bound to 0.0.0.0 in production or development environments exposed to untrusted networks. Keep network bindings restricted to localhost or specific internal IPs.
• Medium · Insufficient Access Controls in Development Setup — docker-compose.yml. The docker-compose.yml exposes Elasticsearch port 9200 to the host (ports: 9200:9200) without authentication barriers. This allows any service with network access to interact with Elasticsearch. Fix: Implement network segmentation, use reverse proxies with authentication, or restrict port exposure to only necessary services. Use environment-specific configurations for dev/test/production.
• Low · Missing Go Module Checksum File — go.mod / go.sum. While not visible in the provided content, go.sum file integrity should be verified. Tampering with go.mod without corresponding go.sum changes could introduce malicious dependencies. Fix: Ensure go.sum is committed and verified in version control. Use 'go mod verify' regularly to detect tampering. Consider using GitHub's dependency scanning and Dependabot for automated updates.
• Low · Development Branch Usage Warning Not Enforced — README.md / client.go. The README warns 'This is a development branch that is actively being worked on. DO NOT USE IN PRODUCTION!' However, there are no runtime guards or version checks to prevent accidental production use of unstable code. Fix: Migrate to the official client. If forced to use this library, implement startup checks that verify the version and environment, raising alerts in production configurations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.