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}