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;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.StoreTimeAccess;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import java.time.Instant;
026import java.util.Optional;
027
028import static java.util.Objects.requireNonNull;
029
030/**
031 * An engine-created exact time predicate, inspected by the backend inside its final atomic context.
032 * <p>
033 * The lower bound is inclusive and the optional upper bound is exclusive. The engine must additionally include
034 * its authenticated namespace minimum, relevant entity floors and original business expiries. Absence of an upper
035 * bound is reserved for nonexpiring maintenance/barriers and never removes the operation's monotonic deadline,
036 * healthy time, worker-health or final-admission requirements. Construction alone establishes no trust.
037 *
038 * @since 1.0.0
039 */
040@Immutable
041@CheckReturnValue
042public final class StoreTemporalCondition {
043        private final @NonNull StoreAdmission admission;
044        private final @NonNull String clockGeneration;
045        private final @NonNull Instant notBeforeInclusive;
046        private final @Nullable Instant validBeforeExclusive;
047
048        static {
049                StoreTimeAccess.set(new AccessOperations());
050        }
051
052        private StoreTemporalCondition(StoreTimeObservation.@NonNull Healthy observation,
053                        @NonNull Instant notBeforeInclusive, @Nullable Instant validBeforeExclusive) {
054                requireNonNull(observation);
055                StoreTimeObservation.Healthy.validateInstant(notBeforeInclusive);
056                if (notBeforeInclusive.isBefore(observation.getObservedAt()))
057                        throw new IllegalArgumentException("Store-time lower bound precedes its observation.");
058                if (validBeforeExclusive != null) {
059                        StoreTimeObservation.Healthy.validateInstant(validBeforeExclusive);
060                        if (!validBeforeExclusive.isAfter(notBeforeInclusive))
061                                throw new IllegalArgumentException("Invalid store-time exclusive upper bound.");
062                }
063                this.admission = observation.getAdmission();
064                this.clockGeneration = observation.getClockGeneration();
065                this.notBeforeInclusive = notBeforeInclusive;
066                this.validBeforeExclusive = validBeforeExclusive;
067        }
068
069        /**
070         * Returns the expected authority and data/recovery identities.
071         * @return the admission metadata
072         * @since 1.0.0
073         */
074        public @NonNull StoreAdmission getAdmission() {
075                return this.admission;
076        }
077
078        /**
079         * Returns the expected admitted time incarnation.
080         * @return the clock-generation identifier
081         * @since 1.0.0
082         */
083        public @NonNull String getClockGeneration() {
084                return this.clockGeneration;
085        }
086
087        /**
088         * Returns the exact inclusive lower bound to check after all final lock waits.
089         * @return the lower bound
090         * @since 1.0.0
091         */
092        public @NonNull Instant getNotBeforeInclusive() {
093                return this.notBeforeInclusive;
094        }
095
096        /**
097         * Returns the original exclusive upper bound, when this operation is expiring.
098         * @return the optional exclusive upper bound
099         * @since 1.0.0
100         */
101        public @NonNull Optional<@NonNull Instant> getValidBeforeExclusive() {
102                return Optional.ofNullable(this.validBeforeExclusive);
103        }
104
105        /**
106         * Returns a fixed description that discloses no identities or bounds.
107         * @return the redacted description
108         * @since 1.0.0
109         */
110        @Override
111        public @NonNull String toString() {
112                return "StoreTemporalCondition{condition=<redacted>}";
113        }
114
115        private static final class AccessOperations implements StoreTimeAccess.Operations {
116                @Override
117                public @NonNull StoreTemporalCondition fromObservation(StoreTimeObservation.@NonNull Healthy observation,
118                                @NonNull Instant notBeforeInclusive, @Nullable Instant validBeforeExclusive) {
119                        return new StoreTemporalCondition(observation, notBeforeInclusive, validBeforeExclusive);
120                }
121        }
122}