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

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.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import ca.uhn.fhir.test.utilities.HttpTestRequest;
import jakarta.annotation.Nonnull;

/**
 * Interface for interacting with a Smile CDR instance during testing. It hands out the clients a
 * test needs, in four kinds:
 * <ul>
 * <li><b>Request builders</b> ? {@link #fhirRequest(String)}, {@link #request(int, String)} and
 *     {@link #adminJsonRequest(String)}. Reach for these first. They resolve the module's port, add
 *     the harness credentials, and hand back the whole exchange, so a test can assert on a status
 *     code, a response header or a redirect. {@link #fhirAnonymousRequest(String)} and
 *     {@link #anonymousRequest(int, String)} are their unauthenticated counterparts.</li>
 * <li><b>FHIR clients</b> ? {@link #getFhirClient()} and {@link #getSuperuserFhirClient()}. Use
 *     these to <em>do</em> FHIR work (read, search, transact) rather than to assert on HTTP.</li>
 * <li><b>Protocol clients</b> ? {@link #getAdminJsonClient()}, {@link #getHL7V2RestClient()},
 *     {@link #getNpmPackageClient()}, {@link #getOutboundSmartClient()} and
 *     {@link #getCdsHooksClient()}. Each wraps one API, so a test does not have to hand-build its
 *     requests.</li>
 * <li><b>The raw HTTP client</b> ? {@link #getHttpClient()}, for a URL this harness cannot build,
 *     such as a service outside the CDR node.</li>
 * </ul>
 * A harness owns a single HTTP client, so the request builders and the protocol clients all share
 * one cookie store and one connection pool. That shared store is what lets a multi-request login
 * flow work across them: a SMART login is visible to a later {@link #fhirRequest(String)}. Cookies
 * are scoped to the host rather than the port, so the session reaches every module.
 * {@link #clearCookies()} ends it; {@link #close()} releases the pool. The FHIR clients are the
 * exception ? they are HAPI {@link IGenericClient}s with their own transport, and none of this
 * applies to them.
 * <p>
 * Every URL a harness builds includes the target module's {@code context_path}, so a module
 * mounted at {@code /fhir-request} is reached there by the request builders and the clients alike;
 * paths passed to the request builders are relative to it.
 * <p>
 * Where a no-argument accessor has several modules of its type to choose from, it takes the one
 * with the conventional ID ({@code fhir_endpoint} for FHIR, {@code smart_auth} for SMART) if there
 * is one, and otherwise the first in the node's configuration.
 * <p>
 * {@link #fhirAnonymousRequest(String)} and {@link #anonymousRequest(int, String)} opt out of the
 * session too: they send no cookies and store none, so a test asserting that an unauthenticated
 * caller is rejected cannot be answered as whoever logged in last.
 */
public interface SmileHarness extends AutoCloseable {
        /**
         * Gets an administrative JSON client for interacting with the CDR's admin API.
         * This will create an {@link AdminJsonRestClient} with the first available ADMIN_JSON module
         * u
         *
         * @return An autodiscovered AdminJsonRestClient.
         */
        AdminJsonRestClient getAdminJsonClient();

        /**
         * Gets an {@link AdminJsonRestClient} for interacting with the CDR's admin API on a specific port.
         *
         * @param thePort The port to connect to
         * @return The admin JSON client configured with the specified port
         */
        AdminJsonRestClient getAdminJsonClient(int thePort);

        /**
         * Gets a FHIR client with superuser privileges.
         * This will create an {@link IGenericClient} with the first available FHIR_ENDPOINT module
         *
         * @return The FHIR client with superuser authentication
         */
        CdrFhirClient getSuperuserFhirClient();

        /**
         * Gets a FHIR client with superuser privileges on a specific port.
         *
         * @param thePort The port to connect to
         * @return The FHIR client with superuser authentication on the specified port
         */
        CdrFhirClient getSuperuserFhirClient(int thePort);

        /**
         * Gets a FHIR client with superuser privileges for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The FHIR client with superuser authentication for the specified module
         */
        CdrFhirClient getSuperuserFhirClient(String theModuleId);

        /**
         * Gets a standard FHIR client.
         *
         * @return The FHIR client with default authentication
         */
        CdrFhirClient getFhirClient();

        /**
         * Gets a standard FHIR client on a specific port.
         *
         * @param thePort The port to connect to
         * @return The FHIR client with default authentication on the specified port
         */
        CdrFhirClient getFhirClient(int thePort);

        /**
         * Gets a standard FHIR client for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The FHIR client with default authentication for the specified module
         */
        CdrFhirClient getFhirClient(String theModuleId);

        /**
         * Gets a FHIR client for a specific module that authenticates with an OAuth 2.0 access token,
         * such as one from {@link OutboundSmartClient#clientCredentials(String, String, String...)},
         * rather than with this harness's credentials.
         *
         * @param theModuleId The ID of the module to connect to
         * @param theBearerToken the access token to send as {@code Authorization: Bearer}
         * @return The FHIR client for the specified module, authenticating with the token
         */
        CdrFhirClient getFhirClient(@Nonnull String theModuleId, @Nonnull String theBearerToken);

        /**
         * Gets the FHIR context used by this harness.
         *
         * @return The FHIR context
         */
        FhirContext getFhirContext();

        /**
         * Gets the FHIR context for a specific module.
         *
         * @param moduleId The ID of the module
         * @return The FHIR context for the specified module
         */
        FhirContext getFhirContext(String moduleId);

        /**
         * Gets an HL7V2 REST client for interacting with the CDR's HL7V2 endpoint.
         *
         * @return The HL7V2 REST client configured with default port
         */
        HL7V2RestClient getHL7V2RestClient();

        /**
         * Gets an HL7V2 REST client for interacting with the CDR's HL7V2 endpoint on a specific port.
         *
         * @param thePort The port to connect to
         * @return The HL7V2 REST client configured with the specified port
         */
        HL7V2RestClient getHL7V2RestClient(int thePort);

        /**
         * Gets an HL7V2 REST client for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The HL7V2 REST client for the specified module
         */
        HL7V2RestClient getHL7V2RestClient(String theModuleId);

        /**
         * Gets an outbound SMART client for OAuth 2.0 authorization flows.
         * This will create an OutboundSmartClient targeting the first available SMART endpoint module.
         *
         * @return The outbound SMART client configured with default endpoint
         */
        OutboundSmartClient getOutboundSmartClient();

        /**
         * Gets an outbound SMART client for OAuth 2.0 authorization flows on a specific port.
         *
         * @param thePort The port to connect to
         * @return The outbound SMART client configured with the specified port
         */
        OutboundSmartClient getOutboundSmartClient(int thePort);

        /**
         * Gets an outbound SMART client for OAuth 2.0 authorization flows for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The outbound SMART client for the specified module
         */
        OutboundSmartClient getOutboundSmartClient(String theModuleId);

        /**
         * Gets an NPM Package client for interacting with the CDR's package registry endpoint.
         * This will create an NpmPackageClient targeting the first available PACKAGE_REGISTRY endpoint module.
         *
         * @return The NPM Package client configured with default endpoint
         */
        NpmPackageClient getNpmPackageClient();

        /**
         * Gets an NPM Package client for interacting with the CDR's package registry endpoint on a specific port.
         *
         * @param thePort The port to connect to
         * @return The NPM Package client configured with the specified port
         */
        NpmPackageClient getNpmPackageClient(int thePort);

        /**
         * Gets an NPM Package client for interacting with the CDR's package registry endpoint for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The NPM Package client for the specified module
         */
        NpmPackageClient getNpmPackageClient(String theModuleId);

        @Nonnull
        SmartHealthLinkClient getSmartHealthLinkClient(@Nonnull String theModuleId);

        @Nonnull
        SmilePortalClient getSmilePortalClient(@Nonnull String theModuleId);

        /**
         * Gets a CDS Hooks client for the default CDS Hooks endpoint module, authenticating with this
         * harness's {@link HarnessContext} credentials. For an unauthenticated client, use
         * {@link CdsHooksClient#openAnonymous(String)}.
         *
         * @return The CDS Hooks client for the first discovered {@code ENDPOINT_CDS_HOOKS} module
         * @throws IllegalStateException if the node has no CDS Hooks endpoint
         */
        @Nonnull
        CdsHooksClient getCdsHooksClient();

        /**
         * Gets a CDS Hooks client for the module configured with a specific port.
         *
         * @param thePort The port the module is configured with
         * @return The CDS Hooks client for that module
         */
        @Nonnull
        CdsHooksClient getCdsHooksClient(int thePort);

        /**
         * Gets a CDS Hooks client for a specific module.
         *
         * @param theModuleId The ID of the module to connect to
         * @return The CDS Hooks client for the specified module
         */
        @Nonnull
        CdsHooksClient getCdsHooksClient(@Nonnull String theModuleId);

        /**
         * Starts building a request against the first discovered FHIR endpoint module, pre-authenticated
         * with this harness's {@link HarnessContext} credentials via HTTP Basic Auth.
         * <p>
         * The single argument here is a <b>path</b>, unlike the single argument to
         * {@link #getFhirClient(String)} and its siblings, which is a module ID. To target a named module
         * use {@link #fhirRequest(String, String)}.
         *
         * @param thePath the path below the FHIR endpoint's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the discovered FHIR endpoint
         * @throws IllegalArgumentException if the path is neither empty nor beginning with a slash ? the
         *    shape a module ID passed here by mistake would have
         */
        @Nonnull
        HttpTestRequest fhirRequest(@Nonnull String thePath);

        /**
         * Starts building a request against a specific FHIR endpoint module, pre-authenticated
         * with this harness's {@link HarnessContext} credentials via HTTP Basic Auth.
         *
         * @param theModuleId The ID of the FHIR endpoint module to target
         * @param thePath the path below the FHIR endpoint's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the specified FHIR endpoint module
         */
        @Nonnull
        HttpTestRequest fhirRequest(@Nonnull String theModuleId, @Nonnull String thePath);

        /**
         * Starts building an unauthenticated request against the first discovered FHIR endpoint module.
         * It carries neither credentials nor cookies, so it cannot be answered as whoever logged in last.
         * Add credentials with {@link HttpTestRequest#withBasicAuth(String, String)} if you need them.
         * <p>
         * The single argument here is a <b>path</b>; to target a named module use
         * {@link #fhirAnonymousRequest(String, String)}.
         *
         * @param thePath the path below the FHIR endpoint's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the discovered FHIR endpoint, with no authentication
         * @throws IllegalArgumentException if the path is neither empty nor beginning with a slash ? the
         *    shape a module ID passed here by mistake would have
         */
        @Nonnull
        HttpTestRequest fhirAnonymousRequest(@Nonnull String thePath);

        /**
         * Starts building an unauthenticated request against a specific FHIR endpoint module. It carries
         * neither credentials nor cookies, so it cannot be answered as whoever logged in last.
         * <p>
         * This is the builder to use when asserting how a <em>different</em> user is treated:
         * {@code fhirAnonymousRequest(moduleId, path).withBasicAuth(user, password)} sends that user's
         * credentials and nothing else. Adding credentials to {@link #fhirRequest(String, String)}
         * instead would leave the shared session cookie on the request alongside them.
         *
         * @param theModuleId The ID of the FHIR endpoint module to target
         * @param thePath the path below the FHIR endpoint's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the specified module, with no authentication
         */
        @Nonnull
        HttpTestRequest fhirAnonymousRequest(@Nonnull String theModuleId, @Nonnull String thePath);

        @Nonnull
        HttpTestRequest serverUrlRequest(@Nonnull String theServerUrl);

        /**
         * Starts building a request against a specific FHIR endpoint module that authenticates with an
         * OAuth 2.0 access token. Like {@link #fhirAnonymousRequest(String, String)}, it carries neither
         * this harness's credentials nor its cookies; it adds {@code Authorization: Bearer} instead.
         *
         * @param theModuleId The ID of the FHIR endpoint module to target
         * @param thePath the path below the FHIR endpoint's base URL, beginning with a slash
         * @param theBearerToken the access token to send
         * @return A {@link HttpTestRequest} builder targeting the specified module
         */
        @Nonnull
        HttpTestRequest fhirBearerRequest(
                        @Nonnull String theModuleId, @Nonnull String thePath, @Nonnull String theBearerToken);

        /**
         * Starts building a request against any port this harness can reach, pre-authenticated with this
         * harness's {@link HarnessContext} credentials via HTTP Basic Auth. Pass the port the module is
         * configured with; the harness maps it to the port the module is published on.
         * <p>
         * This carries no {@link FhirContext} and so cannot encode a FHIR resource body ? use
         * {@link #fhirRequest(String)} for that.
         *
         * @param thePort the port the target module is configured with; a port no module is configured
         *    with is addressed at its root
         * @param thePath the path below that module's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the given port
         */
        @Nonnull
        HttpTestRequest request(int thePort, @Nonnull String thePath);

        /**
         * Starts building a request against a specific module, resolving that module's port from the
         * running node's configuration.
         *
         * @param theModuleId The ID of the module to target
         * @param thePath the path below that module's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the specified module
         * @see #request(int, String)
         */
        @Nonnull
        HttpTestRequest request(@Nonnull String theModuleId, @Nonnull String thePath);

        /**
         * Starts building a request against the Admin JSON API, pre-authenticated with this harness's
         * {@link HarnessContext} credentials via HTTP Basic Auth.
         * <p>
         * A {@link HarnessContext} naming no Admin JSON port falls back to the default one, which is the
         * port this harness already read the node's configuration from. The path is relative to
         * {@link HarnessContext#jsonAdminContextPath()}.
         *
         * @param thePath the path below the Admin JSON base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the Admin JSON API
         */
        @Nonnull
        HttpTestRequest adminJsonRequest(@Nonnull String thePath);

        /**
         * Starts building an unauthenticated request against any port this harness can reach. It carries
         * neither credentials nor cookies, so it cannot be answered as whoever logged in last. Add
         * credentials with {@link HttpTestRequest#withBasicAuth(String, String)} if you need them.
         *
         * @param thePort the port the target module is configured with
         * @param thePath the path below that module's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the given port, with no authentication
         */
        @Nonnull
        HttpTestRequest anonymousRequest(int thePort, @Nonnull String thePath);

        /**
         * Starts building an unauthenticated request against a specific module, resolving that module's
         * port the way {@link #request(String, String)} does. It carries neither credentials nor
         * cookies, so it cannot be answered as whoever logged in last. Add credentials with
         * {@link HttpTestRequest#withBasicAuth(String, String)} to assert how a particular user is
         * treated without the shared session riding along.
         *
         * @param theModuleId The ID of the module to target
         * @param thePath the path below that module's base URL, beginning with a slash
         * @return A {@link HttpTestRequest} builder targeting the specified module, with no authentication
         */
        @Nonnull
        HttpTestRequest anonymousRequest(@Nonnull String theModuleId, @Nonnull String thePath);

        /**
         * Returns this harness's HTTP client as a handle that can issue requests but cannot close it.
         * Use it only for a URL this harness cannot build ? a service outside the CDR node, or a port it
         * did not discover. Prefer {@link #fhirRequest(String)} and {@link #request(String, String)},
         * which resolve the module's port and build the URL for you.
         * <p>
         * {@link ISmileTestHttpClient#request(String)} shares this harness's session and pool;
         * {@link ISmileTestHttpClient#cookielessRequest(String)} shares only the pool.
         *
         * @return a handle whose lifetime is this harness's ? {@link #close()} ends it
         */
        @Nonnull
        ISmileTestHttpClient getHttpClient();

        /**
         * Discards every cookie held by this harness's HTTP client, ending any session established by
         * prior requests. Tests exercising several login flows in sequence need this between flows.
         */
        void clearCookies();

        /**
         * Releases this harness's HTTP client and its connection pool. Declares no checked exception, so
         * callers need not handle one.
         */
        @Override
        void close();
}