--- title: Interceptors description: Interceptors are middleware functions that can modify HTTP requests and responses on every call to Elasticsearch. They are useful for injecting authentication... url: https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/clients/go/advanced/interceptors products: - Elasticsearch Client - Elasticsearch Go Client applies_to: - Elastic Stack: Generally available since 8.19 --- # Interceptors Interceptors are middleware functions that can modify HTTP requests and responses on every call to Elasticsearch. They are useful for injecting authentication credentials, adding custom headers, implementing observability, and handling challenge-response authentication protocols. ## How interceptors work An interceptor wraps the transport's round-trip function. It receives the next function in the chain and returns a new function that can modify the request before calling `next`, and modify the response after. The type signatures are defined in the `elastictransport` package: ```go type RoundTripFunc func(*http.Request) (*http.Response, error) type InterceptorFunc func(next RoundTripFunc) RoundTripFunc ``` Interceptors are configured in `elasticsearch.Config` and applied at client creation. They cannot be changed after the transport is created. ```go es, err := elasticsearch.NewClient(elasticsearch.Config{ Interceptors: []elastictransport.InterceptorFunc{ myFirstInterceptor(), mySecondInterceptor(), }, }) ``` ### Execution order Interceptors are applied **left to right** for requests and **right to left** for responses. In the example above: 1. `myFirstInterceptor` modifies the request first 2. `mySecondInterceptor` modifies the request second, then sends it to Elasticsearch 3. `mySecondInterceptor` sees the response first 4. `myFirstInterceptor` sees the response last ```mermaid sequenceDiagram participant App as Application participant I1 as Interceptor_1 participant I2 as Interceptor_2 participant ES as Elasticsearch App->>I1: request I1->>I2: request I2->>ES: request ES-->>I2: response I2-->>I1: response I1-->>App: response ``` ## Dynamic credential rotation When credentials may change at runtime — for example, during token refresh or credential rotation — an interceptor can inject the latest credentials into each request dynamically. ```go func DynamicAuthInterceptor(provider *CredentialProvider) elastictransport.InterceptorFunc { return func(next elastictransport.RoundTripFunc) elastictransport.RoundTripFunc { return func(req *http.Request) (*http.Response, error) { username, password := provider.Get() req.SetBasicAuth(username, password) return next(req) } } } ``` The `CredentialProvider` uses a `sync.RWMutex` so credentials can be updated safely from another goroutine: ```go type CredentialProvider struct { mu sync.RWMutex username string password string } func (p *CredentialProvider) Get() (string, string) { p.mu.RLock() defer p.mu.RUnlock() return p.username, p.password } func (p *CredentialProvider) Update(username, password string) { p.mu.Lock() defer p.mu.Unlock() p.username = username p.password = password } ``` Usage: ```go authProvider := NewCredentialProvider("user1", "password1") es, err := elasticsearch.NewClient(elasticsearch.Config{ Addresses: []string{"https://localhost:9200"}, Interceptors: []elastictransport.InterceptorFunc{ DynamicAuthInterceptor(authProvider), }, }) // Later, rotate credentials — all future requests use the new credentials authProvider.Update("user2", "password2") ``` ## Per-request auth via context In multi-tenant applications or impersonation scenarios, different requests may need different credentials. An interceptor can read credentials from the request's `context.Context`: ```go type basicAuthKey struct{} type basicAuthValue struct { username string password string } // WithBasicAuth attaches credentials to a context. func WithBasicAuth(ctx context.Context, username, password string) context.Context { return context.WithValue(ctx, basicAuthKey{}, basicAuthValue{username, password}) } func ContextAuthInterceptor() elastictransport.InterceptorFunc { return func(next elastictransport.RoundTripFunc) elastictransport.RoundTripFunc { return func(req *http.Request) (*http.Response, error) { if auth, ok := req.Context().Value(basicAuthKey{}).(basicAuthValue); ok { req.SetBasicAuth(auth.username, auth.password) } return next(req) } } } ``` Usage: ```go es, err := elasticsearch.NewClient(elasticsearch.Config{ Username: "default_user", Password: "default_password", Interceptors: []elastictransport.InterceptorFunc{ ContextAuthInterceptor(), }, }) // Uses default credentials res, err := es.Info() if err != nil { log.Fatal(err) } defer res.Body.Close() // Uses per-request credentials ctx := WithBasicAuth(context.Background(), "tenant_a", "tenant_a_secret") res, err = es.Info(es.Info.WithContext(ctx)) if err != nil { log.Fatal(err) } defer res.Body.Close() ``` Interceptors can also handle challenge-response protocols. The following example implements Kerberos/SPNEGO authentication by retrying a request when a 401 challenge is received: ```go func KerberosInterceptor(tokenProvider func() (string, error)) elastictransport.InterceptorFunc { return func(next elastictransport.RoundTripFunc) elastictransport.RoundTripFunc { return func(req *http.Request) (*http.Response, error) { resp, err := next(req) if err != nil { return nil, err } if resp.StatusCode == http.StatusUnauthorized { authHeader := resp.Header.Get("WWW-Authenticate") if strings.HasPrefix(authHeader, "Negotiate") { resp.Body.Close() token, err := tokenProvider() if err != nil { return nil, fmt.Errorf("failed to obtain Kerberos token: %w", err) } retryReq := req.Clone(req.Context()) retryReq.Header.Set("Authorization", "Negotiate "+token) return next(retryReq) } } return resp, nil } } } ``` While the client has [built-in OpenTelemetry support](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/clients/go/advanced/observability), interceptors can add custom observability. Here is a logging interceptor that records request and response details: ```go func LoggingInterceptor() elastictransport.InterceptorFunc { logger := slog.New(slog.NewTextHandler(os.Stdout, nil)) return func(next elastictransport.RoundTripFunc) elastictransport.RoundTripFunc { return func(req *http.Request) (*http.Response, error) { start := time.Now() logger.Info("elasticsearch request started", slog.String("method", req.Method), slog.String("url", req.URL.String()), ) resp, err := next(req) duration := time.Since(start) if err != nil { logger.Error("elasticsearch request failed", slog.Duration("duration", duration), slog.String("error", err.Error()), ) return nil, err } logger.Info("elasticsearch request completed", slog.Int("status_code", resp.StatusCode), slog.Duration("duration", duration), ) return resp, nil } } } ``` You can compose multiple interceptors for logging, metrics, and tracing: ```go es, err := elasticsearch.NewClient(elasticsearch.Config{ Interceptors: []elastictransport.InterceptorFunc{ LoggingInterceptor(), MetricsInterceptor(requestCounter, requestDuration), TracingInterceptor(tracer), }, }) ``` Prefer using the built-in [OpenTelemetry instrumentation](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/clients/go/advanced/observability) over custom interceptors for observability when possible. The built-in support follows OpenTelemetry semantic conventions and provides richer span attributes. Interceptors can be used to monitor internal HTTP behavior, such as counting retry attempts made for a request. An interceptor can track each round-trip attempt by storing a counter in the request context: ```go type attemptCounterKey struct{} // AttemptCounter tracks the number of round-trip attempts for a single // Perform call. Attach it to the request context before calling Perform, // and read it back afterwards. type AttemptCounter struct { value atomic.Int64 } func (c *AttemptCounter) Attempts() int { return int(c.value.Load()) } func (c *AttemptCounter) Retries() int { return max(c.Attempts()-1, 0) } // NewAttemptContext returns a context carrying a fresh AttemptCounter, // along with the counter itself so the caller can inspect it after Perform. func NewAttemptContext(ctx context.Context) (context.Context, *AttemptCounter) { counter := &AttemptCounter{} return context.WithValue(ctx, attemptCounterKey{}, counter), counter } // CountRetriesInterceptor returns an interceptor that increments the // AttemptCounter stored in the request context on every round-trip. func CountRetriesInterceptor() elastictransport.InterceptorFunc { return func(next elastictransport.RoundTripFunc) elastictransport.RoundTripFunc { return func(req *http.Request) (*http.Response, error) { if counter, ok := req.Context().Value(attemptCounterKey{}).(*AttemptCounter); ok { counter.value.Add(1) } return next(req) } } } ``` Usage: ```go es, err := elasticsearch.NewClient(elasticsearch.Config{ Addresses: []string{"https://localhost:9200"}, Interceptors: []elastictransport.InterceptorFunc{ CountRetriesInterceptor(), }, }) // Create a context with an attempt counter ctx, counter := NewAttemptContext(context.Background()) // Perform a request that might be retried res, err := es.Info(es.Info.WithContext(ctx)) if err != nil { log.Fatal(err) } defer res.Body.Close() // Check how many attempts were made fmt.Printf("Request completed after %d attempts (%d retries)\n", counter.Attempts(), counter.Retries()) ``` ## Best practices - **Keep interceptors lightweight.** Interceptors run on every request. Avoid expensive operations like disk I/O or network calls inside the hot path. - **Ordering matters.** Place authentication interceptors before observability interceptors so that traces capture the final request state. - **Always call `next`.** Failing to call `next(req)` will prevent the request from reaching Elasticsearch. Only skip `next` if you intentionally want to short-circuit (e.g., returning a cached response). - **Close response bodies on retry.** If your interceptor retries a request (like the Kerberos example), always close the original response body to avoid resource leaks. - **Use `req.Clone()` for retries.** When retrying, clone the request to avoid mutating the original. - **Handle errors from `next`.** If `next` returns an error, return it to the caller rather than swallowing it.