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 org.jspecify.annotations.NonNull; 021 022import javax.annotation.concurrent.Immutable; 023import java.time.Duration; 024import java.time.Instant; 025 026import static java.util.Objects.requireNonNull; 027 028/** 029 * A backend's immutable time statement, bound to the active data/recovery admission. 030 * <p> 031 * A healthy statement advertises a deployment capability; it is not itself proof of trusted UTC, current 032 * admission, causal worker-clock health or an operation's eligibility. Unavailable time retains only admission 033 * identities and never substitutes worker time or an earlier healthy sample. 034 * 035 * @since 1.0.0 036 */ 037@Immutable 038@CheckReturnValue 039public sealed interface StoreTimeObservation 040 permits StoreTimeObservation.Healthy, StoreTimeObservation.Unavailable { 041 /** 042 * Returns the active authority and data/recovery identities. 043 * @return the admission metadata 044 * @since 1.0.0 045 */ 046 @NonNull StoreAdmission getAdmission(); 047 048 /** 049 * An admitted UTC observation with a fixed generation profile. 050 * <p> 051 * The profile is maximum advance rate 2, maximum worker offset five seconds and a declared UTC-error bound 052 * from zero through 250 milliseconds. Engines must authenticate the root binding and verify the profile, 053 * floors, causal health and original operation budget before using this statement. 054 * 055 * @since 1.0.0 056 */ 057 @Immutable 058 @CheckReturnValue 059 final class Healthy implements StoreTimeObservation { 060 private static final @NonNull Duration MAXIMUM_UTC_ERROR = Duration.ofMillis(250); 061 private static final @NonNull Duration MAXIMUM_WORKER_CLOCK_OFFSET = Duration.ofSeconds(5); 062 private final @NonNull StoreAdmission admission; 063 private final @NonNull String clockGeneration; 064 private final @NonNull Instant observedAt; 065 private final @NonNull Duration maximumUtcError; 066 067 private Healthy(@NonNull StoreAdmission admission, @NonNull String clockGeneration, 068 @NonNull Instant observedAt, @NonNull Duration maximumUtcError) { 069 this.admission = requireNonNull(admission); 070 StoreAdmission.validateIdentifier(clockGeneration); 071 validateInstant(observedAt); 072 requireNonNull(maximumUtcError); 073 if (maximumUtcError.isNegative() || maximumUtcError.compareTo(MAXIMUM_UTC_ERROR) > 0) 074 throw new IllegalArgumentException("Invalid store-time UTC-error bound."); 075 this.clockGeneration = clockGeneration; 076 this.observedAt = observedAt; 077 this.maximumUtcError = maximumUtcError; 078 } 079 080 /** 081 * Validates a backend's UTC statement without authenticating or admitting it. 082 * 083 * @param admission the active authority and data/recovery identities 084 * @param clockGeneration canonical unpadded Base64URL encoding of exactly 32 bytes 085 * @param observedAt UTC instant with epoch seconds in 0 through 253402300799, preserving nanoseconds 086 * @param maximumUtcError the fixed generation's declared bound, zero through 250 milliseconds inclusive 087 * @return the immutable observation 088 * @throws NullPointerException if an argument is {@code null} 089 * @throws IllegalArgumentException if an identifier, instant or error bound is outside the supported profile 090 * @since 1.0.0 091 */ 092 public static StoreTimeObservation.@NonNull Healthy fromObservation(@NonNull StoreAdmission admission, 093 @NonNull String clockGeneration, @NonNull Instant observedAt, @NonNull Duration maximumUtcError) { 094 return new Healthy(admission, clockGeneration, observedAt, maximumUtcError); 095 } 096 097 /** 098 * Returns the active authority and data/recovery identities. 099 * @return the admission metadata 100 * @since 1.0.0 101 */ 102 @Override 103 public @NonNull StoreAdmission getAdmission() { 104 return this.admission; 105 } 106 107 /** 108 * Returns the admitted time incarnation's identity. 109 * @return the canonical clock-generation identifier 110 * @since 1.0.0 111 */ 112 public @NonNull String getClockGeneration() { 113 return this.clockGeneration; 114 } 115 116 /** 117 * Returns the exact UTC observation, without rounding or clamping. 118 * @return the observed instant 119 * @since 1.0.0 120 */ 121 public @NonNull Instant getObservedAt() { 122 return this.observedAt; 123 } 124 125 /** 126 * Returns the declared UTC-error bound fixed for this generation. 127 * @return the maximum error 128 * @since 1.0.0 129 */ 130 public @NonNull Duration getMaximumUtcError() { 131 return this.maximumUtcError; 132 } 133 134 /** 135 * Returns the supported maximum UTC advance per measured elapsed second. 136 * @return the fixed boxed rate, 2 137 * @since 1.0.0 138 */ 139 public @NonNull Integer getMaximumUtcAdvanceRate() { 140 return 2; 141 } 142 143 /** 144 * Returns the supported maximum worker-wall-clock offset, independent of protocol skew. 145 * @return the fixed five-second bound 146 * @since 1.0.0 147 */ 148 public @NonNull Duration getMaximumWorkerClockOffset() { 149 return MAXIMUM_WORKER_CLOCK_OFFSET; 150 } 151 152 /** 153 * Returns a fixed description that discloses no time, profile or identifier. 154 * @return the redacted description 155 * @since 1.0.0 156 */ 157 @Override 158 public @NonNull String toString() { 159 return "Healthy{observation=<redacted>}"; 160 } 161 162 static void validateInstant(@NonNull Instant value) { 163 requireNonNull(value); 164 if (value.getEpochSecond() < 0 || value.getEpochSecond() > 253402300799L) 165 throw new IllegalArgumentException("Invalid store-time instant."); 166 } 167 } 168 169 /** 170 * Time is unavailable while the authority/data admission metadata remains obtainable. 171 * 172 * @since 1.0.0 173 */ 174 @Immutable 175 @CheckReturnValue 176 final class Unavailable implements StoreTimeObservation { 177 private final @NonNull StoreAdmission admission; 178 179 private Unavailable(@NonNull StoreAdmission admission) { 180 this.admission = requireNonNull(admission); 181 } 182 183 /** 184 * Retains active admission metadata without inventing UTC evidence. 185 * @param admission the authority and data/recovery identities 186 * @return the time-unavailable observation 187 * @throws NullPointerException if {@code admission} is {@code null} 188 * @since 1.0.0 189 */ 190 public static StoreTimeObservation.@NonNull Unavailable fromAdmission(@NonNull StoreAdmission admission) { 191 return new Unavailable(admission); 192 } 193 194 /** 195 * Returns the active authority and data/recovery identities. 196 * @return the admission metadata 197 * @since 1.0.0 198 */ 199 @Override 200 public @NonNull StoreAdmission getAdmission() { 201 return this.admission; 202 } 203 204 /** 205 * Returns a fixed description that discloses neither identity. 206 * @return the redacted description 207 * @since 1.0.0 208 */ 209 @Override 210 public @NonNull String toString() { 211 return "Unavailable{admission=<redacted>}"; 212 } 213 } 214}