001/*
002 * Copyright 2022-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.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.ThreadSafe;
022
023/**
024 * One-shot lifecycle runtime returned by an HTTP or SSE transport attachment.
025 * One lifecycle owner invokes this object: Soklet drives the configured outer
026 * runtime, while an enclosing transport drives a termination-owning child
027 * runtime obtained from {@link TransportDelegateAttachment}. Other callers
028 * must not invoke the runtime independently.
029 * The transport implementation continues to own every external resource and
030 * asynchronous activity started by those calls. It reports failures and final
031 * termination proof through the {@link TransportTerminationSignal} borrowed
032 * from its attachment context.
033 * <p>
034         * Implementations must make shutdown phase methods prompt, nonblocking,
035         * idempotent, thread-safe, and monotonic. A shutdown method initiates work; it
036         * does not itself constitute termination proof. Shutdown may be requested
037         * before start is invoked; even an unused runtime must report affirmative
038         * termination proof after its owned activity has ended.
039         * <p>
040         * Soklet defers phase delivery while the configured runtime's start call is
041         * still running. If that call returns or throws after the forced boundary,
042         * Soklet makes one best-effort forced shutdown invocation on that same
043         * lifecycle worker, with the original deadline (remaining time may be zero).
044         * This does not extend shutdown or change its frozen result, including its
045         * recorded causes. A blocking or failed compensation cannot establish complete
046         * termination. Runtime implementations must still honor startup cancelation
047         * and initiate shutdown promptly.
048 *
049 * @author <a href="https://www.revetkn.com">Mark Allen</a>
050 */
051@ThreadSafe
052public interface TransportRuntime {
053        /**
054         * Binds the transport and returns only after it is ready. The runtime owner
055         * invokes this method at most once.
056         * <p>
057         * For a synchronous startup failure, throw the original runtime exception or
058         * error (retain a checked failure as the cause of a runtime exception). Do not
059         * report that same failure or termination proof through the signal before
060         * throwing: a signal before the owner's shutdown intent describes independent
061         * premature termination. The owner delivers shutdown phases after a failed
062         * start, including a partially completed bind. Those methods must remain safe
063         * and report affirmative proof once every owned resource and activity ends.
064         * <p>
065         * An independent worker failure must still be signaled when observed, even
066         * before readiness; an earlier independent failure can control the outcome
067         * instead of a later synchronous throw.
068         *
069         * @param startupContext startup timing and cancelation information
070         */
071        void start(@NonNull StartupContext startupContext);
072
073        /**
074         * Stops admission and initiates graceful wind-up without waiting for it.
075         * Shutdown phases can run even when {@link #start(StartupContext)} was never
076         * invoked, for example after another member failed to attach or start.
077         * The transport must signal termination once all owned activity has ended,
078         * including affirmative proof when no resources or activity were started.
079         *
080         * @param shutdownContext graceful shutdown timing information
081         */
082        void shutdownGracefully(@NonNull ShutdownContext shutdownContext);
083
084        /**
085         * Subsumes graceful shutdown and interrupts or cancels only runtime-owned
086         * execution.
087         * Shutdown phases can run even when {@link #start(StartupContext)} was never
088         * invoked, for example after another member failed to attach or start.
089         * The transport must signal termination once all owned activity has ended,
090         * including affirmative proof when no resources or activity were started.
091         *
092         * @param shutdownContext forced shutdown timing information
093         */
094        void shutdownForcibly(@NonNull ShutdownContext shutdownContext);
095}