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.oauth.server; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import com.revetsec.StoreAdmission; 021import com.revetsec.StoreCommitTiming; 022import org.jspecify.annotations.NonNull; 023import org.jspecify.annotations.Nullable; 024import javax.annotation.concurrent.Immutable; 025import java.util.Optional; 026import static java.util.Objects.requireNonNull; 027 028/** 029 * Immutable factual issuer commitment, definitive refusal or uncertainty. 030 * Acknowledgement lateness or later admission failure cannot erase a known commitment. 031 * This carrier grants no credential, current readiness or permission to retry. 032 * @since 1.0.0 033 */ 034@Immutable 035@CheckReturnValue 036public final class OAuthStoreCommitReceipt { 037 private final @NonNull OAuthStoreCommitStatus status; 038 private final @Nullable StoreAdmission admission; 039 private final @Nullable StoreCommitTiming timing; 040 private OAuthStoreCommitReceipt(@NonNull OAuthStoreCommitStatus status, 041 @Nullable StoreAdmission admission,@Nullable StoreCommitTiming timing) { 042 this.status=requireNonNull(status);this.admission=admission;this.timing=timing; 043 } 044 /** Records a known committed timed mutation or predicate barrier. 045 * @param timing required validation and optional completion timing 046 * @return the factual committed receipt 047 * @since 1.0.0 */ 048 public static @NonNull OAuthStoreCommitReceipt fromCommittedTiming(@NonNull StoreCommitTiming timing) { 049 requireNonNull(timing); 050 return new OAuthStoreCommitReceipt(OAuthStoreCommitStatus.COMMITTED, 051 timing.getValidatedTime().getAdmission(),timing); 052 } 053 /** Records a known committed FENCE_ONLY epoch transition without claiming UTC health. 054 * @param admission the current current admitted identities 055 * @return the factual fence receipt 056 * @since 1.0.0 */ 057 public static @NonNull OAuthStoreCommitReceipt fromFenceAdmission(@NonNull StoreAdmission admission) { 058 return new OAuthStoreCommitReceipt(OAuthStoreCommitStatus.COMMITTED,requireNonNull(admission),null); 059 } 060 /** Records a definitive refusal with no effects from this callback. 061 * @param status a refusal other than COMMITTED or UNKNOWN 062 * @return the no-effect receipt 063 * @throws IllegalArgumentException if status is COMMITTED or UNKNOWN 064 * @since 1.0.0 */ 065 public static @NonNull OAuthStoreCommitReceipt fromRefusal(@NonNull OAuthStoreCommitStatus status) { 066 requireNonNull(status); 067 if(status==OAuthStoreCommitStatus.COMMITTED || status==OAuthStoreCommitStatus.UNKNOWN) throw OAuthStoreFormat.invalid(); 068 return new OAuthStoreCommitReceipt(status,null,null); 069 } 070 /** Records a genuinely uncertain possible commitment with no claimed timing or admission. 071 * @return the unknown receipt 072 * @since 1.0.0 */ 073 public static @NonNull OAuthStoreCommitReceipt unknownInstance() { 074 return new OAuthStoreCommitReceipt(OAuthStoreCommitStatus.UNKNOWN,null,null); 075 } 076 /** Returns the factual outcome. 077 * @return the status 078 * @since 1.0.0 */ 079 public @NonNull OAuthStoreCommitStatus getStatus(){return this.status;} 080 /** Returns current admission only for a committed receipt. 081 * @return optional admission 082 * @since 1.0.0 */ 083 public @NonNull Optional<@NonNull StoreAdmission> getAdmission(){return Optional.ofNullable(this.admission);} 084 /** Returns timing for a committed TIMED request; FENCE_ONLY has no timing. 085 * @return optional timing 086 * @since 1.0.0 */ 087 public @NonNull Optional<@NonNull StoreCommitTiming> getTiming(){return Optional.ofNullable(this.timing);} 088 /** Redacts all identities and timestamps. 089 * @return a fixed description 090 * @since 1.0.0 */ 091 @Override public @NonNull String toString(){return "OAuthStoreCommitReceipt{receipt=<redacted>}";} 092}