/*
 * Copyright 2022-2026 Revetware LLC.
 *
 * Licensed 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 com.soklet;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import java.util.function.Consumer;

import static java.lang.String.format;

/**
 * Simulates server behavior of accepting a request and returning a response without touching the network, useful for writing integration tests.
 * <p>
 * <a href="https://www.soklet.com/docs/server-sent-events">Server-Sent Event</a> simulation is also supported.
 * <p>
 * Instances of {@link Simulator} are made available via {@link com.soklet.Soklet#runSimulator(SokletConfig, Consumer)}.
 * <p>
 * Usage example:
 * <pre>{@code @Test
 * public void basicIntegrationTest () {
 *   // Just use your app's existing configuration
 *   SokletConfig config = obtainMySokletConfig();
 *
 *   // With the Simulator, you can issue requests
 *   // and receive responses just like you would with real servers.
 *   Soklet.runSimulator(config, (simulator) -> {
 *     // Construct a request
 *     Request request = Request.withPath(HttpMethod.GET, "/hello")
 *       .queryParameters(Map.of("name", Set.of("Mark")))
 *       .build();
 *
 *     // Perform the request and get a handle to the result
 *     HttpRequestResult result = simulator.performHttpRequest(request);
 *
 *     // Verify status code
 *     Integer expectedCode = 200;
 *     Integer actualCode = result.getMarshaledResponse().getStatusCode();
 *     assertEquals(expectedCode, actualCode, "Bad status code");
 *
 *     // Now, create a request for an SSE Event Source...
 *     Request eventSourceRequest = Request.withPath(HttpMethod.GET, "/sse-test")
 *         .queryParameters(Map.of("signingToken", Set.of("xxx")))
 *         .build();
 *
 *     // ...and perform it and get a handle to the result.
 *     SseRequestResult eventSourceResult =
 *       simulator.performSseRequest(eventSourceRequest);
 *
 *     // Single-shot latch; we'll wait until a Server-Sent Event comes through
 *     CountDownLatch eventReceivedLatch = new CountDownLatch(1);
 *
 *     // The Simulator provides 3 logical outcomes for SSE connections:
 *     // * Accepted Handshake (connection stays open)
 *     // * Rejected Handshake (explicit rejection, connection closed)
 *     // * Request Failed (implicit rejection, e.g. uncaught exception, connection closed)
 *     switch (eventSourceResult) {
 *       // Explicit handshake acceptance
 *       case HandshakeAccepted handshakeAccepted -> {
 *         handshakeAccepted.registerEventConsumer((event) -> {
 *           // Server-Sent Event received: open the latch to end the test
 *           eventReceivedLatch.countDown();
 *         });
 *
 *         // On a separate thread, broadcast a Server-Sent Event
 *         new Thread(() -> {
 *           // ... not shown
 *         }).start();
 *       }
 *
 *       // Explicit handshake rejection
 *       case HandshakeRejected handshakeRejected ->
 *         Assertions.fail("SSE Handshake Rejected: " + handshakeRejected);
 *
 *       // Uncaught exception
 *       case RequestFailed requestFailed ->
 *         Assertions.fail("SSE Request Failed: " + requestFailed);
 *     }
 *
 *     // Finally, wait a bit for the latch to open
 *     try {
 *       eventReceivedLatch.await(5, SECONDS);
 *     } catch (InterruptedException e) {
 *       Assertions.fail("Didn't receive a Server-Sent Event in time");
 *     }
 *   });
 * }}</pre>
 * <p>
 * Full documentation is available at <a href="https://www.soklet.com/docs/testing">https://www.soklet.com/docs/testing</a>.
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 */
public interface Simulator {
        /**
         * Given a request that would normally be handled by your standard {@link HttpServer}, process it and return response data (both logical {@link Response}, if present, and the {@link MarshaledResponse} bytes to be sent over the wire) as well as the matching <em>Resource Method</em>, if available.
         * <p>
         * To make requests that would normally be handled by your {@link SseServer}, use {@link #performSseRequest(Request)}.
         *
         * @param request the standard HTTP request to process
         * @return the result (logical response, marshaled response, etc.) that corresponds to the request
         */
        @NonNull
        HttpRequestResult performHttpRequest(@NonNull Request request);

        /**
         * Given a request that would normally be handled by your {@link SseServer} (that is, for a <em>Resource Method</em> decorated with the {@link com.soklet.annotation.SseEventSource} annotation), process it and return response data ({@link com.soklet.SseRequestResult.HandshakeAccepted}, {@link com.soklet.SseRequestResult.HandshakeRejected}, or {@link com.soklet.SseRequestResult.RequestFailed});
         * <p>
         * To make requests that would normally be handled by your {@link HttpServer}, use {@link #performHttpRequest(Request)}.
         *
         * @param request the Server-Sent Event HTTP request to process
         * @return the result (handshake outcode, etc.) that corresponds to the request
         */
        @NonNull
        SseRequestResult performSseRequest(@NonNull Request request);

        /**
         * Given a request that would normally be handled by your MCP server, process it and return the corresponding MCP-oriented simulator result.
         * <p>
         * The default implementation fails fast until MCP simulator support is wired in.
         *
         * @param request the MCP HTTP request to process
         * @return the MCP simulator result
         */
        @NonNull
        default McpRequestResult performMcpRequest(@NonNull Request request) {
                throw new IllegalStateException(format("You must specify an MCP server in your %s to simulate MCP requests",
                                SokletConfig.class.getSimpleName()));
        }

        /**
         * Registers a handler for exceptions thrown by simulated Server-Sent Event consumers.
         * <p>
         * This only applies to simulator-mode SSE broadcasts.
         *
         * @param onBroadcastError handler for broadcast errors, or {@code null} to clear
         * @return this simulator
         */
        @NonNull
        default Simulator onBroadcastError(@Nullable Consumer<Throwable> onBroadcastError) {
                return this;
        }

        /**
         * Registers a handler for exceptions thrown by simulated Server-Sent Event unicast consumers.
         * <p>
         * This only applies to simulator-mode SSE unicast deliveries (including client initializers).
         *
         * @param onUnicastError handler for unicast errors, or {@code null} to clear
         * @return this simulator
         */
        @NonNull
        default Simulator onUnicastError(@Nullable Consumer<Throwable> onUnicastError) {
                return this;
        }

        /**
         * Registers a handler for exceptions thrown by simulated MCP stream consumers.
         *
         * @param onMcpStreamError handler for MCP stream consumer errors, or {@code null} to clear
         * @return this simulator
         */
        @NonNull
        default Simulator onMcpStreamError(@Nullable Consumer<Throwable> onMcpStreamError) {
                return this;
        }
}