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}