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}