towards a Jetty 9 decoupling baseline for the Jetty 12 migration

16 files changed, 360 insertions, 82 deletions

diff --git a/source/net/yacy/http/AbstractRemoteHandler.java b/source/net/yacy/http/AbstractRemoteHandler.java
index 826162c98..8f791c2a7 100644
--- a/source/net/yacy/http/AbstractRemoteHandler.java
+++ b/source/net/yacy/http/AbstractRemoteHandler.java
@@ -26,10 +26,9 @@ package net.yacy.http;
 
 import java.io.IOException;
 import java.net.InetAddress;
-import java.util.HashSet;
 import java.util.Locale;
 import java.util.Set;
-import java.util.StringTokenizer;
+import java.util.concurrent.ConcurrentHashMap;
 
 import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
@@ -42,17 +41,16 @@ import net.yacy.search.Switchboard;
 import net.yacy.search.SwitchboardConstants;
 
 import org.eclipse.jetty.proxy.ConnectHandler;
-import org.eclipse.jetty.server.Handler;
 import org.eclipse.jetty.server.Request;
 
 /**
  * abstract jetty http handler
  * only request to remote hosts (proxy requests) are processed by derived classes 
  */
-abstract public class AbstractRemoteHandler extends ConnectHandler implements Handler {
+abstract public class AbstractRemoteHandler extends ConnectHandler {
 	
     protected Switchboard sb = null;
-    private final Set<String> localVirtualHostNames = new HashSet<String>(); // list for quick check for req to local peer
+    private final Set<String> localVirtualHostNames = ConcurrentHashMap.newKeySet(); // updated by discovery thread and request threads
     
     @Override
     protected void doStart() throws Exception {
@@ -99,7 +97,7 @@ abstract public class AbstractRemoteHandler extends ConnectHandler implements Ha
         }.start();
     }
 	
-    abstract public void handleRemote(String target, Request baseRequest, HttpServletRequest request,
+    abstract public void handleRemote(String target, RequestCompletion completion, HttpServletRequest request,
             HttpServletResponse response) throws IOException, ServletException;
 
     @Override
@@ -135,7 +133,8 @@ abstract public class AbstractRemoteHandler extends ConnectHandler implements Ha
         }
         
         final String remoteHost = request.getRemoteHost();
-        if (!proxyippatternmatch(remoteHost)) {
+        if (!ProxyAccessPolicy.isClientAllowed(
+                Switchboard.getSwitchboard().getConfig("proxyClient", "*"), remoteHost)) {
             // TODO: handle proxy account
             response.sendError(HttpServletResponse.SC_FORBIDDEN,
                     "proxy use not granted for IP " + remoteHost + " (see Advanced Settings -> Proxy Access Settings -> IP-Number filter).");
@@ -157,28 +156,8 @@ abstract public class AbstractRemoteHandler extends ConnectHandler implements Ha
         	return;
         }
         
-        handleRemote(target, baseRequest, request, response);
+        handleRemote(target, () -> baseRequest.setHandled(true), request, response);
 
     }
     
-    /**
-     * helper for proxy IP config pattern check
-     */
-    private boolean proxyippatternmatch(final String key) {
-        // the cfgippattern is a comma-separated list of patterns
-        // each pattern may contain one wildcard-character '*' which matches anything
-        final String cfgippattern = Switchboard.getSwitchboard().getConfig("proxyClient", "*");
-        if (cfgippattern.equals("*")) {
-            return true;
-        }
-        final StringTokenizer st = new StringTokenizer(cfgippattern, ",");
-        String pattern;
-        while (st.hasMoreTokens()) {
-            pattern = st.nextToken();
-            if (key.matches(pattern)) {
-                return true;
-            }
-        }
-        return false;
-    }
 }
diff --git a/source/net/yacy/http/AdminAccessPolicy.java b/source/net/yacy/http/AdminAccessPolicy.java
index e4bad1350..5560200ec 100644
--- a/source/net/yacy/http/AdminAccessPolicy.java
+++ b/source/net/yacy/http/AdminAccessPolicy.java
@@ -1,3 +1,23 @@
+/**
+ *  AdminAccessPolicy
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http;
 
 import java.net.MalformedURLException;
diff --git a/source/net/yacy/http/AdminAuthenticationContext.java b/source/net/yacy/http/AdminAuthenticationContext.java
index e276d4cbd..5080c9b05 100644
--- a/source/net/yacy/http/AdminAuthenticationContext.java
+++ b/source/net/yacy/http/AdminAuthenticationContext.java
@@ -1,3 +1,23 @@
+/**
+ *  AdminAuthenticationContext
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http;
 
 import net.yacy.cora.protocol.Domains;
diff --git a/source/net/yacy/http/CrashProtectionHandler.java b/source/net/yacy/http/CrashProtectionHandler.java
index 1cbf27bcd..1456ba778 100644
--- a/source/net/yacy/http/CrashProtectionHandler.java
+++ b/source/net/yacy/http/CrashProtectionHandler.java
@@ -1,3 +1,23 @@
+/**
+ *  CrashProtectionHandler
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http;
 
 import java.io.IOException;
@@ -8,7 +28,6 @@ import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.HandlerContainer;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.Server;
 import org.eclipse.jetty.server.handler.HandlerWrapper;
@@ -25,7 +44,7 @@ import net.yacy.cora.util.ConcurrentLog;
  * trace. Its purpose is to catch failures outside the servlet context, e.g.
  * in the transparent proxy handlers.
  */
-public class CrashProtectionHandler extends HandlerWrapper implements Handler, HandlerContainer {
+public class CrashProtectionHandler extends HandlerWrapper implements Handler {
 	
 	public CrashProtectionHandler() {
 		super();
diff --git a/source/net/yacy/http/HttpServerBootstrapConfig.java b/source/net/yacy/http/HttpServerBootstrapConfig.java
new file mode 100644
index 000000000..f8ee311ef
--- /dev/null
+++ b/source/net/yacy/http/HttpServerBootstrapConfig.java
@@ -0,0 +1,103 @@
+/**
+ *  HttpServerBootstrapConfig
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package net.yacy.http;
+
+import net.yacy.search.Switchboard;
+import net.yacy.search.SwitchboardConstants;
+
+/** Immutable, servlet-container-neutral input for the embedded HTTP server. */
+public final class HttpServerBootstrapConfig {
+
+    public static final int REQUEST_HEADER_SIZE = 16_384;
+    public static final long CONNECTOR_IDLE_TIMEOUT_MILLIS = 9_000L;
+    public static final int ACCEPT_QUEUE_SIZE = 128;
+    public static final int REQUEST_INFLATE_BUFFER_SIZE = 4_096;
+    public static final int MAX_FORM_CONTENT_SIZE = -1;
+
+    private final int httpPort;
+    private final String bindHost;
+    private final int acceptorCount;
+    private final boolean httpsEnabled;
+    private final int httpsPort;
+    private final String htrootPath;
+    private final String defaultsWebXml;
+    private final String overrideWebXml;
+    private final boolean gzipResponsesEnabled;
+    private final boolean transparentProxyEnabled;
+    private final String serverClientRules;
+    private final String adminRealm;
+
+    private HttpServerBootstrapConfig(final int httpPort, final String bindHost,
+            final int acceptorCount, final boolean httpsEnabled, final int httpsPort,
+            final String htrootPath, final String defaultsWebXml, final String overrideWebXml,
+            final boolean gzipResponsesEnabled, final boolean transparentProxyEnabled,
+            final String serverClientRules, final String adminRealm) {
+        this.httpPort = httpPort;
+        this.bindHost = bindHost;
+        this.acceptorCount = acceptorCount;
+        this.httpsEnabled = httpsEnabled;
+        this.httpsPort = httpsPort;
+        this.htrootPath = htrootPath;
+        this.defaultsWebXml = defaultsWebXml;
+        this.overrideWebXml = overrideWebXml;
+        this.gzipResponsesEnabled = gzipResponsesEnabled;
+        this.transparentProxyEnabled = transparentProxyEnabled;
+        this.serverClientRules = serverClientRules;
+        this.adminRealm = adminRealm;
+    }
+
+    public static HttpServerBootstrapConfig from(final Switchboard switchboard,
+            final int httpPort, final String bindHost) {
+        final int cores = Runtime.getRuntime().availableProcessors();
+        return new HttpServerBootstrapConfig(
+                httpPort,
+                bindHost,
+                acceptorCountFor(cores),
+                switchboard.getConfigBool("server.https", false),
+                switchboard.getConfigInt(SwitchboardConstants.SERVER_SSLPORT, 8443),
+                switchboard.appPath + "/" + switchboard.getConfig(
+                        SwitchboardConstants.HTROOT_PATH, SwitchboardConstants.HTROOT_PATH_DEFAULT),
+                switchboard.appPath + "/defaults/web.xml",
+                switchboard.dataPath + "/DATA/SETTINGS/web.xml",
+                switchboard.getConfigBool(SwitchboardConstants.SERVER_RESPONSE_COMPRESS_GZIP,
+                        SwitchboardConstants.SERVER_RESPONSE_COMPRESS_GZIP_DEFAULT),
+                switchboard.getConfigBool(SwitchboardConstants.PROXY_TRANSPARENT_PROXY, false),
+                switchboard.getConfig("serverClient", "*"),
+                switchboard.getConfig(SwitchboardConstants.ADMIN_REALM, "YaCy"));
+    }
+
+    static int acceptorCountFor(final int availableProcessors) {
+        return Math.max(1, Math.min(4, availableProcessors / 2));
+    }
+
+    public int httpPort() { return this.httpPort; }
+    public String bindHost() { return this.bindHost; }
+    public int acceptorCount() { return this.acceptorCount; }
+    public boolean httpsEnabled() { return this.httpsEnabled; }
+    public int httpsPort() { return this.httpsPort; }
+    public String htrootPath() { return this.htrootPath; }
+    public String defaultsWebXml() { return this.defaultsWebXml; }
+    public String overrideWebXml() { return this.overrideWebXml; }
+    public boolean gzipResponsesEnabled() { return this.gzipResponsesEnabled; }
+    public boolean transparentProxyEnabled() { return this.transparentProxyEnabled; }
+    public String serverClientRules() { return this.serverClientRules; }
+    public String adminRealm() { return this.adminRealm; }
+}
diff --git a/source/net/yacy/http/InetPathAccessRule.java b/source/net/yacy/http/InetPathAccessRule.java
index f93f6336b..c93200829 100644
--- a/source/net/yacy/http/InetPathAccessRule.java
+++ b/source/net/yacy/http/InetPathAccessRule.java
@@ -1,3 +1,23 @@
+/**
+ *  InetPathAccessRule
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http;
 
 /** Container-neutral representation of a server-client address/path rule. */
diff --git a/source/net/yacy/http/Jetty9HttpServerImpl.java b/source/net/yacy/http/Jetty9HttpServerImpl.java
index 5bf942e06..137330acc 100644
--- a/source/net/yacy/http/Jetty9HttpServerImpl.java
+++ b/source/net/yacy/http/Jetty9HttpServerImpl.java
@@ -52,7 +52,6 @@ import org.eclipse.jetty.server.handler.InetAccessHandler;
 import org.eclipse.jetty.server.handler.gzip.GzipHandler;
 import org.eclipse.jetty.servlet.FilterHolder;
 import org.eclipse.jetty.servlet.ServletHolder;
-import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.resource.Resource;
 import org.eclipse.jetty.util.ssl.SslContextFactory;
 import org.eclipse.jetty.webapp.WebAppContext;
@@ -78,6 +77,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
      */
     public Jetty9HttpServerImpl(final int port, final String host) {
         final Switchboard sb = Switchboard.getSwitchboard();
+        final HttpServerBootstrapConfig bootstrap = HttpServerBootstrapConfig.from(sb, port, host);
 
         this.server = new Server();
 
@@ -96,32 +96,29 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
             }
         };
 
-        final int cores = Runtime.getRuntime().availableProcessors();
-        final int acceptors = Math.max(1, Math.min(4, cores/2)); // original: Math.max(1, Math.min(4,cores/8));
-
         final HttpConfiguration httpConfig = new HttpConfiguration();
-        httpConfig.setRequestHeaderSize(16384);
+        httpConfig.setRequestHeaderSize(HttpServerBootstrapConfig.REQUEST_HEADER_SIZE);
         final HttpConnectionFactory hcf = new HttpConnectionFactory(httpConfig);
-        final ServerConnector connector = new ServerConnector(this.server, null, null, null, acceptors, -1, hcf);
-        connector.setPort(port);
-        connector.setHost(host);
-        connector.setName("httpd-" + host + ":" + Integer.toString(port));
-        connector.setIdleTimeout(9000); // timout in ms when no bytes send / received
-        connector.setAcceptQueueSize(128);
+        final ServerConnector connector = new ServerConnector(this.server, null, null, null, bootstrap.acceptorCount(), -1, hcf);
+        connector.setPort(bootstrap.httpPort());
+        connector.setHost(bootstrap.bindHost());
+        connector.setName("httpd-" + bootstrap.bindHost() + ":" + Integer.toString(bootstrap.httpPort()));
+        connector.setIdleTimeout(HttpServerBootstrapConfig.CONNECTOR_IDLE_TIMEOUT_MILLIS);
+        connector.setAcceptQueueSize(HttpServerBootstrapConfig.ACCEPT_QUEUE_SIZE);
         connector.addBean(connectionCloseMonitor);
 
         this.server.addConnector(connector);
 
 
         // add ssl/https connector
-        final boolean useSSL = sb.getConfigBool("server.https", false);
+        final boolean useSSL = bootstrap.httpsEnabled();
 
         if (useSSL) {
             final SslContextFactory sslContextFactory = new SslContextFactory.Server();
             final SSLContext sslContext = this.initSslContext(sb);
             if (sslContext != null) {
 
-                final int sslport = sb.getConfigInt(SwitchboardConstants.SERVER_SSLPORT, 8443);
+                final int sslport = bootstrap.httpsPort();
                 sslContextFactory.setSslContext(sslContext);
 
                 // SSL HTTP Configuration
@@ -134,7 +131,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
                         new HttpConnectionFactory(https_config));
                 sslConnector.setPort(sslport);
                 sslConnector.setName("ssld:" + Integer.toString(sslport)); // name must start with ssl (for withSSL() to work correctly)
-                sslConnector.setIdleTimeout(9000); // timout in ms when no bytes send / received
+                sslConnector.setIdleTimeout(HttpServerBootstrapConfig.CONNECTOR_IDLE_TIMEOUT_MILLIS);
                 sslConnector.addBean(connectionCloseMonitor);
 
                 this.server.addConnector(sslConnector);
@@ -148,7 +145,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
         // configure root context
         final WebAppContext htrootContext = new WebAppContext();
         htrootContext.setContextPath("/");
-        final String htrootpath = sb.appPath + "/" + sb.getConfig(SwitchboardConstants.HTROOT_PATH, SwitchboardConstants.HTROOT_PATH_DEFAULT);
+        final String htrootpath = bootstrap.htrootPath();
         ConcurrentLog.info("Jetty9HttpServerImpl", "htrootpath = " + htrootpath);
         htrootContext.setErrorHandler(new YaCyErrorHandler()); // handler for custom error page
         try {
@@ -158,8 +155,8 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
             // make use of Jetty feature to define web.xml other as default WEB-INF/web.xml
             // and to use a DefaultsDescriptor merged with a individual web.xml
             // use defaults/web.xml as default and look in DATA/SETTINGS for local addition/changes
-            htrootContext.setDefaultsDescriptor(sb.appPath + "/defaults/web.xml");
-            final Resource webxml = Resource.newResource(sb.dataPath + "/DATA/SETTINGS/web.xml");
+            htrootContext.setDefaultsDescriptor(bootstrap.defaultsWebXml());
+            final Resource webxml = Resource.newResource(bootstrap.overrideWebXml());
             if (webxml.exists()) {
                 htrootContext.setDescriptor(webxml.getName());
             }
@@ -191,10 +188,9 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
          * APIs /yacy/transferRWI.html and /yacy/transferURL.html This was previously
          * handled by a GZIPRequestWrapper in the YaCyDefaultServlet.
          */
-        gzipHandler.setInflateBufferSize(4096);
+        gzipHandler.setInflateBufferSize(HttpServerBootstrapConfig.REQUEST_INFLATE_BUFFER_SIZE);
 
-        if (!sb.getConfigBool(SwitchboardConstants.SERVER_RESPONSE_COMPRESS_GZIP,
-                SwitchboardConstants.SERVER_RESPONSE_COMPRESS_GZIP_DEFAULT)) {
+        if (!bootstrap.gzipResponsesEnabled()) {
             /* Gzip compression of responses can be disabled by user configuration */
             gzipHandler.setExcludedMethods(HttpMethod.GET.asString(), HttpMethod.POST.asString());
         }
@@ -224,7 +220,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
 
         // define list of YaCy specific general handlers
         final HandlerList handlers = new HandlerList();
-        if (sb.getConfigBool(SwitchboardConstants.PROXY_TRANSPARENT_PROXY, false)) {
+        if (bootstrap.transparentProxyEnabled()) {
             // Proxyhandlers are only needed if feature activated (save resources if not used)
             ConcurrentLog.info("SERVER", "load Jetty handler for transparent proxy");
             handlers.setHandlers(new Handler[]{domainHandler, new ProxyCacheHandler(), new ProxyHandler()});
@@ -236,9 +232,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
         context.setServer(this.server);
         context.setContextPath("/");
         context.setHandler(handlers);
-        context.setMaxFormContentSize(-1);
-        final org.eclipse.jetty.util.log.Logger log = Log.getRootLogger();
-        context.setLogger(log);
+        context.setMaxFormContentSize(HttpServerBootstrapConfig.MAX_FORM_CONTENT_SIZE);
         // make YaCy handlers (in context) and servlet context handlers available (both contain root context "/")
         // logic: 1. YaCy handlers are called if request not handled (e.g. proxy) then servlets handle it
         final ContextHandlerCollection allrequesthandlers = new ContextHandlerCollection();
@@ -250,7 +244,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
         final YaCyLoginService loginService = new YaCyLoginService();
         // This is part of the built-in administrator's DIGEST password hash.
         // Changing it invalidates the configured administrator password hash.
-        loginService.setName(sb.getConfig(SwitchboardConstants.ADMIN_REALM,"YaCy"));
+        loginService.setName(bootstrap.adminRealm());
 
         final YaCySecurityHandler securityHandler = new YaCySecurityHandler();
         securityHandler.setLoginService(loginService);
@@ -261,7 +255,7 @@ public class Jetty9HttpServerImpl implements YaCyHttpServer {
         final Handler crashHandler = new CrashProtectionHandler(this.server, allrequesthandlers);
         // check server access restriction and add InetAccessHandler if restrictions are needed
         // otherwise don't (to save performance)
-        final String white = sb.getConfig("serverClient", "*");
+        final String white = bootstrap.serverClientRules();
         if (!white.equals("*")) { // full ip (allowed ranges 0-255 or prefix  10.0-255,0,0-100  or CIDR notation 192.168.1.0/24)
             final StringTokenizer st = new StringTokenizer(white, ",");
             final InetAccessHandler whiteListHandler;
diff --git a/source/net/yacy/http/ProxyAccessPolicy.java b/source/net/yacy/http/ProxyAccessPolicy.java
new file mode 100644
index 000000000..f0fab158d
--- /dev/null
+++ b/source/net/yacy/http/ProxyAccessPolicy.java
@@ -0,0 +1,43 @@
+/**
+ *  ProxyAccessPolicy
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package net.yacy.http;
+
+/** Container-neutral checks for the configured transparent-proxy client list. */
+public final class ProxyAccessPolicy {
+
+    private ProxyAccessPolicy() {
+    }
+
+    public static boolean isClientAllowed(final String configuredPatterns, final String clientHost) {
+        if ("*".equals(configuredPatterns)) {
+            return true;
+        }
+        if (configuredPatterns == null || configuredPatterns.isEmpty() || clientHost == null) {
+            return false;
+        }
+        for (final String pattern : configuredPatterns.split(",")) {
+            if (!pattern.isEmpty() && clientHost.matches(pattern)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
diff --git a/source/net/yacy/http/ProxyCacheHandler.java b/source/net/yacy/http/ProxyCacheHandler.java
index 7c8597795..27e043191 100644
--- a/source/net/yacy/http/ProxyCacheHandler.java
+++ b/source/net/yacy/http/ProxyCacheHandler.java
@@ -31,8 +31,6 @@ import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
-import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.Request;
 
 import net.yacy.cora.document.id.DigestURL;
 import net.yacy.cora.protocol.RequestHeader;
@@ -43,7 +41,7 @@ import net.yacy.crawler.retrieval.Response;
 /**
  * jetty http handler serves pages from cache if available and valid
  */
-public class ProxyCacheHandler extends AbstractRemoteHandler implements Handler {
+public class ProxyCacheHandler extends AbstractRemoteHandler {
 
     private void handleRequestFromCache(@SuppressWarnings("unused") HttpServletRequest request, HttpServletResponse response, ResponseHeader cachedResponseHeader, byte[] content) throws IOException {
 
@@ -57,7 +55,7 @@ public class ProxyCacheHandler extends AbstractRemoteHandler implements Handler
     }
     
     @Override
-    public void handleRemote(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
+    public void handleRemote(String target, RequestCompletion completion, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
         if (request.getMethod().equals("GET")) {
             String queryString = request.getQueryString() != null ? "?" + request.getQueryString() : "";
             DigestURL url = new DigestURL(request.getRequestURL().toString() + queryString);
@@ -86,7 +84,7 @@ public class ProxyCacheHandler extends AbstractRemoteHandler implements Handler
                 byte[] cacheContent = Cache.getContent(url.hash());
                 if (cacheContent != null && cachedResponse.isFreshForProxy()) {
                     handleRequestFromCache(request, response, cachedResponseHeader, cacheContent);
-                    baseRequest.setHandled(true);
+                    completion.complete();
                 }
             }
 
diff --git a/source/net/yacy/http/ProxyHandler.java b/source/net/yacy/http/ProxyHandler.java
index 95f4dca56..9c86a6b09 100644
--- a/source/net/yacy/http/ProxyHandler.java
+++ b/source/net/yacy/http/ProxyHandler.java
@@ -52,14 +52,12 @@ import net.yacy.server.http.MultiOutputStream;
 
 import org.apache.http.Header;
 import org.apache.http.HttpResponse;
-import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.Request;
 
 /**
  * jetty http handler
  * proxies request, caches responses and adds urls to crawler
  */
-public class ProxyHandler extends AbstractRemoteHandler implements Handler {
+public class ProxyHandler extends AbstractRemoteHandler {
 
     protected int timeout = 10000;
 
@@ -124,7 +122,7 @@ public class ProxyHandler extends AbstractRemoteHandler implements Handler {
     }
 
 	@Override
-	public void handleRemote(String target, Request baseRequest, HttpServletRequest request,
+	public void handleRemote(String target, RequestCompletion completion, HttpServletRequest request,
 		HttpServletResponse response) throws IOException, ServletException {
 		
 		sb.proxyLastAccess = System.currentTimeMillis();
@@ -222,7 +220,7 @@ public class ProxyHandler extends AbstractRemoteHandler implements Handler {
         
         // we handled this request, break out of handler chain
         logProxyAccess(request);
-        baseRequest.setHandled(true);
+        completion.complete();
 	}
 
     /**
diff --git a/source/net/yacy/http/RequestCompletion.java b/source/net/yacy/http/RequestCompletion.java
new file mode 100644
index 000000000..7dce04d59
--- /dev/null
+++ b/source/net/yacy/http/RequestCompletion.java
@@ -0,0 +1,28 @@
+/**
+ *  RequestCompletion
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package net.yacy.http;
+
+/** Container-neutral callback used when a handler has completed a request. */
+@FunctionalInterface
+public interface RequestCompletion {
+
+    void complete();
+}
diff --git a/source/net/yacy/http/YaCyHttpServer.java b/source/net/yacy/http/YaCyHttpServer.java
index a4bff7bbd..60cd9c219 100644
--- a/source/net/yacy/http/YaCyHttpServer.java
+++ b/source/net/yacy/http/YaCyHttpServer.java
@@ -28,51 +28,48 @@ package net.yacy.http;
  */
 public interface YaCyHttpServer {
 
-    /**
-     * start the http server
-     */
+    /** Start all configured connectors and handlers before returning. */
     void startupServer() throws Exception;
 
-    /**
-     * stop the http server
-     */
+    /** Stop all connectors and handlers and wait for complete termination. */
     void stop() throws Exception;
 
     /**
-     * reconnect with new port settings (after waiting milsec) - routine returns immediately
-     * @param milsec wait time
+     * Apply current HTTP and HTTPS port settings asynchronously after a delay.
+     * Existing connectors are reused; implementations must not rebuild the handler graph.
+     * @param milsec non-negative delay before applying current configuration
      */
     void reconnect(int milsec);
 
     /**
-     * @return true if the server runs a ssl/https connector
+     * @return true when a usable HTTPS connector was configured
      */
     boolean withSSL();
 
     /**
-     * @return the ssl/https port or -1 if not active
+     * @return the bound HTTPS port, or -1 when HTTPS is not active
      */
     int getSslPort();
 
     /**
-     * forces loginservice to reload user credentials
+     * Evict and immediately reload the named administrator identity from configuration.
      * @param username
      */
     void resetUser(String username);
 
     /**
-     * removes user from the loginservice
+     * Evict the named administrator identity from the container login cache.
      * @param username
      */
     void removeUser(String username);
 
     /**
-     * @return version string of the servlet container
+     * @return human-readable name and version of the servlet container
      */
     String getVersion();
 
     /**
-     * @return the number of currently active (busy) server threads
+     * @return current number of non-idle container worker threads
      */
     int getServerThreads();
 }
diff --git a/source/net/yacy/http/YacyDomainHandler.java b/source/net/yacy/http/YacyDomainHandler.java
index 747b0fe5d..a61a72fac 100644
--- a/source/net/yacy/http/YacyDomainHandler.java
+++ b/source/net/yacy/http/YacyDomainHandler.java
@@ -38,7 +38,6 @@ import javax.servlet.http.HttpServletResponse;
 import net.yacy.cora.protocol.Domains;
 import net.yacy.server.http.AlternativeDomainNames;
 
-import org.eclipse.jetty.server.Handler;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.handler.AbstractHandler;
 
@@ -53,7 +52,7 @@ import org.eclipse.jetty.server.handler.AbstractHandler;
  * host is picked up and forwarded to the peer by the transparent proxy
  * handlers, before the local servlet context would handle it.
  */
-public class YacyDomainHandler extends AbstractHandler implements Handler {
+public class YacyDomainHandler extends AbstractHandler {
 
     private AlternativeDomainNames alternativeResolvers;
 
diff --git a/source/net/yacy/http/servlets/Jetty9ServletResource.java b/source/net/yacy/http/servlets/Jetty9ServletResource.java
index ba1d3d576..0a4054e45 100644
--- a/source/net/yacy/http/servlets/Jetty9ServletResource.java
+++ b/source/net/yacy/http/servlets/Jetty9ServletResource.java
@@ -1,3 +1,23 @@
+/**
+ *  Jetty9ServletResource
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http.servlets;
 
 import java.io.File;
diff --git a/source/net/yacy/http/servlets/ServletResource.java b/source/net/yacy/http/servlets/ServletResource.java
index 74e35113a..e5ee160fa 100644
--- a/source/net/yacy/http/servlets/ServletResource.java
+++ b/source/net/yacy/http/servlets/ServletResource.java
@@ -1,3 +1,23 @@
+/**
+ *  ServletResource
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http.servlets;
 
 import java.io.IOException;
diff --git a/source/net/yacy/http/servlets/UrlProxyServlet.java b/source/net/yacy/http/servlets/UrlProxyServlet.java
index 14ab7d863..378664448 100644
--- a/source/net/yacy/http/servlets/UrlProxyServlet.java
+++ b/source/net/yacy/http/servlets/UrlProxyServlet.java
@@ -1,3 +1,23 @@
+/**
+ *  UrlProxyServlet
+ *  Copyright 2026 by Michael Peter Christen
+ *  First released 12.07.2026 at https://yacy.net
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program in the file lgpl21.txt
+ *  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package net.yacy.http.servlets;
 
 import java.io.ByteArrayInputStream;