001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.jose;
018
019import com.revetsec.json.JsonObject;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022
023import javax.annotation.concurrent.Immutable;
024import java.util.Collections;
025import java.util.LinkedHashMap;
026import java.util.List;
027import java.util.Map;
028import java.util.Optional;
029
030/**
031 * An immutable HTTP response containing only public JWKS data. Emit its prepared status, headers and bytes together;
032 * in particular, a HEAD response has no body but describes the GET representation's length.
033 *
034 * @since 1.0.0
035 */
036@Immutable
037public final class JwksResponse {
038
039        private final int statusCode;
040        private final @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> headers;
041        private final byte @NonNull [] body;
042        private final @Nullable JsonObject document;
043
044        JwksResponse(int statusCode,
045                        @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> headers, byte @NonNull [] body,
046                        @Nullable JsonObject document) {
047                this.statusCode = statusCode;
048                Map<String, List<String>> snapshot = new LinkedHashMap<>();
049                headers.forEach((name, values) -> snapshot.put(name, List.copyOf(values)));
050                this.headers = Collections.unmodifiableMap(snapshot);
051                this.body = body.clone();
052                this.document = document;
053        }
054
055        /**
056         * Returns the prepared HTTP status.
057         * @return the status code
058         * @since 1.0.0
059         */
060        public @NonNull Integer getStatusCode() {
061                return this.statusCode;
062        }
063
064        /**
065         * Returns immutable HTTP header occurrences.
066         * @return the prepared headers
067         * @since 1.0.0
068         */
069        public @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> getHeaders() {
070                return this.headers;
071        }
072
073        /**
074         * Returns a defensive copy of the prepared public response body.
075         * @return the body, empty for HEAD, 304 and method/header rejections
076         * @since 1.0.0
077         */
078        public byte @NonNull [] toHttpBody() {
079                return this.body.clone();
080        }
081
082        /**
083         * Returns the immutable public document when this response has a GET body. This is an explicit public-key
084         * document emission; diagnostics remain redacted. The prepared headers describe {@link #toHttpBody()}, so an
085         * application that serializes this document itself must calculate its own representation length and validator.
086         * @return the document, absent for HEAD, 304 and method/header rejections
087         * @since 1.0.0
088         */
089        public @NonNull Optional<@NonNull JsonObject> getDocument() {
090                return Optional.ofNullable(this.document);
091        }
092
093        /**
094         * Returns a description without keys or header contents.
095         * @return the diagnostic description
096         * @since 1.0.0
097         */
098        @Override
099        public @NonNull String toString() {
100                return "JwksResponse{statusCode=" + this.statusCode + "}";
101        }
102}