001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.server.mcp.v20260728; 018 019import java.time.*; 020 021import org.apache.juneau.commons.concurrent.*; 022 023/** 024 * Binding-owned MRTR (Multi-Round-Trip Request) configuration for a v2 {@link McpRevision}. 025 * 026 * <p> 027 * Mirrors {@link McpCacheConfig}'s exact placement precedent (spec Open item #2): MRTR is as 028 * {@code 2026-07-28}-only as cache hints, so its configuration lives here, on the v2 adapter, never on the 029 * revision-neutral {@link org.apache.juneau.rest.server.mcp.McpServerConfig}. 030 * 031 * <p> 032 * <b>Mutable during setup, effectively immutable once published.</b> This is a builder-less mutable-setup 033 * bean: its fluent setters exist to configure it during construction, but a binding must fully configure it 034 * <i>before</i> handing it to a {@link McpRevision} and must never mutate it afterward. The dispatcher reads 035 * the codec/TTL/max-rounds on every request with no synchronization, so a post-publication mutation is a data 036 * race; treat a published instance as read-only. 037 * 038 * <p> 039 * Defaults: {@link AeadRequestStateCodec} (a fresh instance per {@link McpMrtrConfig}), a 5-minute 040 * {@code requestState} TTL, a max-rounds cap of 10, a per-process {@link InMemoryReplayCache} (single-use tokens; see 041 * {@link #setReplayCache(ReplayCache)}), and a {@link Clock#systemUTC()} clock for stamping and checking token 042 * expiry (see {@link #setClock(Clock)}). Operators inject a shared/rotating-key {@link RequestStateCodec} here 043 * for multi-instance or restart-durable resumption. 044 * 045 * <h2 class='section'>Trust model:</h2> 046 * <ul> 047 * <li><b>{@code requestState} is a bearer token for its principal.</b> Anyone holding a sealed {@code requestState} 048 * and authenticated as the same principal can resume the paused operation until it expires. It must be 049 * transported only over authenticated TLS and <b>never logged</b> (it is opaque ciphertext, but logging 050 * it hands a replayable credential to anyone with log access). See {@link RequestStateCodec}. 051 * <li><b>Single-use by default.</b> The default {@link InMemoryReplayCache} rejects a second submission of the same 052 * token within its {@link #getTtlMs() TTL}; it is per-process only, so cross-node single-use requires a shared 053 * {@link ReplayCache} (see {@link #setReplayCache(ReplayCache)}). Passing <jk>null</jk> disables the check, and 054 * a handler must then write idempotent resume side effects. 055 * </ul> 056 */ 057public class McpMrtrConfig { 058 059 /** Default {@code requestState} TTL in milliseconds: 5 minutes. */ 060 public static final long DEFAULT_TTL_MS = 5 * 60 * 1000L; 061 062 /** Default max-rounds cap. */ 063 public static final int DEFAULT_MAX_ROUNDS = 10; 064 065 private RequestStateCodec codec = new AeadRequestStateCodec(); 066 private long ttlMs = DEFAULT_TTL_MS; 067 private int maxRounds = DEFAULT_MAX_ROUNDS; 068 private ReplayCache replayCache = new InMemoryReplayCache(); 069 private Clock clock = Clock.systemUTC(); 070 071 /** 072 * The codec used to seal/unseal {@code requestState} tokens. 073 * 074 * @return The codec. Never {@code null}. 075 */ 076 public RequestStateCodec getCodec() { 077 return codec; 078 } 079 080 /** 081 * Sets the codec. 082 * 083 * @param value The new value. Must not be {@code null}. 084 * @return This object. 085 * @throws IllegalArgumentException If {@code value} is {@code null}. 086 */ 087 public McpMrtrConfig setCodec(RequestStateCodec value) { 088 if (value == null) 089 throw new IllegalArgumentException("codec must not be null"); 090 codec = value; 091 return this; 092 } 093 094 /** 095 * Sets the key provider, wrapping it in a fresh {@link AeadRequestStateCodec}. 096 * 097 * <p> 098 * Sugar for the common "keep AES-GCM, just supply my keys" case — equivalent to 099 * {@code setCodec(new AeadRequestStateCodec(value))}. {@link #setKeyProvider} and {@link #setCodec} are 100 * last-wins: both assign the same {@code codec} field, so whichever is called more recently determines the 101 * effective codec. There is no getter for the provider itself — {@link #getCodec()} remains the sole 102 * accessor, since the codec (not the provider) is the source of truth once either setter has been called. 103 * 104 * @param value The new value. Must not be {@code null}. 105 * @return This object. 106 * @throws IllegalArgumentException If {@code value} is {@code null}. 107 */ 108 public McpMrtrConfig setKeyProvider(KeyProvider value) { 109 if (value == null) 110 throw new IllegalArgumentException("keyProvider must not be null"); 111 return setCodec(new AeadRequestStateCodec(value)); 112 } 113 114 /** 115 * The {@code requestState} time-to-live in milliseconds. 116 * 117 * @return The TTL. Always {@code > 0}. 118 */ 119 public long getTtlMs() { 120 return ttlMs; 121 } 122 123 /** 124 * Sets the TTL. 125 * 126 * @param value The new value. Must be {@code > 0}. 127 * @return This object. 128 * @throws IllegalArgumentException If {@code value} is not {@code > 0}. 129 */ 130 public McpMrtrConfig setTtlMs(long value) { 131 if (value <= 0) 132 throw new IllegalArgumentException("ttlMs " + value + " must be > 0"); 133 ttlMs = value; 134 return this; 135 } 136 137 /** 138 * The max-rounds cap. 139 * 140 * <p> 141 * Counts total handler invocations in a single resume chain, not just the resumes: the default of 10 permits 142 * 1 initial call plus 9 resumes before {@link McpRevision#CODE_MAX_ROUNDS_EXCEEDED} is returned. 143 * 144 * @return The cap. Always {@code >= 1}. 145 */ 146 public int getMaxRounds() { 147 return maxRounds; 148 } 149 150 /** 151 * Sets the max-rounds cap. 152 * 153 * @param value The new value. Must be {@code >= 1}. 154 * @return This object. 155 * @throws IllegalArgumentException If {@code value} is not {@code >= 1}. 156 */ 157 public McpMrtrConfig setMaxRounds(int value) { 158 if (value < 1) 159 throw new IllegalArgumentException("maxRounds " + value + " must be >= 1"); 160 maxRounds = value; 161 return this; 162 } 163 164 /** 165 * The {@link ReplayCache} used to reject reuse of a consumed {@code requestState} token, or <jk>null</jk> if 166 * none is configured. 167 * 168 * <p> 169 * <b>A per-process {@link InMemoryReplayCache} by default</b>, so a {@code requestState} token is single-use. 170 * A dispatcher only performs a replay check when this returns non-<jk>null</jk> (see 171 * {@code McpRevision#resolveMrtrContext}); a deployment that runs several nodes should supply a shared 172 * implementation. 173 * 174 * @return The configured replay cache, or <jk>null</jk> if replay rejection was explicitly disabled. 175 */ 176 public ReplayCache getReplayCache() { 177 return replayCache; 178 } 179 180 /** 181 * Sets the replay cache, enabling replay rejection. 182 * 183 * <p> 184 * Passing <jk>null</jk> is allowed and explicitly disables replay rejection (a token then stays multi-use 185 * within its TTL) — unlike {@link #setCodec(RequestStateCodec)}, there is no always-non-null invariant to 186 * preserve here. 187 * 188 * @param value The replay cache to use, or <jk>null</jk> to disable replay rejection. 189 * @return This object. 190 */ 191 public McpMrtrConfig setReplayCache(ReplayCache value) { 192 replayCache = value; 193 return this; 194 } 195 196 /** 197 * The clock used to stamp a new {@code requestState}'s expiry and to check an echoed one against it. 198 * 199 * @return The clock. Never {@code null}. 200 */ 201 public Clock getClock() { 202 return clock; 203 } 204 205 /** 206 * Sets the clock. 207 * 208 * <p> 209 * Defaults to {@link Clock#systemUTC()}. Tests can supply a {@link Clock#fixed(Instant, ZoneId) fixed} or 210 * manually-advanced clock to drive {@code requestState} expiry deterministically instead of sleeping past the 211 * {@link #getTtlMs() TTL}. 212 * 213 * @param value The new value. Must not be {@code null}. 214 * @return This object. 215 * @throws IllegalArgumentException If {@code value} is {@code null}. 216 */ 217 public McpMrtrConfig setClock(Clock value) { 218 if (value == null) 219 throw new IllegalArgumentException("clock must not be null"); 220 clock = value; 221 return this; 222 } 223}