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.ThreadSafe;
022
023/**
024 * Thread-safe application provider of request-local MCP localization contexts.
025 * <p>
026 * Soklet may call one provider concurrently for independent admitted requests.
027 * The provider is application-owned and is never closed by Soklet. Context
028 * creation runs under the operation's existing bounded execution owner:
029 * application operations consume their acquired handler slot, while framework
030 * catalogs and subscriptions consume bounded protocol ownership. Creation
031 * therefore must use already-loaded, in-memory state rather than remote
032 * translation lookup.
033 * <p>
034 * Soklet exposes the exact returned context to application handlers and
035 * interceptors. Soklet's no-leak guarantee applies when Soklet invokes this
036 * callback. Direct application invocation remains application-owned and has
037 * normal application failure semantics.
038 *
039 * @author <a href="https://www.revetkn.com">Mark Allen</a>
040 */
041@ThreadSafe
042@FunctionalInterface
043public interface McpLocalizationContextProvider {
044        /**
045         * Provides the immutable localization context for one admitted
046         * localization-capable operation.
047         *
048         * @param localizationRequest bounded localization inputs and admitted request context
049         * @return non-null request-local context
050         * @throws Exception if context creation fails; when Soklet invokes this
051         * callback it treats the exception as untrusted localization data and never
052         * forwards it through framework-owned lifecycle, simulation, logging,
053         * response-throwable, or cause surfaces
054         */
055        @NonNull
056        McpLocalizationContext provideContext(
057                        @NonNull McpLocalizationRequest localizationRequest) throws Exception;
058}