001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.ThreadSafe;
023import java.util.Collections;
024import java.util.EnumSet;
025import java.util.Objects;
026import java.util.Set;
027
028import static java.lang.String.format;
029import static java.util.Objects.requireNonNull;
030
031/**
032 * Immutable decision from evaluating HTTP conditional request fields against a selected representation snapshot.
033 * <p>
034 * Only {@link ConditionalRequests} and the framework's shared evaluator create these values. A decision does not
035 * authorize a request, lock storage, or establish that its preconditions will remain true when a mutation commits.
036 * <p>
037 * This is a closed domain; exhaustive switches are supported, and any new alternative requires an explicit reviewed
038 * contract amendment.
039 *
040 * @author <a href="https://www.revetkn.com">Mark Allen</a>
041 */
042@ThreadSafe
043public sealed interface ConditionalRequestResult permits ConditionalRequestResult.Proceed,
044                ConditionalRequestResult.NotModified, ConditionalRequestResult.PreconditionFailed {
045        /**
046         * Preconditions handled by this decision API. Range selection and {@code If-Range} are separate.
047         * <p>
048         * This is a closed domain; exhaustive switches are supported, and any new alternative requires an explicit reviewed
049         * contract amendment.
050         */
051        enum Precondition {
052                /** The {@code If-Match} strong entity-tag or existence precondition. */
053                IF_MATCH("If-Match"),
054                /** The {@code If-Unmodified-Since} modification-date precondition. */
055                IF_UNMODIFIED_SINCE("If-Unmodified-Since"),
056                /** The {@code If-None-Match} weak entity-tag or nonexistence precondition. */
057                IF_NONE_MATCH("If-None-Match"),
058                /** The {@code If-Modified-Since} GET/HEAD modification-date precondition. */
059                IF_MODIFIED_SINCE("If-Modified-Since");
060
061                @NonNull
062                private final String headerName;
063
064                Precondition(@NonNull String headerName) {
065                        this.headerName = requireNonNull(headerName);
066                }
067
068                /**
069                 * The name of the request header that carries this precondition, such as {@code If-Match}.
070                 * <p>
071                 * Useful when an application-owned response or log entry names the precondition that decided a request.
072                 *
073                 * @return the request header name
074                 */
075                @NonNull
076                public String getHeaderName() {
077                        return this.headerName;
078                }
079        }
080
081        /**
082         * No conditional short circuit is required. Ignored or invalid fields do not necessarily prevent this result.
083         * <p>
084         * The satisfied set describes only the supplied snapshot. It does not certify complete header validity, adequate
085         * lost-update protection, authorization, or continued truth at commit time. An internal storage compare-and-set
086         * failure requires fresh evaluation unless the application establishes an equivalent, narrowly accepted predicate.
087         */
088        @ThreadSafe
089        final class Proceed implements ConditionalRequestResult {
090                @NonNull
091                private final Set<@NonNull Precondition> satisfiedPreconditions;
092
093                Proceed(@NonNull Set<@NonNull Precondition> satisfiedPreconditions) {
094                        requireNonNull(satisfiedPreconditions);
095                        EnumSet<Precondition> copied = EnumSet.noneOf(Precondition.class);
096                        copied.addAll(satisfiedPreconditions);
097                        if ((copied.contains(Precondition.IF_MATCH) && copied.contains(Precondition.IF_UNMODIFIED_SINCE))
098                                        || (copied.contains(Precondition.IF_NONE_MATCH) && copied.contains(Precondition.IF_MODIFIED_SINCE)))
099                                throw new IllegalArgumentException("Satisfied preconditions cannot contain a suppressed date condition.");
100                        this.satisfiedPreconditions = Collections.unmodifiableSet(copied);
101                }
102
103                /**
104                 * Returns an immutable set of the present preconditions that were actually evaluated and true.
105                 * <table>
106                 * <caption>Meaning of satisfied preconditions</caption>
107                 * <tr><th>Member</th><th>What held</th><th>What it does not establish</th></tr>
108                 * <tr><td>{@code IF_MATCH}</td><td>A wildcard found an existing representation, or a list contained its current
109                 * strong tag.</td><td>A wildcard identifies no revision; this set does not disclose which form was used.</td></tr>
110                 * <tr><td>{@code IF_UNMODIFIED_SINCE}</td><td>An available modification time was no later than the valid supplied
111                 * date, at whole-second precision.</td><td>No intervening write within that second.</td></tr>
112                 * <tr><td>{@code IF_NONE_MATCH}, existing representation</td><td>A valid list matched no current tag. An empty
113                 * list qualifies, and every valid list is nonmatching when the current tag is unavailable.</td>
114                 * <td>Revision-level lost-update protection.</td></tr>
115                 * <tr><td>{@code IF_NONE_MATCH}, missing representation</td><td>A wildcard or valid list evaluated true.</td>
116                 * <td>That the client specifically required create-if-absent with a wildcard.</td></tr>
117                 * <tr><td>{@code IF_MODIFIED_SINCE}</td><td>GET/HEAD's available modification time was later than the valid
118                 * supplied date.</td><td>Any write guard.</td></tr>
119                 * </table>
120                 * <p>
121                 * Invalid or unavailable dates and method-inapplicable or suppressed fields are absent. Any {@code If-Match}
122                 * presence suppresses {@code If-Unmodified-Since}; any {@code If-None-Match} presence suppresses
123                 * {@code If-Modified-Since}, including empty or malformed values. {@code OPTIONS} always has an empty set.
124                 * No set contains both {@code IF_MATCH} and {@code IF_UNMODIFIED_SINCE}, or both {@code IF_NONE_MATCH} and
125                 * {@code IF_MODIFIED_SINCE}. With no representation, only the empty set and {@code IF_NONE_MATCH} are possible.
126                 * For an existing representation, GET/HEAD permits nine sets: empty; each individual member; and each of
127                 * {@code IF_MATCH}/{@code IF_UNMODIFIED_SINCE} paired with each of {@code IF_NONE_MATCH}/{@code IF_MODIFIED_SINCE}.
128                 * Other applicable methods permit six: empty; {@code IF_MATCH}, {@code IF_UNMODIFIED_SINCE}, or
129                 * {@code IF_NONE_MATCH} individually; and either of the first two paired with {@code IF_NONE_MATCH}.
130                 *
131                 * @return immutable satisfied preconditions; the set may be empty
132                 */
133                @NonNull
134                public Set<@NonNull Precondition> getSatisfiedPreconditions() {
135                        return this.satisfiedPreconditions;
136                }
137
138                @Override
139                public boolean equals(@Nullable Object object) {
140                        return object instanceof Proceed other
141                                        && this.satisfiedPreconditions.equals(other.satisfiedPreconditions);
142                }
143
144                @Override
145                public int hashCode() {
146                        return Objects.hash(Proceed.class, this.satisfiedPreconditions);
147                }
148
149                @Override
150                @NonNull
151                public String toString() {
152                        return format("%s{satisfiedPreconditions=%s}", Proceed.class.getSimpleName(), getSatisfiedPreconditions());
153                }
154        }
155
156        /**
157         * GET/HEAD cache validation selected a bodyless {@code 304 Not Modified}. The decisive precondition is
158         * {@code IF_NONE_MATCH} or {@code IF_MODIFIED_SINCE}; a missing representation never produces this variant.
159         */
160        @ThreadSafe
161        final class NotModified implements ConditionalRequestResult {
162                @NonNull
163                private final Precondition precondition;
164
165                NotModified(@NonNull Precondition precondition) {
166                        this.precondition = requireNonNull(precondition);
167                        if (precondition != Precondition.IF_NONE_MATCH && precondition != Precondition.IF_MODIFIED_SINCE)
168                                throw new IllegalArgumentException("NotModified requires a cache-validation precondition.");
169                }
170
171                /** @return the decisive cache-validation precondition */
172                @NonNull
173                public Precondition getPrecondition() {
174                        return this.precondition;
175                }
176
177                @Override
178                public boolean equals(@Nullable Object object) {
179                        return object instanceof NotModified other && this.precondition == other.precondition;
180                }
181
182                @Override
183                public int hashCode() {
184                        return Objects.hash(NotModified.class, this.precondition);
185                }
186
187                @Override
188                @NonNull
189                public String toString() {
190                        return format("%s{precondition=%s}", NotModified.class.getSimpleName(), getPrecondition());
191                }
192        }
193
194        /**
195         * A precondition stopped processing. The convenience wrapper maps every reason to bodyless {@code 412}.
196         * <p>
197         * {@code IF_MATCH} and {@code IF_UNMODIFIED_SINCE} may fail on GET/HEAD as well as applicable mutation methods.
198         * {@code IF_NONE_MATCH} appears here only for non-GET/HEAD methods. {@code OPTIONS} never produces this result.
199         * Malformed or over-limit entity-tag fields fail closed on applicable mutation methods; invalid dates are ignored.
200         */
201        @ThreadSafe
202        final class PreconditionFailed implements ConditionalRequestResult {
203                @NonNull
204                private final Precondition precondition;
205                @NonNull
206                private final Reason reason;
207
208                PreconditionFailed(@NonNull Precondition precondition, @NonNull Reason reason) {
209                        this.precondition = requireNonNull(precondition);
210                        this.reason = requireNonNull(reason);
211                        if (precondition == Precondition.IF_MODIFIED_SINCE
212                                        || (precondition == Precondition.IF_UNMODIFIED_SINCE && reason != Reason.CONDITION_FALSE))
213                                throw new IllegalArgumentException("The precondition and failure reason cannot form this result.");
214                }
215
216                /** @return the first decisive precondition in evaluation order */
217                @NonNull
218                public Precondition getPrecondition() {
219                        return this.precondition;
220                }
221
222                /** @return why the decisive precondition stopped processing */
223                @NonNull
224                public Reason getReason() {
225                        return this.reason;
226                }
227
228                /**
229                 * Reason the decisive precondition stopped processing. Invalid dates never produce a failure reason.
230                 * <p>
231                 * This enum may gain reviewed constants in Soklet 4.x; use a forward-compatible default when switching over
232                 * its values.
233                 */
234                public enum Reason {
235                        /** Valid input evaluated false; weak If-Match tags and valid empty If-Match lists use this reason. */
236                        CONDITION_FALSE,
237                        /** The applicable entity-tag field could not be parsed. */
238                        MALFORMED,
239                        /**
240                         * Quote-aware list splitting exceeded its budget, currently 256 elements including empty elements.
241                         * Commas inside quoted tags do not count. This is not a claim that the field's syntax is invalid.
242                         */
243                        ENTITY_TAG_LIST_LIMIT_EXCEEDED
244                }
245
246                @Override
247                public boolean equals(@Nullable Object object) {
248                        return object instanceof PreconditionFailed other && this.precondition == other.precondition
249                                        && this.reason == other.reason;
250                }
251
252                @Override
253                public int hashCode() {
254                        return Objects.hash(PreconditionFailed.class, this.precondition, this.reason);
255                }
256
257                @Override
258                @NonNull
259                public String toString() {
260                        return format("%s{precondition=%s, reason=%s}", PreconditionFailed.class.getSimpleName(),
261                                        getPrecondition(), getReason());
262                }
263        }
264}