/*
 * Copyright 2022-2026 Revetware LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.soklet;

import com.soklet.exception.IllegalRequestException;
import com.soklet.internal.spring.LinkedCaseInsensitiveMap;
import com.soklet.internal.util.HostHeaderValidator;
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import javax.annotation.concurrent.ThreadSafe;
import java.io.ByteArrayOutputStream;
import java.lang.Thread.UncaughtExceptionHandler;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.invoke.MethodHandles.Lookup;
import java.lang.invoke.MethodType;
import java.net.InetAddress;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URLEncoder;
import java.net.UnknownHostException;
import java.nio.charset.Charset;
import java.nio.charset.IllegalCharsetNameException;
import java.nio.charset.StandardCharsets;
import java.nio.charset.UnsupportedCharsetException;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Comparator;
import java.util.Deque;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Locale.LanguageRange;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;
import java.util.function.Predicate;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import static java.lang.String.format;
import static java.util.Objects.requireNonNull;

/**
 * A non-instantiable collection of utility methods.
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 */
@ThreadSafe
public final class Utilities {
        private static final boolean VIRTUAL_THREADS_AVAILABLE;
        private static final byte @NonNull [] EMPTY_BYTE_ARRAY;
        @NonNull
        private static final Pattern HEAD_WHITESPACE_PATTERN;
        @NonNull
        private static final Pattern TAIL_WHITESPACE_PATTERN;
        @NonNull
        private static final Pattern HEADER_PERCENT_ENCODING_PATTERN;

        static {
                EMPTY_BYTE_ARRAY = new byte[0];

                boolean virtualThreadsAvailable = false;

                try {
                        // Detect if Virtual Threads are usable by feature testing via reflection.
                        // Hat tip to https://github.com/javalin/javalin for this technique
                        Class.forName("java.lang.Thread$Builder$OfVirtual");
                        virtualThreadsAvailable = true;
                } catch (Exception ignored) {
                        // We don't care why this failed, but if we're here we know JVM does not support virtual threads
                }

                VIRTUAL_THREADS_AVAILABLE = virtualThreadsAvailable;

                // See https://www.regular-expressions.info/unicode.html
                // \p{Z} or \p{Separator}: Unicode space-separator characters.
                //
                // First pattern matches those separator characters at the head of a string, second matches the same for tail.
                // Useful for a "stronger" trim() function, which is almost always what we want in a web context
                // with user-supplied input.
                HEAD_WHITESPACE_PATTERN = Pattern.compile("^(\\p{Z})+");
                TAIL_WHITESPACE_PATTERN = Pattern.compile("(\\p{Z})+$");

                HEADER_PERCENT_ENCODING_PATTERN = Pattern.compile("%([0-9A-Fa-f]{2})");
        }

        private Utilities() {
                // Non-instantiable
        }

        /**
         * Does the platform runtime support virtual threads (either Java 19 and 20 w/preview enabled or Java 21+)?
         *
         * @return {@code true} if the runtime supports virtual threads, {@code false} otherwise
         */
        @NonNull
        static Boolean virtualThreadsAvailable() {
                return VIRTUAL_THREADS_AVAILABLE;
        }

        /**
         * Provides a virtual thread factory if supported by the runtime.
         * <p>
         * In order to support Soklet users who are not yet ready to enable virtual threads (those <strong>not</strong> running either Java 19 and 20 w/preview enabled or Java 21+),
         * we compile Soklet with a source level &lt; 19 and avoid any hard references to virtual threads by dynamically creating our {@link ThreadFactory} via {@link MethodHandle} references.
         * <p>
         * <strong>You should not call this method if {@link Utilities#virtualThreadsAvailable()} is {@code false}.</strong>
         *
         * @param threadNamePrefix         thread name prefix for the virtual thread factory builder
         * @param uncaughtExceptionHandler uncaught exception handler for the virtual thread factory builder
         * @return a virtual thread factory
         * @throws IllegalStateException if the runtime environment does not support virtual threads
         */
        @NonNull
        static ThreadFactory createVirtualThreadFactory(@NonNull String threadNamePrefix,
                                                                                                                                                                                                        @NonNull UncaughtExceptionHandler uncaughtExceptionHandler) {
                requireNonNull(threadNamePrefix);
                requireNonNull(uncaughtExceptionHandler);

                if (!virtualThreadsAvailable())
                        throw new IllegalStateException("Virtual threads are not available. Please confirm you are using Java 19-20 with the '--enable-preview' javac parameter specified or Java 21+");

                // Hat tip to https://github.com/javalin/javalin for this technique
                Class<?> threadBuilderOfVirtualClass;

                try {
                        threadBuilderOfVirtualClass = Class.forName("java.lang.Thread$Builder$OfVirtual");
                } catch (ClassNotFoundException e) {
                        throw new IllegalStateException("Unable to load virtual thread builder class", e);
                }

                Lookup lookup = MethodHandles.publicLookup();

                MethodHandle methodHandleThreadOfVirtual;
                MethodHandle methodHandleThreadBuilderOfVirtualName;
                MethodHandle methodHandleThreadBuilderOfVirtualUncaughtExceptionHandler;
                MethodHandle methodHandleThreadBuilderOfVirtualFactory;

                try {
                        methodHandleThreadOfVirtual = lookup.findStatic(Thread.class, "ofVirtual", MethodType.methodType(threadBuilderOfVirtualClass));
                        methodHandleThreadBuilderOfVirtualName = lookup.findVirtual(threadBuilderOfVirtualClass, "name", MethodType.methodType(threadBuilderOfVirtualClass, String.class, long.class));
                        methodHandleThreadBuilderOfVirtualUncaughtExceptionHandler = lookup.findVirtual(threadBuilderOfVirtualClass, "uncaughtExceptionHandler", MethodType.methodType(threadBuilderOfVirtualClass, UncaughtExceptionHandler.class));
                        methodHandleThreadBuilderOfVirtualFactory = lookup.findVirtual(threadBuilderOfVirtualClass, "factory", MethodType.methodType(ThreadFactory.class));
                } catch (NoSuchMethodException | IllegalAccessException e) {
                        throw new IllegalStateException("Unable to load method handle for virtual thread factory", e);
                }

                try {
                        // Thread.ofVirtual()
                        Object virtualThreadBuilder = methodHandleThreadOfVirtual.invoke();
                        // .name(threadNamePrefix, start)
                        methodHandleThreadBuilderOfVirtualName.invoke(virtualThreadBuilder, threadNamePrefix, 1);
                        // .uncaughtExceptionHandler(uncaughtExceptionHandler)
                        methodHandleThreadBuilderOfVirtualUncaughtExceptionHandler.invoke(virtualThreadBuilder, uncaughtExceptionHandler);
                        // .factory();
                        return (ThreadFactory) methodHandleThreadBuilderOfVirtualFactory.invoke(virtualThreadBuilder);
                } catch (Throwable t) {
                        throw new IllegalStateException("Unable to create virtual thread factory", t);
                }
        }

        /**
         * Provides a virtual-thread-per-task executor service if supported by the runtime.
         * <p>
         * In order to support Soklet users who are not yet ready to enable virtual threads (those <strong>not</strong> running either Java 19 and 20 w/preview enabled or Java 21+),
         * we compile Soklet with a source level &lt; 19 and avoid any hard references to virtual threads by dynamically creating our executor service via {@link MethodHandle} references.
         * <p>
         * <strong>You should not call this method if {@link Utilities#virtualThreadsAvailable()} is {@code false}.</strong>
         * <pre>{@code // This method is effectively equivalent to this code
         * return Executors.newThreadPerTaskExecutor(
         *   Thread.ofVirtual()
         *    .name(threadNamePrefix)
         *    .uncaughtExceptionHandler(uncaughtExceptionHandler)
         *    .factory()
         * );}</pre>
         *
         * @param threadNamePrefix         thread name prefix for the virtual thread factory builder
         * @param uncaughtExceptionHandler uncaught exception handler for the virtual thread factory builder
         * @return a virtual-thread-per-task executor service
         * @throws IllegalStateException if the runtime environment does not support virtual threads
         */
        @NonNull
        static ExecutorService createVirtualThreadsNewThreadPerTaskExecutor(@NonNull String threadNamePrefix,
                                                                                                                                                                                                                                                                                        @NonNull UncaughtExceptionHandler uncaughtExceptionHandler) {
                requireNonNull(threadNamePrefix);
                requireNonNull(uncaughtExceptionHandler);

                if (!virtualThreadsAvailable())
                        throw new IllegalStateException("Virtual threads are not available. Please confirm you are using Java 19-20 with the '--enable-preview' javac parameter specified or Java 21+");

                ThreadFactory threadFactory = createVirtualThreadFactory(threadNamePrefix, uncaughtExceptionHandler);

                Lookup lookup = MethodHandles.publicLookup();
                MethodHandle methodHandleExecutorsNewThreadPerTaskExecutor;

                try {
                        methodHandleExecutorsNewThreadPerTaskExecutor = lookup.findStatic(Executors.class, "newThreadPerTaskExecutor", MethodType.methodType(ExecutorService.class, ThreadFactory.class));
                } catch (NoSuchMethodException | IllegalAccessException e) {
                        throw new IllegalStateException("Unable to load method handle for virtual thread factory", e);
                }

                try {
                        // return Executors.newThreadPerTaskExecutor(threadFactory);
                        return (ExecutorService) methodHandleExecutorsNewThreadPerTaskExecutor.invoke(threadFactory);
                } catch (Throwable t) {
                        throw new IllegalStateException("Unable to create virtual thread executor service", t);
                }
        }

        /**
         * Returns a shared zero-length {@code byte[]} instance.
         * <p>
         * Useful as a sentinel when you need a non-{@code null} byte array but have no content.
         *
         * @return a zero-length byte array (never {@code null})
         */
        static byte @NonNull [] emptyByteArray() {
                return EMPTY_BYTE_ARRAY;
        }

        /**
         * Parses a query string such as {@code "a=1&b=2&c=%20"} into a multimap of names to values.
         * <p>
         * Decodes percent-escapes using UTF-8, which is usually what you want (see {@link #extractQueryParametersFromQuery(String, QueryFormat, Charset)} if you need to specify a different charset).
         * <p>
         * Pairs missing a name are ignored.
         * <p>
         * Multiple occurrences of the same name are collected into a {@link Set} in insertion order (duplicates are de-duplicated).
         *
         * @param query       a raw query string such as {@code "a=1&b=2&c=%20"}
         * @param queryFormat how to decode: {@code application/x-www-form-urlencoded} or "strict" RFC 3986
         * @return a map of parameter names to their distinct values, preserving first-seen name order; empty if none
         * @throws IllegalRequestException if the query string contains malformed percent-encoding
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractQueryParametersFromQuery(@NonNull String query,
                                                                                                                                                                                                                                                                                                                                                                                                                @NonNull QueryFormat queryFormat) {
                requireNonNull(query);
                requireNonNull(queryFormat);

                return extractQueryParametersFromQuery(query, queryFormat, StandardCharsets.UTF_8);
        }

        /**
         * Parses a query string such as {@code "a=1&b=2&c=%20"} into a multimap of names to values.
         * <p>
         * Decodes percent-escapes using the specified charset.
         * <p>
         * Pairs missing a name are ignored.
         * <p>
         * Multiple occurrences of the same name are collected into a {@link Set} in insertion order (duplicates are de-duplicated).
         *
         * @param query       a raw query string such as {@code "a=1&b=2&c=%20"}
         * @param queryFormat how to decode: {@code application/x-www-form-urlencoded} or "strict" RFC 3986
         * @param charset     the charset to use when decoding percent-escapes
         * @return a map of parameter names to their distinct values, preserving first-seen name order; empty if none
         * @throws IllegalRequestException if the query string contains malformed percent-encoding
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractQueryParametersFromQuery(@NonNull String query,
                                                                                                                                                                                                                                                                                                                                                                                                                @NonNull QueryFormat queryFormat,
                                                                                                                                                                                                                                                                                                                                                                                                                @NonNull Charset charset) {
                requireNonNull(query);
                requireNonNull(queryFormat);
                requireNonNull(charset);

                // For form parameters, body will look like "One=Two&Three=Four" ...a query string.
                String syntheticUrl = format("https://soklet.invalid?%s", query); // avoid referencing real domain
                return extractQueryParametersFromUrl(syntheticUrl, queryFormat, charset);
        }

        @NonNull
        static Optional<Set<@NonNull String>> extractQueryParameterValuesFromQuery(@NonNull String query,
                                                                                                                                                                                                                                                                                                                 @NonNull String name,
                                                                                                                                                                                                                                                                                                                 @NonNull QueryFormat queryFormat,
                                                                                                                                                                                                                                                                                                                 @NonNull Charset charset) {
                requireNonNull(query);
                requireNonNull(name);
                requireNonNull(queryFormat);
                requireNonNull(charset);

                query = trimAggressivelyToEmpty(query);

                if (query.isEmpty())
                        return Optional.empty();

                String singleValue = null;
                Set<String> values = null;
                boolean matched = false;
                int pairStart = 0;

                while (pairStart <= query.length()) {
                        int pairEnd = query.indexOf('&', pairStart);
                        if (pairEnd == -1)
                                pairEnd = query.length();

                        if (pairEnd > pairStart) {
                                int separator = query.indexOf('=', pairStart);
                                if (separator == -1 || separator > pairEnd)
                                        separator = pairEnd;

                                String rawName = trimAggressivelyToNull(query.substring(pairStart, separator));

                                if (rawName != null) {
                                        String decodedName = decodeQueryComponent(rawName, queryFormat, charset);

                                        if (decodedName.equals(name)) {
                                                String rawValue = separator < pairEnd ? trimAggressivelyToNull(query.substring(separator + 1, pairEnd)) : null;

                                                if (rawValue == null)
                                                        rawValue = "";

                                                String value = decodeQueryComponent(rawValue, queryFormat, charset);

                                                if (!matched) {
                                                        singleValue = value;
                                                        matched = true;
                                                } else {
                                                        if (values == null) {
                                                                values = new LinkedHashSet<>();
                                                                values.add(singleValue);
                                                        }

                                                        values.add(value);
                                                }
                                        }
                                }
                        }

                        if (pairEnd == query.length())
                                break;

                        pairStart = pairEnd + 1;
                }

                if (!matched)
                        return Optional.empty();

                if (values == null)
                        return Optional.of(Set.of(singleValue));

                return Optional.of(Collections.unmodifiableSet(values));
        }

        /**
         * Parses query strings from relative or absolute URLs such as {@code "/example?a=a=1&b=2&c=%20"} or {@code "https://www.soklet.com/example?a=1&b=2&c=%20"} into a multimap of names to values.
         * <p>
         * Decodes percent-escapes using UTF-8, which is usually what you want (see {@link #extractQueryParametersFromUrl(String, QueryFormat, Charset)} if you need to specify a different charset).
         * <p>
         * Pairs missing a name are ignored.
         * <p>
         * Multiple occurrences of the same name are collected into a {@link Set} in insertion order (duplicates are de-duplicated).
         *
         * @param url         a relative or absolute URL/URI string
         * @param queryFormat how to decode: {@code application/x-www-form-urlencoded} or "strict" RFC 3986
         * @return a map of parameter names to their distinct values, preserving first-seen name order; empty if none
         * @throws IllegalRequestException if the URL or query contains malformed percent-encoding
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractQueryParametersFromUrl(@NonNull String url,
                                                                                                                                                                                                                                                                                                                                                                                                        @NonNull QueryFormat queryFormat) {
                requireNonNull(url);
                requireNonNull(queryFormat);

                return extractQueryParametersFromUrl(url, queryFormat, StandardCharsets.UTF_8);
        }

        /**
         * Parses query strings from relative or absolute URLs such as {@code "/example?a=a=1&b=2&c=%20"} or {@code "https://www.soklet.com/example?a=1&b=2&c=%20"} into a multimap of names to values.
         * <p>
         * Decodes percent-escapes using the specified charset.
         * <p>
         * Pairs missing a name are ignored.
         * <p>
         * Multiple occurrences of the same name are collected into a {@link Set} in insertion order (duplicates are de-duplicated).
         *
         * @param url         a relative or absolute URL/URI string
         * @param queryFormat how to decode: {@code application/x-www-form-urlencoded} or "strict" RFC 3986
         * @param charset     the charset to use when decoding percent-escapes
         * @return a map of parameter names to their distinct values, preserving first-seen name order; empty if none
         * @throws IllegalRequestException if the URL or query contains malformed percent-encoding
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractQueryParametersFromUrl(@NonNull String url,
                                                                                                                                                                                                                                                                                                                                                                                                        @NonNull QueryFormat queryFormat,
                                                                                                                                                                                                                                                                                                                                                                                                        @NonNull Charset charset) {
                requireNonNull(url);
                requireNonNull(queryFormat);
                requireNonNull(charset);

                URI uri;

                try {
                        uri = new URI(url);
                } catch (URISyntaxException e) {
                        throw new IllegalRequestException(format("Invalid URL '%s'", url), e);
                }

                String query = trimAggressivelyToNull(uri.getRawQuery());

                if (query == null)
                        return Map.of();

                Map<String, Set<String>> queryParameters = new LinkedHashMap<>();
                for (String pair : query.split("&", -1)) {
                        if (pair.isEmpty())
                                continue;

                        String[] nv = pair.split("=", 2);
                        String rawName = trimAggressivelyToNull(nv.length > 0 ? nv[0] : null);
                        String rawValue = trimAggressivelyToNull(nv.length > 1 ? nv[1] : null);

                        if (rawName == null)
                                continue;

                        // Preserve empty values; it's what users probably expect
                        if (rawValue == null)
                                rawValue = "";

                        String name = decodeQueryComponent(rawName, queryFormat, charset);
                        String value = decodeQueryComponent(rawValue, queryFormat, charset);

                        addStringValue(queryParameters, name, value);
                }

                freezeStringValueSets(queryParameters);
                return queryParameters;
        }

        /**
         * Decodes a single key or value using the given mode and charset.
         */
        @NonNull
        private static String decodeQueryComponent(@NonNull String string,
                                                                                                                                                                                 @NonNull QueryFormat queryFormat,
                                                                                                                                                                                 @NonNull Charset charset) {
                requireNonNull(string);
                requireNonNull(queryFormat);
                requireNonNull(charset);

                if (string.isEmpty())
                        return "";

                // Step 1: in form mode, '+' means space
                String prepped = (queryFormat == QueryFormat.X_WWW_FORM_URLENCODED) ? string.replace('+', ' ') : string;
                // Step 2: percent-decode bytes, then interpret bytes with the provided charset
                return percentDecode(prepped, charset);
        }

        /**
         * Percent-decodes a string into bytes, then constructs a String using the provided charset.
         * One pass only: invalid %xy sequences trigger an exception.
         */
        @NonNull
        private static String percentDecode(@NonNull String s, @NonNull Charset charset) {
                requireNonNull(s);
                requireNonNull(charset);

                if (s.isEmpty())
                        return "";

                StringBuilder sb = new StringBuilder(s.length());
                ByteArrayOutputStream bytes = new ByteArrayOutputStream();

                for (int i = 0; i < s.length(); ) {
                        char c = s.charAt(i);

                        if (c == '%') {
                                // Consume one or more consecutive %xx triplets into bytes
                                bytes.reset();
                                int j = i;

                                while (j < s.length() && s.charAt(j) == '%') {
                                        if (j + 2 >= s.length())
                                                throw new IllegalRequestException("Invalid percent-encoding in URL component");

                                        int hi = hex(s.charAt(j + 1));
                                        int lo = hex(s.charAt(j + 2));
                                        if (hi < 0 || lo < 0)
                                                throw new IllegalRequestException("Invalid percent-encoding in URL component");

                                        bytes.write((hi << 4) | lo);
                                        j += 3;
                                }

                                sb.append(new String(bytes.toByteArray(), charset));
                                i = j;
                                continue;
                        }

                        // Non-'%' char: append it as-is.
                        // This preserves surrogate pairs naturally as the loop hits both chars.
                        sb.append(c);
                        i++;
                }

                return sb.toString();
        }

        static void validatePercentEncodingInUrlComponent(@NonNull String urlComponent) {
                requireNonNull(urlComponent);

                for (int i = 0; i < urlComponent.length(); i++) {
                        if (urlComponent.charAt(i) != '%')
                                continue;

                        if (i + 2 >= urlComponent.length())
                                throw new IllegalRequestException("Invalid percent-encoding in URL component");

                        int hi = hex(urlComponent.charAt(i + 1));
                        int lo = hex(urlComponent.charAt(i + 2));
                        if (hi < 0 || lo < 0)
                                throw new IllegalRequestException("Invalid percent-encoding in URL component");

                        i += 2;
                }
        }

        private static int hex(char c) {
                if (c >= '0' && c <= '9') return c - '0';
                if (c >= 'A' && c <= 'F') return c - 'A' + 10;
                if (c >= 'a' && c <= 'f') return c - 'a' + 10;
                return -1;
        }

        /**
         * Parses {@code Cookie} request headers into a map of cookie names to values.
         * <p>
         * Header name matching is case-insensitive ({@code "Cookie"} vs {@code "cookie"}), but <em>cookie names are case-sensitive</em>.
         * Values are parsed per the following liberal rules:
         * <ul>
         *   <li>Components are split on {@code ';'} unless inside a quoted string.</li>
         *   <li>Quoted values have surrounding quotes removed and common backslash escapes unescaped.</li>
         *   <li>Percent-escapes are decoded as UTF-8. {@code '+'} is <strong>not</strong> treated specially.</li>
         * </ul>
         * Multiple occurrences of the same cookie name are collected into a {@link Set} in insertion order.
         *
         * @param headers request headers as a multimap of header name to values (must be non-{@code null})
         * @return a map of cookie name to distinct values; empty if no valid cookies are present
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractCookiesFromHeaders(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers) {
                requireNonNull(headers);

                // Cookie *names* must be case-sensitive; keep LinkedHashMap (NOT case-insensitive)
                Map<String, Set<String>> cookies = new LinkedHashMap<>();

                for (Entry<String, Set<String>> entry : headers.entrySet()) {
                        String headerName = entry.getKey();
                        if (headerName == null || !"cookie".equalsIgnoreCase(headerName.trim()))
                                continue;

                        Set<String> values = entry.getValue();
                        if (values == null) continue;

                        for (String headerValue : values) {
                                headerValue = trimAggressivelyToNull(headerValue);
                                if (headerValue == null) continue;

                                // Split on ';' only when NOT inside a quoted string
                                List<String> cookieComponents = splitCookieHeaderRespectingQuotes(headerValue);

                                for (String cookieComponent : cookieComponents) {
                                        cookieComponent = trimAggressivelyToNull(cookieComponent);
                                        if (cookieComponent == null) continue;

                                        String[] cookiePair = cookieComponent.split("=", 2);
                                        String rawName = trimAggressivelyToNull(cookiePair[0]);
                                        String rawValue = (cookiePair.length == 2 ? trimAggressivelyToNull(cookiePair[1]) : null);

                                        if (rawName == null) continue;

                                        // DO NOT decode the name; cookie names are case-sensitive and rarely encoded
                                        String cookieName = rawName;

                                        String cookieValue = null;
                                        if (rawValue != null) {
                                                // If it's quoted, unquote+unescape first, then percent-decode (still no '+' -> space)
                                                String unquoted = unquoteCookieValueIfNeeded(rawValue);
                                                cookieValue = percentDecodeCookieValue(unquoted);
                                        }

                                        cookies.putIfAbsent(cookieName, Set.of());
                                        if (cookieValue != null)
                                                addStringValue(cookies, cookieName, cookieValue);
                                }
                        }
                }

                freezeStringValueSets(cookies);
                return cookies;
        }

        /**
         * Percent-decodes %HH to bytes->UTF-8. Does NOT treat '+' specially.
         */
        @NonNull
        private static String percentDecodeCookieValue(@NonNull String cookieValue) {
                requireNonNull(cookieValue);

                ByteArrayOutputStream out = new ByteArrayOutputStream(cookieValue.length());

                for (int i = 0; i < cookieValue.length(); ) {
                        char c = cookieValue.charAt(i);
                        if (c == '%') {
                                if (i + 2 >= cookieValue.length())
                                        throw new IllegalRequestException("Invalid percent-encoding in Cookie header");

                                int hi = Character.digit(cookieValue.charAt(i + 1), 16);
                                int lo = Character.digit(cookieValue.charAt(i + 2), 16);
                                if (hi < 0 || lo < 0)
                                        throw new IllegalRequestException("Invalid percent-encoding in Cookie header");

                                out.write((hi << 4) + lo);
                                i += 3;
                                continue;
                        }

                        String rawCharacter;

                        if (Character.isHighSurrogate(c) && i + 1 < cookieValue.length() && Character.isLowSurrogate(cookieValue.charAt(i + 1))) {
                                rawCharacter = cookieValue.substring(i, i + 2);
                                i += 2;
                        } else {
                                rawCharacter = Character.toString(c);
                                i++;
                        }

                        byte[] encoded = rawCharacter.getBytes(StandardCharsets.UTF_8);
                        out.write(encoded, 0, encoded.length);
                }

                return out.toString(StandardCharsets.UTF_8);
        }

        /**
         * Splits a Cookie header string into components on ';' but ONLY when not inside a quoted value.
         * Supports backslash-escaped quotes within quoted strings.
         */
        private static List<@NonNull String> splitCookieHeaderRespectingQuotes(@NonNull String headerValue) {
                List<String> parts = new ArrayList<>();
                StringBuilder cur = new StringBuilder(headerValue.length());
                boolean inQuotes = false;
                boolean escape = false;

                for (int i = 0; i < headerValue.length(); i++) {
                        char c = headerValue.charAt(i);

                        if (escape) {
                                // keep escaped char literally (e.g., \" \; \\)
                                cur.append(c);
                                escape = false;
                                continue;
                        }

                        if (c == '\\') {
                                escape = true;
                                // keep the backslash for now; unquote step will handle unescaping
                                cur.append(c);
                                continue;
                        }

                        if (c == '"') {
                                inQuotes = !inQuotes;
                                cur.append(c);
                                continue;
                        }

                        if (c == ';' && !inQuotes) {
                                parts.add(cur.toString());
                                cur.setLength(0);
                                continue;
                        }

                        cur.append(c);
                }

                if (cur.length() > 0)
                        parts.add(cur.toString());

                return parts;
        }

        /**
         * If the cookie value is a quoted-string, remove surrounding quotes and unescape \" \\ and \; .
         * Otherwise returns the input as-is.
         */
        @NonNull
        private static String unquoteCookieValueIfNeeded(@NonNull String rawValue) {
                requireNonNull(rawValue);

                if (rawValue.length() >= 2 && rawValue.charAt(0) == '"' && rawValue.charAt(rawValue.length() - 1) == '"') {
                        // Strip the surrounding quotes
                        String inner = rawValue.substring(1, rawValue.length() - 1);

                        // Unescape \" \\ and \; (common patterns seen in the wild)
                        // Order matters: unescape backslash-escape sequences, then leave other chars intact.
                        StringBuilder sb = new StringBuilder(inner.length());
                        boolean escape = false;

                        for (int i = 0; i < inner.length(); i++) {
                                char c = inner.charAt(i);
                                if (escape) {
                                        // Keep the escaped character literally (liberal in what we accept).
                                        sb.append(c);

                                        escape = false;
                                } else if (c == '\\') {
                                        escape = true;
                                } else {
                                        sb.append(c);
                                }
                        }

                        // If string ended with a dangling backslash, keep it literally
                        if (escape)
                                sb.append('\\');

                        return sb.toString();
                }

                return rawValue;
        }

        /**
         * Normalizes a URL or path into a canonical request path and optionally performs percent-decoding on the path.
         * <p>
         * For example, {@code "https://www.soklet.com/ab%20c?one=two"} would be normalized to {@code "/ab c"}.
         * <p>
         * The {@code OPTIONS *} special case returns {@code "*"}.
         * <p>
         * Behavior:
         * <ul>
         *   <li>If input starts with {@code http://} or {@code https://}, the path portion is extracted.</li>
         *   <li>Ensures the result begins with {@code '/'}.</li>
         *   <li>Removes any trailing {@code '/'} (except for the root path {@code '/'}).</li>
         *   <li>Safely normalizes path traversals, e.g. path {@code '/a/../b'} would be normalized to {@code '/b'}</li>
         *   <li>Strips any query string.</li>
         *   <li>Applies aggressive trimming of Unicode whitespace.</li>
         *   <li>Rejects malformed percent-encoding when decoding is enabled.</li>
         * </ul>
         *
         * @param url             a URL or path to normalize
         * @param performDecoding {@code true} if decoding should be performed on the path (e.g. replace {@code %20} with a space character), {@code false} otherwise
         * @return the normalized path, {@code "/"} for empty input
         */
        @NonNull
        public static String extractPathFromUrl(@NonNull String url,
                                                                                                                                                                        @NonNull Boolean performDecoding) {
                requireNonNull(url);

                url = trimAggressivelyToEmpty(url);

                // Special case for OPTIONS * requests
                if (url.equals("*"))
                        return "*";

                // Parse with java.net.URI to isolate raw path; then percent-decode only the path
                try {
                        URI uri = new URI(url);

                        String rawPath = uri.getRawPath(); // null => "/"

                        if (rawPath == null || rawPath.isEmpty())
                                rawPath = "/";

                        if (!performDecoding)
                                return rawPath;

                        String decodedPath = percentDecode(rawPath, StandardCharsets.UTF_8);

                        // Sanitize path traversal (e.g. /a/../b -> /b)
                        decodedPath = removeDotSegments(decodedPath);

                        // Normalize trailing slashes like normalizedPathForUrl currently does
                        if (!decodedPath.startsWith("/"))
                                decodedPath = "/" + decodedPath;

                        if (!"/".equals(decodedPath))
                                while (decodedPath.endsWith("/"))
                                        decodedPath = decodedPath.substring(0, decodedPath.length() - 1);

                        return decodedPath;
                } catch (URISyntaxException e) {
                        // If it's not an absolute URL, treat the whole string as a path and percent-decode
                        String path = url;
                        int q = path.indexOf('?');

                        if (q != -1)
                                path = path.substring(0, q);

                        if (path.isEmpty())
                                path = "/";

                        if (!performDecoding)
                                return path;

                        String decodedPath = percentDecode(path, StandardCharsets.UTF_8);

                        // Sanitize path traversal (e.g. /a/../b -> /b)
                        decodedPath = removeDotSegments(decodedPath);

                        if (!decodedPath.startsWith("/"))
                                decodedPath = "/" + decodedPath;

                        if (!"/".equals(decodedPath))
                                while (decodedPath.endsWith("/"))
                                        decodedPath = decodedPath.substring(0, decodedPath.length() - 1);

                        return decodedPath;
                }
        }

        /**
         * Extracts the raw (un-decoded) query component from a URL.
         * <p>
         * For example, {@code "/path?a=b&c=d%20e"} would return {@code "a=b&c=d%20e"}.
         *
         * @param url a raw URL or path
         * @return the raw query component, or {@link Optional#empty()} if none
         */
        @NonNull
        public static Optional<String> extractRawQueryFromUrl(@NonNull String url) {
                requireNonNull(url);

                url = trimAggressivelyToEmpty(url);

                if ("*".equals(url))
                        return Optional.empty();

                try {
                        URI uri = new URI(url);
                        return Optional.ofNullable(trimAggressivelyToNull(uri.getRawQuery()));
                } catch (URISyntaxException e) {
                        // Not a valid URI, try to extract query manually
                        int q = url.indexOf('?');
                        if (q == -1)
                                return Optional.empty();

                        String query = trimAggressivelyToNull(url.substring(q + 1));
                        return Optional.ofNullable(query);
                }
        }

        @NonNull
        static Optional<String> extractRawQueryFromUrlStrict(@NonNull String url) {
                requireNonNull(url);

                url = trimAggressivelyToEmpty(url);

                if ("*".equals(url))
                        return Optional.empty();

                try {
                        URI uri = new URI(url);
                        return Optional.ofNullable(trimAggressivelyToNull(uri.getRawQuery()));
                } catch (URISyntaxException e) {
                        throw new IllegalRequestException(format("Invalid URL '%s'", url), e);
                }
        }

        /**
         * Encodes decoded query parameters into a raw query string.
         * <p>
         * For example, given {@code {a=[b], c=[d e]}} and {@link QueryFormat#RFC_3986_STRICT},
         * returns {@code "a=b&c=d%20e"}.
         *
         * @param queryParameters the decoded query parameters
         * @param queryFormat     the encoding strategy
         * @return the encoded query string, or the empty string if no parameters
         */
        @NonNull
        public static String encodeQueryParameters(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> queryParameters,
                                                                                                                                                                                 @NonNull QueryFormat queryFormat) {
                requireNonNull(queryParameters);
                requireNonNull(queryFormat);

                if (queryParameters.isEmpty())
                        return "";

                StringBuilder sb = new StringBuilder();
                boolean first = true;

                for (Entry<String, Set<String>> entry : queryParameters.entrySet()) {
                        String encodedName = encodeQueryComponent(entry.getKey(), queryFormat);

                        for (String value : entry.getValue()) {
                                if (!first)
                                        sb.append('&');

                                sb.append(encodedName);
                                sb.append('=');
                                sb.append(encodeQueryComponent(value, queryFormat));

                                first = false;
                        }
                }

                return sb.toString();
        }

        @NonNull
        static String encodeQueryComponent(@NonNull String queryComponent,
                                                                                                                                                 @NonNull QueryFormat queryFormat) {
                requireNonNull(queryComponent);
                requireNonNull(queryFormat);

                String encoded = URLEncoder.encode(queryComponent, StandardCharsets.UTF_8);

                if (queryFormat == QueryFormat.RFC_3986_STRICT)
                        encoded = encoded.replace("+", "%20");

                return encoded;
        }

        @NonNull
        static String encodePath(@NonNull String path) {
                requireNonNull(path);

                if ("*".equals(path))
                        return path;

                // Encode each path segment individually, preserving '/' separators.
                // RFC 3986 is used for path encoding (spaces as %20, not +).
                return Arrays.stream(path.split("/", -1))
                                .map(segment -> URLEncoder.encode(segment, StandardCharsets.UTF_8).replace("+", "%20"))
                                .collect(Collectors.joining("/"));
        }

        /**
         * Parses an {@code Accept-Language} header value into a best-effort ordered list of {@link Locale}s.
         * <p>
         * Quality weights are honored by {@link Locale.LanguageRange#parse(String)}; results are then converted to
         * {@link Locale} instances that represent the client-supplied language tags. Wildcard ranges are ignored unless
         * they include a language component (e.g. {@code en-*} becomes {@code en}). On parse failure, an empty list is
         * returned.
         *
         * @param acceptLanguageHeaderValue the raw header value (must be non-{@code null})
         * @return locales in descending preference order; empty if none could be resolved
         */
        @NonNull
        public static List<@NonNull Locale> extractLocalesFromAcceptLanguageHeaderValue(@NonNull String acceptLanguageHeaderValue) {
                requireNonNull(acceptLanguageHeaderValue);

                try {
                        List<LanguageRange> languageRanges = LanguageRange.parse(acceptLanguageHeaderValue);
                        List<Locale> locales = new ArrayList<>(languageRanges.size());

                        for (LanguageRange languageRange : languageRanges) {
                                if (!(languageRange.getWeight() > 0.0))
                                        continue;

                                String range = languageRange.getRange();
                                String languageTag = range;

                                if (range.indexOf('*') != -1) {
                                        int wildcardIndex = range.indexOf('*');

                                        if (wildcardIndex == 0)
                                                continue;

                                        int languageEndIndex = range.indexOf('-');

                                        if (languageEndIndex == -1 || languageEndIndex > wildcardIndex)
                                                languageEndIndex = wildcardIndex;

                                        languageTag = range.substring(0, languageEndIndex);
                                }

                                if (languageTag.isBlank())
                                        continue;

                                Locale locale = Locale.forLanguageTag(languageTag);

                                if (!locale.getLanguage().isBlank() && !locales.contains(locale))
                                        locales.add(locale);
                        }

                        return Collections.unmodifiableList(locales);
                } catch (Exception ignored) {
                        return List.of();
                }
        }

        /**
         * Parses an {@code Accept} header value into a best-effort ordered list of {@link MediaRange}s.
         * <p>
         * Media ranges are ordered by descending {@code q} weight, then by descending specificity:
         * a concrete {@code type/subtype} outranks {@code type/*}, which outranks {@code *}{@code /*};
         * within the same wildcard specificity, ranges with more media-type parameters outrank ranges with fewer.
         * When both are equal, original header order is preserved (the sort is stable). See
         * <a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1">RFC 9110, Section 12.5.1</a>.
         * Malformed media ranges are skipped.
         *
         * @param acceptHeaderValue the raw header value (must be non-{@code null})
         * @return media ranges in descending preference order; empty if none could be resolved
         */
        @NonNull
        public static List<@NonNull MediaRange> extractMediaRangesFromAcceptHeaderValue(@NonNull String acceptHeaderValue) {
                requireNonNull(acceptHeaderValue);

                List<MediaRange> mediaRanges = new ArrayList<>(4);

                for (String fragment : splitCommaAware(acceptHeaderValue)) {
                        MediaRange mediaRange = MediaRange.fromHeaderRepresentation(fragment).orElse(null);

                        if (mediaRange != null)
                                mediaRanges.add(mediaRange);
                }

                // Stable sort: q weight descending, then specificity descending; original order breaks ties
                mediaRanges.sort(Comparator
                                .comparing(MediaRange::getQuality, Comparator.reverseOrder())
                                .thenComparing(Utilities::mediaRangeWildcardSpecificity, Comparator.reverseOrder())
                                .thenComparing(Utilities::mediaRangeParameterSpecificity, Comparator.reverseOrder()));

                return Collections.unmodifiableList(mediaRanges);
        }

        @NonNull
        private static Integer mediaRangeWildcardSpecificity(@NonNull MediaRange mediaRange) {
                requireNonNull(mediaRange);

                if (mediaRange.isWildcardType())
                        return 0;

                if (mediaRange.isWildcardSubtype())
                        return 1;

                return 2;
        }

        @NonNull
        private static Integer mediaRangeParameterSpecificity(@NonNull MediaRange mediaRange) {
                requireNonNull(mediaRange);
                return mediaRange.getParameters().size();
        }

        @Nullable
        private static String firstHeaderValue(@Nullable Set<String> headerValues) {
                if (headerValues == null || headerValues.isEmpty())
                        return null;

                for (String value : headerValues) {
                        String trimmed = trimAggressivelyToNull(value);
                        if (trimmed == null)
                                continue;

                        for (String part : splitCommaAware(trimmed)) {
                                String candidate = trimAggressivelyToNull(part);
                                if (candidate != null)
                                        return candidate;
                        }
                }

                return null;
        }

        /**
         * Best-effort attempt to determine a client's effective origin by examining request headers.
         * <p>
         * An effective origin in this context is defined as {@code <scheme>://host<:optional port>}, but no path or query components.
         * <p>
         * Soklet is generally the "last hop" behind a load balancer/reverse proxy but may also be accessed directly by clients.
         * <p>
         * Normally a load balancer/reverse proxy/other upstream proxies will provide information about the true source of the
         * request through headers like the following:
         * <ul>
         *   <li>{@code Host}</li>
         *   <li>{@code Forwarded}</li>
         *   <li>{@code Origin}</li>
         *   <li>{@code X-Forwarded-Proto}</li>
         *   <li>{@code X-Forwarded-Protocol}</li>
         *   <li>{@code X-Url-Scheme}</li>
         *   <li>{@code Front-End-Https}</li>
         *   <li>{@code X-Forwarded-Ssl}</li>
         *   <li>{@code X-Forwarded-Host}</li>
         *   <li>{@code X-Forwarded-Port}</li>
         * </ul>
         * <p>
         * This method may take these and other headers into account when determining an effective origin.
         * <p>
         * For example, the following would be legal effective origins returned from this method:
         * <ul>
         *   <li>{@code https://www.soklet.com}</li>
         *   <li>{@code http://www.fake.com:1234}</li>
         * </ul>
         * <p>
         * The following would NOT be legal effective origins:
         * <ul>
         *   <li>{@code www.soklet.com} (missing protocol) </li>
         *   <li>{@code https://www.soklet.com/} (trailing slash)</li>
         *   <li>{@code https://www.soklet.com/test} (trailing slash, path)</li>
         *   <li>{@code https://www.soklet.com/test?abc=1234} (trailing slash, path, query)</li>
         * </ul>
         * <p>
         * {@code Origin} is treated as a fallback signal only and will not override a conflicting {@code Host} or forwarded host value.
         * <p>
         * Forwarded headers are only used when permitted by {@link EffectiveOriginResolver.TrustPolicy}. When using
         * {@link EffectiveOriginResolver.TrustPolicy#TRUST_PROXY_ALLOWLIST}, you must provide a trusted proxy predicate or allowlist.
         * If the remote address is missing or not trusted, forwarded headers are ignored.
         * <p>
         * Extraction order is: trusted forwarded headers → {@code Host} → (optional) {@code Origin} fallback.
         * If {@link EffectiveOriginResolver#allowOriginFallback(Boolean)} is unset, {@code Origin} fallback is enabled only for
         * {@link EffectiveOriginResolver.TrustPolicy#TRUST_ALL}.
         *
         * @param effectiveOriginResolver request headers and trust settings
         * @return the effective origin, or {@link Optional#empty()} if it could not be determined
         */
        @NonNull
        static Optional<String> extractEffectiveOrigin(@NonNull EffectiveOriginResolver effectiveOriginResolver) {
                requireNonNull(effectiveOriginResolver);
                requireNonNull(effectiveOriginResolver.getHeaders());
                requireNonNull(effectiveOriginResolver.getTrustPolicy());

                if (effectiveOriginResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST
                                && effectiveOriginResolver.getTrustedProxyPredicate() == null) {
                        throw new IllegalStateException(format("%s policy requires a trusted proxy predicate or allowlist.",
                                        EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST));
                }

                Map<String, Set<String>> headers = effectiveOriginResolver.getHeaders();
                boolean trustForwardedHeaders = shouldTrustForwardedHeaders(effectiveOriginResolver);
                boolean allowOriginFallback = effectiveOriginResolver.getAllowOriginFallback() != null
                                ? effectiveOriginResolver.getAllowOriginFallback()
                                : effectiveOriginResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_ALL;

                // Host                   developer.mozilla.org OR developer.mozilla.org:443 OR [2001:db8::1]:8443
                // Forwarded              by=<identifier>;for=<identifier>;host=<host>;proto=<http|https> (can be repeated if comma-separated, e.g. for=12.34.56.78;host=example.com;proto=https, for=23.45.67.89)
                // Origin                 null OR <scheme>://<hostname> OR <scheme>://<hostname>:<port>
                // X-Forwarded-Proto      https
                // X-Forwarded-Protocol   https (Microsoft's alternate name)
                // X-Url-Scheme           https (Microsoft's alternate name)
                // Front-End-Https        on (Microsoft's alternate name)
                // X-Forwarded-Ssl        on (Microsoft's alternate name)
                // X-Forwarded-Host       id42.example-cdn.com
                // X-Forwarded-Port       443

                String protocol = null;
                String host = null;
                String portAsString = null;
                Boolean portExplicit = false;

                // Forwarded: by=<identifier>;for=<identifier>;host=<host>;proto=<http|https>
                if (trustForwardedHeaders) {
                        Set<String> forwardedHeaders = headers.get("Forwarded");
                        if (forwardedHeaders != null) {
                                forwardedHeaderLoop:
                                for (String forwardedHeader : forwardedHeaders) {
                                        String trimmed = trimAggressivelyToNull(forwardedHeader);
                                        if (trimmed == null)
                                                continue;

                                        for (String forwardedEntry : splitCommaAware(trimmed)) {
                                                String entry = trimAggressivelyToNull(forwardedEntry);
                                                if (entry == null)
                                                        continue;

                                                String entryHost = null;
                                                String entryProtocol = null;
                                                String entryPortAsString = null;
                                                Boolean entryPortExplicit = false;

                                                // Each field component might look like "by=<identifier>"
                                                List<String> forwardedHeaderFieldComponents = splitSemicolonAware(entry);
                                                for (String forwardedHeaderFieldComponent : forwardedHeaderFieldComponents) {
                                                        forwardedHeaderFieldComponent = trimAggressivelyToNull(forwardedHeaderFieldComponent);
                                                        if (forwardedHeaderFieldComponent == null)
                                                                continue;

                                                        // Break "by=<identifier>" into "by" and "<identifier>" pieces
                                                        String[] forwardedHeaderFieldNameAndValue = forwardedHeaderFieldComponent.split(Pattern.quote("=" /* escape special Regex char */), 2);
                                                        if (forwardedHeaderFieldNameAndValue.length != 2)
                                                                continue;

                                                        String name = trimAggressivelyToNull(forwardedHeaderFieldNameAndValue[0]);
                                                        String value = trimAggressivelyToNull(forwardedHeaderFieldNameAndValue[1]);
                                                        if (name == null || value == null)
                                                                continue;

                                                        if ("host".equalsIgnoreCase(name)) {
                                                                if (entryHost == null) {
                                                                        HostPort hostPort = parseForwardedHostPort(value).orElse(null);

                                                                        if (hostPort != null) {
                                                                                entryHost = hostPort.getHost();

                                                                                if (hostPort.getPort().isPresent()) {
                                                                                        entryPortAsString = String.valueOf(hostPort.getPort().get());
                                                                                        entryPortExplicit = true;
                                                                                }
                                                                        }
                                                                }
                                                        } else if ("proto".equalsIgnoreCase(name)) {
                                                                if (entryProtocol == null)
                                                                        entryProtocol = stripOptionalQuotes(value);
                                                        }
                                                }

                                                if (entryHost != null || entryProtocol != null) {
                                                        host = entryHost;
                                                        protocol = entryProtocol;
                                                        if (entryPortAsString != null) {
                                                                portAsString = entryPortAsString;
                                                                portExplicit = entryPortExplicit;
                                                        }
                                                        break forwardedHeaderLoop;
                                                }
                                        }
                                }
                        }
                }

                // X-Forwarded-Proto: https
                if (trustForwardedHeaders && protocol == null) {
                        String xForwardedProtoHeader = firstHeaderValue(headers.get("X-Forwarded-Proto"));
                        if (xForwardedProtoHeader != null)
                                protocol = stripOptionalQuotes(xForwardedProtoHeader);
                }

                // X-Forwarded-Protocol: https (Microsoft's alternate name)
                if (trustForwardedHeaders && protocol == null) {
                        String xForwardedProtocolHeader = firstHeaderValue(headers.get("X-Forwarded-Protocol"));
                        if (xForwardedProtocolHeader != null)
                                protocol = stripOptionalQuotes(xForwardedProtocolHeader);
                }

                // X-Url-Scheme: https (Microsoft's alternate name)
                if (trustForwardedHeaders && protocol == null) {
                        String xUrlSchemeHeader = firstHeaderValue(headers.get("X-Url-Scheme"));
                        if (xUrlSchemeHeader != null)
                                protocol = stripOptionalQuotes(xUrlSchemeHeader);
                }

                // Front-End-Https: on (Microsoft's alternate name)
                if (trustForwardedHeaders && protocol == null) {
                        String frontEndHttpsHeader = firstHeaderValue(headers.get("Front-End-Https"));
                        if (frontEndHttpsHeader != null)
                                protocol = "on".equalsIgnoreCase(frontEndHttpsHeader) ? "https" : "http";
                }

                // X-Forwarded-Ssl: on (Microsoft's alternate name)
                if (trustForwardedHeaders && protocol == null) {
                        String xForwardedSslHeader = firstHeaderValue(headers.get("X-Forwarded-Ssl"));
                        if (xForwardedSslHeader != null)
                                protocol = "on".equalsIgnoreCase(xForwardedSslHeader) ? "https" : "http";
                }

                // X-Forwarded-Host: id42.example-cdn.com (or with port / IPv6)
                if (trustForwardedHeaders && host == null) {
                        String xForwardedHostHeader = firstHeaderValue(headers.get("X-Forwarded-Host"));
                        if (xForwardedHostHeader != null) {
                                HostPort hostPort = parseForwardedHostPort(xForwardedHostHeader).orElse(null);

                                if (hostPort != null) {
                                        host = hostPort.getHost();

                                        if (hostPort.getPort().isPresent() && portAsString == null) {
                                                portAsString = String.valueOf(hostPort.getPort().get());
                                                portExplicit = true;
                                        }
                                }
                        }
                }

                // X-Forwarded-Port: 443
                if (trustForwardedHeaders && portAsString == null) {
                        String xForwardedPortHeader = firstHeaderValue(headers.get("X-Forwarded-Port"));
                        if (xForwardedPortHeader != null) {
                                portAsString = stripOptionalQuotes(xForwardedPortHeader);
                                portExplicit = true;
                        }
                }

                // Host: developer.mozilla.org OR developer.mozilla.org:443 OR [2001:db8::1]:8443
                if (host == null) {
                        String hostHeader = firstHeaderValue(headers.get("Host"));

                        if (hostHeader != null) {
                                HostPort hostPort = parseHostPort(hostHeader).orElse(null);

                                if (hostPort != null) {
                                        host = hostPort.getHost();

                                        if (hostPort.getPort().isPresent() && portAsString == null) {
                                                portAsString = String.valueOf(hostPort.getPort().get());
                                                portExplicit = true;
                                        }
                                }
                        }
                }

                // Origin: null OR <scheme>://<hostname> OR <scheme>://<hostname>:<port> (IPv6 supported)
                // Use Origin only when host is missing or when it matches the Host-derived value.
                if (allowOriginFallback && (protocol == null || host == null || portAsString == null)) {
                        String originHeader = firstHeaderValue(headers.get("Origin"));

                        if (originHeader != null) {
                                try {
                                        URI o = new URI(originHeader);
                                        String originProtocol = trimAggressivelyToNull(o.getScheme());
                                        String originHost = o.getHost(); // may be bracketed already on some JDKs
                                        int originPort = o.getPort(); // -1 if absent

                                        if (originHost != null) {
                                                boolean alreadyBracketed = originHost.startsWith("[") && originHost.endsWith("]");
                                                boolean isIpv6Like = originHost.indexOf(':') >= 0; // contains colon(s)
                                                originHost = (isIpv6Like && !alreadyBracketed) ? "[" + originHost + "]" : originHost;
                                        }

                                        boolean hostMatchesOrigin = host != null && originHost != null && host.equalsIgnoreCase(originHost);

                                        if (host == null) {
                                                if (originHost != null)
                                                        host = originHost;
                                                if (originProtocol != null)
                                                        protocol = originProtocol;
                                                if (originPort >= 0) {
                                                        portAsString = String.valueOf(originPort);
                                                        portExplicit = true;
                                                }
                                        } else if (hostMatchesOrigin) {
                                                if (protocol == null && originProtocol != null)
                                                        protocol = originProtocol;
                                                if (portAsString == null && originPort >= 0) {
                                                        portAsString = String.valueOf(originPort);
                                                        portExplicit = true;
                                                }
                                        }
                                } catch (URISyntaxException ignored) {
                                        // no-op
                                }
                        }
                }

                Integer port = null;

                if (portAsString != null) {
                        try {
                                int parsedPort = Integer.parseInt(portAsString, 10);
                                if (parsedPort >= 1 && parsedPort <= 65535)
                                        port = parsedPort;
                        } catch (Exception ignored) {
                                // Not an integer; ignore it
                        }
                }

                if (protocol != null && host != null && port == null) {
                        return Optional.of(format("%s://%s", protocol, host));
                }

                if (protocol != null && host != null && port != null) {
                        boolean usingDefaultPort =
                                        ("http".equalsIgnoreCase(protocol) && port.equals(80)) ||
                                                        ("https".equalsIgnoreCase(protocol) && port.equals(443));

                        // Keep default ports if the client/proxy explicitly sent them
                        String effectiveOrigin = (usingDefaultPort && !portExplicit)
                                        ? format("%s://%s", protocol, host)
                                        : format("%s://%s:%s", protocol, host, port);

                        return Optional.of(effectiveOrigin);
                }

                return Optional.empty();
        }

        /**
         * Best-effort attempt to determine a client's effective IP address by examining request headers.
         * <p>
         * The socket peer is always used as the fallback. Forwarded headers are only used when permitted by
         * {@link EffectiveOriginResolver.TrustPolicy}. When using
         * {@link EffectiveOriginResolver.TrustPolicy#TRUST_PROXY_ALLOWLIST}, you must provide a trusted proxy predicate or allowlist.
         * If the remote address is missing or not trusted, forwarded headers are ignored.
         *
         * @param effectiveClientIpResolver request headers and trust settings
         * @return the effective client IP address, or {@link Optional#empty()} if it could not be determined
         */
        @NonNull
        static Optional<InetAddress> extractEffectiveClientIp(@NonNull EffectiveClientIpResolver effectiveClientIpResolver) {
                requireNonNull(effectiveClientIpResolver);
                requireNonNull(effectiveClientIpResolver.getHeaders());
                requireNonNull(effectiveClientIpResolver.getTrustPolicy());

                if (effectiveClientIpResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST
                                && effectiveClientIpResolver.getTrustedProxyPredicate() == null) {
                        throw new IllegalStateException(format("%s policy requires a trusted proxy predicate or allowlist.",
                                        EffectiveOriginResolver.TrustPolicy.TRUST_PROXY_ALLOWLIST));
                }

                InetSocketAddress remoteAddress = effectiveClientIpResolver.getRemoteAddress();
                InetAddress remoteInetAddress = remoteAddress == null ? null : remoteAddress.getAddress();

                if (!shouldTrustForwardedHeaders(effectiveClientIpResolver))
                        return Optional.ofNullable(remoteInetAddress);

                List<InetAddress> forwardedForAddresses = forwardedForAddresses(effectiveClientIpResolver.getHeaders());
                Optional<InetAddress> effectiveClientIp = effectiveClientIpResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_ALL
                                ? leftmostAddress(forwardedForAddresses)
                                : firstUntrustedAddressFromRight(forwardedForAddresses, effectiveClientIpResolver.getTrustedProxyPredicate());

                if (effectiveClientIp.isPresent())
                        return effectiveClientIp;

                List<InetAddress> xForwardedForAddresses = xForwardedForAddresses(effectiveClientIpResolver.getHeaders());
                effectiveClientIp = effectiveClientIpResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_ALL
                                ? leftmostAddress(xForwardedForAddresses)
                                : firstUntrustedAddressFromRight(xForwardedForAddresses, effectiveClientIpResolver.getTrustedProxyPredicate());

                if (effectiveClientIp.isPresent())
                        return effectiveClientIp;

                return Optional.ofNullable(remoteInetAddress);
        }

        private static boolean shouldTrustForwardedHeaders(@NonNull EffectiveOriginResolver effectiveOriginResolver) {
                if (effectiveOriginResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_ALL)
                        return true;

                if (effectiveOriginResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_NONE)
                        return false;

                var remoteAddress = effectiveOriginResolver.getRemoteAddress();
                var trustedProxyPredicate = effectiveOriginResolver.getTrustedProxyPredicate();

                if (remoteAddress == null || trustedProxyPredicate == null)
                        return false;

                return trustedProxyPredicate.test(remoteAddress);
        }

        private static boolean shouldTrustForwardedHeaders(@NonNull EffectiveClientIpResolver effectiveClientIpResolver) {
                if (effectiveClientIpResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_ALL)
                        return true;

                if (effectiveClientIpResolver.getTrustPolicy() == EffectiveOriginResolver.TrustPolicy.TRUST_NONE)
                        return false;

                var remoteAddress = effectiveClientIpResolver.getRemoteAddress();
                var trustedProxyPredicate = effectiveClientIpResolver.getTrustedProxyPredicate();

                if (remoteAddress == null || trustedProxyPredicate == null)
                        return false;

                return trustedProxyPredicate.test(remoteAddress);
        }

        @NonNull
        private static Optional<InetAddress> leftmostAddress(@NonNull List<@NonNull InetAddress> addresses) {
                requireNonNull(addresses);
                return addresses.isEmpty() ? Optional.empty() : Optional.of(addresses.get(0));
        }

        @NonNull
        private static Optional<InetAddress> firstUntrustedAddressFromRight(@NonNull List<@NonNull InetAddress> addresses,
                                                                                                                                                                                                                                                                                 @Nullable Predicate<InetSocketAddress> trustedProxyPredicate) {
                requireNonNull(addresses);

                if (trustedProxyPredicate == null)
                        return Optional.empty();

                InetAddress leftmostAddress = null;

                for (int i = addresses.size() - 1; i >= 0; i--) {
                        InetAddress address = addresses.get(i);
                        leftmostAddress = address;

                        if (!trustedProxyPredicate.test(new InetSocketAddress(address, 0)))
                                return Optional.of(address);
                }

                return Optional.ofNullable(leftmostAddress);
        }

        @NonNull
        private static List<@NonNull InetAddress> forwardedForAddresses(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers) {
                requireNonNull(headers);
                Set<String> forwardedHeaders = headers.get("Forwarded");

                if (forwardedHeaders == null || forwardedHeaders.isEmpty())
                        return List.of();

                List<InetAddress> addresses = new ArrayList<>();

                for (String forwardedHeader : forwardedHeaders) {
                        String trimmed = trimAggressivelyToNull(forwardedHeader);
                        if (trimmed == null)
                                continue;

                        for (String forwardedEntry : splitCommaAware(trimmed)) {
                                String entry = trimAggressivelyToNull(forwardedEntry);
                                if (entry == null)
                                        continue;

                                for (String forwardedHeaderFieldComponent : splitSemicolonAware(entry)) {
                                        forwardedHeaderFieldComponent = trimAggressivelyToNull(forwardedHeaderFieldComponent);
                                        if (forwardedHeaderFieldComponent == null)
                                                continue;

                                        String[] forwardedHeaderFieldNameAndValue = forwardedHeaderFieldComponent.split(Pattern.quote("="), 2);
                                        if (forwardedHeaderFieldNameAndValue.length != 2)
                                                continue;

                                        String name = trimAggressivelyToNull(forwardedHeaderFieldNameAndValue[0]);
                                        String value = trimAggressivelyToNull(forwardedHeaderFieldNameAndValue[1]);
                                        if (name == null || value == null || !"for".equalsIgnoreCase(name))
                                                continue;

                                        parseForwardedIpLiteral(value).ifPresent(addresses::add);
                                        break;
                                }
                        }
                }

                return addresses.isEmpty() ? List.of() : Collections.unmodifiableList(addresses);
        }

        @NonNull
        private static List<@NonNull InetAddress> xForwardedForAddresses(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers) {
                requireNonNull(headers);
                Set<String> xForwardedForHeaders = headers.get("X-Forwarded-For");

                if (xForwardedForHeaders == null || xForwardedForHeaders.isEmpty())
                        return List.of();

                List<InetAddress> addresses = new ArrayList<>();

                for (String xForwardedForHeader : xForwardedForHeaders) {
                        String trimmed = trimAggressivelyToNull(xForwardedForHeader);
                        if (trimmed == null)
                                continue;

                        for (String part : splitCommaAware(trimmed))
                                parseForwardedIpLiteral(part).ifPresent(addresses::add);
                }

                return addresses.isEmpty() ? List.of() : Collections.unmodifiableList(addresses);
        }

        @NonNull
        private static Optional<InetAddress> parseForwardedIpLiteral(@Nullable String value) {
                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null)
                        return Optional.empty();

                trimmed = trimAggressivelyToNull(stripOptionalQuotes(trimmed));

                if (trimmed == null || "unknown".equalsIgnoreCase(trimmed) || trimmed.startsWith("_"))
                        return Optional.empty();

                if (trimmed.startsWith("[")) {
                        int closeIndex = trimmed.indexOf(']');

                        if (closeIndex <= 1)
                                return Optional.empty();

                        String suffix = trimmed.substring(closeIndex + 1);

                        if (!suffix.isEmpty()) {
                                if (!suffix.startsWith(":") || !isValidPort(suffix.substring(1)))
                                        return Optional.empty();
                        }

                        return parseIpLiteral(trimmed.substring(1, closeIndex));
                }

                int colonCount = countOccurrences(trimmed, ':');

                if (colonCount == 1 && trimmed.contains(".")) {
                        int colonIndex = trimmed.indexOf(':');
                        String addressPart = trimmed.substring(0, colonIndex);
                        String portPart = trimmed.substring(colonIndex + 1);

                        if (isValidPort(portPart))
                                return parseIpv4Literal(addressPart);

                        return Optional.empty();
                }

                return parseIpLiteral(trimmed);
        }

        @NonNull
        private static Optional<InetAddress> parseIpLiteral(@Nullable String value) {
                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null)
                        return Optional.empty();

                Optional<InetAddress> ipv4Address = parseIpv4Literal(trimmed);

                if (ipv4Address.isPresent())
                        return ipv4Address;

                return parseIpv6Literal(trimmed);
        }

        @NonNull
        private static Optional<InetAddress> parseIpv4Literal(@Nullable String value) {
                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null)
                        return Optional.empty();

                String[] parts = trimmed.split(Pattern.quote("."), -1);

                if (parts.length != 4)
                        return Optional.empty();

                byte[] bytes = new byte[4];

                for (int i = 0; i < parts.length; i++) {
                        String part = parts[i];

                        if (part.isEmpty() || part.length() > 3)
                                return Optional.empty();

                        if (part.length() > 1 && part.startsWith("0"))
                                return Optional.empty();

                        for (int j = 0; j < part.length(); j++) {
                                if (!Character.isDigit(part.charAt(j)))
                                        return Optional.empty();
                        }

                        int octet;
                        try {
                                octet = Integer.parseInt(part, 10);
                        } catch (NumberFormatException e) {
                                return Optional.empty();
                        }

                        if (octet < 0 || octet > 255)
                                return Optional.empty();

                        bytes[i] = (byte) octet;
                }

                try {
                        return Optional.of(InetAddress.getByAddress(bytes));
                } catch (UnknownHostException e) {
                        return Optional.empty();
                }
        }

        @NonNull
        private static Optional<InetAddress> parseIpv6Literal(@Nullable String value) {
                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null || !trimmed.contains(":"))
                        return Optional.empty();

                if (trimmed.indexOf('[') >= 0 || trimmed.indexOf(']') >= 0 || trimmed.indexOf('"') >= 0 || trimmed.indexOf('%') >= 0)
                        return Optional.empty();

                try {
                        return Optional.of(InetAddress.getByName(trimmed));
                } catch (Exception e) {
                        return Optional.empty();
                }
        }

        private static boolean isValidPort(@Nullable String value) {
                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null)
                        return false;

                try {
                        int port = Integer.parseInt(trimmed, 10);
                        return port >= 1 && port <= 65535;
                } catch (NumberFormatException e) {
                        return false;
                }
        }

        private static int countOccurrences(@NonNull String value,
                                                                                                                                                        char character) {
                requireNonNull(value);
                int count = 0;

                for (int i = 0; i < value.length(); i++) {
                        if (value.charAt(i) == character)
                                count++;
                }

                return count;
        }

        /**
         * Extracts the media type (without parameters) from the first {@code Content-Type} header.
         * <p>
         * For example, {@code "text/html; charset=UTF-8"} → {@code "text/html"}.
         *
         * @param headers request/response headers (must be non-{@code null})
         * @return the media type if present; otherwise {@link Optional#empty()}
         * @see #extractContentTypeFromHeaderValue(String)
         */
        @NonNull
        public static Optional<String> extractContentTypeFromHeaders(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers) {
                requireNonNull(headers);

                Set<String> contentTypeHeaderValues = headers.get("Content-Type");

                if (contentTypeHeaderValues == null || contentTypeHeaderValues.size() == 0)
                        return Optional.empty();

                return extractContentTypeFromHeaderValue(contentTypeHeaderValues.stream().findFirst().get());
        }

        /**
         * Extracts the media type (without parameters) from a {@code Content-Type} header value.
         * <p>
         * For example, {@code "application/json; charset=UTF-8"} → {@code "application/json"}.
         *
         * @param contentTypeHeaderValue the raw header value; may be {@code null} or blank
         * @return the media type if present; otherwise {@link Optional#empty()}
         */
        @NonNull
        public static Optional<String> extractContentTypeFromHeaderValue(@Nullable String contentTypeHeaderValue) {
                contentTypeHeaderValue = trimAggressivelyToNull(contentTypeHeaderValue);

                if (contentTypeHeaderValue == null)
                        return Optional.empty();

                // Examples
                // Content-Type: text/html; charset=UTF-8
                // Content-Type: multipart/form-data; boundary=something

                int indexOfSemicolon = contentTypeHeaderValue.indexOf(";");

                // Simple case, e.g. "text/html"
                if (indexOfSemicolon == -1)
                        return Optional.ofNullable(trimAggressivelyToNull(contentTypeHeaderValue));

                // More complex case, e.g. "text/html; charset=UTF-8"
                return Optional.ofNullable(trimAggressivelyToNull(contentTypeHeaderValue.substring(0, indexOfSemicolon)));
        }

        /**
         * Extracts the {@link Charset} from the first {@code Content-Type} header, if present and valid.
         * <p>
         * Tolerates additional parameters and arbitrary whitespace. Invalid or unknown charset tokens yield {@link Optional#empty()}.
         *
         * @param headers request/response headers (must be non-{@code null})
         * @return the charset declared by the header; otherwise {@link Optional#empty()}
         * @see #extractCharsetFromHeaderValue(String)
         */
        @NonNull
        public static Optional<Charset> extractCharsetFromHeaders(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers) {
                requireNonNull(headers);

                Set<String> contentTypeHeaderValues = headers.get("Content-Type");

                if (contentTypeHeaderValues == null || contentTypeHeaderValues.size() == 0)
                        return Optional.empty();

                return extractCharsetFromHeaderValue(contentTypeHeaderValues.stream().findFirst().get());
        }

        /**
         * Extracts the {@code charset=...} parameter from a {@code Content-Type} header value.
         * <p>
         * Parsing is forgiving: parameters may appear in any order and with arbitrary spacing. If a charset is found,
         * it is validated via {@link Charset#forName(String)}; invalid names result in {@link Optional#empty()}.
         *
         * @param contentTypeHeaderValue the raw header value; may be {@code null} or blank
         * @return the resolved charset if present and valid; otherwise {@link Optional#empty()}
         */
        @NonNull
        public static Optional<Charset> extractCharsetFromHeaderValue(@Nullable String contentTypeHeaderValue) {
                contentTypeHeaderValue = trimAggressivelyToNull(contentTypeHeaderValue);

                if (contentTypeHeaderValue == null)
                        return Optional.empty();

                // Examples
                // Content-Type: text/html; charset=UTF-8
                // Content-Type: multipart/form-data; boundary=something

                int indexOfSemicolon = contentTypeHeaderValue.indexOf(";");

                // Simple case, e.g. "text/html"
                if (indexOfSemicolon == -1)
                        return Optional.empty();

                // More complex case, e.g. "text/html; charset=UTF-8" or "multipart/form-data; charset=UTF-8; boundary=something"
                boolean finishedContentType = false;
                boolean finishedCharsetName = false;
                StringBuilder buffer = new StringBuilder();
                String charsetName = null;

                for (int i = 0; i < contentTypeHeaderValue.length(); i++) {
                        char c = contentTypeHeaderValue.charAt(i);

                        if (Character.isWhitespace(c))
                                continue;

                        if (c == ';') {
                                // No content type yet?  This just be it...
                                if (!finishedContentType) {
                                        finishedContentType = true;
                                        buffer = new StringBuilder();
                                } else if (!finishedCharsetName) {
                                        if (buffer.indexOf("charset=") == 0) {
                                                charsetName = buffer.toString();
                                                finishedCharsetName = true;
                                                break;
                                        }
                                }
                        } else {
                                buffer.append(Character.toLowerCase(c));
                        }
                }

                // Handle case where charset is the end of the string, e.g. "whatever;charset=UTF-8"
                if (!finishedCharsetName) {
                        String potentialCharset = trimAggressivelyToNull(buffer.toString());
                        if (potentialCharset != null && potentialCharset.startsWith("charset=")) {
                                finishedCharsetName = true;
                                charsetName = potentialCharset;
                        }
                }

                if (finishedCharsetName) {
                        String specifiedCharsetName = charsetName;
                        if (specifiedCharsetName == null)
                                return Optional.empty();

                        // e.g. charset=UTF-8 or charset="UTF-8" or charset='UTF-8'
                        String possibleCharsetName = trimAggressivelyToNull(specifiedCharsetName.replace("charset=", ""));

                        if (possibleCharsetName != null) {
                                // strip optional surrounding quotes
                                if ((possibleCharsetName.length() >= 2) &&
                                                ((possibleCharsetName.charAt(0) == '"' && possibleCharsetName.charAt(possibleCharsetName.length() - 1) == '"') ||
                                                                (possibleCharsetName.charAt(0) == '\'' && possibleCharsetName.charAt(possibleCharsetName.length() - 1) == '\''))) {
                                        possibleCharsetName = possibleCharsetName.substring(1, possibleCharsetName.length() - 1);
                                        possibleCharsetName = trimAggressivelyToNull(possibleCharsetName);
                                }

                                if (possibleCharsetName != null) {
                                        try {
                                                return Optional.of(Charset.forName(possibleCharsetName));
                                        } catch (IllegalCharsetNameException | UnsupportedCharsetException ignored) {
                                                return Optional.empty();
                                        }
                                }
                        }
                }

                return Optional.empty();
        }

        /**
         * A "stronger" version of {@link String#trim()} which discards leading and trailing Unicode space-separator characters ({@code \p{Z}}).
         * <p>
         * In a web environment with user-supplied inputs, this is the behavior we want the vast majority of the time.
         * For example, users copy-paste URLs from Microsoft Word or Outlook and it's easy to accidentally include a {@code U+202F
         * "Narrow No-Break Space (NNBSP)"} character at the end, which might break parsing.
         * <p>
         * Note that this does not remove other whitespace characters such as tabs, carriage returns, or line feeds.
         * <p>
         * See <a href="https://www.compart.com/en/unicode/U+202F">https://www.compart.com/en/unicode/U+202F</a> for details.
         *
         * @param string the string to trim
         * @return the trimmed string, or {@code null} if the input string is {@code null} or the trimmed representation is of length {@code 0}
         */
        @Nullable
        public static String trimAggressively(@Nullable String string) {
                if (string == null)
                        return null;

                string = HEAD_WHITESPACE_PATTERN.matcher(string).replaceAll("");

                if (string.length() == 0)
                        return string;

                string = TAIL_WHITESPACE_PATTERN.matcher(string).replaceAll("");

                return string;
        }

        /**
         * Aggressively trims leading and trailing Unicode space-separator characters from the given string and returns {@code null} if the result is empty.
         * <p>
         * See {@link #trimAggressively(String)} for details on which code points are removed.
         *
         * @param string the input string; may be {@code null}
         * @return a trimmed, non-empty string; or {@code null} if input was {@code null} or trimmed to empty
         */
        @Nullable
        public static String trimAggressivelyToNull(@Nullable String string) {
                if (string == null)
                        return null;

                string = trimAggressively(string);
                if (string == null)
                        return null;
                return string.length() == 0 ? null : string;
        }

        /**
         * Aggressively trims leading and trailing Unicode space-separator characters from the given string and returns {@code ""} if the input is {@code null}.
         * <p>
         * See {@link #trimAggressively(String)} for details on which code points are removed.
         *
         * @param string the input string; may be {@code null}
         * @return a trimmed string (never {@code null}); {@code ""} if input was {@code null}
         */
        @NonNull
        public static String trimAggressivelyToEmpty(@Nullable String string) {
                if (string == null)
                        return "";

                String trimmed = trimAggressively(string);
                return trimmed == null ? "" : trimmed;
        }

        static void validateHeaderNameAndValue(@Nullable String name,
                                                                                                                                                                 @Nullable String value) {
                // First, validate name:
                name = trimAggressivelyToNull(name);

                if (name == null)
                        throw new IllegalArgumentException("Header name is blank");

                for (int i = 0; i < name.length(); i++) {
                        char c = name.charAt(i);
                        // RFC 9110 tchar: "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
                        if (c > 0x7F || !(c == '!' || c == '#' || c == '$' || c == '%' || c == '&' || c == '\'' || c == '*' || c == '+' ||
                                        c == '-' || c == '.' || c == '^' || c == '_' || c == '`' || c == '|' || c == '~' ||
                                        Character.isLetterOrDigit(c))) {
                                throw new IllegalArgumentException(format("Illegal header name '%s'. Offending character: '%s'", name, printableChar(c)));
                        }
                }

                // Then, validate value:
                if (value == null)
                        return;

                for (int i = 0; i < value.length(); i++) {
                        char c = value.charAt(i);
                        if (c == '\r' || c == '\n' || c == 0x00 || c > 0xFF || (c < 0x20 && c != '\t')) {
                                throw new IllegalArgumentException(format("Illegal header value '%s' for header name '%s'. Offending character: '%s'", value, name, printableChar(c)));
                        }
                }

                // Percent-encoded control sequence checks
                Matcher m = HEADER_PERCENT_ENCODING_PATTERN.matcher(value);

                while (m.find()) {
                        int b = Integer.parseInt(m.group(1), 16);
                        if (b == 0x0D || b == 0x0A || b == 0x00 || (b >= 0x00 && b < 0x20 && b != 0x09)) {
                                throw new IllegalArgumentException(format(
                                                "Illegal (percent-encoded) header value '%s' for header name '%s'. Offending octet: 0x%02X",
                                                value, name, b));
                        }
                }
        }

        @NonNull
        static String printableString(@NonNull String input) {
                requireNonNull(input);

                StringBuilder out = new StringBuilder(input.length() + 16);

                for (int i = 0; i < input.length(); i++)
                        out.append(printableChar(input.charAt(i)));

                return out.toString();
        }

        @NonNull
        static String printableChar(char c) {
                if (c == '\r') return "\\r";
                if (c == '\n') return "\\n";
                if (c == '\t') return "\\t";
                if (c == '\f') return "\\f";
                if (c == '\b') return "\\b";
                if (c == '\\') return "\\\\";
                if (c == '\'') return "\\'";
                if (c == '\"') return "\\\"";
                if (c == 0) return "\\0";

                if (c < 0x20 || c == 0x7F)  // control chars
                        return String.format("\\u%04X", (int) c);

                if (Character.isISOControl(c) || Character.getType(c) == Character.FORMAT)
                        return String.format("\\u%04X", (int) c);

                return String.valueOf(c);
        }

        @NonNull
        private static final Set<String> COMMA_JOINABLE_HEADER_NAMES = Set.of(
                        // Common list-type headers (RFC 7230/9110)
                        "accept",
                        "accept-encoding",
                        "accept-language",
                        "cache-control",
                        "pragma",
                        "vary",
                        "connection",
                        "transfer-encoding",
                        "upgrade",
                        "allow",
                        "via",
                        "warning"
                        // intentionally NOT: set-cookie, authorization, cookie, content-disposition, location
        );

        /**
         * Given a list of raw HTTP header lines, convert them into a normalized case-insensitive, order-preserving map which "inflates" comma-separated headers into distinct values where permitted according to RFC 7230/9110.
         * <p>
         * For example, given these raw header lines:
         * <pre>{@code List<String> lines = List.of(
         *   "Cache-Control: no-cache, no-store",
         *   "Set-Cookie: a=b; Path=/; HttpOnly",
         *   "Set-Cookie: c=d; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Path=/"
         * );}</pre>
         * The result of parsing would look like this:
         * <pre>{@code result.get("cache-control") -> [
         *   "no-cache",
         *   "no-store"
         * ]
         * result.get("set-cookie") -> [
         *   "a=b; Path=/; HttpOnly",
         *   "c=d; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Path=/"
         * ]}</pre>
         * <p>
         * Keys in the returned map are case-insensitive and are guaranteed to be in the same order as encountered in {@code rawHeaderLines}.
         * <p>
         * Values in the returned map are guaranteed to be in the same order as encountered in {@code rawHeaderLines}.
         *
         * @param rawHeaderLines the raw HTTP header lines to parse
         * @return a normalized mapping of header name keys to values
         */
        @NonNull
        public static Map<@NonNull String, @NonNull Set<@NonNull String>> extractHeadersFromRawHeaderLines(@NonNull List<@NonNull String> rawHeaderLines) {
                requireNonNull(rawHeaderLines);

                // 1) Unfold obsolete folded lines (obs-fold): lines beginning with SP/HT are continuations
                List<String> lines = unfold(rawHeaderLines);

                // 2) Parse into map
                Map<String, Set<String>> headers = new LinkedCaseInsensitiveMap<>();

                for (String raw : lines) {
                        String line = trimAggressivelyToNull(raw);

                        if (line == null)
                                continue;

                        int idx = line.indexOf(':');

                        if (idx <= 0)
                                continue; // skip malformed

                        addParsedHeader(headers, line.substring(0, idx), line.substring(idx + 1));
                }

                freezeStringValueSets(headers);
                return headers;
        }

        static void addParsedHeader(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> headers,
                                                                                                                        @Nullable String name,
                                                                                                                        @Nullable String value) {
                requireNonNull(headers);

                String key = trimAggressivelyToEmpty(name); // keep original case for display
                String trimmedValue = trimAggressivelyToNull(value);
                if (trimmedValue == null)
                        return;

                if (COMMA_JOINABLE_HEADER_NAMES.contains(key.toLowerCase(Locale.ROOT))) {
                        for (String part : splitCommaAware(trimmedValue)) {
                                String v = trimAggressivelyToNull(part);
                                if (v != null)
                                        addStringValue(headers, key, v);
                        }
                } else {
                        addStringValue(headers, key, trimmedValue.trim());
                }
        }

        static void addParsedHeaderValues(@NonNull Set<@NonNull String> values,
                                                                                                                                                @Nullable String name,
                                                                                                                                                @Nullable String value) {
                requireNonNull(values);

                String key = trimAggressivelyToEmpty(name);
                String keyLowercase = key.toLowerCase(Locale.ROOT);
                value = trimAggressivelyToNull(value);

                if (value == null)
                        return;

                if (COMMA_JOINABLE_HEADER_NAMES.contains(keyLowercase)) {
                        for (String part : splitCommaAware(value)) {
                                String v = trimAggressivelyToNull(part);
                                if (v != null)
                                        values.add(v);
                        }
                } else {
                        values.add(value.trim());
                }
        }

        static void freezeStringValueSets(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> valuesByName) {
                requireNonNull(valuesByName);

                for (Entry<String, Set<String>> entry : valuesByName.entrySet()) {
                        Set<String> values = entry.getValue();

                        if (values == null || values.isEmpty()) {
                                entry.setValue(Set.of());
                        } else if (values instanceof LinkedHashSet) {
                                entry.setValue(Collections.unmodifiableSet(values));
                        }
                }
        }

        private static void addStringValue(@NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> valuesByName,
                                                                                                                                                 @NonNull String name,
                                                                                                                                                 @NonNull String value) {
                requireNonNull(valuesByName);
                requireNonNull(name);
                requireNonNull(value);

                Set<String> values = valuesByName.get(name);

                if (values == null || values.isEmpty()) {
                        valuesByName.put(name, Set.of(value));
                        return;
                }

                if (values.contains(value))
                        return;

                if (values instanceof LinkedHashSet) {
                        values.add(value);
                        return;
                }

                Set<String> promotedValues = new LinkedHashSet<>(values);
                promotedValues.add(value);
                valuesByName.put(name, promotedValues);
        }

        /**
         * Header parsing helper
         */
        @NonNull
        private static List<String> unfold(@NonNull List<String> raw) {
                requireNonNull(raw);
                if (raw.isEmpty()) return List.of();

                List<String> out = new ArrayList<>(raw.size());
                StringBuilder cur = null;
                boolean curIsHeader = false;

                for (String line : raw) {
                        if (line == null) continue;

                        boolean isContinuation = !line.isEmpty() && (line.charAt(0) == ' ' || line.charAt(0) == '\t');
                        if (isContinuation) {
                                if (cur != null && curIsHeader) {
                                        cur.append(' ').append(line.trim());
                                } else {
                                        // Do not fold into a non-header; flush previous and start anew
                                        if (cur != null) out.add(cur.toString());
                                        cur = new StringBuilder(line);
                                        curIsHeader = line.indexOf(':') > 0; // almost certainly false for leading-space lines
                                }
                        } else {
                                if (cur != null) out.add(cur.toString());
                                cur = new StringBuilder(line);
                                curIsHeader = line.indexOf(':') > 0;
                        }
                }
                if (cur != null) out.add(cur.toString());
                return out;
        }

        /**
         * Header parsing helper: split on commas that are not inside a quoted-string; supports \" escapes inside quotes.
         */
        @NonNull
        private static List<String> splitCommaAware(@NonNull String string) {
                requireNonNull(string);

                List<String> out = new ArrayList<>(4);
                StringBuilder cur = new StringBuilder();
                boolean inQuotes = false;
                boolean escaped = false;

                for (int i = 0; i < string.length(); i++) {
                        char c = string.charAt(i);

                        if (escaped) {
                                // Preserve the escaped char as-is
                                cur.append(c);
                                escaped = false;
                        } else if (c == '\\') {
                                if (inQuotes) {
                                        // Preserve the backslash itself, then mark next char as escaped
                                        cur.append('\\');       // ← keep the backslash
                                        escaped = true;
                                } else {
                                        cur.append('\\');       // literal backslash outside quotes
                                }
                        } else if (c == '"') {
                                inQuotes = !inQuotes;
                                cur.append('"');
                        } else if (c == ',' && !inQuotes) {
                                out.add(cur.toString());
                                cur.setLength(0);
                        } else {
                                cur.append(c);
                        }
                }
                out.add(cur.toString());
                return out;
        }

        /**
         * Header parsing helper: split on semicolons that are not inside a quoted-string; supports \" escapes inside quotes.
         */
        @NonNull
        static List<String> splitSemicolonAware(@NonNull String string) {
                requireNonNull(string);

                List<String> out = new ArrayList<>(4);
                StringBuilder cur = new StringBuilder();
                boolean inQuotes = false;
                boolean escaped = false;

                for (int i = 0; i < string.length(); i++) {
                        char c = string.charAt(i);

                        if (escaped) {
                                cur.append(c);
                                escaped = false;
                        } else if (c == '\\') {
                                if (inQuotes) {
                                        cur.append('\\');
                                        escaped = true;
                                } else {
                                        cur.append('\\');
                                }
                        } else if (c == '"') {
                                inQuotes = !inQuotes;
                                cur.append('"');
                        } else if (c == ';' && !inQuotes) {
                                out.add(cur.toString());
                                cur.setLength(0);
                        } else {
                                cur.append(c);
                        }
                }

                out.add(cur.toString());
                return out;
        }

        /**
         * Remove a single pair of surrounding quotes if present.
         */
        @NonNull
        private static String stripOptionalQuotes(@NonNull String string) {
                requireNonNull(string);

                if (string.length() >= 2) {
                        char first = string.charAt(0), last = string.charAt(string.length() - 1);

                        if ((first == '"' && last == '"') || (first == '\'' && last == '\''))
                                return string.substring(1, string.length() - 1);
                }

                return string;
        }

        /**
         * Parse host[:port] with IPv6 support: "[v6](:port)?" or "host(:port)?".
         * Returns host (with brackets for v6) and port (nullable).
         */
        @ThreadSafe
        private static final class HostPort {
                @NonNull
                private final String host;
                @Nullable
                private final Integer port;

                HostPort(@NonNull String host,
                                                 @Nullable Integer port) {
                        this.host = host;
                        this.port = port;
                }

                @NonNull
                public String getHost() {
                        return this.host;
                }

                @NonNull
                public Optional<Integer> getPort() {
                        return Optional.ofNullable(this.port);
                }
        }

        @NonNull
        private static Optional<HostPort> parseForwardedHostPort(@Nullable String input) {
                input = trimAggressivelyToNull(input);

                if (input == null)
                        return Optional.empty();

                input = stripOptionalQuotes(input);

                if (!HostHeaderValidator.isValidHostHeaderValue(input))
                        return Optional.empty();

                return parseHostPort(input);
        }

        @NonNull
        private static Optional<HostPort> parseHostPort(@Nullable String input) {
                input = trimAggressivelyToNull(input);

                if (input == null)
                        return Optional.empty();

                input = stripOptionalQuotes(input);

                if (input.startsWith("[")) {
                        int close = input.indexOf(']');

                        if (close > 0) {
                                String core = input.substring(1, close); // IPv6 literal without brackets
                                String rest = input.substring(close + 1); // maybe ":port"
                                String host = "[" + core + "]";
                                Integer port = null;

                                if (rest.startsWith(":")) {
                                        String ps = trimAggressivelyToNull(rest.substring(1));
                                        if (ps != null) {
                                                try {
                                                        port = Integer.parseInt(ps, 10);
                                                } catch (Exception ignored) {
                                                        // Nothing to do
                                                }
                                        }
                                }

                                return Optional.of(new HostPort(host, port));
                        }
                }

                int colon = input.indexOf(':');

                if (colon > 0 && input.indexOf(':', colon + 1) == -1) {
                        // exactly one ':' -> host:port (IPv4/hostname)
                        String h = trimAggressivelyToNull(input.substring(0, colon));
                        String ps = trimAggressivelyToNull(input.substring(colon + 1));
                        Integer p = null;

                        if (ps != null) {
                                try {
                                        p = Integer.parseInt(ps, 10);
                                } catch (Exception ignored) {
                                        // Nothing to do
                                }
                        }
                        if (h != null)
                                return Optional.of(new HostPort(h, p));
                }

                // no port
                return Optional.of(new HostPort(input, null));
        }

        @NonNull
        private static String removeDotSegments(@NonNull String path) {
                requireNonNull(path);

                Deque<String> stack = new ArrayDeque<>();

                for (String seg : path.split("/", -1)) {
                        if (seg.isEmpty() || ".".equals(seg))
                                continue;

                        if ("..".equals(seg)) {
                                if (!stack.isEmpty())
                                        stack.removeLast();
                        } else {
                                stack.addLast(seg);
                        }
                }

                return "/" + String.join("/", stack);
        }
}