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;
022import java.util.List;
023import java.util.Locale;
024import java.util.Optional;
025
026/**
027 * Immutable, bounded inputs supplied when creating one localization context
028 * for an admitted MCP operation.
029 * <p>
030 * The effective language ranges initially derive from HTTP
031 * {@code Accept-Language}. This value intentionally does not define or reserve
032 * an MCP localization extension. Separate {@code resources/list} and
033 * {@code skills/list} cursor accessors expose the same opaque application cursor
034 * that the corresponding list handler receives, so locale selection can
035 * authenticate application-owned pagination state before context creation.
036 *
037 * @author <a href="https://www.revetkn.com">Mark Allen</a>
038 */
039@ThreadSafe
040public interface McpLocalizationRequest {
041        /**
042         * Returns the admitted semantic MCP request context. Subscription projections
043         * supply a derived request without headers, body, trace identifiers or baggage.
044         * Its current admitted identity and application context remain available;
045         * the authorizer separately receives the original initial request context.
046         *
047         * @return the admitted semantic MCP request context
048         */
049        @NonNull
050        McpRequestContext getRequestContext();
051
052        /**
053         * Returns bounded effective client language preferences. The list contains
054         * at most 32 ranges after JDK alias expansion, preserves zero-weight
055         * exclusions, and is empty for missing, malformed, or over-limit HTTP input.
056         * Applications should use this view instead of reparsing the raw header.
057         *
058         * @return immutable language-range list, possibly empty
059         */
060        @NonNull
061        List<Locale.@NonNull LanguageRange> getLanguageRanges();
062
063        /**
064         * Returns the verified locale carried by framework-protected continuation
065         * state. A present value is a required selection rather than a hint.
066         *
067         * @return required continuation locale, or empty for an independent request
068         */
069        @NonNull
070        Optional<@NonNull Locale> getContinuationLocale();
071
072        /**
073         * Returns the opaque application-owned cursor for a custom
074         * {@code resources/list} operation. A present empty string is preserved.
075         * This is empty for every other operation. Soklet does not decode, rewrite,
076         * sign, bind, or otherwise interpret the value.
077         *
078         * @return custom resource-list cursor, or empty
079         */
080        @NonNull
081        Optional<@NonNull String> getResourceListCursor();
082
083        /**
084         * Returns the opaque application-owned cursor for a {@code skills/list}
085         * operation before localization context creation. A present empty string is
086         * preserved as a continuation value. This is empty for every other operation;
087         * the resource-list cursor accessor is not reused for Skills pagination.
088         *
089         * <p>The application owns cursor integrity, endpoint/caller and content
090         * binding, expiry, and retained snapshot availability across nodes. Soklet
091         * does not decode, rewrite, sign, authenticate, or retain the snapshot.
092         *
093         * @return Skills-list cursor, or empty
094         */
095        @NonNull
096        Optional<@NonNull String> getSkillListCursor();
097
098        /**
099         * Returns the configured locale of every canonical default text hosted by
100         * this server. This default-text fallback is independent of any terminal
101         * fallback configured in the provider's localization library.
102         *
103         * @return configured canonical fallback locale
104         */
105        @NonNull
106        Locale getFallbackLocale();
107}