001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.NotThreadSafe;
022
023/**
024 * One-shot continuation supplied to an {@link McpHandlerInterceptor}.
025 * <p>
026 * The continuation is synchronous and bound to the thread invoking the
027 * interceptor. It must be invoked, if at all, before the interceptor returns
028 * and must not be retained or passed to another thread. The first invocation
029 * enters the remaining validation and handler chain. A second or later
030 * invocation fails synchronously without re-entering downstream code.
031 * <p>
032 * If the downstream handler throws an {@link McpJsonRpcException},
033 * {@link #proceed()} throws that same exception instance. The interceptor may
034 * inspect it and rethrow it unchanged to preserve its intentional client-visible
035 * error, or recover by returning a method-compatible result that traverses
036 * normal result validation. A new exception, including one carrying the same
037 * {@link McpJsonRpcError}, a wrapper, or an exception from a previous invocation
038 * fails closed as an unexpected interception failure.
039 *
040 * @author <a href="https://www.revetkn.com">Mark Allen</a>
041 */
042@NotThreadSafe
043@FunctionalInterface
044public interface McpHandlerContinuation {
045        /**
046         * Invokes the next stage exactly once.
047         *
048         * @return recognized, non-null, method-compatible handler result
049         * @throws IllegalStateException if this continuation was already invoked,
050         *                               retained beyond its interceptor call, or
051         *                               invoked from another thread
052         * @throws McpJsonRpcException the exact intentional error exception thrown
053         *                             by the downstream handler
054         * @throws Exception if downstream validation or application handling fails
055         */
056        @NonNull
057        McpOperationResult proceed() throws Exception;
058}