Interface ResponseCompressor

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

Selects whether and how the standard HTTP server should compress a finalized in-memory response.

A compressor returns a ResponseCompressionPlan; producing compressed bytes is deferred until the transport needs a response body. The same planning step can therefore select representation metadata for HEAD without invoking a codec or compressed-body provider.

Soklet retains HTTP protocol checks, content-coding negotiation, and response-header handling. Streaming, file, file-channel, ranged, already-encoded, transfer-encoded, and otherwise ineligible responses are not compressed. Otherwise eligible responses carrying Content-Digest, Repr-Digest, Digest, or Content-MD5 also retain their original bytes so application integrity metadata remains valid; if identity coding is excluded, negotiation returns 406. The selected codec's coding is checked against Accept-Encoding after planning; a plan does not force a coding the client cannot accept. Selecting one codec does not register alternative codecs or provide automatic fallback to another compression format.

This hook belongs to the standard HTTP transport. It does not compress SSE or MCP transport responses, and the simulator does not perform transport compression. Compression is disabled by default; use HttpServer.Builder.responseCompressor(ResponseCompressor) to opt in.

Implementations must be thread-safe: Soklet can invoke a compressor concurrently from request-handling threads. Soklet does not create a response cache or retain application data for reuse. Applications that cache compressed bodies own cache keys, bounds, expiration, invalidation, and any separation required for private responses; see ResponseCompressionPlan.

Author:
Mark Allen
  • Method Details

    • disabledInstance

      Acquires a compressor that always selects ResponseCompressionPlan.none().
      Returns:
      a disabled response compressor
    • fromDefaultsWithMinimumBodySizeInBytes

      Acquires a compressor that selects Soklet's built-in gzip codec for common text-like response media types when the finalized uncompressed body is at least minimumBodySizeInBytes.

      The default media-type set includes text/*, application/json, application/*+json, application/xml, application/*+xml, application/javascript, application/graphql, application/x-www-form-urlencoded, and image/svg+xml. This factory provides no cache.

      Parameters:
      minimumBodySizeInBytes - the minimum uncompressed body size to gzip
      Returns:
      a default response compressor
      Throws:
      IllegalArgumentException - if the minimum body size is negative
    • plan

      Selects a compression plan for the finalized uncompressed representation.

      The response exposes its actual uncompressed body, including during planning for HEAD; it has not yet been reduced to a bodyless HEAD response. Return ResponseCompressionPlan.none() to decline compression, or select a codec with ResponseCompressionPlan.compress(ResponseCompressionCodec). A custom compressed-body provider can reuse application-cached bytes without replacing Soklet's HTTP header handling.

      Planning must not compress the body eagerly. Put compression or cache-loading work in the plan's provider so it is skipped when the client cannot accept the selected coding or no body is written. Neither this method nor a plan may mutate the response or its body. A null result or an exception is a response-processing failure, not an instruction to use an uncompressed fallback.

      Parameters:
      request - the request being handled
      marshaledResponse - the finalized uncompressed response representation
      Returns:
      a non-null compression plan