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.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.ThreadSafe;
022
023import static java.util.Objects.requireNonNull;
024
025/**
026 * The transport outcome of delivering a complete Soklet request to a core protocol operation. An oversized body
027 * discarded by Soklet never invokes the core operation. A completed transport carries the actual core result;
028 * it does not imply protocol acceptance, authentication, authorization or mutation success.
029 * <p>
030 * Only adapter operations construct these outcomes. Later releases may add variants; consuming switches should
031 * include a rejecting default branch. This wrapper never mutates its result.
032 *
033 * @param <T> the core operation's result type
034 * @author <a href="https://www.revetkn.com">Mark Allen</a>
035 * @since 1.0.0
036 */
037@ThreadSafe
038public abstract sealed class SokletRequestResult<T>
039        permits SokletRequestResult.Completed, SokletRequestResult.TooLarge {
040    SokletRequestResult() { }
041
042    static <T> @NonNull SokletRequestResult<@NonNull T> fromResult(@NonNull T result) {
043        return new Completed<>(requireNonNull(result));
044    }
045    static <T> @NonNull SokletRequestResult<@NonNull T> fromTooLarge() { return new TooLarge<>(); }
046
047    /**
048     * Returns the transport outcome without body, credentials or protocol data.
049     * @return redacted description
050     * @since 1.0.0
051     */
052    @Override public final @NonNull String toString() {
053        return "SokletRequestResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
054    }
055
056    /**
057     * The complete materialized request reached the core operation. Its own result still determines acceptance.
058     * @param <T> the core operation's result type
059     * @author <a href="https://www.revetkn.com">Mark Allen</a>
060     * @since 1.0.0
061     */
062    @ThreadSafe
063    public static final class Completed<T> extends SokletRequestResult<@NonNull T> {
064        private final @NonNull T result;
065        private Completed(@NonNull T result) { this.result = result; }
066        /**
067         * Returns the actual core outcome, including any protocol rejection or infrastructure disposition.
068         * @return core operation result
069         * @since 1.0.0
070         */
071        public @NonNull T getResult() { return this.result; }
072    }
073
074    /**
075     * Soklet discarded the oversized body. No core operation ran and no pending state or mutation was consumed.
076     * @param <T> the core operation's result type
077     * @author <a href="https://www.revetkn.com">Mark Allen</a>
078     * @since 1.0.0
079     */
080    @ThreadSafe
081    public static final class TooLarge<T> extends SokletRequestResult<@NonNull T> {
082        private TooLarge() { }
083    }
084}