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 &mdash; 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 &mdash; {@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) &mdash; 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}