/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.microservice.jetty;

import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;
import static org.apache.juneau.marshall.collections.JsonMap.*;

import java.io.*;
import java.net.*;
import java.nio.file.*;
import java.time.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.util.logging.*;

import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.config.event.*;
import org.apache.juneau.marshall.cp.*;
import org.apache.juneau.microservice.*;
import org.apache.juneau.rest.server.*;
import org.apache.juneau.rest.server.health.*;
import org.apache.juneau.rest.server.servlet.*;
import org.eclipse.jetty.ee11.servlet.*;
import org.eclipse.jetty.server.*;

import jakarta.servlet.*;

/**
 * Drives the Jetty server lifecycle on behalf of the microservice via the {@link MicroserviceListener} fan-out.
 *
 * <p>
 * Contributed by {@link JettyConfiguration} as a <c>@Bean</c>.  The microservice's {@link Microservice#start()}
 * call invokes {@link #onStart(Microservice)}, which:
 * <ol>
 *    <li>Picks the first available port from the resolved {@link JettySettings#getPorts() ports} (falling back to
 *       <c>Jetty/port</c> config, then <c>Jetty-Port</c> manifest, then <c>8000</c>).
 *    <li>Resolves the Jetty {@link Server} — preferring an externally-supplied <c>@Bean Server</c>, otherwise
 *       building one from <c>jetty.xml</c> via the {@link JettyServerFactory}.
 *    <li>Mounts servlets from {@code Jetty/servlets}, {@code Jetty/servletMap}, {@code Jetty/servletAttributes}
 *       config sections, plus auto-mounts every {@code @Bean Servlet} whose runtime class is annotated with
 *       {@link Rest @Rest} (at {@link Rest#path()}, or <c>"/"</c> when no path is set).
 *    <li>Mounts every <c>@Bean</c> {@link ServletFilterRegistration} (and the <c>@Bean</c> <c>AuthFilterChain</c>, at
 *       <c>/*</c>, unless a registration already wraps it) in {@link ServletFilterRegistration#getOrder() order}.
 *    <li>Starts the server and publishes the bound port via the {@code availablePort} / {@code juneau.serverPort}
 *       system properties.
 * </ol>
 *
 * <p>
 * {@link #onStop(Microservice)} performs the inverse: stops the server gracefully in a worker thread.
 *
 * <p>
 * External callers reach this component via
 * {@code Microservice.getInstance().getBeanStore().getBean(JettyServerComponent.class).orElseThrow()}.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauMicroserviceJetty">juneau-microservice-jetty</a>
 * </ul>
 *
 * @since 10.0.0
 */
@SuppressWarnings({
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., KEY_SERVLET_CONTEXT_HANDLER)
   "java:S3878", // Array wrapper required to dispatch to varargs overload; without it the call recurses infinitely back to this single-String overload.
   "resource" // ms.getBeanStore() is owned by the microservice lifecycle; do not close here.
})
public class JettyServerComponent implements MicroserviceListener {

   private static final String KEY_SERVLET_CONTEXT_HANDLER = "ServletContextHandler";

   @SuppressWarnings({
      "java:S2245" // Used only to pick a benign ephemeral listen port (non security-sensitive); SecureRandom is unnecessary.
   })
   private static final Random RANDOM = new Random();

   /** Default bounded graceful-shutdown drain timeout applied to the Jetty server when none is configured. */
   static final Duration DEFAULT_STOP_TIMEOUT = Duration.ofSeconds(30);

   private final Messages messages = Messages.of(JettyServerComponent.class);
   private final AtomicReference<Server> server = new AtomicReference<>();
   private final AtomicReference<Microservice> microservice = new AtomicReference<>();
   private final AtomicReference<Duration> shutdownSettleDelay = new AtomicReference<>(Duration.ZERO);

   /**
    * Env-driven sentinel for {@code availablePort}; {@link Optional#empty()} when unset (in which case
    * {@link #onStart(Microservice)} publishes the bound port back as the {@code availablePort} system property).
    */
   @Value("${availablePort}")
   Optional<String> availablePortEnv = oe();

   /**
    * Env-driven sentinel for {@code juneau.serverPort}; {@link Optional#empty()} when unset (in which case
    * {@link #onStart(Microservice)} publishes the bound port back as the {@code juneau.serverPort} system property).
    */
   @Value("${juneau.serverPort}")
   Optional<String> serverPortEnv = oe();

   /**
    * Creates the directory the bundled <c>jetty.xml</c>'s request log writes into, so a fresh working directory starts.
    *
    * <p>
    * A failure is logged rather than thrown; Jetty reports the unusable directory when the request log starts.
    *
    * @param dir The log directory (<c>Logging/logDir</c>).
    * @param logger The logger to report a failure to.
    */
   static void createLogDir(String dir, Logger logger) {
      try {
         Files.createDirectories(Path.of(dir));
      } catch (IOException | InvalidPathException e) {
         logger.warning("Could not create log directory '" + dir + "': " + e);
      }
   }

   private static int[] parseIntArray(String csv) {
      if (ie(csv))
         return new int[0];
      var parts = csv.split(",");
      var out = new int[parts.length];
      for (var i = 0; i < parts.length; i++)
         out[i] = Integer.parseInt(parts[i].trim());
      return out;
   }

   private static int findOpenPort(int[] ports) {
      for (var port : ports) {
         if (port == 0)
            port = RANDOM.nextInt(32767 - ports[0] + 1) + ports[0];
         try (var ss = new ServerSocket(port)) {
            return port;
         } catch (@SuppressWarnings("unused") IOException e) {
            // Port is in use, try next port in array
         }
      }
      return 0;
   }

   private static String normalizePathSpec(String rawPath) {
      var p = rawPath == null ? "" : rawPath;
      if (p.isEmpty() || eq(p, "/"))
         return "/*";
      if (! p.startsWith("/"))
         p = "/" + p;
      if (! p.endsWith("/*"))
         p = trimTrailingSlashes(p) + "/*";
      return p;
   }

   private static String normalizeExactPathSpec(String rawPath) {
      var p = rawPath == null ? "" : trimTrailingSlashes(rawPath);
      if (p.isEmpty())
         return "/";
      if (! p.startsWith("/"))
         p = "/" + p;
      return p;
   }

   /**
    * Resolves the top-level Jetty mount path-specs for an auto-discovered {@code @Rest}-annotated servlet.
    *
    * <p>
    * Delegates to {@link RestContext#resolveTopLevelPaths(Class, Object, BeanStore)} so the runtime-override
    * resolution chain (programmatic &gt; {@code getPaths()} getter &gt; annotation default) is honored at
    * mount time. The programmatic Builder rung is N/A for Jetty auto-discovery (the {@code RestContext} does
    * not exist yet at this point in the lifecycle); users can substitute by overriding {@code getPaths()} on
    * the resource class, or by leaning on SVL inside {@code @Rest(paths=...)} elements (e.g.
    * {@code paths={"$C{health.paths}"}}) so each element is resolved through {@code Config} /
    * {@code $E{...}} / {@code $S{...}} before being comma-split.
    *
    * @return The normalized exact-match path-specs (for multi-mount), or the singular {@code @Rest(path)}-style
    *    {@code "/...&#47;*"} pathspec when no {@code paths} are resolved.
    */
   private static String[] restPathsFor(Servlet servlet, BeanStore store) {
      var cls = servlet.getClass();
      var r = cls.getAnnotation(Rest.class);
      if (r == null)
         return new String[] {"/*"};
      var resolved = RestContext.resolveTopLevelPaths(cls, servlet, store);
      if (resolved.length > 0)
         return Arrays.stream(resolved).map(JettyServerComponent::normalizeExactPathSpec).toArray(String[]::new);
      return new String[] {normalizePathSpec(r.path())};
   }

   /**
    * Constructor.
    */
   @SuppressWarnings({
      "java:S1186" // Empty constructor; all state is initialized via onStart(Microservice) when wired through the bean store.
   })
   public JettyServerComponent() {}

   @Override /* Overridden from MicroserviceListener */
   @SuppressWarnings({
      "java:S1141", // Nested try blocks scope checked-exception translation tightly to single call sites
      "java:S3776", // Cognitive complexity acceptable for server creation logic
      "java:S6541" // Brain Method acceptable for server startup wiring logic
   })
   public void onStart(Microservice ms) {
      try {
         microservice.set(ms);
         var store = ms.getBeanStore();
         ClassInfo.of(this).inject(this, store);
         var cf = ms.getConfig();
         var mf = ms.getManifest();
         var vr = ms.getVarResolver();
         var settings = store.getBean(JettySettings.class).orElseGet(() -> JettySettings.create().build());

         // Port resolution: settings > Jetty/port config > Jetty-Port manifest > 8000
         var ports = settings.getPorts();
         if (ports == null)
            ports = cf.get("Jetty/port").as(int[].class)
               .orElseGet(() -> mf.get("Jetty-Port").map(JettyServerComponent::parseIntArray).orElseGet(() -> ints(8000)));
         var availablePort = findOpenPort(ports);

         if (availablePortEnv.isEmpty())
            // Intentional real-JVM-property publish: the bundled jetty.xml binds its connector to
            // $S{availablePort,10000}, and the $S{...} SVL var resolves via raw System.getProperty (bypassing
            // the Settings override chain).  A Settings-based write would be invisible to jetty.xml, so the
            // bound port MUST be published as a real system property here.  The @Value-injected availablePortEnv
            // read side is already Settings-abstracted; only this publish must stay raw.
            System.setProperty("availablePort", String.valueOf(availablePort));

         // Prefer a @Bean-supplied Server, else build one from jetty.xml.
         var injectedServer = store.getBean(Server.class).orElse(null);
         if (nn(injectedServer)) {
            server.set(injectedServer);
         } else {
            var factory = store.getBean(JettyServerFactory.class).orElseGet(BasicJettyServerFactory::new);
            var jettyXml = settings.getJettyXml();
            var jettyConfig = cf.get("Jetty/config").orElseGet(() -> mf.get("Jetty-Config").orElse("jetty.xml"));
            var resolveVars = coalesce(settings.getJettyXmlResolveVars(), cf.get("Jetty/resolveVars").asBoolean().orElse(false));
            boolean resolveVars2 = isTrue(resolveVars);

            if (jettyXml == null)
               jettyXml = loadSystemResourceAsString(jettyConfig, ".", "files");
            if (jettyXml == null)
               throw rex("jetty.xml file '%s' was not found on the file system or classpath.", jettyConfig);

            if (resolveVars2)
               jettyXml = vr.resolve(jettyXml);

            ms.getLogger().config(jettyXml);

            createLogDir(cf.get("Logging/logDir").orElse("logs"), ms.getLogger());

            try {
               server.set(factory.create(jettyXml));
            } catch (Exception e) {
               throw toRex(e);
            }
         }

         // Publish back to the store for downstream beans / lookups.
         store.addBean(Server.class, server.get());

         // Graceful-shutdown wiring (zero-downtime k8s rollouts):
         //  - Apply a bounded stopTimeout so server.stop() drains in-flight requests before the connector closes.
         //    Precedence: JettySettings > Jetty/stopTimeout config > jetty.xml value (if any) > 30s default.
         //  - Remember the settle delay so onStop() can let the LB observe the /readyz 503 before draining.
         //  - Mark readiness ready so a freshly-(re)started service serves traffic.
         var stopTimeoutOverride = settings.getStopTimeout() != null
            ? settings.getStopTimeout()
            : cf.get("Jetty/stopTimeout").asLong().map(Duration::ofMillis).orElse(null);
         if (stopTimeoutOverride != null)
            server.get().setStopTimeout(Math.max(0L, stopTimeoutOverride.toMillis()));
         else if (server.get().getStopTimeout() <= 0L)
            server.get().setStopTimeout(DEFAULT_STOP_TIMEOUT.toMillis());
         shutdownSettleDelay.set(coalesce(settings.getShutdownSettleDelay(), cf.get("Jetty/shutdownSettleDelay").asLong().map(Duration::ofMillis).orElse(Duration.ZERO)));

         // Per-service readiness: reuse an app/test-supplied @Bean ReadinessState if present, else construct
         // one, and publish it into this microservice's bean store.  shared() is intentionally NOT used here:
         // it is one JVM-wide singleton, so falling back to it would leak this service's readiness into every
         // other default-configured microservice in the same JVM.  The health-probe servlet side of this
         // dual-store publish happens below, in the @Rest servlet auto-discovery loop.
         var readinessState = store.getBean(ReadinessState.class).orElseGet(ReadinessState::new);
         store.addBean(ReadinessState.class, readinessState);
         readinessState.markReady();

         // Track each servlet pathSpec with its declaring source so we can fail loudly on collisions.
         var mountedPaths = new LinkedHashMap<String,String>();

         for (var s : cf.get("Jetty/servlets").asStringArray().orElse(new String[0])) {
            try {
               var c = info(Class.forName(s));
               if (c.isAssignableTo(RestServlet.class)) {
                  var rs = (RestServlet)c.newInstance();
                  mountWithCollisionCheck(rs, rs.getPath(), "Jetty/servlets[" + s + "]", mountedPaths);
               } else {
                  throw rex("Invalid servlet specified in Jetty/servlets.  Must be a subclass of RestServlet: %s", s);
               }
            } catch (ClassNotFoundException e) {
               throw toRex(e);
            }
         }

         cf.get("Jetty/servletMap").asMap().orElse(EMPTY_MAP).forEach((k, v) -> {
            try {
               var c = info(Class.forName(v.toString()));
               if (c.isAssignableTo(Servlet.class)) {
                  var rs = (Servlet)c.newInstance();
                  mountWithCollisionCheck(rs, k, "Jetty/servletMap[" + k + "]", mountedPaths);
               } else {
                  throw rex("Invalid servlet specified in Jetty/servletMap.  Must be a subclass of Servlet: %s", cn(v));
               }
            } catch (ClassNotFoundException e) {
               throw toRex(e);
            }
         });

         cf.get("Jetty/servletAttributes").asMap().orElse(EMPTY_MAP).forEach(this::addServletAttribute);

         // Mount the @Bean ServletFilterRegistration filters, plus the @Bean AuthFilterChain at /* unless a
         // registration already wraps it, outermost first.  Filter matching does not depend on whether the
         // servlets or the filters were added first, so mounting after the config-sourced servlets is fine.
         for (var registration : ServletFilterRegistration.collect(store))
            addFilter(registration);

         // Auto-discover @Rest servlets contributed via @Configuration/@Bean methods.
         // Path source precedence: @Rest(path=...) on the resource class, else "/".
         for (var e : store.getBeansOfType(Servlet.class).entrySet()) {
            var servlet = e.getValue();
            var cls = servlet.getClass();
            if (cls.getAnnotation(Rest.class) == null)
               continue;
            if (servlet instanceof HealthServlet hs)
               // Dual-store publish (READY-394): this probe's own RestContext bean store is not linked to
               // ms.getBeanStore(), so the lifecycle-owned instance must be handed to it explicitly before
               // it initializes; HealthServlet.initReadinessState() registers it into its own bean store.
               hs.publishReadinessState(readinessState);
            if (servlet instanceof ReadinessStateAware rsa)
               // Lets servlets holding long-lived streams (e.g. MCP subscriptions/listen) end them when shutdown
               // begins, so the graceful drain does not wait out the full stopTimeout for them.
               rsa.acceptReadinessState(readinessState);
            var pathSpecs = restPathsFor(servlet, store);
            var source = "@Bean " + cls.getName() + (ine(e.getKey()) ? "[" + e.getKey() + "]" : "");
            for (var pathSpec : pathSpecs)
               checkPathCollision(pathSpec, source, mountedPaths);
            addServlet(servlet, pathSpecs);
         }

         if (serverPortEnv.isEmpty())
            // Intentional real-JVM-property publish: juneau.serverPort is a documented cross-component/external
            // publication of the bound port, consumed via raw System.getProperty (and $S{...} SVL).  A
            // Settings-based write would not be visible to those raw readers, so this is kept.  The
            // @Value-injected serverPortEnv read side is already Settings-abstracted.
            System.setProperty("juneau.serverPort", String.valueOf(availablePort));

         server.get().start();
         ms.out(messages, "ServerStarted", getPort());
      } catch (Exception e) {
         throw toRex(e);
      }
   }

   @Override /* Overridden from MicroserviceListener */
   public void onStop(Microservice ms) {
      final Logger logger = ms.getLogger();
      // Flip readiness out of service BEFORE the connector stops so /readyz returns 503 and the load balancer /
      // Kubernetes stops routing new traffic while in-flight requests drain.  /livez stays healthy so the pod is
      // not killed mid-drain.  The settle delay (default 0) gives the LB a window to observe the 503.
      ReadinessState.resolve(ms.getBeanStore()).markOutOfService();
      ms.out(messages, "DrainingRequests");
      sleepQuietly(shutdownSettleDelay.get());
      var t = new Thread("JettyServerComponentStop") {
         @Override /* Overridden from Thread */
         public void run() {
            try {
               var s = server.get();
               if (s == null || s.isStopping() || s.isStopped())
                  return;
               ms.out(messages, "StoppingServer");
               s.stop();
               ms.out(messages, "ServerStopped");
            } catch (Exception e) {
               logger.log(Level.WARNING, localizedMessage(e), e);
            }
         }
      };
      t.start();
      try {
         t.join();
      } catch (@SuppressWarnings("unused") InterruptedException e) {
         Thread.currentThread().interrupt();
      }
   }

   private static void sleepQuietly(Duration d) {
      if (d == null || d.isZero() || d.isNegative())
         return;
      try {
         Thread.sleep(d.toMillis());
      } catch (@SuppressWarnings("unused") InterruptedException e) {
         Thread.currentThread().interrupt();
      }
   }

   @Override /* Overridden from MicroserviceListener */
   public void onConfigChange(Microservice ms, ConfigEvents events) {
      // No-op: Intentional empty implementation - this component is purely lifecycle-driven.
   }

   /**
    * Adds an arbitrary servlet to this Jetty server.
    *
    * @param servlet The servlet instance.
    * @param pathSpec The context path of the servlet.
    * @return This object.
    */
   public JettyServerComponent addServlet(Servlet servlet, String pathSpec) {
      if (nn(pathSpec) && ! pathSpec.endsWith("/*"))
         pathSpec = trimTrailingSlashes(pathSpec) + "/*";
      return addServlet(servlet, new String[]{pathSpec});
   }

   /**
    * Adds an arbitrary servlet to this Jetty server at one or more context paths.
    *
    * @param servlet The servlet instance.
    * @param pathSpecs The context paths of the servlet.
    * @return This object.
    */
   public JettyServerComponent addServlet(Servlet servlet, String...pathSpecs) {
      var sh = new ServletHolder(servlet);
      for (var pathSpec : pathSpecs)
         getServletContextHandler().addServlet(sh, pathSpec);
      return this;
   }

   /**
    * Adds a servlet filter to this Jetty server at the specified URL pattern.
    *
    * @param filter The filter instance.
    * @param urlPattern The URL pattern the filter applies to (e.g. {@code "/*"}, {@code "/api/*"}).
    * @return This object.
    */
   public JettyServerComponent addFilter(jakarta.servlet.Filter filter, String urlPattern) {
      return addFilter(filter, new String[]{urlPattern});
   }

   /**
    * Adds a servlet filter to this Jetty server at one or more URL patterns.
    *
    * @param filter The filter instance.
    * @param urlPatterns The URL patterns the filter applies to.
    * @return This object.
    */
   public JettyServerComponent addFilter(jakarta.servlet.Filter filter, String... urlPatterns) {
      var fh = new FilterHolder(filter);
      for (var urlPattern : urlPatterns)
         getServletContextHandler().addFilter(fh, urlPattern, EnumSet.of(DispatcherType.REQUEST));
      return this;
   }

   /**
    * Adds a servlet filter registration to this Jetty server.
    *
    * <p>
    * Maps the filter on every URL pattern and dispatcher type of the registration with one mapping, so the filter runs at
    * most once per dispatch even when the patterns overlap.  Mapping order is call order, so call this outermost first.
    *
    * <p>
    * Applications contribute a {@link ServletFilterRegistration} <c>@Bean</c> instead; {@link #onStart(Microservice)}
    * applies the beans through this method in {@link ServletFilterRegistration#getOrder() order}.  Calling it directly
    * is only possible once the server object exists (during startup) and before the server runs.
    *
    * @param registration The registration.  Cannot be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If the registration is <jk>null</jk>.
    * @throws IllegalStateException If the server has already started.
    */
   public JettyServerComponent addFilter(ServletFilterRegistration registration) {
      if (registration == null)
         throw iaex("registration must not be null.");
      var jetty = getServer();
      if (jetty.isRunning() || jetty.isStopping())
         throw isex("Filters must be added before the server starts.");
      var filter = registration.getFilter();
      var name = registration.getName().orElseGet(() -> cn(filter) + "#" + UUID.randomUUID());
      var holder = new FilterHolder(filter);
      holder.setName(name);
      holder.setAsyncSupported(registration.isAsyncSupported());
      var mapping = new FilterMapping();
      mapping.setFilterName(name);
      mapping.setPathSpecs(registration.getUrlPatterns().toArray(new String[0]));
      mapping.setDispatcherTypes(EnumSet.copyOf(registration.getDispatcherTypes()));
      getServletContextHandler().getServletHandler().addFilter(holder, mapping);
      return this;
   }

   /**
    * Adds a servlet filter to this Jetty server on the given dispatcher types and URL patterns.
    *
    * <p>
    * Shorthand for {@link #addFilter(ServletFilterRegistration)} with the default order and async support, and the same
    * validation.  The overloads without dispatcher types keep their {@code REQUEST}-only behavior.
    *
    * @param filter The filter instance.  Cannot be <jk>null</jk>.
    * @param dispatcherTypes The dispatcher types.  Cannot be empty.
    * @param urlPatterns The URL patterns.  At least one is required; see {@link org.apache.juneau.microservice.ServletFilterRegistration.Builder#urlPatterns(String...) ServletFilterRegistration.Builder#urlPatterns(String...)}.
    * @return This object.
    * @throws IllegalArgumentException If an argument is invalid.
    * @throws IllegalStateException If the server has already started.
    */
   public JettyServerComponent addFilter(jakarta.servlet.Filter filter, Set<DispatcherType> dispatcherTypes, String... urlPatterns) {
      if (dispatcherTypes == null)
         throw iaex("dispatcherTypes must not be null.");
      return addFilter(ServletFilterRegistration.create(filter).urlPatterns(urlPatterns).dispatcherTypes(dispatcherTypes.toArray(DispatcherType[]::new)).build());
   }

   /**
    * Adds an attribute to the Jetty server.
    *
    * @param name The server attribute name.
    * @param value The attribute value.
    * @return This object.
    */
   public JettyServerComponent addServletAttribute(String name, Object value) {
      getServer().setAttribute(name, value);
      return this;
   }

   /**
    * Returns the context path that this server is using.
    *
    * @return The context path.
    */
   public String getContextPath() {
      return getServletContextHandler().getContextPath();
   }

   /**
    * Returns the hostname of this microservice.
    *
    * @return The hostname.
    */
   public String getHostName() {
      String hostname = "localhost";
      try {
         hostname = InetAddress.getLocalHost().getHostName();
      } catch (@SuppressWarnings("unused") UnknownHostException e) {
         // Cannot determine hostname, use default "localhost"
      }
      return hostname;
   }

   /**
    * Returns the port that this server is listening on.
    *
    * @return The port.
    */
   public int getPort() {
      for (var c : getServer().getConnectors())
         if (c instanceof ServerConnector c2)
            return c2.getPort();
      throw new IllegalStateException("Could not locate ServerConnector in Jetty server.");
   }

   /**
    * Returns whether this server is using <js>"http"</js> or <js>"https"</js>.
    *
    * @return The protocol.
    */
   public String getProtocol() {
      for (var c : getServer().getConnectors())
         if (c instanceof ServerConnector c2)
            for (var cf : c2.getConnectionFactories())
               if (cf instanceof SslConnectionFactory)
                  return "https";
      return "http";
   }

   /**
    * Returns the underlying Jetty server.
    *
    * @return The underlying Jetty server.
    * @throws NullPointerException If the server has not been created yet.
    */
   public Server getServer() {
      return Objects.requireNonNull(server.get(), "Server not found.  Microservice has not been started yet.");
   }

   /**
    * Finds and returns the servlet context handler defined in the Jetty container.
    *
    * @return The servlet context handler.
    * @throws IllegalStateException If the context handler is not defined.
    */
   public ServletContextHandler getServletContextHandler() {
      var obj = getServer().getAttribute(KEY_SERVLET_CONTEXT_HANDLER);
      if (obj instanceof ServletContextHandler obj2)
         return obj2;
      throw isex("Servlet context handler not found in jetty server or at attribute '%s'", KEY_SERVLET_CONTEXT_HANDLER);
   }

   /**
    * Returns the URI where this server is listening.
    *
    * @return The URI.
    */
   public URI getURI() {
      var cp = getContextPath();
      try {
         return new URI(getProtocol(), null, getHostName(), getPort(), eq(cp, "/") ? null : cp, null, null);
      } catch (URISyntaxException e) {
         throw toRex(e);
      }
   }

   private void mountWithCollisionCheck(Servlet servlet, String rawPath, String source, Map<String,String> mountedPaths) {
      var pathSpec = normalizePathSpec(rawPath);
      checkPathCollision(pathSpec, source, mountedPaths);
      addServlet(servlet, pathSpec);
   }

   private void checkPathCollision(String pathSpec, String source, Map<String,String> mountedPaths) {
      var prior = mountedPaths.get(pathSpec);
      if (nn(prior))
         throw rex("Servlet mount path collision: '%s' is already mounted by %s; refused by %s.", pathSpec, prior, source);
      mountedPaths.put(pathSpec, source);
   }
}