Package com.tnsai.mcp.client

Interface HttpInterceptor

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface HttpInterceptor
Pluggable hook in the HttpTransport request/response path.

An interceptor sits between the transport and the underlying HttpClient. It receives the outbound request via HttpInterceptor.Chain.request(), may inspect or replace it, calls HttpInterceptor.Chain.proceed(HttpRequest) to forward through any later interceptors and ultimately the network, and finally returns (and may transform) the response.

What it enables

  • Auth refresh — catch 401, mint a fresh token, retry once.
  • Rate limiting — block / queue requests when a token bucket is empty.
  • Tracing / metrics — wrap each call in a span; record latency and status histograms.
  • Payment-aware transport — catch HTTP 402, settle a micropayment, replay the request with payment proof (tracked under TNS-449).

Composition

Interceptors are invoked in the order they were registered with the transport. Each interceptor must call chain.proceed(...) exactly zero or more times:
  • Zero — short-circuit: return a synthetic response (offline cache hit, fast-fail on circuit breaker, etc.).
  • Once — typical pass-through.
  • More than once — retry: examine the response, decide it should be reattempted, call proceed again with a different request.

Threading

The chain executes on the calling thread of HttpTransport.send(String). Implementations must be thread-safe if shared across transports.

Example — payment interceptor sketch

 HttpInterceptor x402 = chain -> {
     HttpResponse<String> response = chain.proceed(chain.request());
     if (response.statusCode() != 402) {
         return response;
     }
     Quote quote = parsePaymentRequirement(response.body());
     Settlement settlement = broker.settle(quote);
     HttpRequest paid = HttpRequest.newBuilder(chain.request(), (n, v) -> true)
         .header("X-PAYMENT", settlement.paymentToken())
         .build();
     return chain.proceed(paid);
 };
Since:
0.10.5

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    HttpInterceptor.Chain
    Forwards a request through the remaining interceptor chain and ultimately the network.

  • Method Summary

    Modifier and Type
    Method
    Description
    HttpResponse<String>
    intercept(HttpInterceptor.Chain chain)
    Invokes this interceptor with the given chain.