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}