/*-
 * #%L
 * Smile CDR - CDR
 * %%
 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
 * %%
 * All rights reserved.
 * #L%
 */
package ca.cdr.test.app.harness.impl;

import ca.cdr.test.app.clients.AdminJsonRestClient;
import ca.cdr.test.app.clients.CdrFhirClient;
import ca.cdr.test.app.clients.CdsHooksClient;
import ca.cdr.test.app.clients.HL7V2RestClient;
import ca.cdr.test.app.clients.NpmPackageClient;
import ca.cdr.test.app.clients.OutboundSmartClient;
import ca.cdr.test.app.clients.SmartHealthLinkClient;
import ca.cdr.test.app.clients.SmilePortalClient;
import ca.cdr.test.app.clients.common.ISmileTestHttpClient;
import ca.cdr.test.app.clients.common.RequestFactoryUtil;
import ca.cdr.test.app.clients.common.SmileTestHttpClient;
import ca.cdr.test.app.harness.api.HarnessContext;
import ca.cdr.test.app.harness.api.SmileHarness;
import ca.cdr.test.model.NodeConfigurations;
import ca.cdr.test.util.UrlPathUtil;
import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.context.FhirVersionEnum;
import ca.uhn.fhir.rest.client.api.IClientInterceptor;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import ca.uhn.fhir.rest.client.interceptor.BasicAuthInterceptor;
import ca.uhn.fhir.rest.client.interceptor.BearerTokenAuthInterceptor;
import ca.uhn.fhir.rest.server.exceptions.InternalErrorException;
import ca.uhn.fhir.test.utilities.HttpTestRequest;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.Validate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.client.RestClient;

import java.net.URI;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;
import java.util.function.UnaryOperator;

/**
 * The {@code LocalhostSmileHarness} class is responsible for managing interaction
 * with a Smile CDR environment running on the localhost. It provides utility methods to
 * identify and interact with Smile modules, such as FHIR endpoints and HL7v2 endpoints,
 * through exposed ports and administrative interfaces.
 * <p>
 * This class implements the {@link SmileHarness} interface to provide concrete
 * implementations of the methods required to handle FHIR and administrative operations.
 * <p>
 * Every URL it builds is {@code protocol://host:port} followed by the target module's
 * {@code context_path}, so modules mounted beneath a context path are reached there. The Admin JSON
 * module's own context path comes from {@link HarnessContext#jsonAdminContextPath()}, since it is
 * needed before any module configuration can be read; every other module's comes from that
 * configuration. A port no module is configured with is addressed at the root.
 * <p>
 * This class was generated partly with the help of Claude Sonnet 3.7
 */
public class LocalhostSmileHarness implements SmileHarness {
        private static final Logger ourLog = LoggerFactory.getLogger(LocalhostSmileHarness.class);
        private static final int DEFAULT_JSON_ADMIN_PORT = 9000;

        private final Function<Integer, Integer> portResolver;
        private final HarnessContext myContext;
        private final SmileTestHttpClient myHttpClient;
        /**
         * The Admin JSON port this harness talks to, resolved once so that every caller agrees on it.
         * A context that names no port falls back to {@link #DEFAULT_JSON_ADMIN_PORT}, which is the port
         * the connectivity check then runs against.
         */
        private final int myJsonAdminPort;
        /**
         * Filled in configuration order, which is what makes the no-argument accessors deterministic
         * when a node has several modules of one type.
         */
        private final Map<String, Integer> myFhirModulePortMap = new LinkedHashMap<>();
        private final Map<String, Integer> myEndpointHl7V2PortMap = new LinkedHashMap<>();
        private final Map<String, Integer> mySmartEndpointPortMap = new LinkedHashMap<>();
        private final Map<String, Integer> myPackageRegistryPortMap = new LinkedHashMap<>();
        private final Map<String, Integer> myCdsHooksPortMap = new LinkedHashMap<>();
        /**
         * Every discovered port map, in the order {@link #discoveredPortFor(String)} searches them. Constant
         * once the constructor has run, since the maps behind it are only written during discovery.
         */
        private final List<Map<String, Integer>> myDiscoveredPortMaps = List.of(
                myFhirModulePortMap, myEndpointHl7V2PortMap, mySmartEndpointPortMap, myPackageRegistryPortMap, myCdsHooksPortMap);
        /**
         * The normalized context path of each module, keyed by the port it is configured with rather
         * than the one it is published on. Written only in the constructor.
         */
        private final Map<Integer, String> myContextPathByPort = new HashMap<>();
        /**
         * Holds only the contexts resolved from {@link #myNodeConfigurations}, which cannot go stale
         * because that snapshot cannot change. A module the snapshot does not cover is re-resolved per
         * call and never lands here ? see {@link #locateFhirModule(String)}.
         * <p>
         * One harness is shared by every test using a given {@link ca.cdr.test.extensions.SmileCdrContainer},
         * so this is populated on demand from more than one thread.
         */
        private final Map<String, FhirContext> myFhirContextByModuleId = new ConcurrentHashMap<>();
        /**
         * The node's module configuration as it was when this harness was built ? one
         * {@code GET /module-config/} response, kept so that building a request costs no round trip.
         * A module added to the node afterwards will not be in here; {@link #locateFhirModule(String)},
         * {@link #addressOf(String)} and {@link #cachedFhirContext(String)} fall back to the node for
         * those.
         */
        private final NodeConfigurations myNodeConfigurations;

        private static final List<String> HL7V2_COMPATIBLE_MODULE_TYPES = List.of(
                "ENDPOINT_HL7V2_IN_V2",
                "ENDPOINT_HL7V2_IN"
        );

        private static final List<String> SMART_COMPATIBLE_MODULE_TYPES = List.of(
                "SECURITY_OUT_SMART"
        );

        private static final List<String> PACKAGE_REGISTRY_COMPATIBLE_MODULE_TYPES = List.of(
                "ENDPOINT_PACKAGE_REGISTRY"
        );

        private static final List<String> CDS_HOOKS_COMPATIBLE_MODULE_TYPES = List.of(
                "ENDPOINT_CDS_HOOKS"
        );

        private static final String DEFAULT_FHIR_MODULE_ID = "fhir_endpoint";
        private static final String DEFAULT_SMART_MODULE_ID = "smart_auth";
        private static final int DEFAULT_HL7V2_PORT = 7000;
        private static final String CONTEXT_PATH = "context_path";

        /**
         * Version markers that can appear inside a module type, checked in this order ? the first one
         * the type contains wins.
         */
        private static final List<Map.Entry<String, Supplier<FhirContext>>> CONTEXT_BY_VERSION_MARKER = List.of(
                Map.entry("R4", FhirContext::forR4Cached),
                Map.entry("DSTU3", FhirContext::forDstu3Cached),
                Map.entry("R5", FhirContext::forR5Cached),
                Map.entry("DSTU2", FhirContext::forDstu2Cached)
        );

        public LocalhostSmileHarness(HarnessContext theContext) {
                this(theContext, null);
        }
        public LocalhostSmileHarness(HarnessContext theContext, Map<Integer, Integer> theExposedPortMappings) {
                this(theContext, theExposedPortMappings, SmileTestHttpClient.create());
        }

        /**
         * Builds a harness over an existing HTTP client. The harness takes ownership: {@link #close()}
         * releases the client, as does a failure during discovery.
         */
        LocalhostSmileHarness(
                        HarnessContext theContext,
                        Map<Integer, Integer> theExposedPortMappings,
                        SmileTestHttpClient theHttpClient) {
                myContext = theContext;
                if (theExposedPortMappings == null || theExposedPortMappings.isEmpty()) {
                        portResolver = i -> i;
                } else {
                        portResolver = theExposedPortMappings::get;
                }
                myHttpClient = theHttpClient;
                myJsonAdminPort = resolveJsonAdminPort(theContext);
                myContextPathByPort.put(myJsonAdminPort, theContext.jsonAdminContextPath());
                try {
                        myNodeConfigurations = fetchNodeConfigurations();
                        recordContextPaths();
                        discoverEndpoints();
                } catch (RuntimeException e) {
                        // Discovery talks to the running node, so it fails whenever the node is not up yet or
                        // the ports are wrong. Without this the caller never gets a reference to close, and the
                        // connection pool survives until the JVM exits.
                        myHttpClient.close();
                        throw e;
                }
        }

        /**
         * Records the port of every module this harness can reach, all read from
         * {@link #myNodeConfigurations}.
         */
        private void discoverEndpoints() {
                discoverEndpoints("FHIR", NodeConfigurations.ModuleConfiguration::isFhirEndpointModuleType, myFhirModulePortMap);
                discoverEndpoints("HL7v2", moduleTypeIn(HL7V2_COMPATIBLE_MODULE_TYPES), myEndpointHl7V2PortMap);
                discoverEndpoints("SMART", moduleTypeIn(SMART_COMPATIBLE_MODULE_TYPES), mySmartEndpointPortMap);
                discoverEndpoints("package registry", moduleTypeIn(PACKAGE_REGISTRY_COMPATIBLE_MODULE_TYPES), myPackageRegistryPortMap);
                discoverEndpoints("CDS Hooks", moduleTypeIn(CDS_HOOKS_COMPATIBLE_MODULE_TYPES), myCdsHooksPortMap);
        }

        /**
         * Records the context path of every module with a port. The Admin JSON port keeps the context
         * path the {@link HarnessContext} named, since that is the one discovery just succeeded with.
         */
        private void recordContextPaths() {
                myNodeConfigurations.getNodes().stream()
                        .flatMap(node -> node.getModules().stream())
                        .filter(module -> StringUtils.isNotBlank(optionalConfigProperty(module, "port")))
                        .forEach(module -> myContextPathByPort.putIfAbsent(
                                Integer.parseInt(module.getConfigProperty("port")), contextPathOf(module)));
        }

        private static @Nullable String optionalConfigProperty(
                        NodeConfigurations.ModuleConfiguration theModule, String theKey) {
                // Unlike getConfigProperty(String), this tolerates a key the node reports with a null value.
                return theModule.getConfigProperties().stream()
                        .filter(property -> theKey.equals(property.getKey()))
                        .map(NodeConfigurations.ModuleConfigProperty::getValue)
                        .filter(Objects::nonNull)
                        .findFirst()
                        .orElse(null);
        }

        /**
         * A module's {@code context_path}, normalized. Only {@code context_path} decides where a module's
         * server is mounted; {@code base_url.fixed} changes the links a module writes, not where it
         * listens, so it is not consulted.
         */
        private static String contextPathOf(NodeConfigurations.ModuleConfiguration theModule) {
                return UrlPathUtil.normalizeContextPath(optionalConfigProperty(theModule, CONTEXT_PATH));
        }

        /**
         * Records the configured port of every module {@code theIsWanted} accepts, then fails fast if
         * the port resolver cannot map one of them.
         *
         * @param theKind how to describe this group of modules in the log
         */
        private void discoverEndpoints(
                        String theKind,
                        Predicate<NodeConfigurations.ModuleConfiguration> theIsWanted,
                        Map<String, Integer> theTargetPortMap) {
                myNodeConfigurations.getNodes().stream()
                        .flatMap(node -> node.getModules().stream())
                        .filter(theIsWanted)
                        .forEach(module -> {
                                String port = module.getConfigProperty("port");
                                if (StringUtils.isBlank(port)) {
                                        ourLog.warn("Found {} module, but it had no port assigned! [moduleId={}, moduleType={}]",
                                                theKind, module.getModuleId(), module.getModuleType());
                                        return;
                                }
                                ourLog.info("Found {} module. [moduleId={}, moduleType={}, port={}, contextPath={}]",
                                        theKind, module.getModuleId(), module.getModuleType(), port, contextPathOf(module));
                                theTargetPortMap.put(module.getModuleId(), Integer.parseInt(port));
                        });

                validatePortResolverCanResolvePorts(theTargetPortMap);
        }

        private static Predicate<NodeConfigurations.ModuleConfiguration> moduleTypeIn(List<String> theModuleTypes) {
                return module -> theModuleTypes.contains(module.getModuleType());
        }

        private void validatePortResolverCanResolvePorts(Map<String, Integer> theModuleToPortMap) {
                //Ensure all the endpoints we found have Mappings
                theModuleToPortMap.forEach((key, value) -> {
                        if (portResolver.apply(value) == null) {
                                throw unmappedPort(key + " (" + value + ")");
                        }
                });
        }

        /**
         * The one failure both discovery and {@link #resolvePort(int)} report, so that the same condition
         * does not read two different ways depending on which of them reached it.
         *
         * @param theSubject what could not be mapped ? a port on its own, or a module ID and its port
         */
        private static IllegalStateException unmappedPort(String theSubject) {
                return new IllegalStateException(
                        "Could not find a mapped port for module. Please ensure your port resolver can resolve this port! : " + theSubject);
        }

        /**
         * The Admin JSON port to use, which is the one the context names or {@link #DEFAULT_JSON_ADMIN_PORT}.
         * Resolved once in the constructor so that discovery, {@link #getAdminJsonClient()} and
         * {@link #adminJsonRequest(String)} cannot disagree about which port this harness talks to.
         */
        static int resolveJsonAdminPort(HarnessContext theContext) {
                Integer jsonAdminPort = theContext.jsonAdminPort();
                if (jsonAdminPort == null) {
                        ourLog.warn("No JSON Admin port was provided in the provided harness context. Attempting to fallback to the default port [port={}]", DEFAULT_JSON_ADMIN_PORT);
                        return DEFAULT_JSON_ADMIN_PORT;
                }
                ourLog.info("Found a JSON Admin port in the context provided. [port={}]", jsonAdminPort);
                return jsonAdminPort;
        }

        /**
         * The connectivity check and the configuration read are the same request, so this returns what
         * it fetched rather than making the caller ask again.
         */
        private NodeConfigurations fetchNodeConfigurations() {
                try {
                        ourLog.info("Performing a connectivity check for Admin JSON module. [host={}, port={}, contextPath={}]", myContext.getContextRoot(), myJsonAdminPort, myContext.jsonAdminContextPath());
                        NodeConfigurations retVal = getAdminJsonClient(myJsonAdminPort).getNodeConfigurations();
                        ourLog.info("Connectivity check succeeded, client can be used! [host={}, port={}]", myContext.getContextRoot(), myJsonAdminPort);
                        return retVal;
                } catch(Exception e) {
                        throw new InternalErrorException(String.format("Connectivity check failed for Admin JSON module. [host=%s, port=%d, contextPath=%s]", myContext.getContextRoot(), myJsonAdminPort, myContext.jsonAdminContextPath()), e);
                }
        }

        @Override
        public CdrFhirClient getSuperuserFhirClient() {
                return getSuperuserFhirClient(firstFhirModule().getKey());
        }

        @Override
        public CdrFhirClient getSuperuserFhirClient(int thePort) {
                return cdrFhirClient(
                        addressAt(thePort),
                        () -> cachedFhirContext(fhirModuleIdForPort(thePort)),
                        new BasicAuthInterceptor(myContext.username(), myContext.password()),
                        this::withSuperuserAuth);
        }

        @Override
        public AdminJsonRestClient getAdminJsonClient() {
                return getAdminJsonClient(myJsonAdminPort);
        }

        @Override
        public AdminJsonRestClient getAdminJsonClient(int theAdminPort) {
                return AdminJsonRestClient.issuingOn(
                        myHttpClient, restClientBaseUrl(addressAt(theAdminPort)), myContext.username(), myContext.password());
        }

        @Override
        public CdrFhirClient getSuperuserFhirClient(String theModuleId) {
                ModuleLocation module = locateFhirModule(theModuleId);
                return cdrFhirClient(
                        module.address(),
                        module::fhirContext,
                        new BasicAuthInterceptor(myContext.username(), myContext.password()),
                        this::withSuperuserAuth);
        }

        @Override
        public CdrFhirClient getFhirClient() {
                return getFhirClient(firstFhirModule().getKey());
        }

        /**
         * The FHIR endpoint used whenever a caller does not name one, so that {@link #getFhirClient()}
         * and {@link #fhirAnonymousRequest(String)} always pick the same one. The entry carries both the
         * module ID and its port, which callers generally need together.
         */
        private Map.Entry<String, Integer> firstFhirModule() {
                return defaultModule(myFhirModulePortMap, DEFAULT_FHIR_MODULE_ID)
                        .orElseThrow(() -> new IllegalStateException("No FHIR Endpoint found in the configuration."));
        }

        /**
         * The module a no-argument accessor uses: the one with the conventional ID if there is one,
         * otherwise the first of its type in the node's configuration.
         */
        private static Optional<Map.Entry<String, Integer>> defaultModule(
                        Map<String, Integer> theDiscovered, @Nullable String theConventionalModuleId) {
                if (theConventionalModuleId != null && theDiscovered.containsKey(theConventionalModuleId)) {
                        return Optional.of(Map.entry(theConventionalModuleId, theDiscovered.get(theConventionalModuleId)));
                }
                return theDiscovered.entrySet().stream().findFirst();
        }

        @Override
        public CdrFhirClient getFhirClient(int thePort) {
                return cdrFhirClient(
                        addressAt(thePort), () -> cachedFhirContext(fhirModuleIdForPort(thePort)), null, UnaryOperator.identity());
        }

        @Override
        public CdrFhirClient getFhirClient(String theModuleId) {
                ModuleLocation module = locateFhirModule(theModuleId);
                return cdrFhirClient(module.address(), module::fhirContext, null, UnaryOperator.identity());
        }

        @Override
        public CdrFhirClient getFhirClient(@Nonnull String theModuleId, @Nonnull String theBearerToken) {
                Validate.notEmpty(theBearerToken, "Bearer token is required");
                ModuleLocation module = locateFhirModule(theModuleId);
                return cdrFhirClient(
                        module.address(),
                        module::fhirContext,
                        new BearerTokenAuthInterceptor(theBearerToken),
                        request -> request.withHeader("Authorization", "Bearer " + theBearerToken));
        }

        private CdrFhirClient cdrFhirClient(
                        ModuleAddress theAddress,
                        Supplier<FhirContext> theFhirContext,
                        @Nullable IClientInterceptor theAuthInterceptor,
                        UnaryOperator<HttpTestRequest> theAuth) {
                String baseUrl = baseUrl(theAddress);
                FhirContext fhirContext = theFhirContext.get();
                IGenericClient delegate = fhirContext.newRestfulGenericClient(baseUrl);
                if (theAuthInterceptor != null) {
                        delegate.registerInterceptor(theAuthInterceptor);
                }
                return new CdrFhirClient(
                        delegate,
                        path -> theAuth.apply(myHttpClient.cookielessRequest(fhirContext, buildUrl(theAddress, path))),
                        url -> theAuth.apply(myHttpClient.cookielessRequest(fhirContext, resolveServerUrl(url))));
        }

        private HttpTestRequest withSuperuserAuth(HttpTestRequest theRequest) {
                return theRequest.withBasicAuth(myContext.username(), myContext.password());
        }

        @Override
        public @Nonnull HttpTestRequest fhirRequest(@Nonnull String thePath) {
                return fhirRequest(firstFhirModule().getKey(), thePath);
        }

        @Override
        public @Nonnull HttpTestRequest fhirRequest(@Nonnull String theModuleId, @Nonnull String thePath) {
                return buildFhirRequest(theModuleId, thePath)
                        .withBasicAuth(myContext.username(), myContext.password());
        }

        @Override
        public @Nonnull HttpTestRequest fhirAnonymousRequest(@Nonnull String thePath) {
                return fhirAnonymousRequest(firstFhirModule().getKey(), thePath);
        }

        @Override
        public @Nonnull HttpTestRequest fhirAnonymousRequest(@Nonnull String theModuleId, @Nonnull String thePath) {
                return buildFhirAnonymousRequest(theModuleId, thePath);
        }

        @Override
        public @Nonnull HttpTestRequest serverUrlRequest(@Nonnull String theServerUrl) {
                return withSuperuserAuth(myHttpClient.request(resolveServerUrl(theServerUrl)));
        }

        private String resolveServerUrl(String theServerUrl) {
                URI uri = URI.create(theServerUrl);
                Validate.isTrue(uri.isAbsolute(), "Expected an absolute URL the server returned, got %s", theServerUrl);
                if (uri.getPort() == -1) {
                        return theServerUrl;
                }
                return myContext.getContextRoot() + ":" + resolvePort(uri.getPort()) + uri.getRawPath()
                        + (uri.getRawQuery() == null ? "" : "?" + uri.getRawQuery());
        }

        @Override
        public @Nonnull HttpTestRequest fhirBearerRequest(
                        @Nonnull String theModuleId, @Nonnull String thePath, @Nonnull String theBearerToken) {
                Validate.notEmpty(theBearerToken, "Bearer token is required");
                return buildFhirAnonymousRequest(theModuleId, thePath).withHeader("Authorization", "Bearer " + theBearerToken);
        }

        @Override
        public @Nonnull HttpTestRequest request(int thePort, @Nonnull String thePath) {
                return authenticatedRequest(addressAt(thePort), thePath);
        }

        @Override
        public @Nonnull HttpTestRequest request(@Nonnull String theModuleId, @Nonnull String thePath) {
                return authenticatedRequest(addressOf(theModuleId), thePath);
        }

        private HttpTestRequest authenticatedRequest(ModuleAddress theAddress, String thePath) {
                return myHttpClient.request(buildUrl(theAddress, thePath))
                        .withBasicAuth(myContext.username(), myContext.password());
        }

        @Override
        public @Nonnull HttpTestRequest adminJsonRequest(@Nonnull String thePath) {
                return request(myJsonAdminPort, thePath);
        }

        @Override
        public @Nonnull HttpTestRequest anonymousRequest(int thePort, @Nonnull String thePath) {
                return myHttpClient.cookielessRequest(buildUrl(addressAt(thePort), thePath));
        }

        @Override
        public @Nonnull HttpTestRequest anonymousRequest(@Nonnull String theModuleId, @Nonnull String thePath) {
                return myHttpClient.cookielessRequest(buildUrl(addressOf(theModuleId), thePath));
        }

        @Override
        public @Nonnull ISmileTestHttpClient getHttpClient() {
                return myHttpClient;
        }

        @Override
        public void clearCookies() {
                myHttpClient.clearCookies();
        }

        @Override
        public void close() {
                myHttpClient.close();
        }

        /**
         * Whether {@link #close()} has been called. {@link ca.cdr.test.extensions.SmileCdrContainer}
         * caches a harness and uses this to replace one a caller closed, since every request through a
         * closed harness fails on the shut-down pool.
         */
        public boolean isClosed() {
                return myHttpClient.isClosed();
        }

        private HttpTestRequest buildFhirRequest(String theModuleId, String thePath) {
                ModuleLocation module = locateFhirModule(theModuleId);
                return myHttpClient.request(module.fhirContext(), buildUrl(module.address(), thePath));
        }

        private HttpTestRequest buildFhirAnonymousRequest(String theModuleId, String thePath) {
                ModuleLocation module = locateFhirModule(theModuleId);
                return myHttpClient.cookielessRequest(module.fhirContext(), buildUrl(module.address(), thePath));
        }

        /**
         * Where a module is served: the port it is configured with, which {@link #resolvePort(int)} has
         * yet to map, and its normalized context path.
         */
        private record ModuleAddress(int port, String contextPath) {}

        /**
         * A module's address together with the {@link FhirContext} its requests encode with.
         */
        private record ModuleLocation(ModuleAddress address, FhirContext fhirContext) {}

        /**
         * Both halves of a FHIR request builder, always resolved from one configuration ? a port read
         * live against a FHIR version read from the stored snapshot would find a module and then fail on
         * its version.
         * <p>
         * Which configuration that is, is what decides whether either half may be cached. A module
         * {@link #myNodeConfigurations} covers is resolved from that snapshot, which cannot change, so the
         * context is cached and nothing goes over the wire. A module added after this harness was built is
         * resolved from one live {@code GET /module-config/} per call and <em>neither</em> half is cached:
         * discovery's port map is written only at construction, so that module's port is re-read every
         * time, and a version cached beside a port that is not would leave a re-versioned module encoding
         * its body against whichever version it happened to have the first time it was asked for.
         */
        private ModuleLocation locateFhirModule(String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                if (isInNodeConfigurations(theModuleId)) {
                        return new ModuleLocation(
                                addressIn(myNodeConfigurations, theModuleId), cachedSnapshotFhirContext(theModuleId));
                }

                NodeConfigurations live = getAdminJsonClient().getNodeConfigurations();
                return new ModuleLocation(addressIn(live, theModuleId), resolveFhirContext(live, theModuleId));
        }

        /**
         * A module's address, from the snapshot for a module it covers and otherwise from one live
         * {@code GET /module-config/}, for the reasons given on {@link #locateFhirModule(String)}.
         */
        private ModuleAddress addressOf(String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                NodeConfigurations nodeConfigs = isInNodeConfigurations(theModuleId)
                        ? myNodeConfigurations
                        : getAdminJsonClient().getNodeConfigurations();
                return addressIn(nodeConfigs, theModuleId);
        }

        private ModuleAddress addressIn(NodeConfigurations theNodeConfigs, String theModuleId) {
                int port = portIn(theNodeConfigs, theModuleId);
                String contextPath = moduleIn(theNodeConfigs, theModuleId)
                        .map(LocalhostSmileHarness::contextPathOf)
                        .orElseGet(() -> addressAt(port).contextPath());
                return new ModuleAddress(port, contextPath);
        }

        /**
         * The address of whichever module the snapshot says is configured with {@code thePort}, or the
         * root of that port when none is.
         */
        private ModuleAddress addressAt(int thePort) {
                return new ModuleAddress(thePort, myContextPathByPort.getOrDefault(thePort, ""));
        }

        /**
         * The port discovery recorded for a module, or the one the given configuration names for a module
         * discovery did not cover.
         */
        private int portIn(NodeConfigurations theNodeConfigs, String theModuleId) {
                Integer discovered = discoveredPortFor(theModuleId);
                return discovered != null ? discovered : portFromConfiguration(theNodeConfigs, theModuleId);
        }

        /**
         * The port discovery recorded for a module, or {@literal null} for one it did not cover.
         */
        private Integer discoveredPortFor(String theModuleId) {
                for (Map<String, Integer> discovered : myDiscoveredPortMaps) {
                        Integer port = discovered.get(theModuleId);
                        if (port != null) {
                                return port;
                        }
                }
                return null;
        }

        /**
         * The port a module is configured with, read from a configuration the caller already holds ? the
         * same {@code port} property discovery reads, so a module resolved here and one resolved at
         * construction agree.
         */
        private static int portFromConfiguration(NodeConfigurations theNodeConfigs, String theModuleId) {
                NodeConfigurations.ModuleConfiguration module = moduleIn(theNodeConfigs, theModuleId)
                        .orElseThrow(() -> new IllegalArgumentException(
                                "Module with ID " + theModuleId + " not found in node configuration"));

                String port = module.getConfigProperty("port");
                if (StringUtils.isBlank(port)) {
                        throw new IllegalArgumentException("Module has no port configured. [moduleId=%s, moduleType=%s]"
                                .formatted(theModuleId, module.getModuleType()));
                }
                return Integer.parseInt(port);
        }

        private static Optional<NodeConfigurations.ModuleConfiguration> moduleIn(
                        NodeConfigurations theNodeConfigs, String theModuleId) {
                return theNodeConfigs.getNodes().stream()
                        .map(node -> node.getModule(theModuleId))
                        .flatMap(Optional::stream)
                        .findFirst();
        }

        /**
         * The ID of the FHIR endpoint module configured with the given port, falling back to the node
         * for a port discovery did not cover.
         */
        private String fhirModuleIdForPort(int thePort) {
                return myFhirModulePortMap.entrySet().stream()
                        .filter(entry -> entry.getValue() == thePort)
                        .map(Map.Entry::getKey)
                        .findFirst()
                        .orElseGet(() -> getAdminJsonClient().getFhirEndpointModuleIdFromPort(thePort));
        }

        /**
         * The FHIR context of a module {@link #myNodeConfigurations} covers, read once from that snapshot
         * and then cached ? the snapshot cannot change, so neither can the answer.
         * {@link #getFhirContext(String)} re-reads the node's configuration on every call, which a
         * request builder must not do: that would cost a round trip per assertion and would make an
         * anonymous request depend on the Admin JSON credentials.
         * <p>
         * A module added after this harness was built falls back to that live lookup, and its answer is
         * deliberately <em>not</em> cached, for the reason given on {@link #locateFhirModule(String)}.
         */
        private FhirContext cachedFhirContext(String theModuleId) {
                return isInNodeConfigurations(theModuleId)
                        ? cachedSnapshotFhirContext(theModuleId)
                        : getFhirContext(theModuleId);
        }

        /**
         * The cached half of {@link #cachedFhirContext(String)}, for a caller that has already established
         * that {@link #myNodeConfigurations} covers the module.
         */
        private FhirContext cachedSnapshotFhirContext(String theModuleId) {
                FhirContext cached = myFhirContextByModuleId.get(theModuleId);
                if (cached != null) {
                        return cached;
                }
                return cacheFhirContext(theModuleId, resolveFhirContext(myNodeConfigurations, theModuleId));
        }

        /**
         * Publishes a resolved context, keeping whichever value won if another thread resolved the same
         * module first. A duplicate resolve under a race costs nothing ? the work is a string match over
         * a configuration already in memory, and {@link FhirContext#forR4Cached()} and its siblings are
         * themselves cached.
         */
        private FhirContext cacheFhirContext(String theModuleId, FhirContext theResolved) {
                FhirContext raced = myFhirContextByModuleId.putIfAbsent(theModuleId, theResolved);
                return raced != null ? raced : theResolved;
        }

        private boolean isInNodeConfigurations(String theModuleId) {
                return moduleIn(myNodeConfigurations, theModuleId).isPresent();
        }

        private String buildUrl(ModuleAddress theAddress, String thePath) {
                return baseUrl(theAddress) + requirePath(thePath);
        }

        /**
         * A module's base URL, such as {@code http://localhost:8000/fhir-request}, with no trailing
         * slash. Every URL this harness builds starts here.
         */
        private String baseUrl(ModuleAddress theAddress) {
                return myContext.getContextRoot() + ":" + resolvePort(theAddress.port()) + theAddress.contextPath();
        }

        private String restClientBaseUrl(ModuleAddress theAddress) {
                return UrlPathUtil.withTrailingSlash(baseUrl(theAddress));
        }

        /**
         * Guards every request builder against being handed a module ID where it wants a path ? the two
         * single-{@code String} request builders take a path, every other single-{@code String} method on
         * {@link SmileHarness} takes a module ID, and {@code fhirRequest("my_endpoint")} would otherwise
         * issue against the default module and report a 404 from a module the caller never named.
         * <p>
         * An empty path is allowed: it addresses the module's base URL, where a transaction bundle is
         * posted.
         */
        private static String requirePath(String thePath) {
                if (!thePath.isEmpty() && !thePath.startsWith("/")) {
                        throw new IllegalArgumentException(
                                "Path must begin with a slash; a module ID belongs in the two-argument overload. [path=%s]"
                                        .formatted(thePath));
                }
                return thePath;
        }

        /**
         * The port a module configured with {@code thePort} is actually published on. Every URL this
         * harness builds goes through here, so that an unresolvable port fails with the port that could
         * not be mapped rather than with a URL containing the literal {@literal null}.
         */
        private int resolvePort(int thePort) {
                Integer resolvedPort = portResolver.apply(thePort);
                if (resolvedPort == null) {
                        throw unmappedPort(String.valueOf(thePort));
                }
                return resolvedPort;
        }

        /**
         * Gets the only persistence module's FhirContext.
         * If More or less than 1 persistence modules are present, throws {@link IllegalStateException}.}
         * <p>
         * See {@link #getFhirContext(String)} if you have multiple persistence modules.
         *
         * @return the {@link FhirContext} of the only persistence module.}
         */
        @Override
        public FhirContext getFhirContext() {
                NodeConfigurations nodeConfigs = getAdminJsonClient().getNodeConfigurations();
                Set<String> persistenceModuleIds = new HashSet<>();

                for (NodeConfigurations.NodeConfiguration node : nodeConfigs.getNodes()) {
                        for (NodeConfigurations.ModuleConfiguration module : node.getModules()) {
                                String moduleType = module.getModuleType();
                                if (moduleType != null && moduleType.startsWith("PERSISTENCE_")) {
                                        persistenceModuleIds.add(module.getModuleId());
                                }
                        }
                }

                if (persistenceModuleIds.size() > 1) {
                        throw new IllegalStateException("Multiple different persistence modules found in the configuration, please specify. " + String.join(", ", persistenceModuleIds));
                } else {
                        return persistenceModuleIds.stream().map(this::getFhirContext).findFirst().orElseThrow(() -> new IllegalStateException("No persistence module found in the configuration."));
                }
        }

        /**
         * Get the FHIR context for a specific persistence/fhir endpoint  module.
         * @param moduleId The ID of the persistence or FHIR endpoint module to get the FHIR context for
         * @return The FHIR context for the specified module
         * @throws IllegalStateException if the module is not found or has an unsupported type
         */
        @Override
        public FhirContext getFhirContext(String moduleId) {
                return resolveFhirContext(getAdminJsonClient().getNodeConfigurations(), moduleId);
        }

        private FhirContext resolveFhirContext(NodeConfigurations theNodeConfigs, String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                NodeConfigurations.ModuleConfiguration module = moduleIn(theNodeConfigs, theModuleId)
                        .orElseThrow(() -> new IllegalArgumentException("No module found. [moduleId=%s]".formatted(theModuleId)));

                return fhirContextOf(theNodeConfigs, module)
                        .orElseThrow(() -> new IllegalArgumentException(
                                "Could not retrieve a FhirContext from the provided module. [moduleId=%s, module_type=%s]"
                                        .formatted(theModuleId, module.getModuleType())));
        }

        /**
         * A module's FHIR version comes from one of two places: a version marker in its own type
         * ({@code ENDPOINT_FHIR_REST_R4}), or ? for the types that carry no version ? whatever the
         * module points at. Empty when the type offers neither.
         */
        private Optional<FhirContext> fhirContextOf(
                        NodeConfigurations theNodeConfigs, NodeConfigurations.ModuleConfiguration theModule) {
                String moduleType = theModule.getModuleType();
                if (moduleType == null) {
                        return Optional.empty();
                }
                return fhirContextFromVersionMarker(moduleType)
                        .or(() -> fhirContextFromDelegatingType(theNodeConfigs, theModule, moduleType));
        }

        private static Optional<FhirContext> fhirContextFromVersionMarker(String theModuleType) {
                return CONTEXT_BY_VERSION_MARKER.stream()
                        .filter(marker -> theModuleType.contains(marker.getKey()))
                        .findFirst()
                        .map(marker -> marker.getValue().get());
        }

        /**
         * The types that name no version of their own: the FHIR endpoint takes its version from the
         * persistence module it depends on, and the other two read it from their configuration.
         */
        private Optional<FhirContext> fhirContextFromDelegatingType(
                        NodeConfigurations theNodeConfigs,
                        NodeConfigurations.ModuleConfiguration theModule,
                        String theModuleType) {
                return switch (theModuleType) {
                        case "ENDPOINT_FHIR_REST" -> persistenceModuleIdOf(theModule)
                                .map(targetModuleId -> resolveFhirContext(theNodeConfigs, targetModuleId));
                        case "ENDPOINT_FHIR_GATEWAY" ->
                                Optional.of(fhirContextForVersion(theModule.getConfigProperty("fhir_version")));
                        case "ENDPOINT_HYBRID_PROVIDERS" ->
                                Optional.of(fhirContextForVersion(theModule.getConfigProperty("definitions.fhir_version")));
                        default -> Optional.empty();
                };
        }

        private static Optional<String> persistenceModuleIdOf(NodeConfigurations.ModuleConfiguration theModule) {
                return theModule.getDependencies().stream()
                        .filter(dependency -> dependency.getDependencyType().startsWith("PERSISTENCE_"))
                        .map(NodeConfigurations.ModuleDependency::getTargetModuleId)
                        .findFirst();
        }

        private static FhirContext fhirContextForVersion(String theFhirVersion) {
                return FhirContext.forCached(FhirVersionEnum.forVersionString(theFhirVersion));
        }

        @Override
        public HL7V2RestClient getHL7V2RestClient() {
                Optional<Map.Entry<String, Integer>> discovered = defaultModule(myEndpointHl7V2PortMap, null);
                if (discovered.isPresent()) {
                        return getHL7V2RestClient(discovered.get().getKey());
                }
                ourLog.warn("No HL7v2 endpoint found in configuration, using default port {}", DEFAULT_HL7V2_PORT);
                return getHL7V2RestClient(DEFAULT_HL7V2_PORT);
        }

        @Override
        public HL7V2RestClient getHL7V2RestClient(int thePort) {
                return hl7V2RestClientAt(addressAt(thePort));
        }

        @Override
        public HL7V2RestClient getHL7V2RestClient(String theModuleId) {
                return hl7V2RestClientAt(addressOf(theModuleId));
        }

        private HL7V2RestClient hl7V2RestClientAt(ModuleAddress theAddress) {
                // The HL7v2 client posts to its base URL itself, so it takes that URL without a trailing slash.
                return HL7V2RestClient.issuingOn(myHttpClient, baseUrl(theAddress), myContext.username(), myContext.password());
        }

        @Override
        public OutboundSmartClient getOutboundSmartClient() {
                return defaultModule(mySmartEndpointPortMap, DEFAULT_SMART_MODULE_ID)
                        .map(module -> getOutboundSmartClient(module.getKey()))
                        .orElseThrow(() -> new IllegalStateException("No SMART endpoint found in the configuration for OutboundSmartClient."));
        }

        @Override
        public OutboundSmartClient getOutboundSmartClient(int thePort) {
                return outboundSmartClientAt(addressAt(thePort));
        }

        @Override
        public OutboundSmartClient getOutboundSmartClient(String theModuleId) {
                return outboundSmartClientAt(addressOf(theModuleId));
        }

        private OutboundSmartClient outboundSmartClientAt(ModuleAddress theAddress) {
                String baseUrl = baseUrl(theAddress);
                RestClient restClient = RestClient.builder()
                        .requestFactory(RequestFactoryUtil.wrap(myHttpClient))
                        .baseUrl(UrlPathUtil.withTrailingSlash(baseUrl))
                        .build();
                return new OutboundSmartClient(restClient, baseUrl);
        }

        @Override
        public NpmPackageClient getNpmPackageClient() {
                // Look for the first available Package Registry module
                Optional<Map.Entry<String, Integer>> discovered = defaultModule(myPackageRegistryPortMap, null);
                if (discovered.isPresent()) {
                        return getNpmPackageClient(discovered.get().getKey());
                } else {
                        // Fall back to default port 8002 if no modules discovered
                        ourLog.warn("No Package Registry endpoint found in configuration, using default port 8002");
                        return getNpmPackageClient(8002);
                }
        }

        @Override
        public NpmPackageClient getNpmPackageClient(int thePort) {
                return npmPackageClientAt(addressAt(thePort));
        }

        @Override
        public NpmPackageClient getNpmPackageClient(String theModuleId) {
                return npmPackageClientAt(addressOf(theModuleId));
        }

        @Override
        public @Nonnull SmartHealthLinkClient getSmartHealthLinkClient(@Nonnull String theModuleId) {
                return SmartHealthLinkClient.issuingOn(
                        myHttpClient, restClientBaseUrl(addressOf(theModuleId)), myContext.username(), myContext.password());
        }

        @Override
        public @Nonnull SmilePortalClient getSmilePortalClient(@Nonnull String theModuleId) {
                return SmilePortalClient.issuingOn(
                        myHttpClient, restClientBaseUrl(addressOf(theModuleId)), myContext.username(), myContext.password());
        }

        private NpmPackageClient npmPackageClientAt(ModuleAddress theAddress) {
                return NpmPackageClient.issuingOn(
                        myHttpClient, restClientBaseUrl(theAddress), myContext.username(), myContext.password());
        }

        @Override
        public @Nonnull CdsHooksClient getCdsHooksClient() {
                return defaultModule(myCdsHooksPortMap, null)
                        .map(module -> getCdsHooksClient(module.getKey()))
                        .orElseThrow(() -> new IllegalStateException("No CDS Hooks endpoint found in the configuration."));
        }

        @Override
        public @Nonnull CdsHooksClient getCdsHooksClient(int thePort) {
                return cdsHooksClientAt(addressAt(thePort));
        }

        @Override
        public @Nonnull CdsHooksClient getCdsHooksClient(@Nonnull String theModuleId) {
                return cdsHooksClientAt(addressOf(theModuleId));
        }

        private CdsHooksClient cdsHooksClientAt(ModuleAddress theAddress) {
                return CdsHooksClient.issuingOn(myHttpClient, baseUrl(theAddress), myContext.username(), myContext.password());
        }
}