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 com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.ThreadSafe;
023import java.util.Optional;
024import java.util.function.Supplier;
025
026import static java.util.Objects.requireNonNull;
027
028/**
029 * Framework-owned HTTP attachment capability borrowed by one
030 * {@link HttpServer#attach(HttpTransportAttachmentContext, StartupContext)}
031 * invocation. The context itself must not be retained after that invocation
032 * returns. Delegate attachment is unary, same-thread, and valid only during the
033 * dynamic extent of the enclosing call.
034 * <p>
035 * The type is thread-safe so its immutable values can be read safely, but that
036 * does not relax the thread confinement or lifetime of the delegate-attachment
037 * methods. The request handler and termination signal obtained from this
038 * context may be retained for the attached runtime according to their
039 * individual contracts.
040 *
041 * @author <a href="https://www.revetkn.com">Mark Allen</a>
042 */
043@ThreadSafe
044public final class HttpTransportAttachmentContext {
045        @NonNull
046        private final InternalTransportAttachmentContext<HttpServer.@NonNull RequestHandler>
047                        internalContext;
048
049        HttpTransportAttachmentContext(
050                        @NonNull InternalTransportAttachmentContext<HttpServer.@NonNull RequestHandler>
051                                        internalContext) {
052                this.internalContext = requireNonNull(internalContext);
053        }
054
055        /**
056         * @return the configuration that owns this transport graph; the stable
057         * reference may be retained by the attached runtime
058         */
059        @NonNull
060        public SokletConfig getSokletConfig() {
061                return (SokletConfig) this.internalContext.configuration();
062        }
063
064        /**
065         * Returns the framework admission-fenced request handler. The attached
066         * runtime may retain and invoke it for that runtime's lifetime. While
067         * admission is open it dispatches to the application; before admission opens
068         * and after it is sealed, it completes the supplied result callback with a
069         * framework-marshaled HTTP 503 response instead of silently dropping the
070         * request.
071         *
072         * @return the framework admission-fenced request handler
073         */
074        public HttpServer.@NonNull RequestHandler getAdmissionFencedRequestHandler() {
075                return this.internalContext.requestHandler();
076        }
077
078        @NonNull
079        Supplier<@NonNull Optional<AdmissionFence.@NonNull Admission>> builtInDispatchAdmissionSupplier() {
080                return this.internalContext.builtInDispatchAdmissionSupplier();
081        }
082
083        @NonNull
084        Object executionOwnerToken() {
085                return this.internalContext.executionOwnerToken();
086        }
087
088        /**
089         * Acquires this transport member's framework-owned termination capability.
090         * The attached runtime may retain the signal after {@code attach(...)}
091         * returns and must use it to report honest failure and termination evidence.
092         *
093         * @return this member's termination signal
094         */
095        @NonNull
096        public TransportTerminationSignal getTransportTerminationSignal() {
097                return this.internalContext.terminationSignal().publicSignal();
098        }
099
100        /**
101         * Attaches one transparent delegate using this member's identity and exact
102         * termination signal. The delegate does not receive an independently
103         * terminating child member. The enclosing transport must return the delegate's
104         * runtime and must not drive a separate runtime or signal termination itself;
105         * the transparent delegate owns the shared member's lifecycle and signal.
106         *
107         * @param delegate delegate transport
108         * @param delegateRequestHandler handler supplied to the delegate
109         * @return the exact runtime returned by the delegate
110         */
111        @NonNull
112        @CheckReturnValue
113        public TransportRuntime attachTransparentDelegate(@NonNull HttpServer delegate,
114                        HttpServer.@NonNull RequestHandler delegateRequestHandler) {
115                return this.internalContext.attachTransparentHttpDelegate(delegate,
116                                delegateRequestHandler);
117        }
118
119        /**
120         * Attaches one independently terminating delegate child. Soklet owns the
121         * child's completion state; the enclosing transport may observe the returned
122         * stage but cannot complete or otherwise mutate it.
123         *
124         * @param delegate delegate transport
125         * @param delegateRequestHandler handler supplied to the delegate
126         * @return the child runtime and commit-gated subtree proof
127         */
128        @NonNull
129        @CheckReturnValue
130        public TransportDelegateAttachment attachTerminationOwningDelegate(
131                        @NonNull HttpServer delegate,
132                        HttpServer.@NonNull RequestHandler delegateRequestHandler) {
133                return this.internalContext.attachLifecycleOwningHttpDelegate(delegate,
134                                delegateRequestHandler);
135        }
136
137        @NonNull
138        InternalTransportAttachmentContext<HttpServer.@NonNull RequestHandler> internalContext() {
139                return this.internalContext;
140        }
141}