/*
 * 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 org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import javax.annotation.concurrent.NotThreadSafe;
import javax.annotation.concurrent.ThreadSafe;
import java.net.HttpCookie;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.SignStyle;
import java.time.temporal.ChronoField;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;

import static com.soklet.Utilities.trimAggressivelyToNull;
import static java.lang.String.format;
import static java.util.Objects.requireNonNull;

/**
 * HTTP "response" Cookie representation which supports {@code Set-Cookie} header encoding.
 * <p>
 * Threadsafe instances can be acquired via these builder factory methods:
 * <ul>
 *   <li>{@link #with(String, String)} (builder primed with name and value)</li>
 *   <li>{@link #withName(String)} (builder primed with name only)</li>
 * </ul>
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 */
@ThreadSafe
public final class ResponseCookie {
        @NonNull
        private final String name;
        @Nullable
        private final String value;
        @Nullable
        private final Duration maxAge;
        @Nullable
        private final Instant expires;
        @Nullable
        private final String domain;
        @Nullable
        private final String path;
        @NonNull
        private final Boolean secure;
        @NonNull
        private final Boolean httpOnly;
        @Nullable
        private final SameSite sameSite;
        @Nullable
        private final Priority priority;
        @NonNull
        private final Boolean partitioned;

        @NonNull
        private static final DateTimeFormatter RFC_1123_FORMATTER;
        @NonNull
        private static final DateTimeFormatter RFC_1036_PARSER;
        @NonNull
        private static final DateTimeFormatter ASCTIME_PARSER;

        static {
                RFC_1123_FORMATTER = DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneId.of("GMT"));
                RFC_1036_PARSER = new DateTimeFormatterBuilder()
                                .parseCaseInsensitive()
                                .appendPattern("EEE, dd MMM ")
                                .appendValueReduced(ChronoField.YEAR, 2, 2, 1900)
                                .appendPattern(" HH:mm:ss zzz")
                                .toFormatter(Locale.US)
                                .withZone(ZoneOffset.UTC);
                ASCTIME_PARSER = new DateTimeFormatterBuilder()
                                .parseCaseInsensitive()
                                .appendPattern("EEE MMM")
                                .appendLiteral(' ')
                                .optionalStart().appendLiteral(' ').optionalEnd()
                                .appendValue(ChronoField.DAY_OF_MONTH, 1, 2, SignStyle.NOT_NEGATIVE)
                                .appendPattern(" HH:mm:ss yyyy")
                                .toFormatter(Locale.US)
                                .withZone(ZoneOffset.UTC);
        }

        /**
         * Acquires a builder for {@link ResponseCookie} instances.
         *
         * @param name  the cookie name
         * @param value the cookie value
         * @return the builder
         */
        @NonNull
        public static Builder with(@NonNull String name,
                                                                                                                 @Nullable String value) {
                requireNonNull(name);
                return new Builder(name, value);
        }

        /**
         * Acquires a builder for {@link ResponseCookie} instances without specifying the cookie's value.
         *
         * @param name the cookie name
         * @return the builder
         */
        @NonNull
        public static Builder withName(@NonNull String name) {
                requireNonNull(name);
                return new Builder(name);
        }

        /**
         * Vends a mutable copier seeded with this instance's data, suitable for building new instances.
         *
         * @return a copier for this instance
         */
        @NonNull
        public Copier copy() {
                return new Copier(this);
        }

        /**
         * Given a {@code Set-Cookie} header representation, provide a {@link ResponseCookie} that matches it.
         * <p>
         * An example of a {@code Set-Cookie} header representation is {@code Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly}
         * <p>
         * Note: while the spec does not forbid multiple cookie name/value pairs to be specified in the same {@code Set-Cookie} header, this format is unusual - Soklet does not currently support parsing these kinds of cookies.
         * <p>
         * See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie">https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie</a> for details.
         *
         * @param setCookieHeaderRepresentation a {@code Set-Cookie} header representation
         * @return a {@link ResponseCookie} representation of the {@code Set-Cookie} header, or {@link Optional#empty()} if the header is null, empty, or does not include cookie data
         * @throws IllegalArgumentException if the {@code Set-Cookie} header representation is malformed
         */
        @NonNull
        public static Optional<ResponseCookie> fromSetCookieHeaderRepresentation(@Nullable String setCookieHeaderRepresentation) {
                setCookieHeaderRepresentation = setCookieHeaderRepresentation == null ? null : setCookieHeaderRepresentation.trim();

                if (setCookieHeaderRepresentation == null || setCookieHeaderRepresentation.length() == 0)
                        return Optional.empty();

                String normalizedSetCookieHeaderRepresentation = stripSetCookiePrefix(setCookieHeaderRepresentation);

                if (normalizedSetCookieHeaderRepresentation == null || normalizedSetCookieHeaderRepresentation.length() == 0)
                        return Optional.empty();

                List<HttpCookie> cookies = HttpCookie.parse(normalizedSetCookieHeaderRepresentation);

                if (cookies.size() == 0)
                        return Optional.empty();

                // Technically OK per the spec to "fold" multiple cookie name/value pairs into the same header but this is
                // unusual, and we don't support it here.  Pick the first cookie and use it.
                HttpCookie httpCookie = cookies.get(0);

                // Handle session cookies (maxAge = -1) by passing null instead of negative Duration
                long maxAge = httpCookie.getMaxAge();
                Duration maxAgeDuration = (maxAge >= 0) ? Duration.ofSeconds(maxAge) : null;

                ParsedSetCookieAttributes attributes = parseSetCookieAttributes(normalizedSetCookieHeaderRepresentation);

                return Optional.of(ResponseCookie.with(httpCookie.getName(), httpCookie.getValue())
                                .maxAge(maxAgeDuration)
                                .expires(attributes.getExpires().orElse(null))
                                .domain(httpCookie.getDomain())
                                .httpOnly(httpCookie.isHttpOnly())
                                .secure(httpCookie.getSecure())
                                .path(httpCookie.getPath())
                                .sameSite(attributes.getSameSite().orElse(null))
                                .priority(attributes.getPriority().orElse(null))
                                .partitioned(attributes.getPartitioned())
                                .build());
        }

        @Nullable
        private static String stripSetCookiePrefix(@NonNull String setCookieHeaderRepresentation) {
                requireNonNull(setCookieHeaderRepresentation);

                String trimmed = trimAggressivelyToNull(setCookieHeaderRepresentation);

                if (trimmed == null)
                        return null;

                String prefix = "set-cookie:";

                if (trimmed.length() >= prefix.length()
                                && trimmed.regionMatches(true, 0, prefix, 0, prefix.length()))
                        return trimAggressivelyToNull(trimmed.substring(prefix.length()));

                return trimmed;
        }

        @NonNull
        private static ParsedSetCookieAttributes parseSetCookieAttributes(@NonNull String setCookieHeaderRepresentation) {
                requireNonNull(setCookieHeaderRepresentation);

                ParsedSetCookieAttributes attributes = new ParsedSetCookieAttributes();
                List<String> components = splitSetCookieHeaderRespectingQuotes(setCookieHeaderRepresentation);

                if (components.size() <= 1)
                        return attributes;

                for (int i = 1; i < components.size(); i++) {
                        String component = trimAggressivelyToNull(components.get(i));
                        if (component == null)
                                continue;

                        int equalsIndex = component.indexOf('=');
                        String attributeName = trimAggressivelyToNull(equalsIndex == -1 ? component : component.substring(0, equalsIndex));

                        if (attributeName == null)
                                continue;

                        String attributeValue = equalsIndex == -1 ? null : trimAggressivelyToNull(component.substring(equalsIndex + 1));

                        if ("samesite".equalsIgnoreCase(attributeName)) {
                                if (attributes.sameSite == null && attributeValue != null) {
                                        attributeValue = stripOptionalQuotes(attributeValue);
                                        attributes.sameSite = SameSite.fromHeaderRepresentation(attributeValue).orElse(null);
                                }
                                continue;
                        }

                        if ("expires".equalsIgnoreCase(attributeName)) {
                                if (attributes.expires == null && attributeValue != null) {
                                        try {
                                                attributeValue = stripOptionalQuotes(attributeValue);
                                                attributes.expires = parseHttpDate(attributeValue);
                                        } catch (IllegalArgumentException ignored) {
                                                // Ignore malformed Expires attribute
                                        }
                                }
                                continue;
                        }

                        if ("priority".equalsIgnoreCase(attributeName)) {
                                if (attributes.priority == null && attributeValue != null) {
                                        attributeValue = stripOptionalQuotes(attributeValue);
                                        attributes.priority = Priority.fromHeaderRepresentation(attributeValue).orElse(null);
                                }
                                continue;
                        }

                        if ("partitioned".equalsIgnoreCase(attributeName))
                                attributes.partitioned = true;
                }

                return attributes;
        }

        @NonNull
        private static Instant parseHttpDate(@NonNull String value) {
                requireNonNull(value);

                String trimmed = trimAggressivelyToNull(value);

                if (trimmed == null)
                        throw new IllegalArgumentException("Date value cannot be blank");

                for (DateTimeFormatter formatter : List.of(RFC_1123_FORMATTER, RFC_1036_PARSER, ASCTIME_PARSER)) {
                        try {
                                return Instant.from(formatter.parse(trimmed));
                        } catch (Exception ignored) {
                                // try next formatter
                        }
                }

                throw new IllegalArgumentException(format("Unable to parse HTTP-date value '%s'", trimmed));
        }

        @NonNull
        private static List<@NonNull String> splitSetCookieHeaderRespectingQuotes(@NonNull String headerValue) {
                requireNonNull(headerValue);

                List<String> parts = new ArrayList<>();
                StringBuilder current = new StringBuilder(headerValue.length());
                boolean inQuotes = false;
                boolean escaped = false;

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

                        if (escaped) {
                                current.append(c);
                                escaped = false;
                                continue;
                        }

                        if (c == '\\') {
                                escaped = true;
                                current.append(c);
                                continue;
                        }

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

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

                        current.append(c);
                }

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

                return parts;
        }

        @NonNull
        private static String stripOptionalQuotes(@NonNull String value) {
                requireNonNull(value);

                if (value.length() >= 2 && value.startsWith("\"") && value.endsWith("\""))
                        return value.substring(1, value.length() - 1);

                return value;
        }

        private ResponseCookie(@NonNull Builder builder) {
                requireNonNull(builder);

                this.name = builder.name;
                this.value = builder.value;
                this.maxAge = builder.maxAge;
                this.expires = builder.expires;
                this.domain = builder.domain;
                this.path = trimAggressivelyToNull(builder.path); // Can't specify blank paths. Must be null (omitted) or start with "/"
                this.secure = builder.secure == null ? false : builder.secure;
                this.httpOnly = builder.httpOnly == null ? false : builder.httpOnly;
                this.sameSite = builder.sameSite;
                this.priority = builder.priority;
                this.partitioned = builder.partitioned == null ? false : builder.partitioned;

                // Extra validation to ensure we are not creating cookies that are illegal according to the spec

                Rfc6265Utils.validateCookieName(getName());
                Rfc6265Utils.validateCookieValue(getValue().orElse(null));
                Rfc6265Utils.validateDomain(getDomain().orElse(null));
                Rfc6265Utils.validatePath(getPath().orElse(null));

                if (this.maxAge != null && this.maxAge.isNegative())
                        throw new IllegalArgumentException("Max-Age must be >= 0");

                if (this.sameSite == SameSite.NONE && (this.secure == null || !this.secure))
                        throw new IllegalArgumentException(format("Specifying %s value %s.%s requires that you also set secure=true, otherwise browsers will likely discard the cookie",
                                        ResponseCookie.class.getSimpleName(), SameSite.class.getSimpleName(), SameSite.NONE.name()));

                if (this.partitioned) {
                        if (this.secure == null || !this.secure)
                                throw new IllegalArgumentException("Partitioned cookies require secure=true");

                        String cookiePath = getPath().orElse(null);
                        if (cookiePath == null || !cookiePath.equals("/"))
                                throw new IllegalArgumentException("Partitioned cookies require path=\"/\"");

                        if (this.sameSite != SameSite.NONE)
                                throw new IllegalArgumentException("Partitioned cookies require SameSite=None");
                }
        }

        /**
         * Generates a {@code Set-Cookie} header representation of this response cookie, for example {@code Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly}
         * <p>
         * See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie">https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie</a> for details.
         *
         * @return this response cookie in {@code Set-Cookie} header format
         */
        @NonNull
        public String toSetCookieHeaderRepresentation() {
                List<String> components = new ArrayList<>(10);

                components.add(format("%s=%s", getName(), getValue().orElse("")));

                if (getPath().isPresent())
                        components.add(format("Path=%s", getPath().get()));

                if (getDomain().isPresent())
                        components.add(format("Domain=%s", getDomain().get()));

                long maxAge = getMaxAge().isPresent() ? getMaxAge().get().toSeconds() : -1;

                if (maxAge >= 0)
                        components.add(format("Max-Age=%d", maxAge));

                if (getExpires().isPresent())
                        components.add(format("Expires=%s", RFC_1123_FORMATTER.format(getExpires().get())));

                if (getSecure())
                        components.add("Secure");

                if (getHttpOnly())
                        components.add("HttpOnly");

                if (getSameSite().isPresent())
                        components.add(format("SameSite=%s", getSameSite().get().getHeaderRepresentation()));

                if (getPriority().isPresent())
                        components.add(format("Priority=%s", getPriority().get().getHeaderRepresentation()));

                if (getPartitioned())
                        components.add("Partitioned");

                return components.stream().collect(Collectors.joining("; "));
        }

        @Override
        public int hashCode() {
                return Objects.hash(
                                getName(),
                                getValue(),
                                getMaxAge(),
                                getExpires(),
                                getDomain(),
                                getPath(),
                                getSecure(),
                                getHttpOnly(),
                                getSameSite(),
                                getPriority(),
                                getPartitioned()
                );
        }

        @Override
        public boolean equals(@Nullable Object object) {
                if (this == object)
                        return true;

                if (!(object instanceof ResponseCookie responseCookie))
                        return false;

                return Objects.equals(getName(), responseCookie.getName())
                                && Objects.equals(getValue(), responseCookie.getValue())
                                && Objects.equals(getMaxAge(), responseCookie.getMaxAge())
                                && Objects.equals(getExpires(), responseCookie.getExpires())
                                && Objects.equals(getDomain(), responseCookie.getDomain())
                                && Objects.equals(getPath(), responseCookie.getPath())
                                && Objects.equals(getSecure(), responseCookie.getSecure())
                                && Objects.equals(getHttpOnly(), responseCookie.getHttpOnly())
                                && Objects.equals(getSameSite(), responseCookie.getSameSite())
                                && Objects.equals(getPriority(), responseCookie.getPriority())
                                && Objects.equals(getPartitioned(), responseCookie.getPartitioned());
        }

        @Override
        @NonNull
        public String toString() {
                return toSetCookieHeaderRepresentation();
        }

        /**
         * Gets the cookie's name.
         *
         * @return the name of the cookie
         */
        @NonNull
        public String getName() {
                return this.name;
        }

        /**
         * Gets the cookie's value, if present.
         *
         * @return the value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<String> getValue() {
                return Optional.ofNullable(this.value);
        }

        /**
         * Gets the cookie's {@code Max-Age} value expressed as a {@link Duration}, if present.
         *
         * @return the {@code Max-Age} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<Duration> getMaxAge() {
                return Optional.ofNullable(this.maxAge);
        }

        /**
         * Gets the cookie's {@code Expires} value, if present.
         *
         * @return the {@code Expires} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<Instant> getExpires() {
                return Optional.ofNullable(this.expires);
        }

        /**
         * Gets the cookie's {@code Domain} value, if present.
         *
         * @return the {@code Domain} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<String> getDomain() {
                return Optional.ofNullable(this.domain);
        }

        /**
         * Gets the cookie's {@code Path} value, if present.
         *
         * @return the {@code Path} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<String> getPath() {
                return Optional.ofNullable(this.path);
        }

        /**
         * Gets the cookie's {@code Secure} flag, if present.
         *
         * @return {@code true} if the {@code Secure} flag of the cookie is present, {@code false} otherwise
         */
        @NonNull
        public Boolean getSecure() {
                return this.secure;
        }

        /**
         * Gets the cookie's {@code HttpOnly} flag, if present.
         *
         * @return {@code true} if the {@code HttpOnly} flag of the cookie is present, {@code false} otherwise
         */
        @NonNull
        public Boolean getHttpOnly() {
                return this.httpOnly;
        }

        /**
         * Gets the cookie's {@code SameSite} value, if present.
         *
         * @return the {@code SameSite} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<SameSite> getSameSite() {
                return Optional.ofNullable(this.sameSite);
        }

        /**
         * Gets the cookie's {@code Priority} value, if present.
         *
         * @return the {@code Priority} value of the cookie, or {@link Optional#empty()} if there is none
         */
        @NonNull
        public Optional<Priority> getPriority() {
                return Optional.ofNullable(this.priority);
        }

        /**
         * Gets the cookie's {@code Partitioned} flag.
         *
         * @return {@code true} if the {@code Partitioned} flag is present, {@code false} otherwise
         */
        @NonNull
        public Boolean getPartitioned() {
                return this.partitioned;
        }

        /**
         * Values which control whether a response cookie is sent with cross-site requests, providing some protection against cross-site request forgery attacks (CSRF).
         * <p>
         * See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value">https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value</a> for details.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        public enum SameSite {
                /**
                 * Means that the browser sends the cookie only for same-site requests, that is, requests originating from the same site that set the cookie.
                 * If a request originates from a different domain or scheme (even with the same domain), no cookies with the {@code SameSite=Strict} attribute are sent.
                 */
                STRICT("Strict"),
                /**
                 * Means that the cookie is not sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site (for example, when following a link).
                 * This is the default behavior if the {@code SameSite} attribute is not specified.
                 */
                LAX("Lax"),
                /**
                 * Means that the browser sends the cookie with both cross-site and same-site requests.
                 * The {@code Secure} attribute must also be set when setting this value, like so {@code SameSite=None; Secure}. If {@code Secure} is missing, an error will be logged.
                 */
                NONE("None");

                @NonNull
                private final String headerRepresentation;

                SameSite(@NonNull String headerRepresentation) {
                        requireNonNull(headerRepresentation);
                        this.headerRepresentation = headerRepresentation;
                }

                /**
                 * Returns the {@link SameSite} enum value that matches the corresponding {@code SameSite} response header value representation (one of {@code Strict}, {@code Lax}, or {@code None} - case-insensitive).
                 *
                 * @param headerRepresentation a case-insensitive HTTP header value - one of {@code Strict}, {@code Lax}, or {@code None}
                 * @return the enum value that corresponds to the given the header representation, or {@link Optional#empty()} if none matches
                 */
                @NonNull
                public static Optional<SameSite> fromHeaderRepresentation(@NonNull String headerRepresentation) {
                        requireNonNull(headerRepresentation);

                        headerRepresentation = headerRepresentation.trim();

                        for (SameSite sameSite : values())
                                if (headerRepresentation.equalsIgnoreCase(sameSite.getHeaderRepresentation()))
                                        return Optional.of(sameSite);

                        return Optional.empty();
                }

                /**
                 * The HTTP header value that corresponds to this enum value - one of {@code Strict}, {@code Lax}, or {@code None}.
                 *
                 * @return the HTTP header value for this enum
                 */
                @NonNull
                public String getHeaderRepresentation() {
                        return this.headerRepresentation;
                }
        }

        /**
         * Represents the {@code Priority} response cookie attribute.
         */
        public enum Priority {
                LOW("Low"),
                MEDIUM("Medium"),
                HIGH("High");

                @NonNull
                private final String headerRepresentation;

                Priority(@NonNull String headerRepresentation) {
                        requireNonNull(headerRepresentation);
                        this.headerRepresentation = headerRepresentation;
                }

                @NonNull
                public String getHeaderRepresentation() {
                        return this.headerRepresentation;
                }

                @NonNull
                public static Optional<Priority> fromHeaderRepresentation(@NonNull String headerRepresentation) {
                        requireNonNull(headerRepresentation);

                        String normalized = headerRepresentation.trim();

                        for (Priority priority : values())
                                if (normalized.equalsIgnoreCase(priority.getHeaderRepresentation()))
                                        return Optional.of(priority);

                        return Optional.empty();
                }
        }

        /**
         * Builder used to construct instances of {@link ResponseCookie} via {@link ResponseCookie#withName(String)}
         * or {@link ResponseCookie#with(String, String)}.
         * <p>
         * This class is intended for use by a single thread.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class Builder {
                @NonNull
                private String name;
                @Nullable
                private String value;
                @Nullable
                private Duration maxAge;
                @Nullable
                private Instant expires;
                @Nullable
                private String domain;
                @Nullable
                private String path;
                @Nullable
                private Boolean secure;
                @Nullable
                private Boolean httpOnly;
                @Nullable
                private SameSite sameSite;
                @Nullable
                private Priority priority;
                @Nullable
                private Boolean partitioned;

                protected Builder(@NonNull String name) {
                        requireNonNull(name);
                        this.name = name;
                }

                protected Builder(@NonNull String name,
                                                                                        @Nullable String value) {
                        requireNonNull(name);
                        this.name = name;
                        this.value = value;
                }

                @NonNull
                public Builder name(@NonNull String name) {
                        requireNonNull(name);
                        this.name = name;
                        return this;
                }

                @NonNull
                public Builder value(@Nullable String value) {
                        this.value = value;
                        return this;
                }

                @NonNull
                public Builder maxAge(@Nullable Duration maxAge) {
                        this.maxAge = maxAge;
                        return this;
                }

                @NonNull
                public Builder expires(@Nullable Instant expires) {
                        this.expires = expires;
                        return this;
                }

                @NonNull
                public Builder domain(@Nullable String domain) {
                        this.domain = domain;
                        return this;
                }

                @NonNull
                public Builder path(@Nullable String path) {
                        this.path = path;
                        return this;
                }

                @NonNull
                public Builder secure(@Nullable Boolean secure) {
                        this.secure = secure;
                        return this;
                }

                @NonNull
                public Builder httpOnly(@Nullable Boolean httpOnly) {
                        this.httpOnly = httpOnly;
                        return this;
                }

                @NonNull
                public Builder sameSite(@Nullable SameSite sameSite) {
                        this.sameSite = sameSite;
                        return this;
                }

                @NonNull
                public Builder priority(@Nullable Priority priority) {
                        this.priority = priority;
                        return this;
                }

                @NonNull
                public Builder partitioned(@Nullable Boolean partitioned) {
                        this.partitioned = partitioned;
                        return this;
                }

                @NonNull
                public ResponseCookie build() {
                        return new ResponseCookie(this);
                }
        }

        /**
         * Builder used to copy instances of {@link ResponseCookie} via {@link ResponseCookie#copy()}.
         * <p>
         * This class is intended for use by a single thread.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class Copier {
                @NonNull
                private final Builder builder;

                Copier(@NonNull ResponseCookie responseCookie) {
                        requireNonNull(responseCookie);

                        this.builder = new Builder(responseCookie.getName())
                                        .value(responseCookie.getValue().orElse(null))
                                        .maxAge(responseCookie.getMaxAge().orElse(null))
                                        .expires(responseCookie.getExpires().orElse(null))
                                        .domain(responseCookie.getDomain().orElse(null))
                                        .path(responseCookie.getPath().orElse(null))
                                        .secure(responseCookie.getSecure())
                                        .httpOnly(responseCookie.getHttpOnly())
                                        .sameSite(responseCookie.getSameSite().orElse(null))
                                        .priority(responseCookie.getPriority().orElse(null))
                                        .partitioned(responseCookie.getPartitioned());
                }

                @NonNull
                public Copier name(@NonNull String name) {
                        requireNonNull(name);
                        this.builder.name(name);
                        return this;
                }

                @NonNull
                public Copier value(@Nullable String value) {
                        this.builder.value(value);
                        return this;
                }

                @NonNull
                public Copier maxAge(@Nullable Duration maxAge) {
                        this.builder.maxAge(maxAge);
                        return this;
                }

                @NonNull
                public Copier expires(@Nullable Instant expires) {
                        this.builder.expires(expires);
                        return this;
                }

                @NonNull
                public Copier domain(@Nullable String domain) {
                        this.builder.domain(domain);
                        return this;
                }

                @NonNull
                public Copier path(@Nullable String path) {
                        this.builder.path(path);
                        return this;
                }

                @NonNull
                public Copier secure(@Nullable Boolean secure) {
                        this.builder.secure(secure);
                        return this;
                }

                @NonNull
                public Copier httpOnly(@Nullable Boolean httpOnly) {
                        this.builder.httpOnly(httpOnly);
                        return this;
                }

                @NonNull
                public Copier sameSite(@Nullable SameSite sameSite) {
                        this.builder.sameSite(sameSite);
                        return this;
                }

                @NonNull
                public Copier priority(@Nullable Priority priority) {
                        this.builder.priority(priority);
                        return this;
                }

                @NonNull
                public Copier partitioned(@Nullable Boolean partitioned) {
                        this.builder.partitioned(partitioned);
                        return this;
                }

                @NonNull
                public ResponseCookie finish() {
                        return this.builder.build();
                }
        }

        @ThreadSafe
        private static final class ParsedSetCookieAttributes {
                @Nullable
                private Instant expires;
                @Nullable
                private SameSite sameSite;
                @Nullable
                private Priority priority;
                @NonNull
                private Boolean partitioned = false;

                @NonNull
                private Optional<Instant> getExpires() {
                        return Optional.ofNullable(this.expires);
                }

                @NonNull
                private Optional<SameSite> getSameSite() {
                        return Optional.ofNullable(this.sameSite);
                }

                @NonNull
                private Optional<Priority> getPriority() {
                        return Optional.ofNullable(this.priority);
                }

                @NonNull
                private Boolean getPartitioned() {
                        return this.partitioned;
                }
        }

        /**
         * See https://github.com/spring-projects/spring-framework/blob/main/spring-web/src/main/java/org/springframework/http/ResponseCookie.java
         * <p>
         * Copyright 2002-2023 the original author or authors.
         * <p>
         * 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
         * <p>
         * https://www.apache.org/licenses/LICENSE-2.0
         * <p>
         * 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.
         * <p>
         *
         * @author Rossen Stoyanchev
         * @author Brian Clozel
         */
        @ThreadSafe
        private static class Rfc6265Utils {
                @NonNull
                private static final String SEPARATOR_CHARS = new String(new char[]{
                                '(', ')', '<', '>', '@', ',', ';', ':', '\\', '"', '/', '[', ']', '?', '=', '{', '}', ' '
                });

                @NonNull
                private static final String DOMAIN_CHARS =
                                "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-";

                public static void validateCookieName(@NonNull String name) {
                        requireNonNull(name);

                        for (int i = 0; i < name.length(); i++) {
                                char c = name.charAt(i);
                                // CTL = <US-ASCII control chars (octets 0 - 31) and DEL (127)>
                                if (c <= 0x1F || c == 0x7F) {
                                        throw new IllegalArgumentException(
                                                        name + ": RFC2616 token cannot have control chars");
                                }
                                if (SEPARATOR_CHARS.indexOf(c) >= 0) {
                                        throw new IllegalArgumentException(
                                                        name + ": RFC2616 token cannot have separator chars such as '" + c + "'");
                                }
                                if (c >= 0x80) {
                                        throw new IllegalArgumentException(
                                                        name + ": RFC2616 token can only have US-ASCII: 0x" + Integer.toHexString(c));
                                }
                        }
                }

                public static void validateCookieValue(@Nullable String value) {
                        if (value == null) {
                                return;
                        }
                        int start = 0;
                        int end = value.length();
                        if (end > 1 && value.charAt(0) == '"' && value.charAt(end - 1) == '"') {
                                start = 1;
                                end--;
                        }
                        for (int i = start; i < end; i++) {
                                char c = value.charAt(i);
                                if (c < 0x21 || c == 0x22 || c == 0x2c || c == 0x3b || c == 0x5c || c == 0x7f) {
                                        throw new IllegalArgumentException(
                                                        "RFC2616 cookie value cannot have '" + c + "'");
                                }
                                if (c >= 0x80) {
                                        throw new IllegalArgumentException(
                                                        "RFC2616 cookie value can only have US-ASCII chars: 0x" + Integer.toHexString(c));
                                }
                        }
                }

                public static void validateDomain(@Nullable String domain) {
                        if (domain == null || domain.trim().length() == 0) {
                                return;
                        }
                        int char1 = domain.charAt(0);
                        int charN = domain.charAt(domain.length() - 1);
                        if (char1 == '-' || charN == '.' || charN == '-') {
                                throw new IllegalArgumentException("Invalid first/last char in cookie domain: " + domain);
                        }
                        for (int i = 0, c = -1; i < domain.length(); i++) {
                                int p = c;
                                c = domain.charAt(i);
                                if (DOMAIN_CHARS.indexOf(c) == -1 || (p == '.' && (c == '.' || c == '-')) || (p == '-' && c == '.')) {
                                        throw new IllegalArgumentException(domain + ": invalid cookie domain char '" + (char) c + "'");
                                }
                        }
                }

                public static void validatePath(@Nullable String path) {
                        if (path == null)
                                return;

                        // Check for path traversal attempts
                        if (path.contains("..")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain '..' segments (path traversal): " + path
                                );
                        }

                        // Check for query strings
                        if (path.contains("?")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain query strings: " + path
                                );
                        }

                        // Check for fragments
                        if (path.contains("#")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain fragments: " + path
                                );
                        }

                        // Check for backslashes (Windows-style paths)
                        if (path.contains("\\")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain backslashes: " + path
                                );
                        }

                        // Check for URL-encoded dots (potential bypass attempt)
                        if (path.contains("%2E") || path.contains("%2e")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain encoded dots: " + path
                                );
                        }

                        // Must start with forward slash
                        if (!path.startsWith("/")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must start with '/': " + path
                                );
                        }

                        // Check for null bytes
                        if (path.contains("\0") || path.contains("%00")) {
                                throw new IllegalArgumentException(
                                                "Cookie path must not contain null bytes: " + path
                                );
                        }

                        for (int i = 0; i < path.length(); i++) {
                                char c = path.charAt(i);
                                if (c < 0x20 || c > 0x7E || c == ';') {
                                        throw new IllegalArgumentException(path + ": Invalid cookie path char '" + c + "'");
                                }
                        }
                }
        }
}