001/*-
002 * #%L
003 * Smile CDR - CDR
004 * %%
005 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
006 * %%
007 * All rights reserved.
008 * #L%
009 */
010package ca.cdr.test.app.clients.common;
011
012import ca.uhn.fhir.context.FhirContext;
013import ca.uhn.fhir.test.utilities.HttpTestRequest;
014import jakarta.annotation.Nonnull;
015
016/**
017 * What {@link ca.cdr.test.app.harness.api.SmileHarness#getHttpClient()} hands back: the
018 * request-issuing part of a {@link SmileTestHttpClient}, without its lifecycle.
019 * <p>
020 * This interface is deliberately <b>not</b> {@link AutoCloseable}: the owner keeps
021 * {@link SmileTestHttpClient#close()} and {@link SmileTestHttpClient#getClient()}, so a borrower
022 * cannot shut the pool down on every other client sharing it. That is a guard against a mistake,
023 * not a boundary ? casting back to {@link SmileTestHttpClient} reaches both. It is {@code sealed} to
024 * that one class for the same reason: hiding the lifecycle is the interface's whole job, so a second
025 * implementation would be one whose pool nothing can release.
026 * <p>
027 * A handle is not stateless. Every request issued through {@link #request(String)} shares one cookie
028 * store and one connection pool with everything else on the same client, which is what makes a
029 * multi-request login flow work and what {@link #clearCookies()} ends.
030 * {@link #cookielessRequest(String)} opts out of the cookie store while keeping the pool.
031 */
032// Created by claude-opus-5
033public sealed interface ISmileTestHttpClient permits SmileTestHttpClient {
034
035        /**
036         * Starts building a request against a full URL, issued on this client so that it shares the
037         * cookie store and connection pool with everything else sent through it.
038         *
039         * @param theUrl the full request URL
040         */
041        @Nonnull
042        HttpTestRequest request(@Nonnull String theUrl);
043
044        /**
045         * Starts building a request that can carry a FHIR resource body, encoded with the given context.
046         *
047         * @param theFhirContext the context used to encode resource bodies
048         * @param theUrl the full request URL
049         * @see #request(String)
050         */
051        @Nonnull
052        HttpTestRequest request(@Nonnull FhirContext theFhirContext, @Nonnull String theUrl);
053
054        /**
055         * Starts building a request that neither sends nor stores cookies, while still using this
056         * client's connection pool. Use it to assert what a caller carrying no session gets back: a
057         * request built with {@link #request(String)} would replay whatever session an earlier request
058         * established, and could be answered as that user.
059         *
060         * @param theUrl the full request URL
061         */
062        @Nonnull
063        HttpTestRequest cookielessRequest(@Nonnull String theUrl);
064
065        /**
066         * Starts building a cookie-free request that can carry a FHIR resource body, encoded with the
067         * given context.
068         *
069         * @param theFhirContext the context used to encode resource bodies
070         * @param theUrl the full request URL
071         * @see #cookielessRequest(String)
072         */
073        @Nonnull
074        HttpTestRequest cookielessRequest(@Nonnull FhirContext theFhirContext, @Nonnull String theUrl);
075
076        /**
077         * Discards every cookie held by this client, ending any session established by prior requests.
078         */
079        void clearCookies();
080}