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.StoreTimeRules; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023 024import javax.annotation.concurrent.Immutable; 025import java.util.Optional; 026 027import static java.util.Objects.requireNonNull; 028 029/** 030 * Immutable factual validation timing and optional timing after known durable acknowledgement. 031 * <p> 032 * Validation time is not physical commit time. Completion acquisition may fail without changing a known commit; 033 * the backend then supplies absent completion. This factory rejects a supplied inconsistent completion instead of 034 * silently dropping it. Neither observation proves authenticity, effect certainty or service-release eligibility. 035 * 036 * @since 1.0.0 037 */ 038@Immutable 039@CheckReturnValue 040public final class StoreCommitTiming { 041 private final StoreTimeObservation.@NonNull Healthy validatedTime; 042 private final StoreTimeObservation.@Nullable Healthy completedTime; 043 044 private StoreCommitTiming(StoreTimeObservation.@NonNull Healthy validatedTime, 045 StoreTimeObservation.@Nullable Healthy completedTime) { 046 this.validatedTime = validatedTime; 047 this.completedTime = completedTime; 048 } 049 050 /** 051 * Validates the supplied observations without authenticating their timing or transaction outcome. 052 * 053 * @param validatedTime the fresh observation under final transaction locks before the mutation decision 054 * @param completedTime a same-admission/generation/profile observation after known durable acknowledgement, 055 * no earlier than validation, or {@code null} when unavailable 056 * @return the immutable timing 057 * @throws NullPointerException if {@code validatedTime} is {@code null} 058 * @throws IllegalArgumentException if supplied completion differs in admission, generation or profile, 059 * or precedes validation 060 * @since 1.0.0 061 */ 062 public static @NonNull StoreCommitTiming fromTimes(StoreTimeObservation.@NonNull Healthy validatedTime, 063 StoreTimeObservation.@Nullable Healthy completedTime) { 064 requireNonNull(validatedTime); 065 if (completedTime != null && (!StoreTimeRules.sameProfile(validatedTime, completedTime) 066 || completedTime.getObservedAt().isBefore(validatedTime.getObservedAt()))) 067 throw new IllegalArgumentException("Inconsistent store commit timing."); 068 return new StoreCommitTiming(validatedTime, completedTime); 069 } 070 071 /** 072 * Returns the observation from final transaction validation. 073 * @return the validation observation 074 * @since 1.0.0 075 */ 076 public StoreTimeObservation.@NonNull Healthy getValidatedTime() { 077 return this.validatedTime; 078 } 079 080 /** 081 * Returns the optional post-acknowledgement observation. 082 * @return the optional completion observation 083 * @since 1.0.0 084 */ 085 public @NonNull Optional<StoreTimeObservation.@NonNull Healthy> getCompletedTime() { 086 return Optional.ofNullable(this.completedTime); 087 } 088 089 /** 090 * Returns a fixed description that discloses no timing or identities. 091 * @return the redacted description 092 * @since 1.0.0 093 */ 094 @Override 095 public @NonNull String toString() { 096 return "StoreCommitTiming{timing=<redacted>}"; 097 } 098}