001/* 002 * Copyright 2022-2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.soklet; 018 019import org.jspecify.annotations.NonNull; 020 021import javax.annotation.concurrent.ThreadSafe; 022 023/** 024 * Selects whether and how the standard HTTP server should compress a finalized in-memory response. 025 * <p> 026 * A compressor returns a {@link ResponseCompressionPlan}; producing compressed bytes is deferred until 027 * the transport needs a response body. The same planning step can therefore select representation 028 * metadata for {@code HEAD} without invoking a codec or compressed-body provider. 029 * <p> 030 * Soklet retains HTTP protocol checks, content-coding negotiation, and response-header handling. 031 * Streaming, file, file-channel, ranged, already-encoded, transfer-encoded, and otherwise ineligible 032 * responses are not compressed. Otherwise eligible responses carrying {@code Content-Digest}, {@code Repr-Digest}, 033 * {@code Digest}, or {@code Content-MD5} also retain their original bytes so application integrity 034 * metadata remains valid; if identity coding is excluded, negotiation returns 406. 035 * The selected codec's coding is checked against {@code Accept-Encoding} 036 * after planning; a plan does not force a coding the client cannot accept. Selecting one codec does not 037 * register alternative codecs or provide automatic fallback to another compression format. 038 * <p> 039 * This hook belongs to the standard HTTP transport. It does not compress SSE or MCP transport responses, 040 * and the simulator does not perform transport compression. Compression is disabled by default; use 041 * {@link HttpServer.Builder#responseCompressor(ResponseCompressor)} to opt in. 042 * <p> 043 * Implementations must be thread-safe: Soklet can invoke a compressor concurrently from request-handling 044 * threads. Soklet does not create a response cache or retain application data for reuse. Applications 045 * that cache compressed bodies own cache keys, bounds, expiration, invalidation, and any separation 046 * required for private responses; see {@link ResponseCompressionPlan}. 047 * 048 * @author <a href="https://www.revetkn.com">Mark Allen</a> 049 */ 050@FunctionalInterface 051@ThreadSafe 052public interface ResponseCompressor { 053 /** 054 * Acquires a compressor that always selects {@link ResponseCompressionPlan#none()}. 055 * 056 * @return a disabled response compressor 057 */ 058 @NonNull 059 static ResponseCompressor disabledInstance() { 060 return DisabledResponseCompressor.defaultInstance(); 061 } 062 063 /** 064 * Acquires a compressor that selects Soklet's built-in gzip codec for common text-like response 065 * media types when the finalized uncompressed body is at least {@code minimumBodySizeInBytes}. 066 * <p> 067 * The default media-type set includes {@code text/*}, {@code application/json}, 068 * {@code application/*+json}, {@code application/xml}, {@code application/*+xml}, 069 * {@code application/javascript}, {@code application/graphql}, {@code application/x-www-form-urlencoded}, 070 * and {@code image/svg+xml}. This factory provides no cache. 071 * 072 * @param minimumBodySizeInBytes the minimum uncompressed body size to gzip 073 * @return a default response compressor 074 * @throws IllegalArgumentException if the minimum body size is negative 075 */ 076 @NonNull 077 static ResponseCompressor fromDefaultsWithMinimumBodySizeInBytes(@NonNull Integer minimumBodySizeInBytes) { 078 return new DefaultResponseCompressor(minimumBodySizeInBytes); 079 } 080 081 /** 082 * Selects a compression plan for the finalized uncompressed representation. 083 * <p> 084 * The response exposes its actual uncompressed body, including during planning for {@code HEAD}; 085 * it has not yet been reduced to a bodyless HEAD response. Return {@link ResponseCompressionPlan#none()} 086 * to decline compression, or select a codec with {@link ResponseCompressionPlan#compress(ResponseCompressionCodec)}. 087 * A custom compressed-body provider can reuse application-cached bytes without replacing Soklet's 088 * HTTP header handling. 089 * <p> 090 * Planning must not compress the body eagerly. Put compression or cache-loading work in the plan's 091 * provider so it is skipped when the client cannot accept the selected coding or no body is written. 092 * Neither this method nor a plan may mutate the response or its body. A null result or an exception 093 * is a response-processing failure, not an instruction to use an uncompressed fallback. 094 * 095 * @param request the request being handled 096 * @param marshaledResponse the finalized uncompressed response representation 097 * @return a non-null compression plan 098 */ 099 @NonNull 100 ResponseCompressionPlan plan(@NonNull Request request, 101 @NonNull MarshaledResponse marshaledResponse); 102}