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 */
016package com.revetsec.password;
017
018import org.jspecify.annotations.NonNull;
019
020import javax.annotation.concurrent.Immutable;
021
022import static java.util.Objects.requireNonNull;
023
024/** Application pepper-source outcome. Never place key material in a result's diagnostics.
025 * @since 1.0.0 */
026@Immutable
027public abstract sealed class PasswordPepperSnapshotResult permits PasswordPepperSnapshotResult.Available,
028        PasswordPepperSnapshotResult.Unavailable {
029    private static final @NonNull Unavailable UNAVAILABLE = new Unavailable();
030    PasswordPepperSnapshotResult() { }
031
032    /** Reports an available pepper snapshot.
033     * @param snapshot coherent current and retained keys
034     * @return an available result
035     * @since 1.0.0 */
036    public static @NonNull PasswordPepperSnapshotResult available(@NonNull PasswordPepperSnapshot snapshot) {
037        return new Available(snapshot);
038    }
039
040    /** Reports that the pepper source is unavailable.
041     * @return a provider-unavailable result
042     * @since 1.0.0 */
043    public static @NonNull PasswordPepperSnapshotResult unavailable() { return UNAVAILABLE; }
044
045    /** @return a fixed redacted description
046     * @since 1.0.0 */
047    @Override public final @NonNull String toString() { return "PasswordPepperSnapshotResult{<redacted>}"; }
048
049    /** Coherent key snapshot is available.
050     * @since 1.0.0 */
051    @Immutable
052    public static final class Available extends PasswordPepperSnapshotResult {
053        private final @NonNull PasswordPepperSnapshot snapshot;
054        private Available(@NonNull PasswordPepperSnapshot snapshot) { this.snapshot = requireNonNull(snapshot); }
055        /** Returns the available pepper snapshot.
056         * @return the snapshot
057         * @since 1.0.0 */
058        public @NonNull PasswordPepperSnapshot getSnapshot() { return snapshot; }
059    }
060
061    /** The provider could not supply its current snapshot.
062     * @since 1.0.0 */
063    @Immutable
064    public static final class Unavailable extends PasswordPepperSnapshotResult {
065        private Unavailable() { }
066    }
067}