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
023import static java.util.Objects.requireNonNull;
024
025/**
026 * Immutable input to a task lookup or cancelation-intent request.
027 *
028 * <p>The request has already passed Soklet's structural validation and
029 * admission pipeline. A task manager must still use the admitted identity,
030 * selected endpoint, and its application-owned task binding to authorize the
031 * operation atomically. Possession of the task ID is not authorization.
032 *
033 * <p>Instances intentionally retain reference identity. The nested request
034 * context represents one independently admitted invocation and may carry
035 * application principal and context objects; structurally equal-looking
036 * carriers must not be treated as the same authorization decision.
037 *
038 * @author <a href="https://www.revetkn.com">Mark Allen</a>
039 */
040@ThreadSafe
041public final class McpTaskRequestContext {
042        @NonNull
043        private final McpRequestContext requestContext;
044        @NonNull
045        private final String taskId;
046
047        /**
048         * Creates a task-request context from its components.
049         *
050         * <p>This factory is useful for exercising application-provided task managers
051         * in isolation; Soklet constructs the authoritative contexts used for live
052         * requests.
053         *
054         * @param requestContext request context to supply to the task manager
055         * @param taskId nonblank task identifier without carriage-return or newline
056         *               characters
057         * @return immutable task-request context
058         * @throws NullPointerException if an argument is null
059         * @throws IllegalArgumentException if the task ID is blank or contains a
060         * carriage-return or newline character
061         */
062        @NonNull
063        public static McpTaskRequestContext fromComponents(
064                        @NonNull McpRequestContext requestContext,
065                        @NonNull String taskId) {
066                return new McpTaskRequestContext(requestContext, taskId);
067        }
068
069        McpTaskRequestContext(@NonNull McpRequestContext requestContext,
070                        @NonNull String taskId) {
071                this.requestContext = requireNonNull(requestContext);
072                this.taskId = McpTask.requireTaskId(taskId);
073        }
074
075        /** @return independently admitted current request */
076        @NonNull
077        public McpRequestContext getRequestContext() {
078                return this.requestContext;
079        }
080
081        /** @return requested durable task identifier */
082        @NonNull
083        public String getTaskId() {
084                return this.taskId;
085        }
086}