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}