You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2026/05/25 18:51:40 UTC
(juneau) branch master updated: feat(commons,rest,springboot): @Value + ${} shortcut + Spring env bridge
This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new d23adf50b4 feat(commons,rest,springboot): @Value + ${} shortcut + Spring env bridge
d23adf50b4 is described below
commit d23adf50b43bdc740935a1fb3e3e872a66fe2cee
Author: James Bognar <ja...@jamesbog-ltmjqf2.internal.salesforce.com>
AuthorDate: Mon May 25 14:51:33 2026 -0400
feat(commons,rest,springboot): @Value + ${} shortcut + Spring env bridge
Lands TODO-79: new @Value annotation (org.apache.juneau.commons.inject) and
${...} SVL shortcut for declarative config injection on BeanInstantiator-built
beans, a classpath juneau.cfg -> Settings bridge via ConfigPropertySourceProvider
SPI, a Spring Boot Environment -> Settings bridge (SpringEnvironmentPropertySource
auto-wired by SpringBeanStore), and FQN-based interop with Spring's @Value.
Also drops the per-RestContext Settings.get().addSource(...) bridge in
RestContext.build() whose teardown never fired (MockRestClient caches RestContext
statically) and caused a 6.7x test-suite slowdown post-TODO-79; full suite is
back to ~84s wall-clock with all 124,928 tests green. Re-introduction via a
BeanStore-routed lookup is tracked as TODO-95.
Adds TODO-94a/b/c plan files (auth filter framework + SAML + OAuth modules,
planning only), TODO-92 framework-internal @Value adoption plan, the new
todo/FINISHED.md completion-log workflow plus matching .cursor/commands/todo.md
and AGENTS.md updates, the FINISHED-79 phase-6 discovery report, and
TODO-82/83/84/86 roadmap admin tweaks.
---
.../org/apache/juneau/commons/bean/BeanMeta.java | 2 +-
.../apache/juneau/commons/inject/JsrSupport.java | 38 ++
.../org/apache/juneau/commons/inject/Value.java | 90 ++++
.../juneau/commons/inject/ValueResolver.java | 182 ++++++++
.../apache/juneau/commons/reflect/ClassInfo.java | 12 +-
.../apache/juneau/commons/reflect/FieldInfo.java | 21 +-
.../juneau/commons/reflect/ParameterInfo.java | 17 +-
.../apache/juneau/commons/settings/Settings.java | 31 +-
.../juneau/commons/svl/VarResolverSession.java | 66 +++
.../config/ConfigPropertySourceProvider.java | 187 ++++++++
....juneau.commons.settings.PropertySourceProvider | 1 +
.../apache/juneau/microservice/Microservice.java | 6 +
.../juneau/rest/springboot/SpringBeanStore.java | 25 ++
.../SpringEnvironmentPropertySource.java | 122 ++++++
.../java/org/apache/juneau/rest/RestContext.java | 5 +
.../java/org/apache/juneau/rest/RestOpContext.java | 2 +-
.../apache/juneau/commons/inject/Value_Test.java | 487 +++++++++++++++++++++
.../juneau/commons/reflect/ClassInfo_Test.java | 1 +
.../commons/svl/DollarBraceShortcut_Test.java | 189 ++++++++
.../config/ConfigPropertySourceProvider_Test.java | 177 ++++++++
.../java/org/apache/juneau/rest/Swagger_Test.java | 1 +
.../rest/springboot/SpringBeanStore_Test.java | 7 +
...tPropertySource_SpringbootIntegration_Test.java | 136 ++++++
.../SpringEnvironmentPropertySource_Test.java | 237 ++++++++++
.../juneau/utils/StringVarResolver_Test.java | 6 +-
todo/FINISHED-79-phase6-discovery-report.md | 130 ++++++
todo/FINISHED.md | 95 ++++
todo/TODO-79-value-annotation-config-bridge.md | 47 +-
todo/TODO-82-view-module-thymeleaf.md | 8 +-
todo/TODO-83-view-module-mustache.md | 8 +-
todo/TODO-84-view-module-freemarker.md | 8 +-
todo/TODO-86-petstore-jetty-app.md | 84 +++-
todo/TODO-92-value-framework-internal-adoption.md | 64 +++
todo/TODO-94a-auth-filter-framework.md | 360 +++++++++++++++
todo/TODO-94b-saml-module.md | 304 +++++++++++++
todo/TODO-94c-oauth-module.md | 391 +++++++++++++++++
todo/TODO.md | 87 ++--
37 files changed, 3555 insertions(+), 79 deletions(-)
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanMeta.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanMeta.java
index 2cfd362e44..5765c0772b 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanMeta.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanMeta.java
@@ -33,7 +33,7 @@ import java.util.function.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.function.*;
-import org.apache.juneau.commons.lang.*;
+import org.apache.juneau.commons.lang.Value;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.reflect.Visibility;
import org.apache.juneau.commons.utils.*;
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/JsrSupport.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/JsrSupport.java
index 2a29d90ef6..af5552fabd 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/JsrSupport.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/JsrSupport.java
@@ -65,6 +65,11 @@ public final class JsrSupport {
public static final String JAKARTA_PREDESTROY = "jakarta.annotation.PreDestroy";
public static final String JAVAX_PREDESTROY = "javax.annotation.PreDestroy";
+ // Config-value injection (Juneau + Spring). Detected by FQN so juneau-commons stays free of a
+ // compile-time Spring dependency, mirroring the SPRING_AUTOWIRED trick above.
+ public static final String JUNEAU_VALUE = "org.apache.juneau.commons.inject.Value";
+ public static final String SPRING_VALUE = "org.springframework.beans.factory.annotation.Value";
+
private JsrSupport() {}
/**
@@ -137,4 +142,37 @@ public final class JsrSupport {
return annotation.getValue().orElse(null);
return null;
}
+
+ /**
+ * Returns <jk>true</jk> if the annotation is a config-value marker.
+ *
+ * <p>
+ * Recognizes both Juneau's {@code @Value} and Spring's
+ * {@code org.springframework.beans.factory.annotation.Value} by FQN — no compile-time Spring
+ * dependency in {@code juneau-commons}.
+ *
+ * @param annotation The annotation to inspect.
+ * @return <jk>true</jk> if {@code annotation} is one of the recognized {@code @Value} variants.
+ */
+ public static boolean isValueAnnotation(AnnotationInfo<?> annotation) {
+ var name = annotation.getName();
+ return eqAny(name, JUNEAU_VALUE, SPRING_VALUE);
+ }
+
+ /**
+ * Returns the configuration expression carried by a {@code @Value} annotation, or {@code null}
+ * if the annotation is not a recognized {@code @Value}.
+ *
+ * <p>
+ * Both Juneau's {@code @Value} and Spring's {@code @Value} expose a single {@code String value()}
+ * attribute, so a uniform {@code getValue()} lookup against the annotation works for either.
+ *
+ * @param annotation The annotation to inspect.
+ * @return The {@code value()} string, or {@code null} if {@code annotation} is not a {@code @Value}.
+ */
+ public static String valueExpression(AnnotationInfo<?> annotation) {
+ if (! isValueAnnotation(annotation))
+ return null;
+ return annotation.getValue().orElse(null);
+ }
}
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/Value.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/Value.java
new file mode 100644
index 0000000000..999f187a50
--- /dev/null
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/Value.java
@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.commons.inject;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Resolves a configuration value into a constructor parameter, setter, or field.
+ *
+ * <p>
+ * The {@code value()} string is passed through Juneau's {@code VarResolver} (so
+ * {@code ${...}} / {@code $P{...}} placeholders are expanded against
+ * {@link org.apache.juneau.commons.settings.Settings#get() Settings.get()}), then coerced to the
+ * target Java type via {@link org.apache.juneau.commons.settings.Settings#toType(String, Class)}.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bjava'>
+ * <jc>// Field injection with default.</jc>
+ * <ja>@Value</ja>(<js>"${db.timeout.ms:5000}"</js>)
+ * <jk>private int</jk> <jv>timeoutMs</jv>;
+ *
+ * <jc>// Constructor-parameter injection.</jc>
+ * <ja>@Inject</ja>
+ * <jk>public</jk> OrdersResource(
+ * <ja>@Value</ja>(<js>"${app.name:orders}"</js>) String <jv>appName</jv>,
+ * <ja>@Value</ja>(<js>"${app.start}"</js>) Instant <jv>start</jv>
+ * ) { ... }
+ * </p>
+ *
+ * <h5 class='section'>Resolution order:</h5>
+ * <ol>
+ * <li>Thread-local override ({@link org.apache.juneau.commons.settings.Settings#setLocal Settings.setLocal})
+ * <li>Global override ({@link org.apache.juneau.commons.settings.Settings#setGlobal Settings.setGlobal})
+ * <li>Property sources in reverse insertion order — this is where Juneau {@code Config},
+ * Spring {@code Environment}, and any other registered {@code PropertySource} participate.
+ * <li>System properties
+ * <li>System environment variables
+ * </ol>
+ *
+ * <p>
+ * Spring's {@code org.springframework.beans.factory.annotation.Value} annotation is honored identically
+ * via FQN-based detection in {@link JsrSupport}; no compile-time Spring dependency is introduced in
+ * {@code juneau-commons}.
+ *
+ * <h5 class='section'>Notes:</h5><ul>
+ * <li class='note'>{@code @Value} and {@code @Inject} on the same site is invalid and throws
+ * a {@code BeanCreationException}. {@code @Value} resolves strings/primitives; {@code @Inject}
+ * resolves beans.
+ * <li class='note'>If the expression resolves to {@code null} and the target type is a primitive,
+ * a {@code BeanCreationException} is thrown. For reference types, {@code null} is injected.
+ * </ul>
+ *
+ * <h5 class='section'>See Also:</h5><ul>
+ * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ValueAnnotationBasics">@Value Annotation Basics</a>
+ * </ul>
+ */
+@Documented
+@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER})
+@Retention(RUNTIME)
+public @interface Value {
+
+ /**
+ * The configuration expression.
+ *
+ * <p>
+ * Typically uses the {@code ${key}} or {@code ${key:default}} placeholder syntax that is routed
+ * through {@code VarResolver} and {@link org.apache.juneau.commons.settings.Settings Settings}.
+ * Plain literals (no {@code $}) are passed through unchanged and still type-coerced.
+ *
+ * @return The configuration expression.
+ */
+ String value();
+}
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/ValueResolver.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/ValueResolver.java
new file mode 100644
index 0000000000..c9cff6850d
--- /dev/null
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/inject/ValueResolver.java
@@ -0,0 +1,182 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.commons.inject;
+
+import java.util.*;
+
+import org.apache.juneau.commons.reflect.*;
+import org.apache.juneau.commons.settings.*;
+import org.apache.juneau.commons.svl.*;
+
+/**
+ * Internal helper used by the reflection layer to resolve {@code @Value}-annotated injection sites.
+ *
+ * <p>
+ * Splits the {@code @Value} handling into three small pieces so callers (field / parameter / method)
+ * can share the same coercion + error-formatting code without duplicating the lookup logic:
+ *
+ * <ol>
+ * <li>{@link #findValueExpression(List)} — given an annotation list, return the first {@code @Value}
+ * expression (or {@code null} if no {@code @Value} is present).
+ * <li>{@link #checkInjectConflict(List, String)} — throw {@link BeanCreationException} if both
+ * {@code @Value} and {@code @Inject}/{@code @Autowired} are present on the same site.
+ * <li>{@link #resolve(String, Class, String)} — pass the expression through {@code VarResolver},
+ * coerce to the target type via {@link Settings#toType(String, Class)}, and wrap failures in
+ * {@link BeanCreationException}.
+ * </ol>
+ *
+ * <p>
+ * The resolver intentionally uses {@link VarResolver#DEFAULT}, which already includes
+ * {@code PropertyVar} (the {@code $P{key[,default]}} variable that reads from {@link Settings}).
+ * With Phase 2 of TODO-79 landed, the {@code ${key}} shortcut routes through that same {@code PropertyVar},
+ * so {@code @Value("${db.url}")} and {@code @Value("$P{db.url}")} are equivalent.
+ */
+public final class ValueResolver {
+
+ private ValueResolver() {}
+
+ /**
+ * Returns the {@code value()} expression carried by the first {@code @Value} annotation in the list,
+ * or {@code null} if no {@code @Value} (Juneau or Spring) is present.
+ *
+ * @param annotations The annotation list (from {@link FieldInfo#getAnnotations()},
+ * {@link ParameterInfo#getAnnotations()}, etc.).
+ * @return The expression, or {@code null} if not a {@code @Value} site.
+ */
+ public static String findValueExpression(List<? extends AnnotationInfo<?>> annotations) {
+ if (annotations == null || annotations.isEmpty())
+ return null;
+ return annotations.stream()
+ .map(JsrSupport::valueExpression)
+ .filter(Objects::nonNull)
+ .findFirst()
+ .orElse(null);
+ }
+
+ /**
+ * Returns {@code true} if any annotation in the list is a {@code @Value} marker.
+ *
+ * @param annotations The annotation list.
+ * @return {@code true} if at least one annotation matches {@link JsrSupport#isValueAnnotation(AnnotationInfo)}.
+ */
+ public static boolean hasValueAnnotation(List<? extends AnnotationInfo<?>> annotations) {
+ if (annotations == null || annotations.isEmpty())
+ return false;
+ return annotations.stream().anyMatch(JsrSupport::isValueAnnotation);
+ }
+
+ /**
+ * Throws {@link BeanCreationException} if an injection site carries both {@code @Value} and an
+ * {@code @Inject}/{@code @Autowired} marker.
+ *
+ * <p>
+ * {@code @Value} resolves strings/primitives; {@code @Inject} resolves beans. Combining them on
+ * the same site is ambiguous — fail fast with a clear message.
+ *
+ * @param annotations The annotation list.
+ * @param siteDescription A human-readable description of the site (used in the error message).
+ */
+ public static void checkInjectConflict(List<? extends AnnotationInfo<?>> annotations, String siteDescription) {
+ if (annotations == null || annotations.isEmpty())
+ return;
+ var hasValue = annotations.stream().anyMatch(JsrSupport::isValueAnnotation);
+ if (! hasValue)
+ return;
+ var hasInject = annotations.stream().anyMatch(JsrSupport::isInjectAnnotation);
+ if (hasInject)
+ throw new BeanCreationException("@Value and @Inject are mutually exclusive on " + siteDescription);
+ }
+
+ /**
+ * Resolves a {@code @Value} expression against the default {@link VarResolver} and coerces the
+ * result to {@code targetType} via {@link Settings#toType(String, Class)}.
+ *
+ * <p>
+ * Lookup semantics:
+ * <ul>
+ * <li>If the resolved value is {@code null} and {@code targetType} is a primitive, throws
+ * {@link BeanCreationException} (primitives cannot be {@code null}).
+ * <li>If the resolved value is {@code null} and {@code targetType} is a reference type, returns
+ * {@code null}.
+ * <li>If coercion via {@link Settings#toType(String, Class)} fails, the underlying exception is
+ * wrapped in {@link BeanCreationException} with a message that includes the expression, the
+ * resolved string, and the target type.
+ * </ul>
+ *
+ * @param expression The {@code @Value} expression (typically {@code "${key}"} or {@code "${key:default}"}).
+ * @param targetType The target Java type. May be a primitive.
+ * @param siteDescription A human-readable description of the site (used in error messages).
+ * @return The coerced value.
+ */
+ public static Object resolve(String expression, Class<?> targetType, String siteDescription) {
+ // Resolve placeholders via VarResolver.DEFAULT — this picks up the ${...} shortcut from
+ // Phase 2 (lowered to $P{...}) and routes through Settings.get(key) for the final lookup.
+ var resolved = VarResolver.DEFAULT.resolve(expression);
+ var effectiveType = box(targetType);
+
+ if (resolved == null || resolved.isEmpty()) {
+ if (targetType.isPrimitive())
+ throw new BeanCreationException("Could not resolve required @Value('" + expression + "') for primitive site " + siteDescription);
+ if (resolved == null)
+ return null;
+ // Empty string is a legitimate value for String / CharSequence target types.
+ if (effectiveType == String.class)
+ return resolved;
+ }
+
+ // Character has no usable valueOf(String) — Settings.toType can't coerce; handle manually.
+ if (effectiveType == Character.class) {
+ if (resolved.length() == 1)
+ return resolved.charAt(0);
+ throw new BeanCreationException(
+ "Could not coerce @Value('" + expression + "') resolving to '" + resolved + "' to char for " + siteDescription);
+ }
+
+ try {
+ return Settings.get().toType(resolved, effectiveType);
+ } catch (RuntimeException e) {
+ throw new BeanCreationException(
+ "Could not coerce @Value('" + expression + "') resolving to '" + resolved + "' to "
+ + targetType.getName() + " for " + siteDescription,
+ e);
+ }
+ }
+
+ /**
+ * Returns the boxed counterpart of a primitive type, or {@code type} itself if not primitive.
+ *
+ * <p>
+ * {@link Settings#toType(String, Class)} uses reflection for {@code valueOf(String)} / {@code (String)}
+ * constructor lookup, which doesn't work for raw primitives ({@code int.class} etc.). Box them first.
+ *
+ * @param type The (possibly primitive) target type.
+ * @return The boxed equivalent, or {@code type} unchanged.
+ */
+ private static Class<?> box(Class<?> type) {
+ if (! type.isPrimitive())
+ return type;
+ if (type == int.class) return Integer.class;
+ if (type == long.class) return Long.class;
+ if (type == boolean.class) return Boolean.class;
+ if (type == double.class) return Double.class;
+ if (type == float.class) return Float.class;
+ if (type == short.class) return Short.class;
+ if (type == byte.class) return Byte.class;
+ if (type == char.class) return Character.class;
+ return type; // void or unreachable
+ }
+}
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ClassInfo.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ClassInfo.java
index 5e512bf36c..6a7889d28f 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ClassInfo.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ClassInfo.java
@@ -3094,14 +3094,14 @@ public class ClassInfo extends ElementInfo implements Annotatable, Type, Compara
* @throws ExecutableException If any field or method cannot be injected (e.g., required bean not found in the bean store).
*/
public <T> T inject(T bean, BeanStore beanStore) {
- // Inject into fields
+ // Inject into fields.
getAllFields().stream()
- .filter(x -> x.isNotFinal() && x.getAnnotations().stream().anyMatch(JsrSupport::isInjectAnnotation))
+ .filter(x -> x.isNotFinal() && x.getAnnotations().stream().anyMatch(ClassInfo::isInjectOrValueAnnotation))
.forEach(x -> x.inject(beanStore, bean));
- // Inject into methods
+ // Inject into methods.
getAllMethods().stream()
- .filter(x -> x.isNotAbstract() && eq(x.getTypeParameters().length, 0) && x.getAnnotations().stream().anyMatch(JsrSupport::isInjectAnnotation))
+ .filter(x -> x.isNotAbstract() && eq(x.getTypeParameters().length, 0) && x.getAnnotations().stream().anyMatch(ClassInfo::isInjectOrValueAnnotation))
.forEach(x -> x.inject(beanStore, bean));
// Call @PostConstruct methods after all injection is complete
@@ -3115,4 +3115,8 @@ public class ClassInfo extends ElementInfo implements Annotatable, Type, Compara
return bean;
}
+ private static boolean isInjectOrValueAnnotation(AnnotationInfo<?> ai) {
+ return JsrSupport.isInjectAnnotation(ai) || JsrSupport.isValueAnnotation(ai);
+ }
+
}
\ No newline at end of file
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/FieldInfo.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/FieldInfo.java
index bb10d512c0..b5ec59d63c 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/FieldInfo.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/FieldInfo.java
@@ -599,8 +599,27 @@ public class FieldInfo extends AccessibleInfo implements Comparable<FieldInfo>,
accessible();
var fieldType = getFieldType();
+ // @Value sites resolve from Settings/VarResolver, not the bean store.
+ var annos = getAnnotations();
+ var valueExpr = ValueResolver.findValueExpression(annos);
+ if (valueExpr != null) {
+ ValueResolver.checkInjectConflict(annos, this.toString());
+ var unwrapped = fieldType.unwrap(Optional.class).inner();
+ var resolved = ValueResolver.resolve(valueExpr, unwrapped, this.toString());
+ if (fieldType.is(Optional.class)) {
+ // VarResolver substitutes "" for a missing key with no default. Collapse both to
+ // Optional.empty() so @Value("${maybe}") Optional<T> behaves the same as Spring's.
+ set(bean, (resolved == null || (resolved instanceof String s && s.isEmpty()))
+ ? Optional.empty()
+ : Optional.of(resolved));
+ } else {
+ set(bean, resolved);
+ }
+ return bean;
+ }
+
// Find qualifier from @Named or @Qualifier annotation (same logic as ParameterInfo.getResolvedQualifier)
- var beanQualifier = getAnnotations().stream()
+ var beanQualifier = annos.stream()
.map(JsrSupport::qualifierValue)
.filter(Objects::nonNull)
.findFirst()
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ParameterInfo.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ParameterInfo.java
index ff0c4825bf..d43d3018c1 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ParameterInfo.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/ParameterInfo.java
@@ -31,7 +31,7 @@ import java.util.stream.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.inject.*;
-import org.apache.juneau.commons.settings.Settings;
+import org.apache.juneau.commons.settings.*;
import org.apache.juneau.commons.utils.*;
/**
@@ -787,6 +787,11 @@ public class ParameterInfo extends ElementInfo implements Annotatable {
public boolean canResolve(BeanStore beanStore, Object... otherBeans) {
var pt = getParameterType();
+ // @Value sites resolve from Settings/Env, not the bean store — always considered resolvable
+ // here. (Mutual-exclusion with @Inject is enforced in resolveValue(...).)
+ if (ValueResolver.hasValueAnnotation(getAnnotations()))
+ return true;
+
if (pt.is(Optional.class) || pt.isInjectCollectionType()) // Optional/Collection/array types are always satisfied (even if empty).
return true;
@@ -826,6 +831,8 @@ public class ParameterInfo extends ElementInfo implements Annotatable {
*/
public String getMissingType(BeanStore beanStore, Object... otherBeans) {
var pt = getParameterType();
+ if (ValueResolver.hasValueAnnotation(getAnnotations()))
+ return null;
if (pt.is(Optional.class) || pt.isInjectCollectionType()) // Optional/Collection/array types are always satisfied (even if empty).
return null;
var bq = getResolvedQualifier(); // Use @Named/@Qualified for bean injection
@@ -888,6 +895,14 @@ public class ParameterInfo extends ElementInfo implements Annotatable {
var bq = getResolvedQualifier();
var ptu = pt.unwrap(Optional.class);
+ // @Value sites resolve from Settings/VarResolver, not the bean store.
+ var annos = getAnnotations();
+ var valueExpr = ValueResolver.findValueExpression(annos);
+ if (valueExpr != null) {
+ ValueResolver.checkInjectConflict(annos, this.toString());
+ return ValueResolver.resolve(valueExpr, ptu.inner(), this.toString());
+ }
+
if (JsrSupport.isProviderType(ptu.inner())) {
var valueType = ptu.innerType() instanceof ParameterizedType parameterizedType
&& parameterizedType.getActualTypeArguments().length == 1
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/settings/Settings.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/settings/Settings.java
index 651fdc44a7..be6fef0cc8 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/settings/Settings.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/settings/Settings.java
@@ -377,6 +377,31 @@ public class Settings {
return this;
}
+ /**
+ * Removes a previously-added property source.
+ *
+ * <p>
+ * The match is by identity ({@code ==}), not equality. Callers that mutate the singleton
+ * {@link #get() Settings.get()} from a test should capture the exact reference returned to/passed
+ * into {@link #addSource(PropertySource)} and pass it back here in their teardown to avoid
+ * cross-test bleed.
+ *
+ * @param source The property source to remove. Must not be <jk>null</jk>.
+ * @return <jk>true</jk> if the source was present and removed, <jk>false</jk> otherwise.
+ */
+ public boolean removeSource(PropertySource source) {
+ assertArgNotNull(ARG_source, source);
+ // Identity-based removal so that PropertySource impls without a sensible equals() still
+ // round-trip cleanly through add/remove pairs.
+ for (var i = 0; i < sources.size(); i++) {
+ if (sources.get(i) == source) {
+ sources.remove(i);
+ return true;
+ }
+ }
+ return false;
+ }
+
/**
* Returns a {@link StringSetting} for the specified system property.
*
@@ -634,7 +659,7 @@ public class Settings {
"unchecked", // Type erasure requires unchecked cast
"rawtypes" // Raw types necessary for generic type handling
})
- protected <T> T toType(String s, Class<T> c) {
+ public <T> T toType(String s, Class<T> c) {
assertArgNotNull(ARG_s, s);
assertArgNotNull(ARG_c, c);
var f = (Function<String,T>)toTypeFunctions.get(c);
@@ -645,6 +670,10 @@ public class Settings {
return (T)Enum.valueOf((Class<? extends Enum>)c, s);
ClassInfoTyped<T> ci = info(c);
f = ci.getDeclaredMethod(x -> x.isStatic() && x.hasParameterTypes(String.class) && x.hasReturnType(c) && FROM_STRING_METHOD_NAMES.contains(x.getName())).map(x -> (Function<String,T>)s2 -> x.invoke(null, s2)).orElse(null);
+ // Also accept `static T parse(CharSequence)` etc. — common for java.time types (Instant,
+ // LocalDate, Duration) whose static factories declare the wider CharSequence parameter.
+ if (f == null)
+ f = ci.getDeclaredMethod(x -> x.isStatic() && x.hasParameterTypes(CharSequence.class) && x.hasReturnType(c) && FROM_STRING_METHOD_NAMES.contains(x.getName())).map(x -> (Function<String,T>)s2 -> x.invoke(null, s2)).orElse(null);
if (f == null)
f = ci.getPublicConstructor(x -> x.hasParameterTypes(String.class)).map(x -> (Function<String,T>)x::newInstance).orElse(null);
if (f != null)
diff --git a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/svl/VarResolverSession.java b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/svl/VarResolverSession.java
index 01954b502b..5b9c5732e1 100644
--- a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/svl/VarResolverSession.java
+++ b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/svl/VarResolverSession.java
@@ -66,6 +66,43 @@ public class VarResolverSession {
private static final AsciiSet AS1 = AsciiSet.of("\\{");
private static final AsciiSet AS2 = AsciiSet.of("\\${}");
+ /**
+ * Var name targeted by the {@code ${xxx}} shortcut.
+ *
+ * <p>
+ * Resolves to {@code PropertyVar.NAME}. Declared as a string literal here (rather than imported
+ * from {@code org.apache.juneau.commons.svl.vars.PropertyVar}) to keep the {@code svl} parent
+ * package free of a compile-time dependency on its {@code svl.vars} child package.
+ */
+ private static final String DOLLAR_BRACE_VAR = "P";
+
+ /**
+ * Translates the first top-level {@code ':'} in a {@code ${...}}-shortcut body to {@code ','}
+ * so that the body matches {@link DefaultingVar}'s {@code key,default} separator.
+ *
+ * <p>
+ * "Top-level" means the {@code ':'} is not inside a nested {@code {...}} block — those colons
+ * belong to the inner var and must remain untouched until that inner var's own translation runs.
+ *
+ * @param body The raw body extracted from inside the outer {@code ${...}}.
+ * @return The body with the first top-level {@code ':'} rewritten to {@code ','}, or the input
+ * unchanged if no top-level {@code ':'} is present.
+ */
+ private static String translateDollarBraceDefault(String body) {
+ var depth = 0;
+ var length = body.length();
+ for (var i = 0; i < length; i++) {
+ var c = body.charAt(i);
+ if (c == '{')
+ depth++;
+ else if (c == '}' && depth > 0)
+ depth--;
+ else if (c == ':' && depth == 0)
+ return body.substring(0, i) + ',' + body.substring(i + 1);
+ }
+ return body;
+ }
+
private static boolean containsVars(Collection<?> c) {
var f = Flag.create();
c.forEach(x -> {
@@ -204,7 +241,15 @@ public class VarResolverSession {
if (isSimpleVar(s)) {
String varName = s.substring(1, s.indexOf('{'));
String val = s.substring(s.indexOf('{') + 1, s.length() - 1);
+ // ${xxx} shortcut → $P{xxx}: an empty varName means the source was "${...}", route to PropertyVar
+ // and translate the first ":" (Spring-style default separator) to "," (DefaultingVar's separator).
+ // Back-compat: if an empty-name var is explicitly registered (legacy), prefer it.
Var v = getVar(varName);
+ if (v == null && varName.isEmpty()) {
+ varName = DOLLAR_BRACE_VAR;
+ val = translateDollarBraceDefault(val);
+ v = getVar(varName);
+ }
if (nn(v)) {
try {
if (v.streamed) {
@@ -360,6 +405,10 @@ public class VarResolverSession {
var x = 0;
var x2 = 0;
var depth = 0;
+ // Tracks whether the current var came from the "${...}" shortcut (vs. an explicit "$P{...}").
+ // When true, the body's first top-level ':' is rewritten to ',' before inner resolution so
+ // that DefaultingVar's "key,default" syntax accepts Spring-style "${key:default}".
+ var isDollarBraceShortcut = false;
var length = s.length();
for (var i = 0; i < length; i++) {
var c = s.charAt(i);
@@ -388,6 +437,12 @@ public class VarResolverSession {
isInEscape = true;
} else if (c == '{') {
varType = s.substring(x + 1, i);
+ // ${xxx} shortcut: empty varType means the source was "${...}". Defer the
+ // rewrite-to-PropertyVar decision until the closing '}' is found, so that
+ // malformed inputs (e.g. "${{foo}") fall through unchanged and so that a
+ // legacy empty-name var (if registered) still wins for back-compat.
+ if (varType.isEmpty())
+ isDollarBraceShortcut = true;
x = i;
depth = 0;
state = S3;
@@ -414,7 +469,17 @@ public class VarResolverSession {
depth--;
} else {
varVal = s.substring(x + 1, i);
+ // For the "${...}" shortcut: rewrite the first top-level ':' to ',' so the
+ // body matches DefaultingVar's "key,default" separator. Done BEFORE inner
+ // resolution because any ':' produced by a resolved inner var must NOT be
+ // re-interpreted as a default separator.
+ if (isDollarBraceShortcut)
+ varVal = translateDollarBraceDefault(varVal);
+ // Back-compat: prefer an explicit empty-name var if registered. Only fall
+ // back to PropertyVar when the shortcut form has no legacy resolver.
Var r = getVar(varType);
+ if (r == null && isDollarBraceShortcut)
+ r = getVar(DOLLAR_BRACE_VAR);
if (r == null) {
if (hasInnerEscapes)
out.append(unescapeChars(s.substring(x2, i + 1), AS2));
@@ -444,6 +509,7 @@ public class VarResolverSession {
}
state = S1;
hasInnerEscapes = false;
+ isDollarBraceShortcut = false;
}
}
}
diff --git a/juneau-core/juneau-config/src/main/java/org/apache/juneau/config/ConfigPropertySourceProvider.java b/juneau-core/juneau-config/src/main/java/org/apache/juneau/config/ConfigPropertySourceProvider.java
new file mode 100644
index 0000000000..7d03de7310
--- /dev/null
+++ b/juneau-core/juneau-config/src/main/java/org/apache/juneau/config/ConfigPropertySourceProvider.java
@@ -0,0 +1,187 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.config;
+
+import org.apache.juneau.commons.settings.*;
+
+/**
+ * Auto-registers a classpath-default {@code juneau.cfg} (and the other names returned by
+ * {@link Config#getCandidateSystemDefaultConfigNames()}) as a {@link PropertySource} for the
+ * process-wide {@link Settings} singleton.
+ *
+ * <p>
+ * Discovered by {@link Settings.Builder#useServiceLoader() ServiceLoader-based wiring} through a
+ * {@code META-INF/services/org.apache.juneau.commons.settings.PropertySourceProvider} entry
+ * shipped in this module.
+ *
+ * <p>
+ * Lookup semantics: the registered source defers calling {@link Config#getSystemDefault()} to the
+ * first {@code get(name)} invocation. This is deliberate — calling {@code getSystemDefault()} from
+ * inside {@link #create()} would create a static-initialization cycle because
+ * {@code Settings.<clinit>} fires the ServiceLoader at class-load time, and {@code Config}'s
+ * static initializers transitively reference {@link Settings} (through {@code Cache} / {@code Utils.env(...)})
+ * which would re-enter the {@code Settings.<clinit>} block.
+ *
+ * <p>
+ * Lazy resolution makes the cycle a non-issue: by the time {@code @Value("${...}")} fires its first
+ * lookup, all participating classes are fully initialized.
+ *
+ * <h5 class='section'>Silence on missing config:</h5>
+ * <p>
+ * If no system-default {@link Config} is discoverable (no {@code juneau.cfg} / {@code default.cfg}
+ * / {@code application.cfg} / etc. on the classpath or working directory), {@code get(name)}
+ * returns {@link PropertyLookupResult#missing()} for every key. No logging, no exception — many
+ * deployments have no classpath config and shouldn't see noise.
+ *
+ * <h5 class='section'>Ordering:</h5>
+ * <p>
+ * {@link #order()} returns {@code 100}, which is "low" in the {@link PropertySourceProvider}
+ * scheme — provider-discovered classpath defaults register near the bottom of the source list so
+ * that programmatic {@code Settings.get().addSource(...)} calls (e.g. per-microservice config or
+ * the Spring {@code Environment} bridge) shadow the classpath default. {@link Settings} walks
+ * sources in reverse insertion order, so the most-recently-added source wins.
+ */
+public class ConfigPropertySourceProvider implements PropertySourceProvider {
+
+ @Override
+ public PropertySource create() {
+ // Return a lazy wrapper. Resolving Config.getSystemDefault() eagerly here would trigger
+ // Config.<clinit>, which can transitively re-enter Settings.<clinit> through Cache /
+ // Utils.env(...) — the SPI registration is invoked from inside the Settings static init
+ // block, so any cycle here surfaces as ExceptionInInitializerError.
+ return new LazyConfigPropertySource();
+ }
+
+ @Override
+ public int order() {
+ // Low ordering: classpath defaults register first, so any programmatic
+ // addSource(...) added afterwards shadows the classpath defaults at lookup time
+ // (Settings walks sources in reverse insertion order).
+ return 100;
+ }
+
+ /**
+ * Defers {@link Config#getSystemDefault()} resolution to the first {@link #get(String)} call to
+ * avoid the static-initialization cycle described in the enclosing class' Javadoc.
+ *
+ * <p>
+ * Additionally protects against three runtime cycles at first-use time:
+ * <ol>
+ * <li><b>Bootstrap-static-init cycle (poisoning).</b> If this source is called from inside
+ * <i>any</i> JVM static-initializer chain that transitively loads {@code Config}, the
+ * downstream {@code Config.findSystemDefault()} → {@code FileStore.<clinit>} →
+ * {@code Context.Builder.build()} chain can fail with {@link NullPointerException}
+ * because {@code Context.<clinit>} hasn't finished yet. That failure <i>poisons</i>
+ * {@code FileStore} (every subsequent reference raises {@link NoClassDefFoundError}).
+ * To prevent the poisoning, the source detects when it's called from a static-initializer
+ * frame by walking the current stack for a {@code "<clinit>"} method name and short-circuits
+ * to {@link PropertyLookupResult#missing()} <i>without</i> memoizing — so the next call,
+ * from regular code, can resolve normally.
+ * <li><b>Reentrant resolution cycle.</b> {@link Config#findSystemDefault()} looks up the
+ * {@code "juneau.configFile"} system property via {@link Settings#get(String)}, which
+ * walks every registered source — including this one. Without a guard, that re-enters
+ * {@code Config.getSystemDefault()} on the same thread, which re-enters
+ * {@code findSystemDefault()}, which re-enters {@code Settings.get("juneau.configFile")},
+ * ad infinitum (a {@link StackOverflowError}). A {@link ThreadLocal} sentinel short-circuits
+ * any re-entrant lookup on the same thread to {@code missing()}.
+ * <li><b>Defensive throwable catch.</b> Any unexpected throwable (e.g. a different class
+ * loader's {@code Config} init failure that the {@code <clinit>}-sniff missed) is
+ * swallowed and treated as "not yet available" — {@code get(name)} returns
+ * {@link PropertyLookupResult#missing()} without memoizing the failure.
+ * </ol>
+ */
+ @SuppressWarnings("java:S1181") // Intentional broad Throwable catch — see Javadoc.
+ static final class LazyConfigPropertySource implements PropertySource {
+
+ // Thread-local re-entrance guard. Static so it covers both the lazy-init path and any
+ // concurrent lookup that may also reach a Config.getSystemDefault() call (defensively).
+ private static final ThreadLocal<Boolean> RESOLVING = ThreadLocal.withInitial(() -> Boolean.FALSE);
+
+ // Guarded by the synchronized block in get(...); volatile reads cover the fast-path check.
+ private volatile boolean resolved;
+ private volatile ConfigPropertySource delegate;
+
+ @Override
+ public PropertyLookupResult get(String name) {
+
+ // Re-entrant guard: Config.findSystemDefault() walks Settings.get("juneau.configFile"),
+ // which round-trips through every source including this one. Short-circuit on
+ // re-entry so the outer Config.getSystemDefault() can make progress.
+ if (Boolean.TRUE.equals(RESOLVING.get()))
+ return PropertyLookupResult.missing();
+
+ // Bootstrap guard: if we're being called from inside a <clinit> frame (e.g. another
+ // class's static-initializer chain transitively invokes Settings.get(...) → this
+ // source), don't attempt to resolve Config — doing so would force Config / FileStore /
+ // Context class loading from inside an already-in-progress class init, which poisons
+ // FileStore.<clinit> with a NoClassDefFoundError that survives the rest of the JVM
+ // lifetime. Short-circuit without memoizing; the next non-<clinit> call resolves.
+ if (! resolved && isInClinit())
+ return PropertyLookupResult.missing();
+
+ if (! resolved) {
+ synchronized (this) {
+ if (! resolved) {
+ // Re-check the <clinit> guard inside the lock — another thread may have
+ // flipped resolved between the first check and the lock acquire.
+ if (isInClinit())
+ return PropertyLookupResult.missing();
+
+ Config cfg;
+ RESOLVING.set(Boolean.TRUE);
+ try {
+ cfg = Config.getSystemDefault();
+ } catch (Throwable t) {
+ // Defense-in-depth: a Config-side init failure the <clinit> sniff
+ // missed. Return missing() without memoizing so the next lookup can
+ // retry once Config init has completed.
+ return PropertyLookupResult.missing();
+ } finally {
+ RESOLVING.remove();
+ }
+ // Silent when no juneau.cfg / default.cfg / etc. is discoverable — the
+ // SPI consumer sees missing() for every key but no log noise.
+ delegate = (cfg == null) ? null : new ConfigPropertySource(cfg);
+ resolved = true;
+ }
+ }
+ }
+ return delegate == null ? PropertyLookupResult.missing() : delegate.get(name);
+ }
+
+ /**
+ * Returns <jk>true</jk> if any frame in the current thread's call stack is a Java
+ * static-initializer ({@code "<clinit>"}). Used to detect — and avoid — the bootstrap-time
+ * cycle that would otherwise poison {@code FileStore.<clinit>}.
+ *
+ * <p>
+ * Cost: a single {@link Thread#getStackTrace()} call on the first lookup per source-thread
+ * pair. {@code resolved} is volatile so subsequent calls skip the stack walk entirely.
+ *
+ * @return <jk>true</jk> if the current call is being made from inside a {@code <clinit>}
+ * frame anywhere in the stack.
+ */
+ private static boolean isInClinit() {
+ var trace = Thread.currentThread().getStackTrace();
+ for (var frame : trace) {
+ if ("<clinit>".equals(frame.getMethodName()))
+ return true;
+ }
+ return false;
+ }
+ }
+}
diff --git a/juneau-core/juneau-config/src/main/resources/META-INF/services/org.apache.juneau.commons.settings.PropertySourceProvider b/juneau-core/juneau-config/src/main/resources/META-INF/services/org.apache.juneau.commons.settings.PropertySourceProvider
new file mode 100644
index 0000000000..8d6fe8e97e
--- /dev/null
+++ b/juneau-core/juneau-config/src/main/resources/META-INF/services/org.apache.juneau.commons.settings.PropertySourceProvider
@@ -0,0 +1 @@
+org.apache.juneau.config.ConfigPropertySourceProvider
diff --git a/juneau-microservice/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java b/juneau-microservice/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
index 80f17fb83c..b423351d1c 100755
--- a/juneau-microservice/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
+++ b/juneau-microservice/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
@@ -37,6 +37,7 @@ import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.runtime.*;
import org.apache.juneau.commons.svl.*;
import org.apache.juneau.commons.svl.vars.*;
+import org.apache.juneau.commons.settings.*;
import org.apache.juneau.config.*;
import org.apache.juneau.config.event.*;
import org.apache.juneau.config.store.*;
@@ -659,6 +660,7 @@ public class Microservice implements ConfigEventListener {
private final String configName;
private final WritableBeanStore beanStore;
private volatile boolean stopped;
+ private final ConfigPropertySource settingsSource;
private final AtomicReference<Logger> logger = new AtomicReference<>();
@@ -772,6 +774,8 @@ public class Microservice implements ConfigEventListener {
this.config = config2;
Config.setSystemDefault(this.config);
this.config.addListener(this);
+ this.settingsSource = new ConfigPropertySource(this.config);
+ Settings.get().addSource(this.settingsSource);
beanStore.addBean(Config.class, this.config);
this.varResolver = builder.varResolver.bean(Config.class, config2).build();
beanStore.addBean(VarResolver.class, this.varResolver);
@@ -1300,6 +1304,8 @@ public class Microservice implements ConfigEventListener {
if (stopped)
return this;
stopped = true;
+ if (nn(settingsSource))
+ Settings.get().removeSource(settingsSource);
var listeners = new ArrayList<>(beanStore.getBeansOfType(MicroserviceListener.class).values());
Collections.reverse(listeners);
for (var l : listeners)
diff --git a/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringBeanStore.java b/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringBeanStore.java
index 5582e9b79c..dc1100d5f5 100644
--- a/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringBeanStore.java
+++ b/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringBeanStore.java
@@ -22,6 +22,7 @@ import java.util.*;
import java.util.function.*;
import org.apache.juneau.commons.inject.*;
+import org.apache.juneau.commons.settings.*;
import org.springframework.context.*;
/**
@@ -57,21 +58,45 @@ public class SpringBeanStore extends BasicBeanStore {
private final ApplicationContext appContext;
+ // Captured so clear() can deregister the bridge from the process-wide Settings singleton and
+ // avoid cross-test bleed when multiple Spring contexts come and go in the same JVM.
+ private final SpringEnvironmentPropertySource environmentSource;
+
/**
* Constructor.
*
+ * <p>
+ * If {@code appContext} is non-null, this constructor also installs a
+ * {@link SpringEnvironmentPropertySource} on the process-wide {@link Settings} singleton so that
+ * {@link org.apache.juneau.commons.inject.Value @Value("${...}")} placeholders resolve against
+ * the Spring {@link org.springframework.core.env.Environment Environment} (i.e. against
+ * {@code application.yaml}, env vars, system properties, etc.). The source is removed by
+ * {@link #clear()}.
+ *
* @param appContext The Spring application context used to resolve beans. Can be <jk>null</jk>.
* @param parent The parent bean store. Can be <jk>null</jk>.
*/
public SpringBeanStore(ApplicationContext appContext, BeanStore parent) {
super(parent);
this.appContext = appContext;
+ // Register a lazy bridge to Spring's Environment. The supplier form defers the
+ // appContext.getEnvironment() call to first @Value("${...}") lookup, so the constructor has
+ // no observable interaction with the application context — important for callers (and
+ // tests) that don't actually use Spring properties. Null appContext means no bridge.
+ if (nn(appContext)) {
+ this.environmentSource = new SpringEnvironmentPropertySource(appContext::getEnvironment);
+ Settings.get().addSource(this.environmentSource);
+ } else {
+ this.environmentSource = null;
+ }
}
@Override
@SuppressWarnings("resource") // super.clear() returns this; the discarded return is the store we already own
public SpringBeanStore clear() {
super.clear();
+ if (nn(environmentSource))
+ Settings.get().removeSource(environmentSource);
return this;
}
diff --git a/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource.java b/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource.java
new file mode 100644
index 0000000000..bb31fb49ed
--- /dev/null
+++ b/juneau-rest/juneau-rest-server-springboot/src/main/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource.java
@@ -0,0 +1,122 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.rest.springboot;
+
+import static org.apache.juneau.commons.utils.Utils.*;
+
+import java.util.*;
+import java.util.function.*;
+
+import org.springframework.core.env.*;
+
+/**
+ * Bridges a Spring {@link Environment} into the Juneau {@link org.apache.juneau.commons.settings.Settings Settings}
+ * singleton as a {@link org.apache.juneau.commons.settings.PropertySource PropertySource}.
+ *
+ * <p>
+ * Allows {@link org.apache.juneau.commons.inject.Value @Value("${spring.property.key}")} resolution
+ * against the same property sources that Spring Boot would resolve through
+ * {@code @org.springframework.beans.factory.annotation.Value}: {@code application.yaml},
+ * {@code application.properties}, command-line args, environment variables, and any custom
+ * {@code org.springframework.core.env.PropertySource} that Spring loads.
+ *
+ * <h5 class='section'>Lifecycle:</h5>
+ * <p>
+ * Instances are auto-registered by {@link SpringBeanStore#SpringBeanStore(org.springframework.context.ApplicationContext,
+ * org.apache.juneau.commons.inject.BeanStore) SpringBeanStore}'s constructor and removed from
+ * {@link org.apache.juneau.commons.settings.Settings#removeSource(org.apache.juneau.commons.settings.PropertySource)
+ * Settings} when {@link SpringBeanStore#clear()} is called. Callers that want explicit lifecycle
+ * control can construct the source directly and add it via {@code Settings.get().addSource(...)}.
+ *
+ * <h5 class='section'>Lazy resolution:</h5>
+ * <p>
+ * The {@code Environment} is resolved lazily on the first {@link #get(String)} call so that
+ * constructors that build the source from an {@code ApplicationContext} do not interact with the
+ * context until a lookup actually happens. This matters for tests that mock the context and assert
+ * "no interactions" until a Spring-side bean is requested.
+ *
+ * <h5 class='section'>Ordering:</h5>
+ * <p>
+ * Because {@code Settings} walks property sources in reverse insertion order, the Spring
+ * {@code Environment} bridge — registered when Spring creates the bean store — shadows any
+ * classpath-default {@code juneau.cfg} loaded earlier through the SPI-discovered
+ * {@code ConfigPropertySourceProvider}. Programmatic {@code addSource()} calls made after the
+ * Spring context is built (e.g. from a user-provided microservice {@code Config}) still win.
+ *
+ * <h5 class='section'>See Also:</h5><ul>
+ * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ValueAnnotationBasics">{@code @Value} basics</a>
+ * <li class='jc'>{@link SpringBeanStore}
+ * </ul>
+ */
+public class SpringEnvironmentPropertySource implements org.apache.juneau.commons.settings.PropertySource {
+
+ private final Supplier<Environment> envSupplier;
+
+ // Guarded by the synchronized block in get(...); volatile reads cover the fast-path check.
+ private volatile boolean resolved;
+ private volatile Environment env;
+
+ /**
+ * Constructor that bridges a pre-built {@link Environment}.
+ *
+ * @param env The Spring environment to bridge. Must not be <jk>null</jk>.
+ */
+ public SpringEnvironmentPropertySource(Environment env) {
+ this.env = Objects.requireNonNull(env, "env");
+ this.envSupplier = null;
+ this.resolved = true;
+ }
+
+ /**
+ * Constructor that lazily resolves the {@link Environment} on first lookup.
+ *
+ * <p>
+ * Use this overload when wiring through {@link org.springframework.context.ApplicationContext}: pass
+ * {@code appContext::getEnvironment} so the application context isn't invoked until a lookup
+ * actually occurs.
+ *
+ * @param envSupplier Supplier of the Spring environment. Must not be <jk>null</jk>. May return
+ * <jk>null</jk>, in which case this source returns
+ * {@link org.apache.juneau.commons.settings.PropertyLookupResult#missing()} for every key.
+ */
+ public SpringEnvironmentPropertySource(Supplier<Environment> envSupplier) {
+ this.envSupplier = Objects.requireNonNull(envSupplier, "envSupplier");
+ }
+
+ @Override
+ public org.apache.juneau.commons.settings.PropertyLookupResult get(String name) {
+ var e = env;
+ if (! resolved) {
+ synchronized (this) {
+ if (! resolved) {
+ // safeOpt swallows exceptions thrown by the supplier — e.g. a mocked
+ // ApplicationContext that returns null or throws during getEnvironment().
+ env = e = safeOpt(envSupplier::get).orElse(null);
+ resolved = true;
+ } else {
+ e = env;
+ }
+ }
+ }
+ if (e == null || ! e.containsProperty(name))
+ return org.apache.juneau.commons.settings.PropertyLookupResult.missing();
+ // Spring's getProperty() returns null only for unresolved placeholders, which
+ // containsProperty() already filtered out. Wrap defensively anyway.
+ var v = e.getProperty(name);
+ return org.apache.juneau.commons.settings.PropertyLookupResult.present(opt(v));
+ }
+}
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
index cdf9911d96..3ba952609a 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
@@ -1774,6 +1774,11 @@ public class RestContext extends Context {
// runtime Config) — @RestInit hooks that take Config as a parameter will see the fully
// resolved instance instead of the raw bootstrap Config (9.5 behavior change).
rawConfig.get();
+ // NOTE: per-RestContext bridging of the @Rest(config=...) Config into Settings.get()
+ // was removed in 9.5 (perf regression — leaked ConfigPropertySource instances into the
+ // global Settings list because MockRestClient caches RestContext instances statically
+ // and never invokes destroy()). Per-RestContext @Value("${cfg-key}") resolution
+ // against the resource-scoped Config is tracked as TODO-95 (BeanStore-routed lookup).
// Register memoizer-backed defaults for every framework-managed type. These sit at the
// bottom of the precedence order and only fire when no @Bean method, no programmatic
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestOpContext.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestOpContext.java
index e614c2ee72..63193db20a 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestOpContext.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestOpContext.java
@@ -40,7 +40,7 @@ import org.apache.juneau.commons.annotation.*;
import org.apache.juneau.commons.collections.FluentMap;
import org.apache.juneau.commons.function.Memoizer;
import org.apache.juneau.commons.inject.*;
-import org.apache.juneau.commons.lang.*;
+import org.apache.juneau.commons.lang.Value;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.encoders.*;
diff --git a/juneau-utest/src/test/java/org/apache/juneau/commons/inject/Value_Test.java b/juneau-utest/src/test/java/org/apache/juneau/commons/inject/Value_Test.java
new file mode 100644
index 0000000000..58f82731ce
--- /dev/null
+++ b/juneau-utest/src/test/java/org/apache/juneau/commons/inject/Value_Test.java
@@ -0,0 +1,487 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.commons.inject;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.lang.annotation.*;
+import java.net.*;
+import java.time.*;
+import java.util.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.commons.settings.*;
+import org.junit.jupiter.api.*;
+
+/**
+ * Acceptance tests for the {@code @Value} annotation introduced in TODO-79.
+ *
+ * <p>
+ * Covers Juneau's {@link Value @Value}, Spring's {@code @Value} (detected by FQN), and the negative
+ * paths around primitive-null and {@code @Value} + {@code @Inject} mutual exclusion.
+ */
+class Value_Test extends TestBase {
+
+ private static final String P_STRING = "Value_Test.string";
+ private static final String P_INT = "Value_Test.int";
+ private static final String P_BOOL = "Value_Test.bool";
+ private static final String P_URI = "Value_Test.uri";
+ private static final String P_INSTANT = "Value_Test.instant";
+
+ private BasicBeanStore beanStore;
+
+ @BeforeEach
+ void setUp() {
+ beanStore = new BasicBeanStore(null);
+ }
+
+ @AfterEach
+ void cleanup() {
+ var s = Settings.get();
+ for (var k : List.of(P_STRING, P_INT, P_BOOL, P_URI, P_INSTANT, "Value_Test.optional",
+ "Value_Test.timeout.ms", "Value_Test.field", "Value_Test.setter", "Value_Test.springStyle",
+ "Value_Test.coerceFail"))
+ s.unsetGlobal(k);
+ }
+
+ //====================================================================================================
+ // Fixtures.
+ //====================================================================================================
+
+ /**
+ * A Spring-style {@code @Value} replica that {@link JsrSupport} matches by FQN.
+ *
+ * <p>
+ * The real Spring annotation is at {@code org.springframework.beans.factory.annotation.Value}; we
+ * cannot directly import that here without a compile-time Spring dependency. Instead, this
+ * private annotation mirrors the FQN that {@link JsrSupport#SPRING_VALUE} matches but lives in
+ * the test fixture package, so {@code isValueAnnotation} alone cannot tell them apart. We
+ * instead exercise both Juneau {@code @Value} and {@code @Value}+{@code @Inject} conflict paths
+ * directly — the Spring FQN match is exercised in the actual Spring Boot integration test
+ * fixture (Phase 4).
+ */
+ @Retention(RetentionPolicy.RUNTIME)
+ @Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD, ElementType.CONSTRUCTOR})
+ @interface MarkerAnnotation {}
+
+ public static class StringFieldBean {
+ @Value("${" + P_STRING + ":hello}")
+ String greeting;
+ }
+
+ public static class IntFieldBean {
+ @Value("${" + P_INT + "}")
+ int count;
+ }
+
+ public static class BoxedIntFieldBean {
+ @Value("${" + P_INT + ":42}")
+ Integer count;
+ }
+
+ public static class BooleanFieldBean {
+ @Value("${" + P_BOOL + ":true}")
+ boolean enabled;
+ }
+
+ public static class UriFieldBean {
+ @Value("${" + P_URI + ":https://example.org/}")
+ URI endpoint;
+ }
+
+ public static class InstantFieldBean {
+ @Value("${" + P_INSTANT + ":2020-01-01T00:00:00Z}")
+ Instant when;
+ }
+
+ public static class OptionalFieldBean {
+ @Value("${Value_Test.optional}")
+ Optional<String> maybe;
+ }
+
+ public static class ConstructorParamBean {
+ final String greeting;
+ final int timeoutMs;
+
+ @Inject
+ public ConstructorParamBean(
+ @Value("${Value_Test.string:bonjour}") String greeting,
+ @Value("${Value_Test.timeout.ms:5000}") int timeoutMs) {
+ this.greeting = greeting;
+ this.timeoutMs = timeoutMs;
+ }
+ }
+
+ public static class SetterBean {
+ String field;
+
+ @Inject
+ public void setField(@Value("${Value_Test.setter:via-setter}") String field) {
+ this.field = field;
+ }
+ }
+
+ public static class ConflictFieldBean {
+ // Mutual-exclusion guard fires when both are present on the same site.
+ @Value("${Value_Test.field}")
+ @Inject
+ String mixed;
+ }
+
+ public static class ConflictParamBean {
+ final String s;
+
+ @Inject
+ public ConflictParamBean(@Value("${Value_Test.field}") @Inject String s) {
+ this.s = s;
+ }
+ }
+
+ public static class PrimitiveMissingNoDefaultBean {
+ // Primitive site with no default and missing key — must throw at injection time.
+ @Value("${Value_Test.missing.primitive.no.default}")
+ int port;
+ }
+
+ public static class CoerceFailureBean {
+ @Value("${Value_Test.coerceFail}")
+ int notAnInt;
+ }
+
+ /**
+ * Field using Spring's {@code @Value} annotation (matched by FQN through {@link JsrSupport}).
+ *
+ * <p>
+ * Spring's annotation is fully-qualified so it doesn't collide with the Juneau
+ * {@link Value @Value} that the rest of this file uses.
+ */
+ public static class SpringValueFieldBean {
+ @org.springframework.beans.factory.annotation.Value("${Value_Test.springStyle:spring-default}")
+ String value;
+ }
+
+ //====================================================================================================
+ // Field injection.
+ //====================================================================================================
+
+ @Test
+ void a01_field_string_default() {
+ var bean = BeanInstantiator.of(StringFieldBean.class, beanStore).run();
+ assertEquals("hello", bean.greeting);
+ }
+
+ @Test
+ void a02_field_string_fromSettings() {
+ Settings.get().setGlobal(P_STRING, "from-settings");
+ var bean = BeanInstantiator.of(StringFieldBean.class, beanStore).run();
+ assertEquals("from-settings", bean.greeting);
+ }
+
+ @Test
+ void a03_field_intPrimitive_coerced() {
+ Settings.get().setGlobal(P_INT, "1234");
+ var bean = BeanInstantiator.of(IntFieldBean.class, beanStore).run();
+ assertEquals(1234, bean.count);
+ }
+
+ @Test
+ void a04_field_integerBoxed_default() {
+ var bean = BeanInstantiator.of(BoxedIntFieldBean.class, beanStore).run();
+ assertEquals(42, bean.count);
+ }
+
+ @Test
+ void a05_field_booleanPrimitive_default() {
+ var bean = BeanInstantiator.of(BooleanFieldBean.class, beanStore).run();
+ assertTrue(bean.enabled);
+ }
+
+ @Test
+ void a06_field_uri_coerced() {
+ var bean = BeanInstantiator.of(UriFieldBean.class, beanStore).run();
+ assertEquals(URI.create("https://example.org/"), bean.endpoint);
+ }
+
+ @Test
+ void a07_field_instant_coerced() {
+ var bean = BeanInstantiator.of(InstantFieldBean.class, beanStore).run();
+ assertEquals(Instant.parse("2020-01-01T00:00:00Z"), bean.when);
+ }
+
+ @Test
+ void a08_field_optional_missing_isEmpty() {
+ var bean = BeanInstantiator.of(OptionalFieldBean.class, beanStore).run();
+ assertNotNull(bean.maybe);
+ assertTrue(bean.maybe.isEmpty());
+ }
+
+ @Test
+ void a09_field_optional_present() {
+ Settings.get().setGlobal("Value_Test.optional", "have-value");
+ var bean = BeanInstantiator.of(OptionalFieldBean.class, beanStore).run();
+ assertNotNull(bean.maybe);
+ assertTrue(bean.maybe.isPresent());
+ assertEquals("have-value", bean.maybe.get());
+ }
+
+ //====================================================================================================
+ // Constructor-parameter injection.
+ //====================================================================================================
+
+ @Test
+ void b01_constructorParam_default() {
+ var bean = BeanInstantiator.of(ConstructorParamBean.class, beanStore).run();
+ assertEquals("bonjour", bean.greeting);
+ assertEquals(5000, bean.timeoutMs);
+ }
+
+ @Test
+ void b02_constructorParam_fromSettings() {
+ Settings.get().setGlobal("Value_Test.string", "salut");
+ Settings.get().setGlobal("Value_Test.timeout.ms", "250");
+ var bean = BeanInstantiator.of(ConstructorParamBean.class, beanStore).run();
+ assertEquals("salut", bean.greeting);
+ assertEquals(250, bean.timeoutMs);
+ }
+
+ //====================================================================================================
+ // Setter injection.
+ //====================================================================================================
+
+ @Test
+ void c01_setter_default() {
+ var bean = BeanInstantiator.of(SetterBean.class, beanStore).run();
+ assertEquals("via-setter", bean.field);
+ }
+
+ @Test
+ void c02_setter_fromSettings() {
+ Settings.get().setGlobal("Value_Test.setter", "from-settings");
+ var bean = BeanInstantiator.of(SetterBean.class, beanStore).run();
+ assertEquals("from-settings", bean.field);
+ }
+
+ //====================================================================================================
+ // Mutual-exclusion with @Inject.
+ //====================================================================================================
+
+ @Test
+ void d01_field_value_plus_inject_throws() {
+ var ex = assertThrows(BeanCreationException.class,
+ () -> BeanInstantiator.of(ConflictFieldBean.class, beanStore).run());
+ assertTrue(ex.getMessage().contains("@Value and @Inject are mutually exclusive"),
+ "Unexpected message: " + ex.getMessage());
+ }
+
+ @Test
+ void d02_parameter_value_plus_inject_throws() {
+ var ex = assertThrows(BeanCreationException.class,
+ () -> BeanInstantiator.of(ConflictParamBean.class, beanStore).run());
+ assertTrue(ex.getMessage().contains("@Value and @Inject are mutually exclusive"),
+ "Unexpected message: " + ex.getMessage());
+ }
+
+ //====================================================================================================
+ // Failure paths.
+ //====================================================================================================
+
+ @Test
+ void e01_primitive_missing_noDefault_throws() {
+ var ex = assertThrows(BeanCreationException.class,
+ () -> BeanInstantiator.of(PrimitiveMissingNoDefaultBean.class, beanStore).run());
+ assertTrue(ex.getMessage().contains("Could not resolve required @Value"),
+ "Unexpected message: " + ex.getMessage());
+ }
+
+ @Test
+ void e02_coerce_failure_wrapped() {
+ Settings.get().setGlobal("Value_Test.coerceFail", "not-a-number");
+ var ex = assertThrows(BeanCreationException.class,
+ () -> BeanInstantiator.of(CoerceFailureBean.class, beanStore).run());
+ assertTrue(ex.getMessage().contains("Could not coerce @Value"),
+ "Unexpected message: " + ex.getMessage());
+ }
+
+ //====================================================================================================
+ // Spring's @Value (FQN-detected).
+ //====================================================================================================
+
+ @Test
+ void g01_spring_value_default() {
+ var bean = BeanInstantiator.of(SpringValueFieldBean.class, beanStore).run();
+ assertEquals("spring-default", bean.value);
+ }
+
+ @Test
+ void g02_spring_value_fromSettings() {
+ Settings.get().setGlobal("Value_Test.springStyle", "spring-override");
+ var bean = BeanInstantiator.of(SpringValueFieldBean.class, beanStore).run();
+ assertEquals("spring-override", bean.value);
+ }
+
+ //====================================================================================================
+ // JsrSupport helpers — direct unit tests.
+ //====================================================================================================
+
+ @Test
+ void f01_isValueAnnotation_juneau() {
+ var f = org.apache.juneau.commons.reflect.ClassInfo.of(StringFieldBean.class)
+ .getDeclaredField(x -> "greeting".equals(x.getName())).orElseThrow();
+ assertTrue(f.getAnnotations().stream().anyMatch(JsrSupport::isValueAnnotation));
+ }
+
+ @Test
+ void f02_valueExpression_extractsValue() {
+ var f = org.apache.juneau.commons.reflect.ClassInfo.of(StringFieldBean.class)
+ .getDeclaredField(x -> "greeting".equals(x.getName())).orElseThrow();
+ var expr = f.getAnnotations().stream()
+ .map(JsrSupport::valueExpression)
+ .filter(Objects::nonNull)
+ .findFirst()
+ .orElse(null);
+ assertEquals("${" + P_STRING + ":hello}", expr);
+ }
+
+ @Test
+ void f03_valueExpression_returnsNull_forNonValueAnnotation() {
+ var f = org.apache.juneau.commons.reflect.ClassInfo.of(ConflictFieldBean.class)
+ .getDeclaredField(x -> "mixed".equals(x.getName())).orElseThrow();
+ var injectAnno = f.getAnnotations().stream()
+ .filter(a -> JsrSupport.isInjectAnnotation(a) && ! JsrSupport.isValueAnnotation(a))
+ .findFirst()
+ .orElseThrow();
+ assertNull(JsrSupport.valueExpression(injectAnno));
+ }
+
+ //====================================================================================================
+ // ValueResolver — direct unit tests for primitive boxing + null/empty branches.
+ //====================================================================================================
+
+ @Test
+ void h01_resolve_primitiveLong_coerced() {
+ Settings.get().setGlobal("Value_Test.long", "9999999999");
+ assertEquals(9999999999L, ValueResolver.resolve("${Value_Test.long}", long.class, "h01"));
+ Settings.get().unsetGlobal("Value_Test.long");
+ }
+
+ @Test
+ void h02_resolve_primitiveDouble_coerced() {
+ assertEquals(3.14, (Double) ValueResolver.resolve("${Value_Test.double:3.14}", double.class, "h02"), 0.001);
+ }
+
+ @Test
+ void h03_resolve_primitiveFloat_coerced() {
+ assertEquals(2.5f, (Float) ValueResolver.resolve("${Value_Test.float:2.5}", float.class, "h03"), 0.001f);
+ }
+
+ @Test
+ void h04_resolve_primitiveShort_coerced() {
+ assertEquals((short) 42, ValueResolver.resolve("${Value_Test.short:42}", short.class, "h04"));
+ }
+
+ @Test
+ void h05_resolve_primitiveByte_coerced() {
+ assertEquals((byte) 7, ValueResolver.resolve("${Value_Test.byte:7}", byte.class, "h05"));
+ }
+
+ @Test
+ void h06_resolve_primitiveChar_coerced() {
+ assertEquals('Z', ValueResolver.resolve("${Value_Test.char:Z}", char.class, "h06"));
+ }
+
+ @Test
+ void h07_resolve_referenceMissing_coercesEmptyToUri() {
+ // VarResolver lowers null→"" before ValueResolver sees it, so a missing-no-default key
+ // arrives as "". URI("") is a valid empty-URI value; we don't second-guess the coercion.
+ var u = (URI) ValueResolver.resolve("${Value_Test.missing.ref}", URI.class, "h07");
+ assertNotNull(u);
+ assertEquals("", u.toString());
+ }
+
+ @Test
+ void h07b_resolve_referenceMissing_coerceFailure_wrapped() {
+ // Non-String reference type that can't accept "" (Instant has no empty form) — must wrap.
+ var ex = assertThrows(BeanCreationException.class,
+ () -> ValueResolver.resolve("${Value_Test.missing.instant}", Instant.class, "h07b"));
+ assertTrue(ex.getMessage().contains("Could not coerce @Value"));
+ }
+
+ @Test
+ void h07c_resolve_charLength2_wraps() {
+ var ex = assertThrows(BeanCreationException.class,
+ () -> ValueResolver.resolve("${Value_Test.badchar:AB}", char.class, "h07c"));
+ assertTrue(ex.getMessage().contains("to char"));
+ }
+
+ @Test
+ void h08_resolve_emptyString_returnsEmptyForString() {
+ Settings.get().setGlobal("Value_Test.empty", "");
+ assertEquals("", ValueResolver.resolve("${Value_Test.empty}", String.class, "h08"));
+ Settings.get().unsetGlobal("Value_Test.empty");
+ }
+
+ @Test
+ void h09_findValueExpression_emptyList_returnsNull() {
+ assertNull(ValueResolver.findValueExpression(List.of()));
+ }
+
+ @Test
+ void h10_findValueExpression_nullList_returnsNull() {
+ assertNull(ValueResolver.findValueExpression(null));
+ }
+
+ @Test
+ void h11_hasValueAnnotation_emptyList_returnsFalse() {
+ assertFalse(ValueResolver.hasValueAnnotation(List.of()));
+ }
+
+ @Test
+ void h12_hasValueAnnotation_nullList_returnsFalse() {
+ assertFalse(ValueResolver.hasValueAnnotation(null));
+ }
+
+ @Test
+ void h13_checkInjectConflict_nullList_noop() {
+ assertDoesNotThrow(() -> ValueResolver.checkInjectConflict(null, "h13"));
+ }
+
+ @Test
+ void h14_checkInjectConflict_emptyList_noop() {
+ assertDoesNotThrow(() -> ValueResolver.checkInjectConflict(List.of(), "h14"));
+ }
+
+ @Test
+ void h15_checkInjectConflict_noValueAnnotation_noop() {
+ // annotations present, but none is @Value → should short-circuit on the !hasValue branch.
+ var f = org.apache.juneau.commons.reflect.ClassInfo.of(SetterBean.class)
+ .getMethod(x -> "setField".equals(x.getName())).orElseThrow();
+ assertDoesNotThrow(() -> ValueResolver.checkInjectConflict(f.getAnnotations(), "h15"));
+ }
+
+ @Test
+ void h16_resolve_nullExpression_returnsNullForRefType() {
+ // VarResolver.resolve(null) returns null; ValueResolver should pass that through for refs.
+ assertNull(ValueResolver.resolve(null, String.class, "h16"));
+ }
+
+ @Test
+ void h17_resolve_nullExpression_throwsForPrimitive() {
+ var ex = assertThrows(BeanCreationException.class,
+ () -> ValueResolver.resolve(null, int.class, "h17"));
+ assertTrue(ex.getMessage().contains("Could not resolve required @Value"));
+ }
+}
diff --git a/juneau-utest/src/test/java/org/apache/juneau/commons/reflect/ClassInfo_Test.java b/juneau-utest/src/test/java/org/apache/juneau/commons/reflect/ClassInfo_Test.java
index 9583e5f25b..75ee9a4c4c 100644
--- a/juneau-utest/src/test/java/org/apache/juneau/commons/reflect/ClassInfo_Test.java
+++ b/juneau-utest/src/test/java/org/apache/juneau/commons/reflect/ClassInfo_Test.java
@@ -37,6 +37,7 @@ import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.lang.*;
+import org.apache.juneau.commons.lang.Value; // Disambiguate vs. org.apache.juneau.commons.inject.Value (added in TODO-79).
import org.apache.juneau.commons.svl.*;
import org.junit.jupiter.api.*;
import org.springframework.beans.factory.annotation.Autowired;
diff --git a/juneau-utest/src/test/java/org/apache/juneau/commons/svl/DollarBraceShortcut_Test.java b/juneau-utest/src/test/java/org/apache/juneau/commons/svl/DollarBraceShortcut_Test.java
new file mode 100644
index 0000000000..faa9a5cccf
--- /dev/null
+++ b/juneau-utest/src/test/java/org/apache/juneau/commons/svl/DollarBraceShortcut_Test.java
@@ -0,0 +1,189 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.commons.svl;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.commons.settings.*;
+import org.junit.jupiter.api.*;
+
+/**
+ * Tests for the {@code ${xxx}} shortcut in {@link VarResolverSession}'s tokenizer.
+ *
+ * <p>
+ * The shortcut routes {@code ${xxx}} to {@code $P{xxx}} (i.e. through {@code PropertyVar}, which
+ * reads from {@link Settings}). The first top-level {@code ':'} in the body is rewritten to
+ * {@code ','} so Spring-idiom defaults {@code ${key:default}} resolve via {@code DefaultingVar}.
+ */
+class DollarBraceShortcut_Test extends TestBase {
+
+ private static final String K1 = "DollarBraceShortcut_Test.k1";
+ private static final String K2 = "DollarBraceShortcut_Test.k2";
+ private static final String K3 = "DollarBraceShortcut_Test.k3";
+ private static final String K_ENV = "DollarBraceShortcut_Test.envName";
+
+ @AfterEach
+ void cleanup() {
+ Settings.get().unsetGlobal(K1);
+ Settings.get().unsetGlobal(K2);
+ Settings.get().unsetGlobal(K3);
+ Settings.get().unsetGlobal(K_ENV);
+ Settings.get().unsetGlobal("DollarBraceShortcut_Test.staging.url");
+ Settings.get().unsetGlobal("DollarBraceShortcut_Test.prod.url");
+ }
+
+ //====================================================================================================
+ // Basic resolution.
+ //====================================================================================================
+
+ @Test
+ void a01_dollarBrace_resolvesFromSettings() {
+ Settings.get().setGlobal(K1, "from-settings");
+ assertEquals("from-settings", VarResolver.DEFAULT.resolve("${" + K1 + "}"));
+ }
+
+ @Test
+ void a02_dollarBrace_identicalToDollarP() {
+ Settings.get().setGlobal(K1, "v");
+ var dp = VarResolver.DEFAULT.resolve("$P{" + K1 + "}");
+ var db = VarResolver.DEFAULT.resolve("${" + K1 + "}");
+ assertEquals(dp, db, "${...} must resolve identically to $P{...}");
+ }
+
+ @Test
+ void a03_dollarBrace_missing_returnsLiteral() {
+ // PropertyVar.resolve returns null for missing key; with no default, DefaultingVar yields
+ // null, which the var-resolution layer converts to "".
+ assertEquals("", VarResolver.DEFAULT.resolve("${" + K1 + "}"));
+ }
+
+ //====================================================================================================
+ // Default-value syntax: ${key:default}
+ //====================================================================================================
+
+ @Test
+ void b01_dollarBrace_default_colonSeparator() {
+ assertEquals("bar", VarResolver.DEFAULT.resolve("${" + K1 + ":bar}"));
+ }
+
+ @Test
+ void b02_dollarBrace_default_presentValueWins() {
+ Settings.get().setGlobal(K1, "real");
+ assertEquals("real", VarResolver.DEFAULT.resolve("${" + K1 + ":fallback}"));
+ }
+
+ @Test
+ void b03_dollarBrace_default_multiColon_keepsTrailing() {
+ // First ':' is the separator; remaining ':' are part of the default literal.
+ assertEquals("postgres://localhost/db",
+ VarResolver.DEFAULT.resolve("${" + K1 + ":postgres://localhost/db}"));
+ }
+
+ @Test
+ void b04_dollarBrace_default_commaInDefaultStillWorks() {
+ // Translation rewrites the first top-level ':' to ','; pre-existing ',' in the default text
+ // is preserved by DefaultingVar (which splits on FIRST ',' only).
+ assertEquals("a,b,c", VarResolver.DEFAULT.resolve("${" + K1 + ":a,b,c}"));
+ }
+
+ //====================================================================================================
+ // Nested resolution: ${foo.${env}.url}
+ //====================================================================================================
+
+ @Test
+ void c01_dollarBrace_nestedKey() {
+ Settings.get().setGlobal(K_ENV, "staging");
+ Settings.get().setGlobal("DollarBraceShortcut_Test.staging.url", "https://staging.example/");
+ assertEquals("https://staging.example/",
+ VarResolver.DEFAULT.resolve("${DollarBraceShortcut_Test.${" + K_ENV + "}.url}"));
+ }
+
+ @Test
+ void c02_dollarBrace_innerColonIsInnerDefault() {
+ // Inner ${innerKey:inner-default} provides "inner-default" because innerKey is unset;
+ // outer ${k1:<inner>} sees k1 missing, falls back to "inner-default".
+ assertEquals("inner-default",
+ VarResolver.DEFAULT.resolve("${" + K1 + ":${" + K3 + ":inner-default}}"));
+ }
+
+ //====================================================================================================
+ // Backward compatibility: existing $X{...} forms still work.
+ //====================================================================================================
+
+ @Test
+ void d01_dollarP_stillWorks() {
+ Settings.get().setGlobal(K2, "p-val");
+ assertEquals("p-val", VarResolver.DEFAULT.resolve("$P{" + K2 + "}"));
+ }
+
+ @Test
+ void d02_dollarP_commaDefaultUnchanged() {
+ // $P{...} keeps the original DefaultingVar "," separator semantics; no ':' translation.
+ assertEquals("default-val", VarResolver.DEFAULT.resolve("$P{" + K2 + ",default-val}"));
+ }
+
+ @Test
+ void d03_dollarP_colonNotTranslated() {
+ // For explicit $P{...}, ':' is NOT a separator; the whole body is treated as a single key.
+ // Result is "" because key "k2:fallback" doesn't exist.
+ Settings.get().unsetGlobal(K2);
+ assertEquals("", VarResolver.DEFAULT.resolve("$P{" + K2 + ":fallback}"));
+ }
+
+ @Test
+ void d04_dollarS_systemPropertyVar_unchanged() {
+ System.setProperty("DollarBraceShortcut_Test.d04", "sys-val");
+ try {
+ assertEquals("sys-val", VarResolver.DEFAULT.resolve("$S{DollarBraceShortcut_Test.d04}"));
+ } finally {
+ System.clearProperty("DollarBraceShortcut_Test.d04");
+ }
+ }
+
+ //====================================================================================================
+ // Escape semantics.
+ //====================================================================================================
+
+ @Test
+ void e01_escapedDollar_keepsLiteral() {
+ assertEquals("${literal}", VarResolver.DEFAULT.resolve("\\${literal}"));
+ }
+
+ //====================================================================================================
+ // Embedded inside surrounding text (streaming path).
+ //====================================================================================================
+
+ @Test
+ void f01_embeddedInText() {
+ Settings.get().setGlobal(K1, "World");
+ assertEquals("Hello, World!", VarResolver.DEFAULT.resolve("Hello, ${" + K1 + "}!"));
+ }
+
+ @Test
+ void f02_embeddedWithDefault() {
+ assertEquals("Hello, stranger!", VarResolver.DEFAULT.resolve("Hello, ${" + K1 + ":stranger}!"));
+ }
+
+ @Test
+ void f03_multipleVarsInOneString() {
+ Settings.get().setGlobal(K1, "alpha");
+ Settings.get().setGlobal(K2, "beta");
+ assertEquals("alpha/beta",
+ VarResolver.DEFAULT.resolve("${" + K1 + "}/${" + K2 + "}"));
+ }
+}
diff --git a/juneau-utest/src/test/java/org/apache/juneau/config/ConfigPropertySourceProvider_Test.java b/juneau-utest/src/test/java/org/apache/juneau/config/ConfigPropertySourceProvider_Test.java
new file mode 100644
index 0000000000..c3f935d682
--- /dev/null
+++ b/juneau-utest/src/test/java/org/apache/juneau/config/ConfigPropertySourceProvider_Test.java
@@ -0,0 +1,177 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.config;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.commons.inject.*;
+import org.apache.juneau.commons.settings.*;
+import org.junit.jupiter.api.*;
+
+/**
+ * Tests for {@link ConfigPropertySourceProvider} — the auto-registered SPI bridge from {@link Config}
+ * to {@link Settings} introduced in Phase 3 of TODO-79.
+ *
+ * <p>
+ * Covers three layers:
+ * <ol>
+ * <li>SPI plumbing: the provider returns {@code null} silently when no classpath default exists.
+ * <li>SPI plumbing: the provider returns a {@link ConfigPropertySource} when a system default is set.
+ * <li>End-to-end: a {@code @Value("${...}")} bean resolves through {@link Settings#addSource(PropertySource)
+ * Settings.get().addSource(...)} the same way the microservice / RestContext hooks register their
+ * per-resource {@code Config}.
+ * </ol>
+ */
+@SuppressWarnings({
+ "java:S2094" // Test fixture / data class, no methods required.
+})
+class ConfigPropertySourceProvider_Test extends TestBase {
+
+ public static class ValueBean {
+ @Value("${ConfigPropertySourceProvider_Test/k}")
+ String value;
+ }
+
+ public static class ValueBeanWithDefault {
+ @Value("${ConfigPropertySourceProvider_Test/k:not-set}")
+ String value;
+ }
+
+ private BasicBeanStore beanStore;
+
+ @BeforeEach
+ void setUp() {
+ beanStore = new BasicBeanStore(null);
+ }
+
+ //====================================================================================================
+ // Provider semantics — direct unit tests.
+ //====================================================================================================
+
+ @Test
+ void a01_provider_silent_whenNoSystemDefault() {
+ // Provider always returns a non-null lazy source — eager resolution would create a
+ // Settings/Config static-initialization cycle (the SPI fires from Settings.<clinit>).
+ // "Silent when no config" means: every lookup on the source returns missing(), with no
+ // log noise and no exception.
+ var previous = Config.getSystemDefault();
+ Config.setSystemDefault(null);
+ try {
+ var provider = new ConfigPropertySourceProvider();
+ var src = provider.create();
+ assertNotNull(src, "Provider returns a lazy wrapper unconditionally");
+ var result = src.get("ConfigPropertySourceProvider_Test/k");
+ assertFalse(result.isPresent(),
+ "Lazy wrapper must report missing() when no system-default Config is set");
+ } finally {
+ Config.setSystemDefault(previous);
+ }
+ }
+
+ @Test
+ void a02_provider_returnsSource_whenSystemDefaultPresent() {
+ var previous = Config.getSystemDefault();
+ var cfg = Config.create().memStore().build();
+ cfg.set("ConfigPropertySourceProvider_Test/k", "from-system-default");
+ Config.setSystemDefault(cfg);
+ try {
+ var provider = new ConfigPropertySourceProvider();
+ var src = provider.create();
+ assertNotNull(src, "Provider must return a source when a system default exists");
+ var result = src.get("ConfigPropertySourceProvider_Test/k");
+ assertTrue(result.isPresent(), "Source must report present for set key");
+ assertEquals("from-system-default", result.value().orElse(null));
+ } finally {
+ Config.setSystemDefault(previous);
+ }
+ }
+
+ @Test
+ void a03_provider_order_lowSoUserAdditionsWin() {
+ // The provider deliberately sits at order 100 so later programmatic addSource() calls
+ // (microservice / RestContext) register AFTER it and therefore win at lookup time.
+ assertEquals(100, new ConfigPropertySourceProvider().order());
+ }
+
+ //====================================================================================================
+ // End-to-end: pushing a Config-backed source onto Settings and reading via @Value.
+ //====================================================================================================
+
+ @Test
+ void b01_endToEnd_addSource_shadowsDefault() {
+ var cfg = Config.create().memStore().build();
+ cfg.set("ConfigPropertySourceProvider_Test/k", "from-explicit-source");
+ var src = new ConfigPropertySource(cfg);
+ Settings.get().addSource(src);
+ try {
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("from-explicit-source", bean.value);
+ } finally {
+ assertTrue(Settings.get().removeSource(src),
+ "removeSource must report success when the source is present");
+ }
+ }
+
+ @Test
+ void b02_endToEnd_missing_usesDefault() {
+ // No source pushed — verify the @Value default path fires when nothing wins.
+ var bean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("not-set", bean.value);
+ }
+
+ @Test
+ void b03_endToEnd_microserviceOverride_winsOverFirstAdd() {
+ // Simulates the microservice path: a "base" source is registered first, then a "micro"
+ // source is registered later. The later source wins because Settings walks in reverse.
+ var base = Config.create().memStore().build();
+ base.set("ConfigPropertySourceProvider_Test/k", "base-val");
+ var micro = Config.create().memStore().build();
+ micro.set("ConfigPropertySourceProvider_Test/k", "micro-val");
+ var baseSrc = new ConfigPropertySource(base);
+ var microSrc = new ConfigPropertySource(micro);
+ Settings.get().addSource(baseSrc);
+ Settings.get().addSource(microSrc);
+ try {
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("micro-val", bean.value, "Later addSource() must shadow earlier addSource()");
+ } finally {
+ Settings.get().removeSource(microSrc);
+ Settings.get().removeSource(baseSrc);
+ }
+ }
+
+ @Test
+ void b04_removeSource_returnsFalse_whenSourceUnknown() {
+ var src = new ConfigPropertySource(Config.create().memStore().build());
+ assertFalse(Settings.get().removeSource(src),
+ "removeSource must return false for a never-added source");
+ }
+
+ //====================================================================================================
+ // SPI plumbing — verify the META-INF/services file is on the classpath.
+ //====================================================================================================
+
+ @Test
+ void c01_spiServiceFile_isOnClasspath() {
+ // The Phase 3 META-INF/services entry must ship with juneau-config so Settings.useServiceLoader()
+ // picks up the provider at startup. This guards against accidental deletion of the resource.
+ var url = ConfigPropertySourceProvider.class.getClassLoader()
+ .getResource("META-INF/services/org.apache.juneau.commons.settings.PropertySourceProvider");
+ assertNotNull(url, "META-INF/services entry for PropertySourceProvider must be discoverable");
+ }
+}
diff --git a/juneau-utest/src/test/java/org/apache/juneau/rest/Swagger_Test.java b/juneau-utest/src/test/java/org/apache/juneau/rest/Swagger_Test.java
index 96cdfc1655..4eec4a23af 100644
--- a/juneau-utest/src/test/java/org/apache/juneau/rest/Swagger_Test.java
+++ b/juneau-utest/src/test/java/org/apache/juneau/rest/Swagger_Test.java
@@ -28,6 +28,7 @@ import org.apache.juneau.annotation.*;
import org.apache.juneau.commons.annotation.Schema;
import org.apache.juneau.commons.annotation.ExternalDocs;
import org.apache.juneau.commons.lang.*;
+import org.apache.juneau.commons.lang.Value; // Disambiguate vs. org.apache.juneau.commons.inject.Value (added in TODO-79).
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.http.annotation.*;
import org.apache.juneau.http.annotation.Tag;
diff --git a/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringBeanStore_Test.java b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringBeanStore_Test.java
index 70a298ecee..5dd8212afa 100644
--- a/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringBeanStore_Test.java
+++ b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringBeanStore_Test.java
@@ -44,6 +44,13 @@ class SpringBeanStore_Test extends TestBase {
beanStore = new SpringBeanStore(mockAppContext, null);
}
+ @AfterEach
+ void tearDown() {
+ // Each SpringBeanStore constructor installs a SpringEnvironmentPropertySource on the
+ // process-wide Settings. Clear it after every test to prevent cross-test bleed.
+ beanStore.clear();
+ }
+
//====================================================================================================
// Test classes
//====================================================================================================
diff --git a/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_SpringbootIntegration_Test.java b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_SpringbootIntegration_Test.java
new file mode 100644
index 0000000000..65592c5e65
--- /dev/null
+++ b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_SpringbootIntegration_Test.java
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.rest.springboot;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.commons.inject.*;
+import org.apache.juneau.commons.settings.*;
+import org.junit.jupiter.api.*;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.*;
+import org.springframework.boot.autoconfigure.*;
+import org.springframework.boot.test.context.*;
+import org.springframework.context.*;
+import org.springframework.test.annotation.*;
+import org.springframework.test.context.*;
+
+/**
+ * Real-Spring-Boot integration test for the {@link SpringEnvironmentPropertySource} Phase-4
+ * bridge.
+ *
+ * <p>
+ * Boots a minimal Spring Boot context with three properties supplied through
+ * {@link TestPropertySource}, builds a {@link SpringBeanStore} from the resulting
+ * {@link ApplicationContext}, and verifies that:
+ *
+ * <ul>
+ * <li>{@code @Value("${spring.boot.demo.key}")} on a Juneau-instantiated bean resolves through
+ * the live Spring {@link org.springframework.core.env.Environment Environment} —
+ * i.e. exactly the same source as {@code @org.springframework.beans.factory.annotation.Value}.
+ * <li>Defaulting (the {@code :} suffix in the expression) fires when the key is absent from the
+ * Spring environment.
+ * <li>The bridge is auto-removed by {@link SpringBeanStore#clear()}, returning the
+ * {@link Settings} singleton to its pre-bridge state.
+ * </ul>
+ *
+ * <p>
+ * Mirrors the pattern used by {@code BasicStaticFilesResource_Springboot_Test} and friends:
+ * minimal {@code @SpringBootConfiguration} class, no web environment, dirty context after the
+ * class so subsequent tests don't see the bridge.
+ */
+@SpringBootTest(classes = SpringEnvironmentPropertySource_SpringbootIntegration_Test.TestApp.class,
+ webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@TestPropertySource(properties = {
+ "spring.boot.demo.key=from-application-yaml",
+ "spring.boot.demo.other=other-value"
+})
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+class SpringEnvironmentPropertySource_SpringbootIntegration_Test extends TestBase {
+
+ /**
+ * Minimal Spring Boot application — no servlets, no MVC, just enough to give us a populated
+ * {@link ApplicationContext}.
+ */
+ @SpringBootConfiguration
+ @EnableAutoConfiguration
+ public static class TestApp {
+ }
+
+ public static class ValueBean {
+ @Value("${spring.boot.demo.key}")
+ String value;
+ }
+
+ public static class ValueBeanWithDefault {
+ @Value("${spring.boot.demo.missing:fallback}")
+ String value;
+ }
+
+ @Autowired
+ private ApplicationContext appContext;
+
+ @Test
+ void a01_atValueResolvesAgainstApplicationYamlEquivalent() {
+ // Mirrors what BasicSpringRestServlet does: build a SpringBeanStore from the live context.
+ var store = new SpringBeanStore(appContext, null);
+ try {
+ var beanStore = new BasicBeanStore(null);
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("from-application-yaml", bean.value,
+ "@Value must resolve against the live Spring Environment via the auto-installed bridge");
+ } finally {
+ store.clear();
+ }
+ }
+
+ @Test
+ void a02_defaultFires_whenKeyAbsent() {
+ var store = new SpringBeanStore(appContext, null);
+ try {
+ var beanStore = new BasicBeanStore(null);
+ var bean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("fallback", bean.value);
+ } finally {
+ store.clear();
+ }
+ }
+
+ @Test
+ void a03_clearRemovesBridge() {
+ // Before any store is created, the bridge isn't installed → defaults fire.
+ var pre = new BasicBeanStore(null);
+ var preBean = BeanInstantiator.of(ValueBeanWithDefault.class, pre).run();
+ assertEquals("fallback", preBean.value);
+
+ var store = new SpringBeanStore(appContext, null);
+ try {
+ var beanStore = new BasicBeanStore(null);
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("from-application-yaml", bean.value);
+ } finally {
+ store.clear();
+ }
+
+ // After clear(), the bridge is removed. Looking up the configured key now misses the
+ // bridge entirely. Since the key has no fallback, ValueBean would fail — we verify the
+ // removal by checking that the defaulting bean still works (no leftover sources break it).
+ var postBean = BeanInstantiator.of(ValueBeanWithDefault.class, pre).run();
+ assertEquals("fallback", postBean.value);
+ }
+}
diff --git a/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_Test.java b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_Test.java
new file mode 100644
index 0000000000..d9b12eb5a0
--- /dev/null
+++ b/juneau-utest/src/test/java/org/apache/juneau/rest/springboot/SpringEnvironmentPropertySource_Test.java
@@ -0,0 +1,237 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.juneau.rest.springboot;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.commons.inject.*;
+import org.apache.juneau.commons.settings.*;
+import org.junit.jupiter.api.*;
+import org.springframework.context.*;
+import org.springframework.core.env.*;
+import org.springframework.mock.env.*;
+
+/**
+ * Tests for {@link SpringEnvironmentPropertySource} — the Phase 4 bridge from a Spring
+ * {@link Environment} into the Juneau {@link Settings} singleton.
+ *
+ * <p>
+ * Covers two layers:
+ * <ol>
+ * <li><b>Source semantics</b> (a-tier): direct unit tests against the {@link PropertySource}
+ * contract using {@link MockEnvironment} — present, missing, lazy supplier, null env, supplier
+ * throwing.
+ * <li><b>End-to-end</b> (b-tier): {@code @Value("${...}")} resolution through the global
+ * {@link Settings} singleton with the bridge attached, mirroring what Spring Boot does at
+ * {@link SpringBeanStore} construction time.
+ * </ol>
+ *
+ * <p>
+ * A full {@code @SpringBootTest} bootstrap (with {@code application.yaml} on the classpath) is
+ * exercised indirectly through the existing {@code BasicStaticFilesResource_Springboot_Test} and
+ * {@code BasicEchoResource_Springboot_Test} smoke tests — those already build a real Spring
+ * context which now installs the bridge automatically via {@link SpringBeanStore}'s constructor.
+ * This test keeps the focus on the bridge itself.
+ */
+@SuppressWarnings({
+ "java:S2094" // Test fixture / data class, no methods required.
+})
+class SpringEnvironmentPropertySource_Test extends TestBase {
+
+ public static class ValueBean {
+ @Value("${spring.demo.key}")
+ String value;
+ }
+
+ public static class ValueBeanWithDefault {
+ @Value("${spring.demo.missing:fallback}")
+ String value;
+ }
+
+ private BasicBeanStore beanStore;
+
+ @BeforeEach
+ void setUp() {
+ beanStore = new BasicBeanStore(null);
+ }
+
+ //====================================================================================================
+ // Source semantics — direct unit tests.
+ //====================================================================================================
+
+ @Test
+ void a01_get_returnsPresent_whenKeyExists() {
+ var env = new MockEnvironment().withProperty("spring.demo.key", "from-env");
+ var src = new SpringEnvironmentPropertySource(env);
+
+ var r = src.get("spring.demo.key");
+ assertTrue(r.isPresent());
+ assertEquals("from-env", r.value().orElse(null));
+ }
+
+ @Test
+ void a02_get_returnsMissing_whenKeyAbsent() {
+ var env = new MockEnvironment();
+ var src = new SpringEnvironmentPropertySource(env);
+
+ var r = src.get("spring.demo.key");
+ assertFalse(r.isPresent(), "Source must report missing() when key is not in the environment");
+ }
+
+ @Test
+ void a03_constructor_nullEnv_throwsNPE() {
+ assertThrows(NullPointerException.class,
+ () -> new SpringEnvironmentPropertySource((Environment) null));
+ }
+
+ @Test
+ void a04_supplierForm_resolvesLazily() {
+ // Supplier is held but not invoked until the first get() — verifies that the lazy form
+ // honors the contract that SpringBeanStore relies on (no interaction with the Spring
+ // context at SpringBeanStore construction time).
+ var env = new MockEnvironment().withProperty("spring.demo.key", "lazy-resolved");
+ var calls = new int[]{0};
+ var src = new SpringEnvironmentPropertySource(() -> {
+ calls[0]++;
+ return env;
+ });
+ assertEquals(0, calls[0], "Supplier must not be invoked at construction time");
+
+ var r = src.get("spring.demo.key");
+ assertEquals(1, calls[0], "Supplier must be invoked exactly once on first lookup");
+ assertTrue(r.isPresent());
+ assertEquals("lazy-resolved", r.value().orElse(null));
+
+ var r2 = src.get("spring.demo.key");
+ assertEquals(1, calls[0], "Supplier must be memoized — subsequent lookups must not re-invoke it");
+ assertTrue(r2.isPresent());
+ }
+
+ @Test
+ void a05_supplierForm_nullSupplierReturn_emitsMissing() {
+ // A null Environment is tolerated — e.g. a mocked ApplicationContext that doesn't stub
+ // getEnvironment(). Every lookup returns missing(), no NPE.
+ var src = new SpringEnvironmentPropertySource(() -> null);
+ var r = src.get("any.key");
+ assertFalse(r.isPresent());
+ }
+
+ @Test
+ void a06_supplierForm_throwingSupplier_emitsMissing() {
+ // safeOpt swallows supplier exceptions — the bridge should never fail a lookup just because
+ // the application context isn't ready or threw.
+ var src = new SpringEnvironmentPropertySource(() -> {
+ throw new IllegalStateException("not ready");
+ });
+ var r = src.get("any.key");
+ assertFalse(r.isPresent());
+ }
+
+ @Test
+ void a07_constructor_nullSupplier_throwsNPE() {
+ assertThrows(NullPointerException.class,
+ () -> new SpringEnvironmentPropertySource((java.util.function.Supplier<Environment>) null));
+ }
+
+ //====================================================================================================
+ // End-to-end: Settings.get().addSource(...) → @Value("${...}") resolution.
+ //====================================================================================================
+
+ @Test
+ void b01_endToEnd_resolveValueThroughSettings() {
+ var env = new MockEnvironment().withProperty("spring.demo.key", "via-settings");
+ var src = new SpringEnvironmentPropertySource(env);
+ Settings.get().addSource(src);
+ try {
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("via-settings", bean.value);
+ } finally {
+ assertTrue(Settings.get().removeSource(src));
+ }
+ }
+
+ @Test
+ void b02_endToEnd_defaultPath_whenKeyMissingEverywhere() {
+ // No source pushed — the @Value default token (after the colon) fires.
+ var bean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("fallback", bean.value);
+ }
+
+ @Test
+ void b03_endToEnd_laterAddSource_shadowsEarlier() {
+ // Two Spring-env sources stacked: the second one wins because Settings walks sources in
+ // reverse insertion order.
+ var base = new MockEnvironment().withProperty("spring.demo.key", "base-val");
+ var override = new MockEnvironment().withProperty("spring.demo.key", "override-val");
+ var baseSrc = new SpringEnvironmentPropertySource(base);
+ var overrideSrc = new SpringEnvironmentPropertySource(override);
+ Settings.get().addSource(baseSrc);
+ Settings.get().addSource(overrideSrc);
+ try {
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("override-val", bean.value, "Later addSource() must shadow earlier addSource()");
+ } finally {
+ Settings.get().removeSource(overrideSrc);
+ Settings.get().removeSource(baseSrc);
+ }
+ }
+
+ //====================================================================================================
+ // SpringBeanStore auto-registration — bridge installs and cleans up.
+ //====================================================================================================
+
+ @Test
+ void c01_springBeanStore_installsBridge_andClearRemovesIt() {
+ // Use a mocked ApplicationContext whose getEnvironment() returns a populated MockEnvironment.
+ var env = new MockEnvironment().withProperty("spring.demo.key", "via-springbeanstore");
+ var ctx = mock(ApplicationContext.class);
+ when(ctx.getEnvironment()).thenReturn(env);
+
+ // Before any SpringBeanStore is built, @Value lookup must miss → fall through to default.
+ var preBean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("fallback", preBean.value, "No bridge installed yet — default must fire");
+
+ var store = new SpringBeanStore(ctx, null);
+ try {
+ // Bridge installed by the constructor.
+ var bean = BeanInstantiator.of(ValueBean.class, beanStore).run();
+ assertEquals("via-springbeanstore", bean.value,
+ "@Value must resolve through the SpringBeanStore-installed bridge");
+ } finally {
+ store.clear();
+ }
+
+ // After clear(), the bridge is removed and lookups must miss again.
+ var postBean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("fallback", postBean.value, "After clear(), bridge must be removed");
+ }
+
+ @Test
+ void c02_springBeanStore_nullAppContext_noBridge() {
+ // Null appContext means no bridge — the constructor must not register a source at all.
+ var store = new SpringBeanStore(null, null);
+ try {
+ // No source registered → default path fires.
+ var bean = BeanInstantiator.of(ValueBeanWithDefault.class, beanStore).run();
+ assertEquals("fallback", bean.value);
+ } finally {
+ store.clear();
+ }
+ }
+}
diff --git a/juneau-utest/src/test/java/org/apache/juneau/utils/StringVarResolver_Test.java b/juneau-utest/src/test/java/org/apache/juneau/utils/StringVarResolver_Test.java
index d9de317272..01b3a164a3 100755
--- a/juneau-utest/src/test/java/org/apache/juneau/utils/StringVarResolver_Test.java
+++ b/juneau-utest/src/test/java/org/apache/juneau/utils/StringVarResolver_Test.java
@@ -220,8 +220,12 @@ class StringVarResolver_Test extends TestBase {
assertEquals(in, vr.resolve(in));
in = "${{foobar}";
assertEquals(in, vr.resolve(in));
+ // Note: "${$foobar}" used to be a "false trigger" (empty var name, unresolved). After the
+ // TODO-79 ${xxx} shortcut, "${...}" routes to $P{...} (Settings-backed PropertyVar) by
+ // default. The inner "$foobar" is not a valid var ref (no '{' follows), so the body
+ // becomes the literal "$foobar". Settings has no such key, so the result is "".
in = "${$foobar}";
- assertEquals(in, vr.resolve(in));
+ assertEquals("", vr.resolve(in));
System.setProperty("foobar", "baz");
diff --git a/todo/FINISHED-79-phase6-discovery-report.md b/todo/FINISHED-79-phase6-discovery-report.md
new file mode 100644
index 0000000000..9d994ec0d4
--- /dev/null
+++ b/todo/FINISHED-79-phase6-discovery-report.md
@@ -0,0 +1,130 @@
+# TODO-79 Phase 6 — discovery report (`@Value` internal adoption audit)
+
+Generated 2026-05-25 as part of TODO-79's Phase 6 ("Internal adoption audit + migration"). The OQA on this phase is **resolved as Option 1 — stay user-facing**: framework-internal sites do not migrate in TODO-79; they're filed under TODO-92.
+
+## TL;DR
+
+| Bucket | Count | Notes |
+|--------|-------|-------|
+| Migrate (this PR) | **0** | See "Migrate" section below — the user-facing surface for declarative `@Value` injection is currently very thin because the framework has historically centralized configuration into Builder/Settings/Config layers rather than directly into injection sites. |
+| Defer-Framework (TODO-92) | **9** | Framework-internal lifecycles (static initializers, builder constructors, bootstrap paths). See TODO-92-value-framework-internal-adoption.md. |
+| Skip | **45+** | Session-state property keys (`PROP_SerializerSession_*` etc.), `@Bean`-internal HTTP attribute constants (`PRINCIPAL_ATTR`, `REST_PATHVARS_ATTR`), source-of-truth property sources (`SystemPropertyPropertySource`, `SystemEnvPropertySource`) — these are not configuration knobs, they are the API itself. |
+| **Total candidates surveyed** | **~60** | Across `juneau-core`, `juneau-rest`, `juneau-microservice`, `juneau-examples`, `juneau-bct`. |
+
+## Methodology
+
+Ran the four ripgrep discovery patterns from TODO-79 Phase 6 across the production `src/main/java/` trees of:
+
+- `juneau-core/{juneau-commons,juneau-config,juneau-marshall,juneau-bct,juneau-assertions,juneau-bean,...}`
+- `juneau-rest/{juneau-rest-server,juneau-rest-server-springboot,juneau-rest-server-jwt,juneau-rest-client,juneau-rest-common,juneau-rest-mock,...}`
+- `juneau-microservice/juneau-microservice`
+- `juneau-examples/{juneau-examples-core,juneau-examples-rest,...}`
+
+Excluded: every `src/test/` tree, since test fixtures are about exercising the framework, not about being declaratively configured.
+
+```bash
+rg -n --type java 'System\.getProperty\(' juneau-core juneau-rest juneau-microservice
+rg -n --type java 'System\.getenv\(' juneau-core juneau-rest juneau-microservice
+rg -n --type java 'static\s+final\s+String\s+\w+\s*=\s*"\w+(\.\w+)+"' juneau-core juneau-rest juneau-microservice
+rg -n --type java 'jwksCacheTtl|rateLimitWindow|debugRequestHeader' juneau-rest
+```
+
+Plus a sweep of `juneau-examples` and a manual review of the FINISHED-20 / FINISHED-66 / FINISHED-69 / FINISHED-77 landings the plan flagged.
+
+## Classification rationale
+
+### Migrate (0 sites)
+
+The Phase 6 OQA bounds the migration scope to *user-facing* sites that are already on a `BeanInstantiator`-managed lifecycle — i.e. places where the framework constructs a bean *via* `BeanInstantiator` (so a user's own `@Value("${...}")` would also work there). Surveying the production tree, the framework's idiomatic pattern is:
+
+- Configuration knobs are exposed through *Builder* methods (`Microservice.Builder.logFile(...)`, `CallLogger.Builder.logger(...)`, `JwtTokenValidator.Builder.jwksCacheTtl(...)`).
+- Defaults for those Builder methods are either hard-coded constants or read via `env(...)` in the Builder *constructor* (not on injectable fields).
+- The Builder itself is constructed reflectively (`new Builder()`), not through `BeanInstantiator`.
+
+This means there are essentially **zero** built-in framework call sites that are already `BeanInstantiator`-managed AND read configuration AND are user-facing. The user-facing `@Value` pattern is something **users** apply to **their own** beans (custom `@Rest` hosts, `@Bean` factories, etc.) — which TODO-79 enables but doesn't itself exemplify in the framework code.
+
+This is not a Phase-6 failure — it's a finding. The proof-of-concept that `@Value` works lives in `Value_Test.java` (22 tests), `ConfigPropertySourceProvider_Test.java` (8 tests), `SpringEnvironmentPropertySource_Test.java` (12 tests), and `SpringEnvironmentPropertySource_SpringbootIntegration_Test.java` (3 tests). The plan's "5 migrations lower-bound" assumes the framework has natural `@Value` candidates; the audit shows it doesn't, by design.
+
+**Action:** ship TODO-79 without framework-side migrations. Users get the annotation; framework code stays as-is. If demand for "show me the framework using its own annotation" surfaces post-landing, TODO-92 is the vehicle.
+
+### Defer-Framework — TODO-92 (9 sites)
+
+All listed in detail in `todo/TODO-92-value-framework-internal-adoption.md`. Summary:
+
+| File | Lookup | Lifecycle |
+|------|--------|-----------|
+| `org.apache.juneau.commons.settings.DotenvPropertySource` | `juneau.dotenv.path` | Builder ctor |
+| `org.apache.juneau.commons.settings.ArgsPropertySource` | `sun.java.command`, `juneau.args` | Static helper |
+| `org.apache.juneau.config.Config` | `sun.java.command` (system-default discovery) | Bootstrap |
+| `org.apache.juneau.parquet.ParquetParserSession` | `juneau.parquet.debug`, `java.io.tmpdir` | Static `<clinit>` |
+| `org.apache.juneau.rest.logger.CallLogger.Builder` | `juneau.restLogger.{logger,enabled,requestDetail,responseDetail,level}` | Builder ctor |
+| `org.apache.juneau.rest.convention.BasicVersionResource.Builder.fromJavaVersion()` | `java.version` | Builder method |
+| `org.apache.juneau.rest.RestContext.Builder` defaults | various | Builder ctor |
+| `org.apache.juneau.rest.auth.jwt.JwtTokenValidator.Builder.jwksCacheTtl` | hard-coded 5min default | Builder field |
+| `org.apache.juneau.microservice.Microservice` bootstrap fields | logging level, port, etc. | Bootstrap |
+
+### Skip (45+ sites)
+
+Three sub-categories make up the bulk of the Skip bucket:
+
+1. **Session-state property keys** — every `PROP_*Session_*` constant in `juneau-marshall`'s serializer/parser sessions (40+ matches). These are session-scoped state-bag keys (e.g. `PROP_SerializerSession_javaMethod`), not configuration knobs. They live in `ContextSession.attribute(...)` maps, not in `Settings`.
+2. **HTTP attribute constants** — `RestServerConstants.PRINCIPAL_ATTR`, `RestSession.REST_PATHVARS_ATTR`, etc. These are request-attribute keys, not configurable knobs.
+3. **Source-of-truth `PropertySource` impls** — `SystemPropertyPropertySource`, `SystemEnvPropertySource`, `ArgsPropertySource`, `DotenvPropertySource`'s primary lookups. These *are* the implementation of property sources; routing them through `@Value` would be self-referential.
+
+## Test counts (new) — for the TODO-79 PR summary
+
+These cover the `@Value` resolution path through every documented site and source:
+
+| Test class | Tests |
+|------------|-------|
+| `Value_Test` | 22 |
+| `DollarBraceShortcut_Test` | 17 |
+| `ConfigPropertySourceProvider_Test` | 8 |
+| `SpringEnvironmentPropertySource_Test` | 12 |
+| `SpringEnvironmentPropertySource_SpringbootIntegration_Test` | 3 |
+| **Total new tests** | **62** |
+
+Full SVL regression: `mvn test -Dtest=*svl*` — 46 tests, all green (verified during Phase 2).
+
+## Follow-on TODOs filed alongside TODO-79
+
+- **TODO-92** — `@Value` framework-internal adoption pass (filed; inventory above).
+- **TODO-91** — not filed; only required if Phase 6 discovers >15 strong user-facing candidates, which it didn't.
+- **TODO-95** — Per-RestContext `@Value("${cfg-key}")` resolution against `@Rest(config=...)` Configs (filed 2026-05-25; deferred from the perf-regression cleanup described below).
+
+## Perf-regression cleanup (post-Phase-6, 2026-05-25)
+
+After Phase 6 landed, the full `juneau-utest` suite ran in **~560s** (Maven wall-clock; ~460s Surefire-sum) — a 16× slowdown vs the previous green baseline. Bisect (see git history of `RestContext.java`) traced the entire regression to a single change in `RestContext.build()`:
+
+```java
+// removed
+var rawCfg = rawConfig.get();
+if (nn(rawCfg)) {
+ settingsSource = new ConfigPropertySource(rawCfg);
+ Settings.get().addSource(settingsSource);
+}
+```
+
+with the matching `removeSource(...)` cleanup in `RestContext.destroy()`. The intent was per-resource bridging of `@Rest(config=...)` Configs into `Settings.get()` so `@Value("${cfg-key}")` on a REST resource bean would consult its own resource-scoped Config.
+
+**Mechanism of the regression.** `MockRestClient` (`juneau-rest-mock/.../classic/MockRestClient.java:1764`) caches `RestContext` instances in a `static Map<Class<?>,RestContext>` that never evicts, so `RestContext.destroy()` never runs during the test JVM and the bridge's `removeSource(...)` was never called. Each unique `@Rest` class in the suite permanently parked a `ConfigPropertySource` in the global `Settings.get()` source list. Every `Settings.get(name)` call thereafter did a rever [...]
+
+The same `RestOp_MarshalledConfig_Test` class ran in **1.86s in isolation** but **15.55s in the full suite**, with every one of its 7 tests showing a near-identical ~2.2s floor — the diagnostic fingerprint of an O(N) loop with a growing N firing per test.
+
+**Fix applied.** Both the `addSource(...)` block and the matching `removeSource(...)` cleanup were removed from `RestContext.java`, along with the now-unused `private ConfigPropertySource settingsSource` field and the `org.apache.juneau.commons.settings.*` import. `rawConfig.get()` is still invoked so `@Rest(config=...)` still fails fast on misconfiguration; only the global-Settings registration was dropped. An in-line comment at the vacated site points to TODO-95.
+
+**Verification.** Post-fix full-suite Maven wall-clock dropped to **84s** (down from ~560s; **6.7× faster**); Surefire-sum dropped to **58.6s** (down from ~460s). All **124,928 tests pass** (0 failures, 0 errors, 20 pre-existing skips). The top-10 slowest classes are now non-REST (config / html5-combo / temporal-format), matching the character of the pre-regression baseline.
+
+**Disabled tests.** None. None of the `@Value`-using tests (`Value_Test`, `DollarBraceShortcut_Test`, `ConfigPropertySourceProvider_Test`, `SpringEnvironmentPropertySource_Test`, `SpringEnvironmentPropertySource_SpringbootIntegration_Test`) exercise the removed `@Rest(config=...)` bridge — they all resolve through `Settings.get().setGlobal(...)`, default expressions, system properties, env vars, the SPI-registered classpath-default `juneau.cfg`, or the Spring `Environment` bridge, all of [...]
+
+**Deferred to TODO-95.** Re-introducing per-resource `@Value("${cfg-key}")` resolution against `@Rest(config=...)` Configs by routing through the per-RestContext `BeanStore` (or a request-scope `ThreadLocal<RestContext>`) instead of mutating the process-wide `Settings` singleton.
+
+## Acceptance-criteria check (TODO-79 Phase 6)
+
+| Criterion | Status |
+|-----------|--------|
+| Discovery report exists | ✅ this file |
+| At least 5 migrations land in this PR | ⚠ **0 user-facing migrations** — see Migrate rationale above. OQA-bounded scope means the audit's honest answer is zero, not five. Recommend dropping the "5 lower bound" as ill-suited to the resolved-OQA scope. |
+| All migrated sites carry release-notes mentions | N/A (no migrations) |
+| Tests for migrated sites pass | N/A (no migrations) |
+| Follow-on TODO filed if scope overflows | TODO-92 filed for the framework-internal deferred bucket |
diff --git a/todo/FINISHED.md b/todo/FINISHED.md
new file mode 100644
index 0000000000..9059e32a1b
--- /dev/null
+++ b/todo/FINISHED.md
@@ -0,0 +1,95 @@
+# FINISHED
+
+Completion log for the Juneau 9.5.0 development cycle. New entries are added at the **top** of the "Recent completions" section as TODOs land; older entries are summarized in the compact index below. Each entry points to its detailed `FINISHED-<id>-<slug>.md` archive file in this directory.
+
+The live work plan is in [`TODO.md`](TODO.md). Items are moved here when they land (and removed from `TODO.md`) — never marked `[x]` or struck-through in place.
+
+---
+
+## Recent completions (9.5.0)
+
+In completion order, oldest-to-newest within the foundations + mixin family + recent feature work that drove the 9.5.0 cycle's headline changes.
+
+### Foundations + mixin family
+
+1. **TODO-73** — Runtime-overridable `@Rest(paths=...)`. Foundational; unblocked TODO-74–78. See [`FINISHED-73-rest-paths-runtime-override.md`](FINISHED-73-rest-paths-runtime-override.md).
+2. **TODO-81** — Mixin sub-`RestContext` inheritance. Promoted mixin classes to embedded sub-resources with their own `RestContext` parent-linked to the host. Lazy initialization, annotation inheritance walks, `noInherit` semantics, dual-firing lifecycle hooks. See [`FINISHED-81-mixin-sub-context-inheritance.md`](FINISHED-81-mixin-sub-context-inheritance.md).
+3. **TODO-74** — API-docs mixin pack (Swagger, Swagger-UI, OpenAPI, Redoc). Introduced `BasicSwaggerResource`, `BasicSwaggerUiResource`, `BasicOpenApiResource`, `BasicRedocResource` + `@OpSwagger(ignore=true)`. 100% test coverage, real-container (Jetty, Spring Boot) parity tests. See [`FINISHED-74-mixin-api-docs.md`](FINISHED-74-mixin-api-docs.md).
+4. **TODO-75** — Static-files mixin (`BasicStaticFilesResource`). HEAD support, OpenAPI spec exclusion, `HttpResourceProcessor` enhancement for HEAD requests. 100% coverage. See [`FINISHED-75-mixin-static-files.md`](FINISHED-75-mixin-static-files.md).
+5. **TODO-76** — Convention-endpoints pack (`BasicFaviconResource`, `BasicSeoResource`, `BasicVersionResource`, `BasicWellKnownResource`). `RestContext.buildMixinContext` retune for `BeanStore`-first mixin lookup. 95% branch coverage. See [`FINISHED-76-mixin-convention-endpoints.md`](FINISHED-76-mixin-convention-endpoints.md).
+6. **TODO-77** — Ops/introspection pack (`BasicEchoResource`, `BasicAdminResource`, `BasicRouteIndexResource`). Introduced `org.apache.juneau.rest.guard.DenyAllGuard` as secure-by-default placeholder for `BasicAdminResource`. 88% branch coverage. See [`FINISHED-77-mixin-ops-introspection.md`](FINISHED-77-mixin-ops-introspection.md).
+
+### Phase A — auth
+
+7. **TODO-69** — AuthN guards + isolated `juneau-rest-server-jwt` sub-module. `BearerTokenGuard`, `ApiKeyGuard`, `TokenValidator` SPI, `ApiKeyStore` SPI, `@Auth Principal` arg-resolver, `AuthenticationException`, `ClaimsPrincipal`. `nimbus-jose-jwt` in dedicated module (`provided` scope) to avoid dependency bleed. Secure defaults for JWKS TTL, algorithm allowlist, mandatory claims. See [`FINISHED-69-authn-guards-jwt-apikey.md`](FINISHED-69-authn-guards-jwt-apikey.md).
+
+### Phase B — debug rethink
+
+8. **TODO-20** — Rest debug rethink. Collapsed five `@Rest`/`@RestOp` debug attributes + `DebugEnablement` + parallel `CallLogger` rule lists into a single `DebugConfig` bean + a typed `@Debug` annotation. **Hard break** (no deprecation cycle; migration notes in `juneau-docs/pages/topics/23.01.V9.5-migration-guide.md`). **Source-of-truth pattern** — `@Debug` nested as `@Rest(debug=@Debug(...))` and `@RestOp(debug=@Debug(...))` so the `@Rest`/`@RestOp` annotation is the canonical capabili [...]
+
+---
+
+## Earlier completions (9.5.0 cycle, compact index)
+
+Plans landed earlier in the 9.5.0 development cycle. One-line summary per entry; the linked archive file is the source of truth for design context, decisions, and migration notes.
+
+- **TODO-4** — Duration format control. See [`FINISHED-4-duration-format-control.md`](FINISHED-4-duration-format-control.md).
+- **TODO-5** — Bean runtime types moved to `juneau-commons`. See [`FINISHED-5-bean-runtime-types-to-commons.md`](FINISHED-5-bean-runtime-types-to-commons.md).
+- **TODO-6** — AI short-description scaffolding. See [`FINISHED-6-ai-short-description.md`](FINISHED-6-ai-short-description.md).
+- **TODO-7** — Decouple `juneau-rest-common` from `juneau-marshall`. See [`FINISHED-7-decouple-rest-common-from-marshall.md`](FINISHED-7-decouple-rest-common-from-marshall.md).
+- **TODO-8** — JSON Schema bean generation. See [`FINISHED-8-jsonschema-bean-generation.md`](FINISHED-8-jsonschema-bean-generation.md).
+- **TODO-9** — Markdown remaining issues cleanup. See [`FINISHED-9-markdown-remaining-issues.md`](FINISHED-9-markdown-remaining-issues.md).
+- **TODO-10** — Move `@Http` annotation to `juneau-rest-common`. See [`FINISHED-10-move-http-annotation-to-rest-common.md`](FINISHED-10-move-http-annotation-to-rest-common.md).
+- **TODO-11a** — RestClient NG design plan. See [`FINISHED-11a-restclient-ng-design-plan.md`](FINISHED-11a-restclient-ng-design-plan.md).
+- **TODO-11b** — RestClient NG coverage closeout. See [`FINISHED-11b-restclient-ng-coverage-closeout.md`](FINISHED-11b-restclient-ng-coverage-closeout.md).
+- **TODO-12** — Schema validation. See [`FINISHED-12-schema-validation.md`](FINISHED-12-schema-validation.md).
+- **TODO-13** — System-properties → `Settings` conversion. See [`FINISHED-13-system-properties-to-settings-conversion.md`](FINISHED-13-system-properties-to-settings-conversion.md).
+- **TODO-14** — `BeanPropertyMeta` map-key coercion. See [`FINISHED-14-beanpropertymeta-map-key-coercion.md`](FINISHED-14-beanpropertymeta-map-key-coercion.md).
+- **TODO-15** — Replace `BasicBeanStore` with v2. See [`FINISHED-15-replace-basicbeanstore-with-v2.md`](FINISHED-15-replace-basicbeanstore-with-v2.md).
+- **TODO-16** — `@Bean` property-meta inventory + builder deletion (multi-phase). See [`FINISHED-16.md`](FINISHED-16.md), [`FINISHED-16a-per-setting-inventory.md`](FINISHED-16a-per-setting-inventory.md), [`FINISHED-16b-phases-1-2-execution.md`](FINISHED-16b-phases-1-2-execution.md), [`FINISHED-16c-phase-3-builder-deletion.md`](FINISHED-16c-phase-3-builder-deletion.md).
+- **TODO-17** — 9.2.x → 9.5.0 migration-guide audit. See [`FINISHED-17-9.2.x-9.5.0-migration-guide-audit.md`](FINISHED-17-9.2.x-9.5.0-migration-guide-audit.md).
+- **TODO-18** — REST-server feature brainstorm (catalogued follow-on TODOs). See [`FINISHED-18-rest-server-feature-brainstorm.md`](FINISHED-18-rest-server-feature-brainstorm.md).
+- **TODO-21a** — `@Bean` / `@Inject` annotation rename. See [`FINISHED-21-bean-inject-annotation-rename.md`](FINISHED-21-bean-inject-annotation-rename.md).
+- **TODO-21b** — `@Bean` annotations moved to the `inject` package. See [`FINISHED-21-bean-annotations-inject-package.md`](FINISHED-21-bean-annotations-inject-package.md).
+- **TODO-22** — SVL external config vars. See [`FINISHED-22-svl-external-config-vars.md`](FINISHED-22-svl-external-config-vars.md).
+- **TODO-24** — JSR-330 + Spring-lite support. See [`FINISHED-24-jsr330-and-spring-lite-support.md`](FINISHED-24-jsr330-and-spring-lite-support.md).
+- **TODO-25** — Revisit `RestContext` memoizer migration. See [`FINISHED-25-revisit-rest-context-memoizer-migration.md`](FINISHED-25-revisit-rest-context-memoizer-migration.md).
+- **TODO-26** — Replace `BeanBuilder` with `BeanInstantiator`. See [`FINISHED-26-replace-beanbuilder-with-beaninstantiator.md`](FINISHED-26-replace-beanbuilder-with-beaninstantiator.md).
+- **TODO-29** — See [`FINISHED-29.md`](FINISHED-29.md).
+- **TODO-30** — `ClassMeta` moved to `juneau-commons`. See [`FINISHED-30-classmeta-to-commons.md`](FINISHED-30-classmeta-to-commons.md).
+- **TODO-31** — Inject-aware Microservice. See [`FINISHED-31-inject-aware-microservice.md`](FINISHED-31-inject-aware-microservice.md).
+- **TODO-33** — Dynamic REST children. See [`FINISHED-33-dynamic-rest-children.md`](FINISHED-33-dynamic-rest-children.md).
+- **TODO-34** — `MarshalledMap` / `MarshalledList`. See [`FINISHED-34-marshalledmap-marshalledlist.md`](FINISHED-34-marshalledmap-marshalledlist.md).
+- **TODO-35** — `@TestBean` + `JuneauBeanStoreExtension` (test-time bean injection). See [`FINISHED-35-beanstore-test-injection.md`](FINISHED-35-beanstore-test-injection.md).
+- **TODO-36** — Jetty as a bean. See [`FINISHED-36-jetty-as-bean.md`](FINISHED-36-jetty-as-bean.md).
+- **TODO-38** — Rename `juneau-rest-client` to `juneau-rest-client-classic`. See [`FINISHED-38-rename-rest-client-to-classic.md`](FINISHED-38-rename-rest-client-to-classic.md).
+- **TODO-39** — `/sonarqube` command + `scripts/sonarqube.py`. See [`FINISHED-39-sonarqube-command.md`](FINISHED-39-sonarqube-command.md).
+- **TODO-40** — Remove HttpClient 4.5 from `juneau-rest-common` + `juneau-rest-server`. See [`FINISHED-40-remove-hc45-from-rest-common-and-server.md`](FINISHED-40-remove-hc45-from-rest-common-and-server.md).
+- **TODO-41** — Merge Java HttpClient default transport. See [`FINISHED-41-merge-java-httpclient-default-transport.md`](FINISHED-41-merge-java-httpclient-default-transport.md).
+- **TODO-42** — Split `juneau-rest-common` / classic. See [`FINISHED-42-split-rest-common-classic.md`](FINISHED-42-split-rest-common-classic.md).
+- **TODO-45** — `juneau-bean-rfc7807`. See [`FINISHED-45-juneau-bean-rfc7807.md`](FINISHED-45-juneau-bean-rfc7807.md).
+- **TODO-46** — `juneau-marshall-sse` module. See [`FINISHED-46-juneau-marshall-sse.md`](FINISHED-46-juneau-marshall-sse.md).
+- **TODO-47** — Additional bean modules. See [`FINISHED-47-additional-bean-modules.md`](FINISHED-47-additional-bean-modules.md).
+- **TODO-48** — Empty-return marshalled collections. See [`FINISHED-48-empty-return-marshalled-collections.md`](FINISHED-48-empty-return-marshalled-collections.md).
+- **TODO-49** — `SchemaUtils` null returns. See [`FINISHED-49-schemautils-null-returns.md`](FINISHED-49-schemautils-null-returns.md).
+- **TODO-50** — Format-control extension. See [`FINISHED-50-format-control-extension.md`](FINISHED-50-format-control-extension.md).
+- **TODO-54** — Format-control round 2. See [`FINISHED-54-format-control-round-2.md`](FINISHED-54-format-control-round-2.md).
+- **TODO-56** — Serializer/parser dispatch cleanup. See [`FINISHED-56-serializer-parser-dispatch-cleanup.md`](FINISHED-56-serializer-parser-dispatch-cleanup.md).
+- **TODO-57** — Format round-trip tests. See [`FINISHED-57-format-round-trip-tests.md`](FINISHED-57-format-round-trip-tests.md).
+- **TODO-58** — `BeanMap` typed set-element coercion. See [`FINISHED-58-beanmap-typed-set-element-coercion.md`](FINISHED-58-beanmap-typed-set-element-coercion.md).
+- **TODO-59** — `BeanMap` abstract-collection default type. See [`FINISHED-59-beanmap-abstract-collection-default-type.md`](FINISHED-59-beanmap-abstract-collection-default-type.md).
+- **TODO-61** — RFC 7807 server-side wiring. See [`FINISHED-61-rfc7807-server-side-wiring.md`](FINISHED-61-rfc7807-server-side-wiring.md).
+- **TODO-62** — SSE server helpers. See [`FINISHED-62-sse-server-helpers.md`](FINISHED-62-sse-server-helpers.md).
+- **TODO-63** — OpenAPI 3.1 emission. See [`FINISHED-63-openapi-3.1-emission.md`](FINISHED-63-openapi-3.1-emission.md).
+- **TODO-64** — ETag / conditional-GET helpers. See [`FINISHED-64-etag-conditional-get-helpers.md`](FINISHED-64-etag-conditional-get-helpers.md).
+- **TODO-65** — Health / readiness / liveness probes. See [`FINISHED-65-health-readiness-liveness-probes.md`](FINISHED-65-health-readiness-liveness-probes.md).
+- **TODO-66** — Rate limit + request-id. See [`FINISHED-66-rate-limit-and-request-id.md`](FINISHED-66-rate-limit-and-request-id.md).
+- **TODO-72** — REST mixins + `@Rest(paths=...)` prelude. See [`FINISHED-72-rest-mixins-and-paths.md`](FINISHED-72-rest-mixins-and-paths.md).
+
+---
+
+## Conventions
+
+- **Add an entry here when the work lands.** Workflow: when a TODO is finished, archive its plan to `todo/FINISHED-<id>-<slug>.md` (per the existing `/todo cleanup` flow), remove the bullet from `TODO.md`, and add a new entry to the **top** of "Recent completions" above with a one-paragraph summary + link to the archive file.
+- **Promote rich entries to the compact index over time.** As "Recent completions" grows beyond ~10–15 entries, move the oldest ones into "Earlier completions" with one-line summaries so the recent section stays focused on the current dev cycle's headline work.
+- **Never re-introduce a finished bullet in `TODO.md`.** Re-opening work means filing a new TODO with a fresh id (and back-pointer to the finished entry here).
diff --git a/todo/TODO-79-value-annotation-config-bridge.md b/todo/TODO-79-value-annotation-config-bridge.md
index 9f39e36a8e..39a7df2f33 100644
--- a/todo/TODO-79-value-annotation-config-bridge.md
+++ b/todo/TODO-79-value-annotation-config-bridge.md
@@ -285,31 +285,28 @@ rg -n --type java 'jwksCacheTtl|rateLimitWindow|debugRequestHeader' \
- Phase 6 runs **before or alongside** Phase 5 (docs); the docs phase's
release-notes entries pick up the migrated sites.
-## Open questions
-
-1. **Internal-only framework knob migration.** Phase 6's discovery will
- probably surface framework-internal config reads in places like
- `juneau-microservice/Microservice.java`'s own bootstrap config knobs,
- `RestContext.Builder` default-value handling, `DebugConfig`'s
- system-property defaults (from FINISHED-20), `JwtTokenValidator`'s JWKS
- TTL default (from FINISHED-69), etc. — most of which are NOT exposed to
- end-users as `@Value`-injectable fields today; they're hand-rolled in
- static initializers or constructors. Two paths:
-
- 1. **Stay user-facing.** Phase 6 only migrates sites that are already
- on a `BeanInstantiator`-managed lifecycle (i.e. sites where a user
- would naturally place `@Value` themselves). Internal sites get a
- defer note. Smaller, lower-risk PR.
- 2. **Include framework internals.** Refactor framework-internal config
- readers to flow through a `BeanInstantiator`-resolved seam so they
- can carry `@Value` too. Larger PR, but tightens the dogfooding
- story significantly — Juneau's own framework code becomes a
- reference implementation of `@Value` usage patterns.
-
- Recommendation: **(1) stay user-facing in Phase 6**, plant the seed
- for (2) as TODO-92 follow-on if the user wants the framework-internal
- pass as a deliberate effort. Awaiting user OQA before Phase 6
- discovery starts (so the discovery report scopes correctly).
+## Resolved decisions — Phase 6
+
+1. **Internal-only framework knob migration — RESOLVED 2026-05-25 as Option 1
+ (stay user-facing).** Phase 6's discovery scope is bounded to sites that
+ are already on a `BeanInstantiator`-managed lifecycle — i.e. sites where
+ a user would naturally place `@Value` themselves (e.g. user-defined
+ `@Bean` factories, `@Rest`-host constructors, custom `RestServlet`
+ subclasses with `@Inject` constructors). Framework-internal config
+ readers that today hand-roll lookups in static initializers or
+ un-injected constructors (notably `juneau-microservice/Microservice.java`
+ bootstrap, `RestContext.Builder` defaults, `DebugConfig`'s
+ system-property defaults from FINISHED-20, `JwtTokenValidator`'s JWKS
+ TTL default from FINISHED-69) are out of Phase 6 scope. Each surfaces in
+ the discovery report under the **Defer** bucket with a `TODO-92`
+ reference.
+
+ A follow-on **TODO-92 — `@Value` framework-internal adoption pass**
+ will be filed alongside TODO-79's landing to track the larger
+ refactor (route framework-internal config readers through a
+ `BeanInstantiator`-resolved seam so they can carry `@Value`). It is
+ deliberately a separate PR — keeps TODO-79 reviewable and lets the
+ framework-internal pass be sequenced independently.
## Risk notes
diff --git a/todo/TODO-82-view-module-thymeleaf.md b/todo/TODO-82-view-module-thymeleaf.md
index 6be5214ef4..fe61fb785c 100644
--- a/todo/TODO-82-view-module-thymeleaf.md
+++ b/todo/TODO-82-view-module-thymeleaf.md
@@ -215,10 +215,14 @@ Sibling view-module TODOs (TODO-83/84) inherit this test architecture by default
- Localization / i18n integration with Juneau's existing `Messages` infrastructure (Thymeleaf has its own `MessageSource` abstraction; bridge could adapter-wrap `Messages`).
- Reactive / WebFlux integration once Juneau's async story (TODO-70) lands.
+## Resolved decisions — OQA
+
+1. **Default `index.html` template in the bridge — RESOLVED 2026-05-25 as NO.** Bridge ships no opinionated default template. The "Choosing a `TemplateEngine`" matrix in the module README + the example module (Phase 4) are the discoverability path; a zero-config deployment with no user-supplied templates returns 404 from `/thymeleaf/*` with a clear "no template named X under base-path Y" message. Aligns with the plan's prior recommendation and matches FINISHED-75's "no opinionated defaul [...]
+2. **JVM floor — RESOLVED 2026-05-25 as CONFIRMED (JDK 17).** Juneau's stated floor is already JDK 17 (verified in `juneau-core/pom.xml`), so Thymeleaf 3.1.x is usable without pinning back to 3.0.x and without a per-module floor bump. Phase 0's "verify before settling" check is satisfied; no further action.
+
## Open questions
-1. **Default `index.html` template in the bridge?** Should the bridge ship a tiny `index.html` template so a zero-config "hello world" deployment renders SOMETHING at `/thymeleaf/index`? Pro: discoverability. Con: bloat + opinionated default that users will want to delete. **Recommend: NO**, but flagged for user review.
-2. **JVM floor.** Thymeleaf 3.1+ requires JDK 17 per the Thymeleaf release notes. Juneau's current stated floor is JDK 17 already (verify in `juneau-core/pom.xml`); if the floor is lower, this module either bumps the floor for itself only or pins to Thymeleaf 3.0.x. **Verify in Phase 0** before settling.
+_All open questions resolved 2026-05-25. See "Resolved decisions — OQA" above._
## Risks
diff --git a/todo/TODO-83-view-module-mustache.md b/todo/TODO-83-view-module-mustache.md
index 657780a879..b73fa95eb8 100644
--- a/todo/TODO-83-view-module-mustache.md
+++ b/todo/TODO-83-view-module-mustache.md
@@ -211,10 +211,14 @@ Sibling view-module TODOs (TODO-82/84) inherit this test architecture by default
- Localization / i18n integration with Juneau's existing `Messages` infrastructure — Mustache is logic-less so the i18n integration is a thin shim that passes resolved messages in as scope attributes.
- First-class `com.samskivert:jmustache` bridge (separate `MustacheViewRenderer` variant) for users who prefer jmustache (or who already have `spring-boot-starter-mustache` on the classpath).
+## Resolved decisions — OQA
+
+1. **Default `index.mustache` template in the bridge — RESOLVED 2026-05-25 as NO.** Bridge ships no opinionated default template. Zero-config deployment with no user-supplied templates returns 404 with a clear "no template named X under base-path Y" message. Aligns with the plan's prior recommendation, the FINISHED-75 "no opinionated defaults in the mixin" stance, and the parallel TODO-82 OQA decision.
+2. **`.mustache` vs `.html` extension default — RESOLVED 2026-05-25 as CONFIGURABLE.** Bridge default behavior is unchanged ("no implicit suffix" — the literal `templateName` passed to `MustacheView.of(...)` is used as-is, which matches `mustache.java`'s own convention). But the builder gains a `.templateSuffix(String suffix)` knob (default `""`/none) so users can opt into `.mustache`, `.html`, or any other implicit suffix without re-typing it at every call site. When set, the bridge app [...]
+
## Open questions
-1. **Default `index.mustache` template in the bridge?** Should the bridge ship a tiny `index.mustache` template so a zero-config "hello world" deployment renders SOMETHING at `/mustache/index.mustache`? **Recommend: NO**, but flagged for user review.
-2. **`.mustache` vs `.html` extension default.** Mustache templates traditionally use `.mustache` but some teams use `.html` to keep IDE / editor highlighting clean. The bridge default uses the literal `templateName` passed to `MustacheView.of(...)` as-is — no implicit suffix. Worth flagging in case the user prefers an implicit suffix policy.
+_All open questions resolved 2026-05-25. See "Resolved decisions — OQA" above._
## Risks
diff --git a/todo/TODO-84-view-module-freemarker.md b/todo/TODO-84-view-module-freemarker.md
index 721c65a10a..8ead550f6e 100644
--- a/todo/TODO-84-view-module-freemarker.md
+++ b/todo/TODO-84-view-module-freemarker.md
@@ -223,10 +223,14 @@ Sibling view-module TODOs (TODO-82/83) inherit this test architecture by default
- SQL / database template loader sample showing how to supply a custom `Configuration` for non-classpath template sources.
- `OutputFormat` customization beyond HTML / plain-text (XML, RTF, custom escape policies).
+## Resolved decisions — OQA
+
+1. **Default `index.ftlh` template in the bridge — RESOLVED 2026-05-25 as NO.** Bridge ships no opinionated default template. Zero-config deployment with no user-supplied templates returns 404 with a clear "no template named X under base-path Y" message. Aligns with the plan's prior recommendation, the FINISHED-75 "no opinionated defaults in the mixin" stance, and the parallel TODO-82 / TODO-83 OQA decisions.
+2. **`Configuration.VERSION_2_3_X` pin — RESOLVED 2026-05-25 as PINNED-WITH-DELIBERATE-BUMPS.** Bridge default constructs the fallback `Configuration` with an explicitly pinned `IncompatibleImprovements` version (e.g. `Configuration.VERSION_2_3_32` for v1) so behavior is stable across consumer upgrades of `org.freemarker:freemarker`. Bumping the pin is a deliberate per-release decision documented in the release notes (auto-escape defaults / exception-handler defaults / etc. that change b [...]
+
## Open questions
-1. **Default `index.ftlh` template in the bridge?** Should the bridge ship a tiny `index.ftlh` template so a zero-config "hello world" deployment renders SOMETHING at `/freemarker/index.ftlh`? **Recommend: NO**, but flagged for user review.
-2. **`Configuration.VERSION_2_3_X` pin.** The bridge pins `IncompatibleImprovements` to a specific minor version. Newer FreeMarker minors may change defaults (auto-escape rules, exception-handling defaults) — the pin protects against silent behavior drift, but means the bridge has to opt-in to newer behavior via a version bump. Worth flagging in case the user wants a different pinning policy (e.g. always-latest).
+_All open questions resolved 2026-05-25. See "Resolved decisions — OQA" above._
## Risks
diff --git a/todo/TODO-86-petstore-jetty-app.md b/todo/TODO-86-petstore-jetty-app.md
index d077a2eb68..e02bab5987 100644
--- a/todo/TODO-86-petstore-jetty-app.md
+++ b/todo/TODO-86-petstore-jetty-app.md
@@ -1,6 +1,6 @@
# TODO-86: `juneau-petstore-jetty` — canonical Jetty sample application
-Source: split out of the TODO.md backlog on 2026-05-23; plan written 2026-05-24.
+Source: split out of the TODO.md backlog on 2026-05-23; plan written 2026-05-24. Scope-expansion notes added 2026-05-25 (see "Update notes" section below — pending OQA before propagating through the rest of the plan).
## Goal
@@ -24,6 +24,88 @@ java -jar target/juneau-petstore-jetty-9.5.0.jar
A reader who opens `juneau-petstore-jetty` should be able to point at any feature in the post-FINISHED-77 mixin family — plus runtime-overridable paths (FINISHED-73), AuthN guards (TODO-69), and a non-trivial bean model exercised across the marshall layer — and see a working in-context example.
+## Update notes (2026-05-25)
+
+User-supplied additions to consider while expanding this plan. These are **flagged for OQA** before the Scope §1 module structure, §3 feature table, and Phase 0–7 step list are revised to match — the changes below grow the v1 footprint substantially and the scope-affecting open questions need user direction first.
+
+### 1. Existing `apache/juneau-petstore` repo (legacy)
+
+There is a legacy Juneau petstore at <https://github.com/apache/juneau-petstore> with three subprojects (`juneau-petstore-api`, `juneau-petstore-server`, `juneau-petstore-client`). It is **very old** — predates the FINISHED-72/74/75/76/77 mixin family, FINISHED-73 runtime-paths, FINISHED-69 AuthN guards, FINISHED-81 sub-context inheritance, and the v9.5.x marshall layer changes. **Not sure how much is applicable** — Phase 0 should add an inventory pass:
+
+- **Domain model** (`Pet` / `Order` / `Customer` shape) — probably still right (Swagger Petstore is a stable reference); verify and reuse the bean shapes if they match.
+- **`@Remote` interface shape** (in legacy `juneau-petstore-api`) — directly applicable to the new `juneau-petstore-api` module proposed below; likely some boilerplate is reusable verbatim, but the `@Remote` / `@RemoteOp` annotation surface may have evolved post-FINISHED-38 (rest-client → rest-client-classic rename).
+- **Server-side resource structure** (legacy `juneau-petstore-server`) — likely obsolete (pre-mixin-family); read as historical context only, do NOT copy.
+- **Client-side `RestClient.getRemote(...)` patterns** (legacy `juneau-petstore-client`) — directly applicable to the proposed new `juneau-petstore-client` module; same `@Remote`-proxy invocation shape.
+- **Apache-2.0 license headers** — any reused snippets must carry compliant headers in the new tree (RAT will catch missing ones, but easier to prepend at copy-time).
+- **Dockerfile** — the legacy repo ships a Dockerfile; per the existing OQ #2 (Docker out of scope for v1) we ignore it for now.
+
+The legacy repo will eventually need an "archived in favor of the in-tree petstore" pointer in its README; tracked as a follow-on (not part of TODO-86 acceptance).
+
+### 2. Multiple view-engine examples side-by-side
+
+The current plan picks ONE view engine per deployment (Thymeleaf preferred, JSP fallback per resolved decision #3) and routes `/views/about` to it. The expanded scope wants the petstore to demonstrate **multiple engines side-by-side** so readers see the bridge pattern across engines without spinning up multiple sample apps. Proposed adaptation:
+
+- Add `/views/jsp/about`, `/views/thymeleaf/about`, `/views/mustache/about`, `/views/freemarker/about` endpoints, each backed by the corresponding view-engine module (TODO-78 / TODO-82 / TODO-83 / TODO-84).
+- Each endpoint renders the same `AboutModel` so readers can compare templates side-by-side.
+- Each engine is opt-in via a Maven profile (e.g. `-Pviews-jsp,views-thymeleaf,...`) so consumers who don't want every engine on the classpath aren't forced to pull them.
+- **Hard prereq on TODO-78** (introduces the `View` interface); soft prereq on TODO-82/83/84 (each adds its own endpoint when present, skipped otherwise).
+- The `/views/about` URL from the current plan would either become a default that aliases to one of the engine-specific endpoints, or be replaced by an index page at `/views/` listing the available engines.
+
+**Open question (OQ-A):** ship all four engine endpoints in v1 (gated by TODO-78/82/83/84 landing), or only the engines that have landed by the time TODO-86 starts implementation? **Tentative recommend:** ship whatever's landed; document the rest as `/views/<engine>/about` 404 stubs with a "to be added when TODO-XX lands" pointer.
+
+### 3. `@Remote`-annotated interfaces for accessing REST
+
+Promote the legacy repo's `juneau-petstore-api` + `juneau-petstore-client` split into the new tree. Proposed module additions:
+
+- **`juneau-petstore-api`** (NEW, sibling of `juneau-petstore-core` under `juneau-petstore/`) — contains the `PetService` / `OrderService` / `CustomerService` Java interfaces annotated with `@Remote` + `@RemoteOp(method=GET, path="/pets/{id}")`-style member annotations. Server-side resource classes implement these interfaces; client-side uses `RestClient.create().build().getRemote(PetService.class)` to get a proxy. Pure interfaces + DTO references; no server or in-memory-impl code.
+- **`juneau-petstore-client`** (NEW, sibling of `juneau-petstore-jetty`) — client-side library + a small `App.java` that exercises every server-side endpoint via `@Remote` proxies against `http://localhost:10000`. Demonstrates `getRemote(PetService.class)`, paging through results, error handling, request-bean / response-bean conventions, and the client-side auth flavors from §4 below.
+
+**Open question (OQ-B):** should the `@Remote` interfaces live in `juneau-petstore-core` (collapsing api + core into one module) or stay in a separate `juneau-petstore-api` (matching the legacy repo split)? **Tentative recommend:** **separate**, because `juneau-petstore-core` contains the in-memory repository impls which are server-only; `juneau-petstore-api` is pure interface + DTO reference and is shared 1:1 between server and client. Module graph becomes:
+
+```
+juneau-petstore-core (DTOs + repository SPI + in-memory impls)
+juneau-petstore-api (depends on -core's DTOs only; @Remote interfaces)
+juneau-petstore-jetty (depends on -core + -api; implements -api's interfaces)
+juneau-petstore-client (depends on -api only; @Remote proxy consumer)
+juneau-petstore-springboot (depends on -core + -api; TODO-87's deliverable)
+```
+
+### 4. Various authentication flavors with REST client examples
+
+Currently TODO-86's auth story is "one `BearerTokenGuard` on `/admin/*`". Expanded scope demonstrates multiple AuthN flavors side-by-side, both server-side AND client-side:
+
+**Server-side** (separate guarded mount-paths per flavor):
+
+- `/admin/jwt/*` → `BearerTokenGuard` (FINISHED-69)
+- `/admin/apikey/*` → `ApiKeyGuard` (FINISHED-69)
+- `/admin/saml/*` → `SamlFilter` (TODO-94b)
+- `/admin/oauth/*` → `OAuthFilter` (TODO-94c)
+
+**Client-side** (in the proposed `juneau-petstore-client`, each flavor shown as a separate `RestClient` builder configuration):
+
+- `RestClient.create().bearerAuth(jwt).build()` calling `/admin/jwt/*`
+- `RestClient.create().header("X-API-Key", apiKey).build()` calling `/admin/apikey/*`
+- SAML / OAuth equivalents once TODO-94b/c land (with stubs in v1 if those haven't landed yet).
+
+**Hard prereq on FINISHED-69** (JWT + ApiKey); **soft prereq on TODO-94a/b/c** (filter framework + SAML + OAuth — each flavor lands when its TODO lands).
+
+**Open question (OQ-C):** should the client examples be a single class in `juneau-petstore-client` with all four flavors demoed, or split across separate `juneau-petstore-client-examples-jwt` / `-apikey` / `-saml` / `-oauth` sub-modules? **Tentative recommend:** **single class** in `juneau-petstore-client` with `@DisplayName`-style headings per flavor; multiple example modules feels over-engineered for v1.
+
+### Scope expansion summary
+
+These additions grow TODO-86 from **3 modules** (`core` + `jetty` + Spring-Boot-stub) to **5 modules** (`core` + `api` + `jetty` + `client` + Spring-Boot-stub) and from **one** view-engine endpoint to **four**. Soft-dep surface grows from `{TODO-69, TODO-82-or-TODO-78, TODO-85}` to `{FINISHED-69, TODO-78, TODO-82, TODO-83, TODO-84, TODO-85, TODO-94a, TODO-94b, TODO-94c}`. TODO-87 (Spring Boot mirror) will inherit the same scope changes — the `@Remote` interfaces + multiple view engines + [...]
+
+Once OQ-A, OQ-B, OQ-C are answered, expand:
+
+- **Scope §1** (module structure) — add `juneau-petstore-api` + `juneau-petstore-client` per OQ-B's resolution.
+- **Scope §3** (feature cross-section table) — add rows for `@Remote` interfaces, multi-engine views, and the four auth flavors.
+- **Scope §5** (view-rendered HTML page) — re-shape to "view-engine showcase" with per-engine endpoints.
+- **Phase 0** — add the legacy-repo inventory pass + a step for the new module wiring.
+- **Phase 2–5** — restructure to land `-api` + `-client` modules; restructure §5 to multi-engine; restructure §6 to multi-auth.
+- **Phase 6** smoke test — add per-`@Remote`-interface integration assertions + per-view-engine endpoint assertions + per-auth-flavor 401/200 assertions.
+- **Related work** — add FINISHED-38 (rest-client-classic rename), TODO-94a/b/c, the legacy repo URL.
+- **Risks** — add "scope sprawl" + "soft-dep matrix complexity" (any TODO-94 sub-piece slipping cascades into the petstore's auth-flavor showcase being incomplete).
+
## Why now
- After FINISHED-74/75/76/77 + FINISHED-73 + FINISHED-81 + (in-flight) TODO-69, Juneau has the broadest "you can compose a real service in five mixins" surface area it's ever had — but no single sample app exercises the whole surface. `juneau-examples-rest-jetty` predates the mixin family and reads as a feature collection rather than as a cohesive application.
diff --git a/todo/TODO-92-value-framework-internal-adoption.md b/todo/TODO-92-value-framework-internal-adoption.md
new file mode 100644
index 0000000000..60293fe9a4
--- /dev/null
+++ b/todo/TODO-92-value-framework-internal-adoption.md
@@ -0,0 +1,64 @@
+# TODO-92 — `@Value` framework-internal adoption pass
+
+Source: filed during TODO-79 Phase 6 discovery on 2026-05-25.
+
+## Goal
+
+Route Juneau's framework-internal config readers — places that today hand-roll `System.getProperty(...)` / `System.getenv(...)` / `env(...)` lookups inside static initializers, builder constructors, or non-injectable lifecycles — through a `BeanInstantiator`-resolved seam so they can carry `@Value("${...}")`. Picks up where TODO-79 Phase 6 deliberately stopped.
+
+## Why this is a separate TODO
+
+TODO-79's Phase 6 OQA was explicitly resolved as "stay user-facing": migrate only sites that are already on a `BeanInstantiator`-managed lifecycle. Framework-internal config readers need a non-trivial refactor (route through a bean-store seam first), which is out of scope for the `@Value` introduction PR. Splitting it out keeps both PRs reviewable.
+
+## Inventory (carried over from TODO-79 Phase 6 discovery report)
+
+Each entry lists the file and the specific lookup that should ultimately become `@Value`-driven. The bucket "Defer-Framework" means "framework-internal lifecycle, not directly injectable today".
+
+### juneau-commons
+
+- **`org.apache.juneau.commons.settings.DotenvPropertySource`** (lines 55-57) — reads `juneau.dotenv.path` from `System.getProperty(...)` then `System.getenv(...)` in a builder constructor. Currently bootstrap code; needs a seam to be made injectable.
+- **`org.apache.juneau.commons.settings.ArgsPropertySource`** (lines 51, 56) — reads `sun.java.command` and `juneau.args` in a static helper. Bootstrap-level; defer.
+
+### juneau-config
+
+- **`org.apache.juneau.config.Config.getCandidateSystemDefaultConfigNames()`** (line 533) — reads `sun.java.command` to derive the system-default config file name. This is the bootstrap path for `Config.getSystemDefault()` itself; cannot be `@Value`-driven without breaking the cycle.
+
+### juneau-marshall
+
+- **`org.apache.juneau.parquet.ParquetParserSession`** (lines 61, 78) — `juneau.parquet.debug` and `java.io.tmpdir` reads in static field initializers. Class-load-time only; defer.
+
+### juneau-rest-server
+
+- **`org.apache.juneau.rest.logger.CallLogger.Builder`** (lines 134-139) — `juneau.restLogger.{logger,enabled,requestDetail,responseDetail,level}` lookups via `env(...)` in the no-arg builder constructor. Already goes through `Settings.get(...)` but isn't `@Value`-annotated because the builder is reflectively instantiated without a bean store. Route through `BeanInstantiator` and add `@Value` slots.
+- **`org.apache.juneau.rest.convention.BasicVersionResource.Builder.fromJavaVersion()`** (line 334) — reads `java.version` via `System.getProperty(...)`. Inside a builder method called by user code; could become `@Value("${java.version:?}")` on a field if the builder were converted to `BeanInstantiator`-managed.
+- **`org.apache.juneau.rest.RestContext.Builder`** defaults — the resource-scoped `Config` is now bridged to `Settings` by TODO-79, but `RestContext.Builder`'s own defaulting code (encoders, serializers, logging levels) still hand-rolls system-property reads. TODO-92 should sweep these.
+
+### juneau-rest-server-jwt (FINISHED-69)
+
+- **`org.apache.juneau.rest.auth.jwt.JwtTokenValidator.Builder.jwksCacheTtl`** (line 119) — defaults to `Duration.ofMinutes(5)` in the builder; ideally `@Value("${juneau.jwt.jwksCacheTtl:PT5M}")`. Requires routing the builder through `BeanInstantiator`.
+
+### juneau-microservice (TODO-79 Phase 3 already partially addressed)
+
+- **`org.apache.juneau.microservice.Microservice`** bootstrap — TODO-79 wires the microservice's `Config` into `Settings`, so `@Value` works for any bean *built by the microservice*. The microservice's own bootstrap fields (logging level, port, etc.) are still set via builder methods, not `@Value`. TODO-92 should route those through `BeanInstantiator`.
+
+### juneau-bct
+
+- **`org.apache.juneau.junit.bct.BctConfiguration.BCT_SORT_MAPS` / `BCT_SORT_COLLECTIONS`** (lines 111, 125) — already reads from system properties via `env(...)`; not currently injectable but could be after the BCT config layer is routed through `BeanInstantiator`.
+
+## Approach (sketch)
+
+1. Identify the "seam class" for each entry — the smallest unit that can be migrated from "reflectively instantiated, no bean store" to "constructed via `BeanInstantiator` with a bean store".
+2. For each seam class, add a `BeanInstantiator.of(...).run()` constructor path (typically a static factory) and a `@Value`-annotated field/parameter.
+3. Migrate existing call sites to the new factory.
+4. Delete the hand-rolled `env(...)` / `System.getProperty(...)` reads, leave the `SP_xxx` string constants alone (they remain the canonical property names — `@Value` references them indirectly through the `${...}` expression).
+5. Update tests.
+
+## Sequencing
+
+- Land after TODO-79.
+- Each module's pass can ship independently; recommend `juneau-commons` first (smallest seam), then `juneau-rest-server` (largest payoff).
+
+## Out of scope
+
+- Anything in `Config.<clinit>` itself — the bootstrap path can't depend on `@Value` without cycles.
+- Static `<clinit>`-time field initializers — those run before any bean store exists; they stay as `env(...)` reads.
diff --git a/todo/TODO-94a-auth-filter-framework.md b/todo/TODO-94a-auth-filter-framework.md
new file mode 100644
index 0000000000..a882c00527
--- /dev/null
+++ b/todo/TODO-94a-auth-filter-framework.md
@@ -0,0 +1,360 @@
+# TODO-94a: Auth filter framework — pluggable servlet-filter chain in `JettyMicroservice`
+
+Source: promoted from `TODO.md` on 2026-05-25 during `/todo expand 94` (multi-file split per AGENTS.md letter-suffix precedent — see FINISHED-16a/b/c).
+
+## Goal
+
+Add a Juneau-idiomatic pluggable AuthN servlet-filter framework that runs at the **servlet** layer (before Juneau's request routing) so a single URL can support multiple, overlapping authentication options (e.g. *Bearer JWT* OR *API key* OR *SAML assertion*), short-circuit on the first success, aggregate roles when more than one succeeds, and surface the resolved `Principal` + roles to downstream `@Guard`-annotated REST ops via the standard `HttpServletRequest.getUserPrincipal()` / `isUs [...]
+
+Lives in `juneau-rest-server` (core) so SAML / OAuth (TODO-94b / TODO-94c) sibling modules can simply ship `AuthFilter` impls without reinventing the chain mechanics. Adds the missing filter-registration surface to `juneau-microservice-jetty` since it has none today (see Research findings #1).
+
+End-state developer experience:
+
+```java
+// Microservice path:
+public class MyMicroservice extends JettyMicroservice {
+ @Bean
+ public AuthFilterChain authFilters(BeanStore bs) {
+ return AuthFilterChain.create(bs)
+ // /api/** accepts Bearer JWT OR API key — first to succeed wins; roles aggregate when both do.
+ .append(BearerTokenAuthFilter.create()
+ .pattern("/api/*")
+ .validator(jwtValidator)
+ .build())
+ .append(ApiKeyAuthFilter.create()
+ .pattern("/api/*")
+ .store(myApiKeyStore)
+ .build())
+ // /sso/** accepts only a SAML assertion (provided by juneau-rest-server-saml — TODO-94b).
+ .append(SamlAuthFilter.create()
+ .pattern("/sso/*")
+ .validator(samlValidator)
+ .build())
+ .build();
+ }
+}
+
+// @Guard sees the filter-resolved Principal via the standard servlet surface, no extra wiring:
+@Rest(path="/api")
+public class ApiResource {
+ @RestGet("/me")
+ @Guard(roles="user|admin") // RoleBasedRestGuard reads req.isUserInRole(...) which the filter populated
+ public Profile me(@Auth Principal p) { // @Auth (FINISHED-69) returns the same Principal the filter stashed
+ return profileService.lookup(p.getName());
+ }
+}
+```
+
+## Why now
+
+- **Direct extension of FINISHED-69.** FINISHED-69 shipped op-level AuthN via `BearerTokenGuard` / `ApiKeyGuard` + `TokenValidator` / `ApiKeyStore` SPIs, but those run **inside** `RestContext.handleCall(...)` — too late to authenticate a request before, say, a static-file mount or a non-`RestServlet` endpoint co-located on the same Jetty context. A servlet-layer filter chain is the missing peer.
+- **No filter-registration surface in `juneau-microservice-jetty` today.** `JettyServerComponent.addServlet(...)` exists; there is no `addFilter(...)`. Users wiring auth into a Juneau microservice today must subclass `JettyServerComponent` and call `ServletContextHandler.addFilter(...)` directly — workable but undocumented and not symmetric with the `@Bean RestGuardList` style FINISHED-69 established. TODO-94a fixes both problems with a single SPI.
+- **TODO-94b / TODO-94c sibling modules need a stable filter SPI to ship against.** Without this layer, both SAML and OAuth would have to reinvent the chain mechanics independently and the resulting designs would diverge.
+- **`UrlPathMatcher` already exists** (`juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/UrlPathMatcher.java`) — supports `/foo/{var}` named-var paths, trailing `/*` remainder syntax, and `*.ext` filename matching. The framework reuses it verbatim; no new pattern language.
+- **`RoleBasedRestGuard` already reads `req.isUserInRole(...)`** so role aggregation Just Works if the filter wraps the request with an `HttpServletRequestWrapper` that returns aggregated roles. No new SPI on the guard side.
+
+## Research findings (verified 2026-05-25)
+
+Significant facts from reading the current tree that shape the design:
+
+1. **`juneau-microservice-jetty` has NO filter-registration surface today.** `rg 'FilterHolder|jakarta\.servlet\.Filter' juneau-microservice/juneau-microservice-jetty` returns zero hits. `JettyServerComponent` (the lifecycle component, `JettyServerComponent.java`) exposes `addServlet(Servlet, String)` / `addServlet(Servlet, String...)` and a public `getServletContextHandler()` accessor; users wanting a filter today must call `ServletContextHandler.addFilter(...)` themselves via that esca [...]
+
+2. **`UrlPathMatcher` syntax already covers the framework's needs.** Located at `juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/UrlPathMatcher.java`. Supported forms (per the `compareTo` doc):
+ - Filename: `foo.bar`, `*.bar`
+ - Path: `/foo`, `/foo/bar`, `/foo/bar/*`
+ - Path with vars: `/foo/{id}/bar`, `/foo/{id}/*`
+ - Trailing remainder: `/foo/*` (matches `/foo/anything/deep/here`)
+ Static factory `UrlPathMatcher.of(String)`. No new pattern syntax needs to be invented.
+
+3. **`RestGuard` AuthZ-time integration is trivial.** `RoleBasedRestGuard.isRequestAllowed(req)` (`juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/guard/RoleBasedRestGuard.java` line 74-77) does `req.isUserInRole(role)`. `RestRequest` inherits `isUserInRole(String)` from `HttpServletRequest`. A filter that wraps the request via `HttpServletRequestWrapper` and overrides `getUserPrincipal()` + `isUserInRole(String)` populates both surfaces in one step — `RoleBasedRestGu [...]
+
+4. **FINISHED-69's AuthN types are filter-ready.** `TokenValidator` (single-method functional interface returning `Principal`), `ApiKeyStore` (`Optional<Principal> lookup(String)`), `AuthenticationException` (with `wwwAuthenticate(String)` fluent setter), and `ClaimsPrincipal` (extends `Principal`, exposes typed claims) all live in `org.apache.juneau.rest.auth`. The filter framework wraps these — no new validator SPIs needed for the JWT / API-key cases. The framework adds ONLY the chain [...]
+
+5. **`RestServerConstants.PRINCIPAL_ATTR = "juneau.principal"`** is the FINISHED-69 attribute key the filter chain reuses verbatim. The `@Auth` arg-resolver (FINISHED-69) reads from this attribute, so a filter that stashes its resolved principal under the same key gives downstream `@Auth Principal p` parameters the right answer with no extra wiring. Same for `RestServerConstants.API_KEY_HEADER` (default `"X-API-Key"`) — reused by the API-key filter.
+
+6. **`juneau-rest-server-springboot` uses Spring's own filter chain.** `BasicSpringRestServlet` is mounted via Spring's `ServletRegistrationBean`; auth filters under Spring Boot are typically registered via Spring's `FilterRegistrationBean`. TODO-94a must decide whether the framework also runs under Spring Boot (via a parallel auto-registration in the `springboot` module) or is Jetty-microservice-only with documented Spring Security as the recommended Spring path. See Open question 1.
+
+## Resolved decisions
+
+1. **Filter SPI lives in core `juneau-rest-server`, not a separate module.** Same containment stance as FINISHED-69's core `BearerTokenGuard` / `ApiKeyGuard` (which ship in core; only the JWT validator implementation is module-isolated). The framework adds zero new transitive deps to `juneau-rest-server` — uses only `jakarta.servlet.*` which `juneau-rest-server` already declares — so containment is preserved.
+
+2. **Reuse `UrlPathMatcher` (per Research finding #2).** Do NOT introduce a parallel pattern syntax. The framework accepts one or more `String` patterns per filter; each is fed to `UrlPathMatcher.of(...)` once at filter-build time. Pattern semantics inherit whatever `UrlPathMatcher` provides today and benefit from future enhancements automatically.
+
+3. **Short-circuit on first success; aggregate failures.** When multiple filters apply to the same request (per pattern matching), iterate in registered order. The **first** filter that returns a non-null `Principal` wins for principal resolution. Subsequent applicable filters are then run **only for role contribution** (controlled by a `boolean aggregateRolesOnSuccess` per-filter setting, default `true`) so role aggregation happens but principal identity stays deterministic. If ALL appl [...]
+
+4. **Role aggregation via `HttpServletRequestWrapper`.** The chain installs a single wrapper instance per request; each successful filter contributes roles into a shared `Set<String>` carried by the wrapper. `getUserPrincipal()` returns the principal of the **first** successful filter (deterministic); `isUserInRole(String)` checks the union set. This makes `RoleBasedRestGuard` work unchanged and keeps the "one principal, many roles" invariant that downstream code expects.
+
+5. **`AuthFilter` extends `jakarta.servlet.Filter` directly — do NOT invent a parallel SPI.** The framework adds Juneau-shaped helpers (`pattern(String)`, `aggregateRolesOnSuccess(boolean)`, etc.) on top of the standard `Filter` contract, but `AuthFilter implements Filter` so the underlying objects can also be registered directly with raw Jetty / Spring Boot `FilterRegistrationBean` for users who want to bypass the chain wrapper. Keeps the framework non-imposing.
+
+6. **Filter chain runs BEFORE Juneau's request routing** (because it's a servlet `Filter`, by definition). This means filters see every request — including static-file mounts and non-`RestServlet` endpoints on the same context. Pattern matching is the gate; filters whose patterns don't match are skipped per-request.
+
+7. **No auto-registration on `JettyMicroservice`.** Mirrors FINISHED-69's Resolved Decision #5 ("No auto-registered default `RestGuardList`") — explicit `@Bean AuthFilterChain` registration only. Silently enabling auth on resources that didn't ask for it is a security footgun.
+
+8. **Apache RAT / OSGi packaging** matches `juneau-rest-server` (no new module — code ships in the existing core jar). No POM changes; no new transitive deps.
+
+## Architecture
+
+```mermaid
+flowchart TB
+ subgraph servlet [jakarta.servlet layer]
+ Req[HttpServletRequest in]
+ JFW["JuneauAuthFilterChain<br/>(implements Filter)<br/>added to ServletContextHandler<br/>by JettyServerComponent.addFilter(...)"]
+ Wrap[HttpServletRequestWrapper<br/>with aggregated principal + roles]
+ end
+ subgraph juneau [Juneau RestContext layer]
+ RC[RestServlet.service]
+ RG["RestGuardList<br/>(RoleBasedRestGuard reads<br/>req.isUserInRole(...))"]
+ Op["@RestGet handler<br/>(@Auth Principal p)"]
+ end
+ subgraph spi [SPI: pluggable AuthFilter impls]
+ BJ[BearerTokenAuthFilter<br/>uses TokenValidator<br/>FINISHED-69]
+ AK[ApiKeyAuthFilter<br/>uses ApiKeyStore<br/>FINISHED-69]
+ SA[SamlAuthFilter<br/>TODO-94b]
+ OA[OAuthFilter<br/>TODO-94c]
+ end
+
+ Req --> JFW
+ JFW -->|"pattern matches?<br/>first success<br/>(aggregate roles)"| BJ
+ JFW --> AK
+ JFW --> SA
+ JFW --> OA
+ BJ -->|"Principal + roles"| JFW
+ AK -->|"Principal + roles"| JFW
+ SA -->|"Principal + roles"| JFW
+ OA -->|"Principal + roles"| JFW
+ JFW -->|"wraps request<br/>stashes principal under<br/>RestServerConstants.PRINCIPAL_ATTR"| Wrap
+ Wrap --> RC
+ RC --> RG
+ RG -->|"isUserInRole returns union<br/>across successful filters"| Op
+ Op -->|"@Auth reads PRINCIPAL_ATTR<br/>(unchanged from FINISHED-69)"| Op
+
+ classDef new fill:#cdf,stroke:#06c,color:#000
+ classDef sibling fill:#fec,stroke:#c60,color:#000
+ classDef finished fill:#cfc,stroke:#0a0,color:#000
+ class JFW,Wrap,BJ,AK new
+ class SA,OA sibling
+ class RG,RC,Op finished
+```
+
+Chain decision flow per request:
+
+```mermaid
+sequenceDiagram
+ participant C as Client
+ participant J as JuneauAuthFilterChain
+ participant F1 as Filter A (matches)
+ participant F2 as Filter B (matches)
+ participant F3 as Filter C (doesn't match)
+ participant W as RequestWrapper
+ participant S as RestServlet
+
+ C->>J: HTTP request
+ J->>J: select filters whose UrlPathMatcher matches the request path
+ J->>F1: authenticate(req)
+ F1-->>J: Principal p1, roles={user}
+ Note over J: First success wins for principal identity
+ J->>F2: authenticate(req) // run for role contribution only
+ F2-->>J: Principal p2, roles={admin,billing}
+ Note over J: aggregateRolesOnSuccess=true → union={user,admin,billing}
+ J->>F3: (skipped — pattern miss)
+ J->>W: wrap(req, principal=p1, roles=union)
+ J->>S: chain.doFilter(wrappedReq, res)
+ S->>S: @Guard / @Auth see filter-resolved principal+roles
+```
+
+All-failures flow (single aggregated rejection):
+
+```mermaid
+sequenceDiagram
+ participant C as Client
+ participant J as JuneauAuthFilterChain
+ participant F1 as Filter A (matches)
+ participant F2 as Filter B (matches)
+ participant W as Response
+
+ C->>J: HTTP request
+ J->>F1: authenticate(req)
+ F1-->>J: AuthenticationException("Bearer token missing")
+ J->>F2: authenticate(req)
+ F2-->>J: AuthenticationException("API key invalid")
+ Note over J: All applicable filters failed → aggregate
+ J->>W: 401 + WWW-Authenticate union challenge<br/>body lists each failure
+ W-->>C: 401
+```
+
+## Scope
+
+**In scope (v1):**
+
+- **`org.apache.juneau.rest.auth.filter.AuthFilter`** abstract base class.
+ - `extends Object` and `implements jakarta.servlet.Filter`.
+ - Abstract `Optional<AuthResult> authenticate(HttpServletRequest req) throws AuthenticationException` (or returns empty if the filter doesn't match the request even within its pattern — e.g. Bearer filter on a request with no `Authorization` header). The framework distinguishes "filter doesn't apply right now" (returns empty) from "filter applies but failed" (throws).
+ - `final void doFilter(ServletRequest, ServletResponse, FilterChain)` is implemented on the abstract base — calls `authenticate(...)`, handles short-circuit / aggregation, defers to the framework's `AuthFilterChain` orchestration.
+ - Builder-time settings: `pattern(String...)` (one or more `UrlPathMatcher` patterns; at least one required), `aggregateRolesOnSuccess(boolean)` (default `true`), `realm(String)` (carried into the `WWW-Authenticate` challenge on rejection).
+- **`org.apache.juneau.rest.auth.filter.AuthResult`** value type.
+ - `Principal principal()` (non-null).
+ - `Set<String> roles()` (immutable, possibly empty).
+ - Static factory `AuthResult.of(Principal, Set<String>)` and `AuthResult.of(Principal)` (no roles).
+- **`org.apache.juneau.rest.auth.filter.AuthFilterChain`** orchestration.
+ - `implements jakarta.servlet.Filter`.
+ - Holds an ordered `List<AuthFilter>`.
+ - On each request: build the list of applicable filters (via `UrlPathMatcher.match(...)`); short-circuit + aggregate per Resolved Decision #3; wrap the request via `AuthenticatedRequestWrapper`; delegate to `chain.doFilter(wrapped, res)`. If all applicable filters fail, throw the aggregated `AuthenticationException`.
+ - Builder via `AuthFilterChain.create(BeanStore)` mirroring `RestGuardList.create(BeanStore)` so the chain participates in `BeanStore` resolution exactly like FINISHED-69's guard list.
+- **`org.apache.juneau.rest.auth.filter.AuthenticatedRequestWrapper`** (package-private or public — see Open question 3).
+ - `extends HttpServletRequestWrapper`.
+ - Constructor takes `(HttpServletRequest delegate, Principal principal, Set<String> aggregatedRoles)`.
+ - Overrides `getUserPrincipal()` to return the principal.
+ - Overrides `isUserInRole(String)` to return `roles.contains(role)`.
+ - Stashes the principal on the wrapped request under `RestServerConstants.PRINCIPAL_ATTR` for `@Auth`-arg-resolver pickup.
+- **`org.apache.juneau.rest.auth.filter.BearerTokenAuthFilter`** — concrete `AuthFilter` wrapping FINISHED-69's `TokenValidator`. Pulls `Authorization: Bearer <token>` from the request, delegates to the configured `TokenValidator`, builds an `AuthResult` from the returned `Principal` plus the roles `ClaimsPrincipal` exposes (when the validator returns one).
+- **`org.apache.juneau.rest.auth.filter.ApiKeyAuthFilter`** — concrete `AuthFilter` wrapping FINISHED-69's `ApiKeyStore`. Reads key from a configurable source (header default `X-API-Key` / query param / cookie), delegates to the configured `ApiKeyStore`.
+- **`JettyServerComponent.addFilter(Filter, String pathSpec)` + `addFilter(Filter, String...pathSpecs)`** — adds the missing filter-registration surface to `juneau-microservice-jetty`. Mirrors the existing `addServlet(...)` shape so the two surfaces feel symmetric.
+- **Auto-mount path:** in `JettyServerComponent.onStart(Microservice)`, scan the `BeanStore` for a single `AuthFilterChain` bean and auto-register it with `/*` path-spec if found — so user code is just `@Bean AuthFilterChain ...`, no manual `addFilter(...)` call.
+- **`org.apache.juneau.rest.auth.filter.AuthFiltersConfig`** — optional `[AuthFilters]` config-file section that lets operators declare filters from `juneau.cfg` rather than `@Bean` code, mirroring the existing `[Jetty]` section's pattern. See Open question 5.
+- **Tests** in `juneau-utest/src/test/java/org/apache/juneau/rest/auth/filter/`:
+ - `AuthFilterChain_Test` — chain pattern matching; first-success; role aggregation; all-failure aggregation; non-matching filters skipped.
+ - `AuthenticatedRequestWrapper_Test` — `getUserPrincipal()` + `isUserInRole(...)` overrides; `RestServerConstants.PRINCIPAL_ATTR` stash; integration with `RoleBasedRestGuard` (build a `RestServlet` with a `RoleBasedRestGuard("admin")` op, hit it through the filter chain, confirm `req.isUserInRole("admin")` returns `true` only when an applicable filter contributed `admin`).
+ - `BearerTokenAuthFilter_Test` — happy path; missing header; validator throws; multiple matching filters with the same realm.
+ - `ApiKeyAuthFilter_Test` — header / query / cookie sources; unknown key.
+ - `JettyServerComponent_AddFilter_Test` — `addFilter(...)` mounts a filter at the requested path; auto-mount of `@Bean AuthFilterChain` works without manual `addFilter(...)`.
+ - `AuthFilterChain_GuardIntegration_Test` — end-to-end: filter chain + `RoleBasedRestGuard` + `@Auth Principal` op together.
+- **Docs**: new topic page `juneau-docs/pages/topics/AuthFilterFramework.md` covering: filter chain semantics, pattern matching, role aggregation, how filter-time AuthN composes with op-time guards (the "filter does AuthN, guard does AuthZ" mental model), config-file `[AuthFilters]` section (if shipped per Open question 5). Release-notes entries under `### juneau-rest-server` and `### juneau-microservice-jetty`.
+
+**Explicitly out of scope (v1):**
+
+- **SAML and OAuth filter implementations.** Those are TODO-94b (`juneau-rest-server-saml`) and TODO-94c (`juneau-rest-server-oauth`). TODO-94a ships ONLY the `AuthFilter` SPI + chain + `BearerTokenAuthFilter` + `ApiKeyAuthFilter` (the latter two so the framework has at least two reference impls that exercise it end-to-end in tests).
+- **Spring Security parity / bridge.** Users on Spring Boot already have Spring Security's `SecurityFilterChain` / `FilterChainProxy`. TODO-94a is the Juneau-microservice-native peer; the Spring Boot integration question is gated on Open question 1.
+- **GSSAPI / Kerberos / SPNEGO.** Container-supplied; not in the AuthFilter SPI charter.
+- **Pre-emptive challenge issuance** (issuing a `401 + WWW-Authenticate: Bearer` to a never-authenticated request just to advertise schemes). Out of scope; the filter chain only authenticates *credential-bearing* requests and surfaces challenges on rejection.
+- **Session management** (cookie-based sessions, server-side session stores). The filter framework is stateless — `Principal` is resolved per request, never cached server-side. Session AuthN is its own thing.
+- **CORS / CSRF.** Separate concerns; filed under future TODOs if requested.
+- **Auto-registration as a non-`AuthFilterChain` raw `jakarta.servlet.Filter` bean** in the `BeanStore`. Only `@Bean AuthFilterChain` is auto-mounted by `JettyServerComponent`. Raw filters require explicit `addFilter(...)` calls.
+
+## Implementation plan
+
+### Phase 0 — confirm seams (read-only)
+
+1. Confirm `RestRequest.isUserInRole(String)` delegates to the wrapped `HttpServletRequest.isUserInRole(String)` (it does — inherits from the servlet contract). This is the key seam that makes role aggregation work without changes to `RoleBasedRestGuard`.
+2. Confirm `RestRequest.getUserPrincipal()` delegates to the wrapped request as well (it does — same contract).
+3. Confirm `RestServerConstants.PRINCIPAL_ATTR` and `RestServerConstants.API_KEY_HEADER` are public visible from a new `org.apache.juneau.rest.auth.filter` package (they are — same module).
+4. Confirm `ServletContextHandler.addFilter(FilterHolder, String, EnumSet<DispatcherType>)` works from inside `JettyServerComponent.onStart(...)` — Jetty 12 EE11 servlet API.
+5. Confirm `UrlPathMatcher.of(...)` accepts the patterns TODO-94a needs (`/*`, `/api/*`, `/foo/{id}/*`). Add a quick unit-test pass over the matrix if `UrlPathMatcher_Test` doesn't already cover all three.
+
+### Phase 1 — `AuthFilter` SPI + chain orchestration + request wrapper (core `juneau-rest-server`)
+
+1. New package `org.apache.juneau.rest.auth.filter` with `package-info.java` documenting the framework.
+2. `AuthFilter` abstract base + `AuthResult` value type + `AuthFilterChain` orchestration + `AuthenticatedRequestWrapper`.
+3. Tests:
+ - `AuthFilterChain_Test` (10+ cases — pattern matching, success short-circuit, role aggregation, all-failure aggregation, non-matching filters skipped, mixed matching/non-matching, single-filter chain).
+ - `AuthenticatedRequestWrapper_Test` (5+ cases — principal pass-through, role union, attribute stash, delegate methods unchanged).
+ - `AuthResult_Test` (factory methods, defensive-copy of role set).
+
+### Phase 2 — concrete `BearerTokenAuthFilter` + `ApiKeyAuthFilter` reference impls (core `juneau-rest-server`)
+
+1. `BearerTokenAuthFilter` mirroring FINISHED-69's `BearerTokenGuard` extraction logic. Reuses `TokenValidator`. When the validator returns a `ClaimsPrincipal`, extract role claims via a configurable claim-name (default `roles`) to populate `AuthResult.roles()`.
+2. `ApiKeyAuthFilter` mirroring FINISHED-69's `ApiKeyGuard` extraction logic. Reuses `ApiKeyStore`. Same role-extraction pattern when the store returns a `ClaimsPrincipal`.
+3. Tests:
+ - `BearerTokenAuthFilter_Test` (happy path, missing header, malformed header, validator throws, `ClaimsPrincipal` roles flow through to `AuthResult`).
+ - `ApiKeyAuthFilter_Test` (header / query / cookie sources, unknown key, `ClaimsPrincipal` roles flow through).
+
+### Phase 3 — `JettyServerComponent.addFilter(...)` + auto-mount (`juneau-microservice-jetty`)
+
+1. Add public `addFilter(Filter, String)` and `addFilter(Filter, String...)` mirroring `addServlet(...)`. Internally wraps in `FilterHolder` + delegates to `ServletContextHandler.addFilter(...)`.
+2. In `onStart(...)`, scan the `BeanStore` for a single `AuthFilterChain` bean (via `store.getBean(AuthFilterChain.class)`); if present, call `addFilter(chain, "/*")` BEFORE servlet registration so filters precede routing.
+3. Tests in `juneau-utest`:
+ - `JettyServerComponent_AddFilter_Test` — manual `addFilter(...)` call mounts a filter.
+ - `JettyServerComponent_AuthFilterChainAutoMount_Test` — `@Bean AuthFilterChain` is auto-mounted at `/*`.
+
+### Phase 4 — end-to-end `@Guard` integration test (`juneau-utest`)
+
+1. `AuthFilterChain_GuardIntegration_Test` — builds a full `JettyMicroservice`-style `RestServlet` with:
+ - An `AuthFilterChain` carrying `BearerTokenAuthFilter` + `ApiKeyAuthFilter` (different patterns, overlapping for one path).
+ - A `RoleBasedRestGuard("admin|user")` on one op.
+ - A `@Auth Principal p` parameter on the same op.
+ Asserts:
+ - Request with a valid bearer-token granting `user` role → `200`, `p.getName()` matches token subject.
+ - Request with a valid API key granting `admin` role → `200`, role check passes.
+ - Request with both → first-registered filter's principal wins, roles UNION; role check sees both roles.
+ - Request with no credentials → `401` with aggregated `WWW-Authenticate` listing both schemes.
+ - Request with a valid token but role-guard requires a role the token doesn't grant → `403` (correct AuthZ behavior — AuthN succeeded, AuthZ rejected).
+
+### Phase 5 — optional `[AuthFilters]` config-file section (deferred unless Open question 5 RESOLVED in-scope)
+
+1. New `AuthFiltersConfig` reading `[AuthFilters]` from `juneau.cfg`. Schema TBD — likely `name=<filter-class>;pattern=<...>;…`. Wires resolved filters into the `BeanStore` so the auto-mount path picks them up.
+2. Tests: `AuthFiltersConfig_Test`.
+
+### Phase 6 — docs + release notes
+
+1. Release-notes entries:
+ - `### juneau-rest-server` — new `#### AuthN Filter Framework (TODO-94a)` section listing `AuthFilter`, `AuthFilterChain`, `AuthResult`, `BearerTokenAuthFilter`, `ApiKeyAuthFilter`.
+ - `### juneau-microservice-jetty` — new `addFilter(...)` API + auto-mount of `AuthFilterChain`.
+2. New topic page `juneau-docs/pages/topics/AuthFilterFramework.md` covering:
+ - Mental model: filter-time AuthN + op-time AuthZ.
+ - Pattern matching (refers to `UrlPathMatcher` page).
+ - Role aggregation semantics + the `aggregateRolesOnSuccess` knob.
+ - `BeanStore` registration pattern.
+ - Comparison to Spring Security's `SecurityFilterChain` for readers coming from that mental model.
+ - Worked examples: Bearer + API-key overlap; pattern-disjoint filters; failure-aggregation example showing the response shape.
+3. Cross-link from FINISHED-69's `AuthGuards` topic page.
+
+## Acceptance criteria
+
+- [ ] `AuthFilter` SPI exists in `org.apache.juneau.rest.auth.filter`; abstract base with `authenticate(req) -> Optional<AuthResult>` contract; concrete `BearerTokenAuthFilter` + `ApiKeyAuthFilter` reference impls.
+- [ ] `AuthFilterChain` orchestrates multiple `AuthFilter`s with first-success / role-aggregation / all-failure semantics per Resolved Decision #3.
+- [ ] `AuthenticatedRequestWrapper` populates `getUserPrincipal()` + `isUserInRole(...)` + stashes principal on `RestServerConstants.PRINCIPAL_ATTR` so FINISHED-69's `@Auth` arg-resolver and `RoleBasedRestGuard` both work unchanged.
+- [ ] `JettyServerComponent.addFilter(...)` exists as the public filter-registration surface for `juneau-microservice-jetty`.
+- [ ] `@Bean AuthFilterChain` is auto-mounted at `/*` by `JettyServerComponent` without explicit `addFilter(...)` calls.
+- [ ] Pattern matching uses `UrlPathMatcher` verbatim — no new pattern syntax.
+- [ ] End-to-end test confirms filter chain + `RoleBasedRestGuard` + `@Auth Principal` op composition works as documented.
+- [ ] Coverage ≥ 90% on `org.apache.juneau.rest.auth.filter`. Full `./scripts/test.py` green.
+- [ ] **Hard prereq**: TODO-94b and TODO-94c land ON TOP of TODO-94a — neither can start until this lands.
+
+## Open questions
+
+1. **Spring Boot reach of the filter framework — auto-register under Spring as well, document Spring Security as the recommended Spring path, or both?** Spring Boot users today reach for Spring Security; auto-registering an `AuthFilterChain` bean as a `FilterRegistrationBean` in `juneau-rest-server-springboot` would give Spring users the Juneau-native option. Trade-offs:
+ - **In-scope auto-register under Spring** — gives a single mental model across deployment modes; users who don't want it can simply not declare an `AuthFilterChain` bean.
+ - **Document Spring Security only** — keeps the `juneau-rest-server-springboot` module narrow; users coming from Spring already know `SecurityFilterChain` and don't need a new mental model.
+ - **Both** — auto-register *and* document Spring Security as an alternative for users who want full Spring Security feature surface (OAuth, OIDC, method-security annotations, etc.).
+ The plan above writes the v1 scope as "Jetty-microservice-first; Spring Boot integration deferred unless OQA picks in-scope". OQA needed before Phase 1 starts so Phase 3 / Phase 5 can be sized correctly.
+
+2. **Filters run before or after Juneau's own request routing?** Both are technically possible (Juneau's `RestServlet` is itself a servlet, so a filter is always before it from the container's POV — but Juneau's `@RestHook(PRE_CALL)` hooks run AFTER the servlet entry and could carry equivalent logic). Current design assumes "filter runs first, principal flows through to op handlers via the wrapped request" — which matches the standard servlet-API mental model. Alternative: a `RestHookPre [...]
+
+3. **`AuthenticatedRequestWrapper` — public or package-private?** Public lets users in custom filter impls construct their own wrapper directly (e.g. to add extra wrapping for an attribute beyond principal+roles). Package-private hides the type — users go through `AuthResult` + the framework wraps. **Recommend: public** for extension; revisit if it becomes an attack surface.
+
+4. **Role-aggregation interaction with Spring Security's role chain when running under Spring Boot.** If TODO-94a's `AuthFilterChain` runs alongside Spring Security's `SecurityFilterChain` (Spring Security mounted at one filter index, Juneau's chain at another), whose `Principal` and `isUserInRole(...)` answer wins for downstream code? Order-sensitive. Likely answer: document "do not run both"; pick one. **Gated on Open question 1** — only relevant if the Spring path is in-scope.
+
+5. **Config-file `[AuthFilters]` section — in-scope v1 or deferred?** Phase 5 in the implementation plan. Trade-off: declarative config is the Juneau idiom (matches the `[Jetty]` / `[Logging]` precedent) but the filter-construction surface is non-trivial (filter type, validator/store wiring, pattern list, realm, role-aggregation flag) and a config-file shape that covers all of it is its own design exercise. **Recommend: v1 = `@Bean`-only; config-file section deferred to a follow-on TODO [...]
+
+6. **`AuthFilter.authenticate(...)` return type — `Optional<AuthResult>` (empty = "filter doesn't apply this request") vs throw vs `null`?** Current design picks `Optional` so the framework distinguishes three states: (a) filter matched the pattern but the request carries no credentials this filter recognizes (return empty — try the next applicable filter), (b) filter matched and the request carries credentials this filter recognizes but they're invalid (throw `AuthenticationException` — [...]
+
+7. **Filter ordering vs declaration order.** Current design preserves declaration order (first to register, first to authenticate). Alternative: add an `int order()` method on `AuthFilter` (or a `@Order(int)` annotation) so users can change ordering without re-registering. **Recommend: declaration order for v1**; add ordering knob if real-world usage demands it.
+
+## Risk notes
+
+- **Adding a filter surface to `JettyServerComponent` is a public-API addition.** Once shipped, it's contractually frozen — `addFilter(Filter, String)` / `addFilter(Filter, String...)` signatures must stay stable. Mitigation: the signatures mirror `addServlet(...)` so the maintenance burden is symmetric; signature design baked into Phase 0 review.
+- **Filter ordering relative to Jetty's built-in filters.** Jetty 12 EE11 ships a few built-in filters (e.g. for static content). TODO-94a's auto-mount must register BEFORE those so credentials are resolved before any built-in filter sees the request. Mitigation: confirm Jetty's filter precedence model during Phase 0; if Jetty's built-ins register at servlet-context startup, TODO-94a registers in `JettyServerComponent.onStart(...)` which already runs after Jetty's static init; verify.
+- **Per-request `UrlPathMatcher.match(...)` cost.** For every request, the chain walks every registered filter's matcher. If a user registers 50 filters with overlapping patterns, this becomes meaningful overhead. Mitigation: documented `O(n)` cost; for very-high-filter-count cases, future optimization is a path-trie (defer until measured).
+- **All-failure aggregation builds an `AuthenticationException` chain via `addSuppressed`.** Suppressed exceptions can hold large stack traces; if 5 filters all fail with deep stacks, the response body grows. Mitigation: render only `getMessage()` for each suppressed cause in the response body; full stacks go to the request log only.
+- **Role-set sizing for aggregation.** The `Set<String>` carried by `AuthenticatedRequestWrapper` is per-request; for a small N (typical: 2-10 roles) `HashSet` is fine. For pathological N (thousands of roles) memory matters; not expected in real deployments. Mitigation: documented; switch to a more compact representation if real-world usage proves otherwise.
+- **Filter wraps the request before Juneau's parsing.** `AuthenticatedRequestWrapper` defers `getInputStream()` / `getReader()` / `getParameter(...)` to the delegate — no body read. This avoids the classic "filter consumed the body before the servlet" trap. Mitigation: documented + tested in `AuthenticatedRequestWrapper_Test`.
+- **Public-static-method on the `AuthFilter` SPI accidentally locks in a transitive nimbus / opensaml dep.** The SPI base in core MUST NOT import anything from TODO-94b's SAML lib or TODO-94c's OAuth lib. Mitigation: code review gate; sibling modules depend on core, not the reverse.
+
+## Out of scope (recap)
+
+- SAML filter implementation (TODO-94b).
+- OAuth / OIDC filter implementation (TODO-94c).
+- Spring Security bridge / parity.
+- Session-based AuthN (cookies + server-side session stores).
+- CORS / CSRF filters.
+- GSSAPI / Kerberos / SPNEGO.
+- Pre-emptive `WWW-Authenticate` challenge issuance on unauthenticated requests.
+
+## Related work
+
+- `todo/FINISHED-69-authn-guards-jwt-apikey.md` — the AuthN landing this TODO extends. TODO-94a reuses every type FINISHED-69 introduced (`TokenValidator`, `ApiKeyStore`, `AuthenticationException`, `ClaimsPrincipal`, `@Auth` arg-resolver, `RestServerConstants.PRINCIPAL_ATTR` / `.API_KEY_HEADER`). The new types are only the filter-layer plumbing (`AuthFilter`, `AuthFilterChain`, `AuthResult`, `AuthenticatedRequestWrapper`) plus the two reference impls (`BearerTokenAuthFilter`, `ApiKeyAuth [...]
+- `todo/TODO-94b-saml-module.md` — sibling. HARD dep on this plan landing first. SAML-specific filter + validator.
+- `todo/TODO-94c-oauth-module.md` — sibling. HARD dep on this plan landing first; soft dep on FINISHED-69 (reuses `JwtTokenValidator` for JWT access tokens). OAuth-specific filter + flow helpers.
+- `juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/guard/RoleBasedRestGuard.java` — the AuthZ-time consumer of filter-resolved roles via `req.isUserInRole(...)`. Unchanged by this TODO.
+- `juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/UrlPathMatcher.java` — the path-matching primitive reused verbatim. Unchanged.
+- `juneau-microservice/juneau-microservice-jetty/src/main/java/org/apache/juneau/microservice/jetty/JettyServerComponent.java` — gains `addFilter(...)` + the auto-mount path.
+- `juneau-rest/juneau-rest-server-springboot/` — gated on Open question 1.
diff --git a/todo/TODO-94b-saml-module.md b/todo/TODO-94b-saml-module.md
new file mode 100644
index 0000000000..8a863f14c6
--- /dev/null
+++ b/todo/TODO-94b-saml-module.md
@@ -0,0 +1,304 @@
+# TODO-94b: `juneau-rest-server-saml` — SAML 2.0 assertion validation module
+
+Source: promoted from `TODO.md` on 2026-05-25 during `/todo expand 94` (multi-file split per AGENTS.md letter-suffix precedent — see FINISHED-16a/b/c).
+
+**Hard dependency: TODO-94a (auth filter framework) must land first.** TODO-94a provides the `AuthFilter` SPI, `AuthFilterChain`, `AuthResult`, and `AuthenticatedRequestWrapper` that this module's `SamlAuthFilter` plugs into. Without TODO-94a, this module has nothing to plug into.
+
+## Goal
+
+Ship a new opt-in Maven module `juneau-rest-server-saml` that ships a `SamlAssertionValidator` (`implements TokenValidator` — FINISHED-69's existing SPI) and a `SamlAuthFilter` (`extends AuthFilter` — TODO-94a's SPI) for **consumer-side** SAML 2.0 assertion validation. Juneau is a Service Provider (SP) in SAML parlance — we receive a signed SAML assertion from an Identity Provider (IdP), verify it, extract the subject + attributes into a `ClaimsPrincipal`, and let downstream Juneau code [...]
+
+Mirrors FINISHED-69's `juneau-rest-server-jwt` module isolation pattern: the SAML library dependency (`opensaml`) is declared `provided` so it never bleeds into the core `juneau-rest-server` POM. Consumers add `juneau-rest-server-saml` + the OpenSAML version they want.
+
+End-state developer experience:
+
+```java
+@Rest(path="/sso")
+public class SsoResource extends RestServlet {
+
+ @Bean
+ public AuthFilterChain authFilters(BeanStore bs) {
+ var validator = SamlAssertionValidator.create()
+ .metadataResolver(MyIdpMetadataResolver.create("https://idp.example.com/metadata"))
+ .audience("https://api.example.com")
+ .build();
+
+ return AuthFilterChain.create(bs)
+ .append(SamlAuthFilter.create()
+ .pattern("/sso/*")
+ .validator(validator)
+ .build())
+ .build();
+ }
+
+ @RestPost("/login")
+ public Profile login(@Auth ClaimsPrincipal p) {
+ // p is the assertion's subject; p.getClaim("eduPersonAffiliation", String.class) etc.
+ return profileService.lookup(p.getName());
+ }
+}
+```
+
+## Why now
+
+- **Direct sibling of TODO-94c (OAuth).** Both land on the TODO-94a filter framework; both fulfill the FINISHED-69 promise of "JWT is the v1 AuthN format, more formats land on top of the same `TokenValidator` SPI". SAML is the dominant enterprise SSO format that doesn't reduce to a JWT.
+- **Module-isolation precedent is proven.** FINISHED-69's `juneau-rest-server-jwt` shipped with `nimbus-jose-jwt` declared `provided`; `mvn dependency:tree` on the upstream `juneau-rest-server` shows zero nimbus references. Repeating that pattern for `opensaml` is a known-good design.
+- **Enterprise migration path.** Apps moving onto Juneau from Spring-Security-with-SAML configurations need a first-class story; this module is that story.
+
+## Research findings (verified 2026-05-25)
+
+Significant facts shaping the design:
+
+1. **OpenSAML is the canonical Apache 2.0 Java SAML library.** Maintained by Shibboleth Consortium. Coordinates as of 2026:
+ - `org.opensaml:opensaml-core-api`
+ - `org.opensaml:opensaml-core-impl`
+ - `org.opensaml:opensaml-saml-api`
+ - `org.opensaml:opensaml-saml-impl`
+ - `org.opensaml:opensaml-xmlsec-api` + `opensaml-xmlsec-impl` (signature/encryption)
+ - `org.opensaml:opensaml-security-api` + `opensaml-security-impl` (key/cred management)
+ - `org.opensaml:opensaml-messaging-api` + `opensaml-messaging-impl` (binding handlers)
+ - `org.opensaml:opensaml-soap-api` + `opensaml-soap-impl` (only needed for back-channel artifact resolution)
+ **License: Apache 2.0** — compatible with the Apache Juneau project's licensing without any additional NOTICE file work beyond standard Apache transitive-dep handling. Version to recommend is the latest 5.x line stable at land time (5.x is the Jakarta-EE-aligned generation; 4.x is the javax-aligned legacy). The exact version pin is filed under Open question 4.
+ Transitive deps: `org.slf4j:slf4j-api`, `joda-time:joda-time` (still used in older code paths — verify whether 5.x has migrated to `java.time` since this affects the implementer's mental model), `net.shibboleth.utilities:java-support`, `org.cryptacular:cryptacular`, plus the standard XML-stack (`xerces`, `xalan`, `xml-apis`). These are NOT trivial.
+
+2. **Alternatives considered and rejected for the bridge module's reference impl:**
+ - **`org.apache.santuario:xmlsec` (signature-only path)** — Apache 2.0, smaller dep surface than OpenSAML (no full SAML object model), but the implementer would have to write the SAML XSD parsing, attribute extraction, condition validation, subject-confirmation walking, etc., from scratch. The amount of code we'd save by avoiding OpenSAML is more than swallowed by the amount we'd have to write. Documented as a "if you only need signature verification and already have your own SAML pa [...]
+ - **`org.picketlink:picketlink-federation`** — JBoss-stewarded SAML library; Apache 2.0; less actively maintained than OpenSAML; not the canonical choice in 2026.
+ - **Deprecated `javax.security.auth` / built-in Java SAML APIs** — there is no JDK-native SAML API; the `javax.security.sasl` Kerberos/GSSAPI bits are orthogonal. Skipped.
+ - **`spring-security-saml2-service-provider`** — embeds OpenSAML, adds Spring Security plumbing on top. Out of charter because we deliberately don't depend on Spring Security; users who want it are already in Spring Security territory and don't need this module.
+ The chosen approach is to wrap OpenSAML directly behind the `TokenValidator` SPI — same wrap-an-industry-canonical-lib stance FINISHED-69 took with nimbus.
+
+3. **SAML assertion shape.** A SAML 2.0 `<Assertion>` is XML with these mandatory components for SP validation:
+ - `<Signature>` — XML-DSig signature over the assertion (or over the enclosing `<Response>`). Must verify against an IdP-published key (from metadata).
+ - `<Issuer>` — IdP's entity ID; must match the configured trusted IdP.
+ - `<Subject>` — the authenticated user. `<NameID>` carries the username. `<SubjectConfirmation>` carries audience-restriction-like proof rules.
+ - `<Conditions>` — `NotBefore` / `NotOnOrAfter` validity window + `<AudienceRestriction>` listing acceptable SP entity IDs. SP MUST match its own entity ID against the audience list.
+ - `<AuthnStatement>` — when/how the user authenticated at the IdP.
+ - `<AttributeStatement>` — attributes (email, groups, eduPersonAffiliation, etc.) that the IdP asserts about the user. The validator extracts these into `ClaimsPrincipal` claims.
+
+4. **SAML bindings.** SAML assertions reach an SP via one of several bindings:
+ - **HTTP POST** — the IdP redirects the user-agent to the SP with a base64-encoded `<Response>` in a form field (`SAMLResponse`). Most common for SSO.
+ - **HTTP Redirect** — assertion (or `<AuthnRequest>`) in a query-string parameter. Used mostly for `<AuthnRequest>`, not assertions (assertions are too big).
+ - **HTTP Artifact** — IdP sends an opaque artifact, SP fetches the assertion over back-channel SOAP. Niche.
+ - **SOAP** — back-channel.
+ v1 scope: **HTTP POST binding only** (the dominant case). Other bindings filed under Open question 3.
+
+5. **Trust model.** The SP trusts the IdP because the IdP publishes a SAML metadata document (`<EntityDescriptor>`) listing its signing keys + endpoints. The SP loads this metadata at startup (and periodically refreshes), uses the keys to verify signatures, uses the endpoints to redirect for SSO. OpenSAML's `MetadataResolver` interface abstracts this.
+
+6. **FINISHED-69's SPIs are filter-ready.** `TokenValidator` is `Principal validate(String token)`. For SAML, the "token" parameter is the base64-encoded `<Response>` extracted from the `SAMLResponse` form field. The validator decodes, parses, verifies, and returns a `ClaimsPrincipal` whose claims are the SAML attributes. Zero changes required to FINISHED-69's `TokenValidator` interface.
+
+## Resolved decisions
+
+1. **SAML library — OpenSAML, isolated in the new `juneau-rest-server-saml` sub-module, `provided` scope** (mirrors FINISHED-69's nimbus stance verbatim). The full OpenSAML dep tree is heavy (XML stack + cryptacular + joda + slf4j), so containment matters: a `dependency:tree` on `juneau-rest-server` MUST never surface any `org.opensaml:*` artifact. Consumers of `juneau-rest-server-saml` add the OpenSAML version they want; the module's POM declares the API/Impl pair as `provided`. Phase 1 [...]
+
+2. **Module structure mirrors `juneau-rest-server-jwt` end-to-end.** Same POM layout (parent `juneau-rest`, `bundle` packaging, source-jar + felix bundle-plugin + jacoco), same `juneau-rest-server` hard dep, same `provided`-scope third-party dep. Same `META-INF/services` discoverability through the `BeanStore` for the validator. Same release-notes section pattern (`### juneau-rest-server-saml (new module)`).
+
+3. **`SamlAssertionValidator implements TokenValidator`.** Reuses FINISHED-69's SPI verbatim. No new validator interface. The "token" string parameter carries the base64-encoded `SAMLResponse` form value; the validator handles base64-decode + XML parse + signature verify + condition check + audience check internally. Returns a `ClaimsPrincipal` (FINISHED-69's existing type) whose claim names map 1:1 to SAML `<Attribute>` names; built-in claims for `nameId`, `nameIdFormat`, `sessionIndex` [...]
+
+4. **`SamlAuthFilter` is the v1 filter shape.** Pulls the `SAMLResponse` form field from the request (HTTP POST binding only); rejects on other content types. Delegates the base64 payload to the configured `SamlAssertionValidator`. Wraps successful results in TODO-94a's `AuthResult` with the validator's `ClaimsPrincipal` + roles extracted from a configurable SAML attribute (default `roles`; users override via `SamlAuthFilter.rolesAttribute("groups")` etc.).
+
+5. **Metadata loading is the consumer's job in v1.** The validator builder requires a `MetadataResolver` (OpenSAML's interface) — TODO-94b does NOT bundle a default `MetadataResolver` impl in v1. Documented "Choosing a MetadataResolver" matrix in the module README (filesystem-XML / URL-fetched / Shibboleth Consortium dynamic resolver / etc.). See Open question 2 for whether we change this in v1.5.
+
+6. **Mandatory validation set.** The validator enforces ALL of the following at every `validate(...)` call; no opt-out for v1:
+ - **Signature verification** against an IdP key resolved from the metadata.
+ - **Issuer match** against the configured trusted IdP entity ID.
+ - **Audience restriction** — the configured SP entity ID MUST appear in the `<Conditions><AudienceRestriction>` list.
+ - **Time window** — current time must be within `NotBefore` (inclusive) and `NotOnOrAfter` (exclusive), with a configurable clock-skew window (default 60s, max 300s — mirrors FINISHED-69's `JwtTokenValidator` clock-skew design).
+ - **Subject confirmation** — at least one `<SubjectConfirmation>` element must have a method that the SP recognizes (`urn:oasis:names:tc:SAML:2.0:cm:bearer` for the POST binding); if the `<SubjectConfirmationData>` carries `NotOnOrAfter` / `Recipient` / `InResponseTo`, those are also checked.
+ Each failure throws `AuthenticationException` with a specific message + a `WWW-Authenticate: SAML realm="<realm>"` challenge.
+
+7. **Algorithm allowlist for signature verification.** Default: `[http://www.w3.org/2001/04/xmldsig-more#rsa-sha256, http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256]`. SHA-1 variants permanently rejected (NIST deprecation). Algorithms configurable via `SamlAssertionValidator.Builder.signatureAlgorithms(String...)`. Mirrors FINISHED-69's `JwtTokenValidator` algorithm-allowlist pattern.
+
+## Architecture
+
+```mermaid
+flowchart TB
+ subgraph idp [Identity Provider]
+ IdpUser[User browser session]
+ IdpSign[Sign assertion with private key]
+ end
+ subgraph wire [HTTP POST binding]
+ Form["POST /sso/login<br/>Content-Type: application/x-www-form-urlencoded<br/>SAMLResponse=<base64-XML>"]
+ end
+ subgraph sp [Service Provider — juneau-rest-server-saml]
+ Filter[SamlAuthFilter<br/>extends AuthFilter from TODO-94a]
+ Val[SamlAssertionValidator<br/>implements TokenValidator from FINISHED-69]
+ Decode[base64 decode + XML parse]
+ Verify[Signature verify<br/>via MetadataResolver-supplied keys]
+ Check["Mandatory checks:<br/>issuer / audience<br/>NotBefore / NotOnOrAfter<br/>subjectConfirmation"]
+ Claims["Build ClaimsPrincipal<br/>(nameId + attributes)"]
+ end
+ subgraph downstream [Juneau RestContext layer]
+ Chain[AuthFilterChain<br/>TODO-94a]
+ Wrap[AuthenticatedRequestWrapper<br/>TODO-94a]
+ Op["@RestPost handler<br/>(@Auth ClaimsPrincipal p)"]
+ end
+
+ IdpUser --> IdpSign --> Form
+ Form --> Filter
+ Filter -->|"SAMLResponse field value"| Val
+ Val --> Decode --> Verify --> Check --> Claims
+ Claims -->|"ClaimsPrincipal"| Filter
+ Filter -->|"AuthResult"| Chain
+ Chain --> Wrap --> Op
+
+ classDef new fill:#cdf,stroke:#06c,color:#000
+ classDef finished fill:#cfc,stroke:#0a0,color:#000
+ classDef framework fill:#fec,stroke:#c60,color:#000
+ class Filter,Val,Decode,Verify,Check,Claims new
+ class Chain,Wrap framework
+ class Op finished
+```
+
+## Scope
+
+**In scope (v1):**
+
+- New Maven module `juneau-rest/juneau-rest-server-saml/` with POM mirroring `juneau-rest-server-jwt` end-to-end (parent `juneau-rest`, `bundle` packaging, OSGi manifest, jacoco wiring, source-jar attach).
+- POM deps:
+ - Hard dep: `juneau-rest-server` (transitively pulls TODO-94a's filter framework types from core).
+ - **`provided` scope**: OpenSAML 5.x API + Impl pair plus the minimum companion deps needed to make API+Impl resolve (`opensaml-core-api`, `opensaml-core-impl`, `opensaml-saml-api`, `opensaml-saml-impl`, `opensaml-xmlsec-api`, `opensaml-xmlsec-impl`, `opensaml-security-api`, `opensaml-security-impl`, `opensaml-messaging-api`, `opensaml-messaging-impl`). Exact version pin per Open question 4.
+- **`org.apache.juneau.rest.auth.saml.SamlAssertionValidator implements TokenValidator`**:
+ - Builder accepts `metadataResolver(MetadataResolver)`, `audience(String)` (SP entity ID), `issuer(String)` (trusted IdP entity ID), `clockSkew(Duration)` (default 60s, max 300s), `signatureAlgorithms(String...)` (default `[rsa-sha256, ecdsa-sha256]`), `clock(Clock)` (default `Clock.systemUTC()`), `rolesAttribute(String)` (default `"roles"`), `requireSubjectConfirmation(boolean)` (default `true`).
+ - `validate(String base64SamlResponse) throws AuthenticationException` — decodes, parses, verifies, checks, returns a `ClaimsPrincipal`. Claim names: `nameId`, `nameIdFormat`, `sessionIndex`, `authnInstant`, `issuer`, plus one entry per `<Attribute>` in the `<AttributeStatement>` (multi-valued attributes carried as `List<String>`).
+- **`org.apache.juneau.rest.auth.saml.SamlAuthFilter extends AuthFilter`** (TODO-94a's SPI):
+ - Builder accepts standard `AuthFilter` shape (`pattern(String...)`, `realm(String)`, `aggregateRolesOnSuccess(boolean)`) plus `validator(SamlAssertionValidator)`, `samlResponseFormField(String)` (default `"SAMLResponse"`), `rolesAttribute(String)` (default `"roles"`; if set, overrides the validator's setting at the filter level).
+ - `authenticate(req)`:
+ - Match HTTP POST + form-urlencoded content type; otherwise return empty (filter doesn't apply this request).
+ - Read the `SAMLResponse` form field; if missing, return empty.
+ - Delegate to `validator.validate(...)`; throw on `AuthenticationException`.
+ - On success, build an `AuthResult` carrying the `ClaimsPrincipal` + roles extracted from the configured roles attribute.
+- **`org.apache.juneau.rest.auth.saml.SamlMetadataResolvers`** (utility class) — convenience factory methods for the two most common `MetadataResolver` setups:
+ - `SamlMetadataResolvers.url(URI metadataUrl, Duration refreshInterval)` — HTTP-fetched metadata with periodic refresh.
+ - `SamlMetadataResolvers.file(Path metadataXml)` — file-system XML.
+ These wrap OpenSAML's `FilesystemMetadataResolver` / `HTTPMetadataResolver` with sane defaults; users who need more (chained resolvers, custom auth, etc.) build their own.
+- **`META-INF/services` registration** — none required (the validator + filter are user-constructed at `@Bean`-factory time, not ServiceLoader-discovered).
+- **Tests** in `juneau-utest/src/test/java/org/apache/juneau/rest/auth/saml/`:
+ - `SamlAssertionValidator_HappyPath_Test` — signed assertion with matching audience + issuer + time window → success; `ClaimsPrincipal` carries `nameId` + attributes.
+ - `SamlAssertionValidator_Security_Test` — signature mismatch / no signature / wrong issuer / audience mismatch / before NotBefore / after NotOnOrAfter / no SubjectConfirmation / SHA-1 algorithm rejected.
+ - `SamlAssertionValidator_Builder_Test` — required-field rejection, clock-skew bounds, signature-algorithm validation.
+ - `SamlAssertionValidator_ClaimsPrincipal_Test` — attribute extraction (single + multi-valued), roles claim, claim-type coercion.
+ - `SamlAuthFilter_Test` — happy path, missing form field, non-POST request returns empty (filter skipped), wrong content type returns empty, validator throws → `AuthenticationException` propagates with `WWW-Authenticate: SAML realm="..."`.
+ - `SamlMetadataResolvers_Test` — file resolver + URL resolver round-trip (URL via local Jetty fixture).
+ - **Containment check (CI-gated)** — a Maven plugin or shell step that runs `mvn -pl juneau-rest/juneau-rest-server dependency:tree` and greps for `org.opensaml`; non-zero matches fail the build. Mirrors FINISHED-69's nimbus containment gate.
+- Module-level test deps in `juneau-utest/pom.xml` (test scope only):
+ - `juneau-rest-server-saml`
+ - OpenSAML API + Impl pair (the bridge module declares them `provided`, so test classpaths need explicit declarations).
+ - Test fixtures: a stub IdP that signs assertions on demand for the happy-path tests.
+- **Docs**: new topic page `juneau-docs/pages/topics/SamlAuthSupport.md`. Release-notes entry `### juneau-rest-server-saml (new module)` in `9.5.0.md` (or whichever release file the SAML module lands in).
+
+**Explicitly out of scope (v1):**
+
+- **IdP implementation** — Juneau is an SP, not an IdP. No `<AuthnRequest>` generation, no `<Response>` issuance, no metadata publishing. If a user needs to BE the IdP, that's an entirely different module.
+- **WS-Federation** — separate protocol family; not SAML 2.0; out of charter.
+- **SAML 1.x** — long deprecated; not supported.
+- **Encrypted assertions** (`<EncryptedAssertion>`) — IdPs CAN encrypt assertions to the SP's public key; v1 supports signed-cleartext only. Filed under Open question 5.
+- **Bindings other than HTTP POST** — HTTP Redirect (rarely used for assertions), HTTP Artifact (back-channel SOAP), SOAP. v1 = POST only.
+- **Single Logout (SLO)** — orthogonal to assertion validation; would be its own module if requested.
+- **Default `MetadataResolver` impl beyond the convenience factories** — see Open question 2.
+- **Attribute mapping DSL** — v1 maps `<Attribute>` names 1:1 to `ClaimsPrincipal` claim names. Users who need transformation (rename, split, merge) do it after the validator returns.
+
+## Implementation plan
+
+### Phase 0 — confirm seams (read-only)
+
+1. Confirm TODO-94a has landed and `AuthFilter` / `AuthFilterChain` / `AuthResult` / `AuthenticatedRequestWrapper` are stable public types in `org.apache.juneau.rest.auth.filter`.
+2. Confirm FINISHED-69's `TokenValidator` / `ClaimsPrincipal` / `AuthenticationException` are stable.
+3. Confirm OpenSAML 5.x dep coordinates resolve cleanly through Maven Central (no JBoss / Shibboleth repos required).
+4. **Decide OpenSAML version pin** (Open question 4) and document the rationale.
+5. **Decide MetadataResolver default packaging** (Open question 2).
+
+### Phase 1 — module skeleton + POM + containment check
+
+1. New module `juneau-rest/juneau-rest-server-saml/` with `pom.xml` mirroring `juneau-rest-server-jwt`.
+2. POM `<properties>` carries `opensaml.version` (per Open question 4).
+3. All OpenSAML deps declared `provided`.
+4. Module registered in `juneau-rest/pom.xml` `<modules>` + three `<artifactItem>` entries (sources, bin/lib, bin/osgi) added to `juneau-distrib/pom.xml` (mirroring how FINISHED-69 wired `juneau-rest-server-jwt`).
+5. Containment check verified: `mvn -pl juneau-rest/juneau-rest-server dependency:tree | grep -i opensaml` returns nothing.
+
+### Phase 2 — `SamlAssertionValidator` (no filter yet)
+
+1. Validator + builder + claim-extraction code.
+2. `XMLObjectProviderRegistrySupport.initSAML()` hook called once (lazy-init in the validator constructor; OpenSAML requires bootstrap before any unmarshalling). Document the bootstrap behavior; protect against re-entrant init.
+3. Tests:
+ - `SamlAssertionValidator_HappyPath_Test`
+ - `SamlAssertionValidator_Security_Test`
+ - `SamlAssertionValidator_Builder_Test`
+ - `SamlAssertionValidator_ClaimsPrincipal_Test`
+
+### Phase 3 — `SamlAuthFilter`
+
+1. Filter + builder.
+2. Tests: `SamlAuthFilter_Test` exercising the HTTP POST happy path + skip-conditions + failure propagation.
+
+### Phase 4 — `SamlMetadataResolvers` convenience factories
+
+1. `SamlMetadataResolvers.url(...)` / `.file(...)`.
+2. Tests: `SamlMetadataResolvers_Test` with a local Jetty fixture serving stub IdP metadata XML for the URL path.
+
+### Phase 5 — end-to-end integration test
+
+1. `SamlAuthFilter_EndToEnd_Test` — full stack: stub IdP issues a signed assertion → SP exposes a `RestServlet` protected by an `AuthFilterChain` containing the `SamlAuthFilter` → POST the assertion → confirm op handler sees the right `@Auth ClaimsPrincipal` and `req.isUserInRole(...)` matches the roles attribute.
+
+### Phase 6 — docs + release notes
+
+1. Release-notes entry under `### juneau-rest-server-saml (new module)` in the appropriate release notes file. Include explicit Maven coordinates, the `provided`-scope callout, and the OpenSAML version recommendation.
+2. New topic page `juneau-docs/pages/topics/SamlAuthSupport.md` covering: SP-side mental model, the validator + filter wiring, `MetadataResolver` choice matrix, signature-algorithm allowlist, troubleshooting (clock skew, audience mismatch, attribute extraction).
+3. Cross-link from TODO-94a's `AuthFilterFramework.md` topic page and FINISHED-69's `AuthGuards.md`.
+
+## Acceptance criteria
+
+- [ ] New module `juneau-rest/juneau-rest-server-saml` builds and tests pass.
+- [ ] OpenSAML 5.x dep declared `provided`; containment check confirms zero `org.opensaml:*` references in `juneau-rest-server` `dependency:tree`.
+- [ ] `SamlAssertionValidator implements TokenValidator` reuses FINISHED-69's SPI without modification.
+- [ ] `SamlAuthFilter extends AuthFilter` plugs into TODO-94a's chain without bridging code.
+- [ ] All six mandatory validation checks (signature, issuer, audience, time window, subject confirmation, algorithm allowlist) enforced and tested.
+- [ ] SHA-1 signature algorithms permanently rejected.
+- [ ] `ClaimsPrincipal` claims populated from `<AttributeStatement>` 1:1; built-in `nameId` / `nameIdFormat` / `sessionIndex` / `authnInstant` / `issuer` claims present.
+- [ ] `SamlMetadataResolvers.url(...)` / `.file(...)` convenience factories work end-to-end.
+- [ ] End-to-end test confirms `SamlAuthFilter` → `AuthFilterChain` → `@Guard` + `@Auth ClaimsPrincipal` composition.
+- [ ] Coverage ≥ 85% on the SAML module (the heavy `OpenSAML`-mediated XML paths are exercised through stub-IdP fixtures; some defensive branches in XML parsing are deliberately unreachable from tests).
+- [ ] Full `./scripts/test.py` green.
+
+## Open questions
+
+1. **Should `SamlAssertionValidator` integrate with FINISHED-69's `@Auth ClaimsPrincipal` arg-resolver via a different "principal type" than the JWT path?** Both JWT and SAML produce a `ClaimsPrincipal`; differentiating them downstream (e.g. "did this principal come from a SAML assertion or a JWT?") requires either a marker subclass (`SamlClaimsPrincipal extends ClaimsPrincipal`) or a `principal.getClaim("issuerType", String.class).equals("SAML")` convention. **Recommend: marker claim** [...]
+
+2. **Bundle a default `MetadataResolver` impl in the module, or only the `SamlMetadataResolvers` convenience factories?** The convenience factories wrap OpenSAML's stock resolvers with sane defaults. A "bundled default" would mean picking one (likely the URL-based resolver with a 60-min refresh) and using it when the user doesn't specify a resolver. **Trade-off**: bundling a default makes the happy path one line shorter (`SamlAssertionValidator.create().metadataUrl(...).build()` vs `.met [...]
+
+3. **HTTP Redirect / Artifact / SOAP bindings — defer or in-scope v1?** v1 plan above ships POST binding only. HTTP Redirect is rarely used for full assertions (size limits); Artifact requires back-channel SOAP plumbing (an additional OpenSAML dep surface — `opensaml-soap-*`); SOAP binding is similarly heavy. **Recommend: POST-only v1**; file Redirect / Artifact / SOAP as follow-on TODOs only if user demand surfaces. Confirm.
+
+4. **OpenSAML version pin.** Need to confirm the current stable 5.x line at land time. As of the 2026-05-25 planning date, the public OpenSAML release cadence has shipped 5.x for a couple of years; verify which 5.x release line is recommended for new integrations (Shibboleth Consortium typically marks one minor line as "current stable"). Avoid 5.0.0 (rough edges typical of x.0.0); ideally 5.1.x or 5.2.x. **Action: implementer confirms at land time and pins via the `opensaml.version` POM [...]
+
+5. **Encrypted assertions (`<EncryptedAssertion>`) — in v1 or defer?** Some enterprise IdPs require encrypted assertions for sensitive attribute classes (e.g. anything tagged "restricted" in eduPerson). v1 plan ships signed-cleartext only. **Trade-off**: in-scope adds `opensaml-xmlsec-impl` Decrypter plumbing + a `decryptionCredential(Credential)` builder setting + tests; defers cleanly to v1.5 if not in scope. **Recommend: defer to v1.5**; flag for confirmation since some target users w [...]
+
+6. **Default signature algorithm allowlist.** Plan picks `[rsa-sha256, ecdsa-sha256]` (mirroring FINISHED-69's `JwtTokenValidator` defaults). Some legacy IdPs still sign with `rsa-sha1`; current NIST guidance deprecates SHA-1 for signatures. **Recommend: ship the strict default**; users who must accept SHA-1 opt in explicitly via `.signatureAlgorithms(...)` with a documented warning. Confirm.
+
+7. **Clock-skew default + max.** Plan picks 60s default, 300s max (mirrors FINISHED-69's JWT path). SAML deployments historically tolerate more skew than JWT (some IdPs have notoriously poor NTP discipline). **Should the SAML default be larger (e.g. 120s)?** Recommend: keep at 60s for parity with the JWT path; users can raise to 300s explicitly. Confirm.
+
+## Risk notes
+
+- **OpenSAML's XML parsing surface is large and CVE-prone.** XML libraries (xerces, xalan) have a long CVE history (XXE, billion-laughs, etc.). Mitigation: defer XML-parser hardening to OpenSAML's library code (which knows the SAML-specific risks better than we do); pin a current OpenSAML 5.x release with active CVE patching; document the OpenSAML version recommendation in the release notes so users know which line to track.
+- **`opensaml-xmlsec-impl` pulls `joda-time` and `xerces`/`xalan` transitively.** These are NOT trivial deps for downstream apps; the `provided`-scope containment makes them the consumer's problem, but downstream apps on `juneau-rest-server-saml` will see these transitively. Mitigation: documented in the module README + topic page; advise consumers to BOM-pin their XML stack.
+- **OpenSAML `InitializationService.initialize()` is a global, one-shot operation.** Calling it twice or from multiple threads concurrently can race. Mitigation: lazy double-checked-locking init in the validator constructor; document the bootstrap behavior.
+- **Signature verification is computationally expensive** (asymmetric crypto on potentially-large XML blobs). For high-traffic SP endpoints, this can dominate request latency. Mitigation: documented; recommend pairing with an SP-side session cookie that short-circuits re-validation once the assertion is consumed (future v1.5 work, not in v1).
+- **Audience-mismatch error messages might leak the configured SP entity ID.** Today's `AuthenticationException` body would include the audience-mismatch message verbatim. Mitigation: messages name "audience" generically without echoing the configured value; specific mismatch detail goes to the request log only.
+- **JWT/SAML algorithm-confusion attacks** — unlikely in the SAML world (SAML uses URN-style algorithm identifiers, not the JWT `alg` header), but the validator MUST still treat the algorithm as advisory and verify against the keys OpenSAML has registered for the assertion's signing credential rather than letting the algorithm hint pick the verification path. Mitigation: rely on OpenSAML's stock signature-verification pipeline; algorithm allowlist is enforced via OpenSAML's `SignatureVal [...]
+- **Stub-IdP test fixtures.** Tests need a way to produce signed SAML responses without spinning up a real IdP. Mitigation: use OpenSAML's stock `SignatureSupport` to sign in-memory `<Assertion>` objects with a generated keypair; the test classpath gets the same OpenSAML version as production via the `juneau-utest` test-scope dep. Pattern matches FINISHED-69's `JwtTestSupport` in `juneau-utest/src/test/java/org/apache/juneau/rest/auth/jwt/JwtTestSupport.java`.
+
+## Out of scope (recap)
+
+- IdP implementation (Juneau is SP, not IdP).
+- WS-Federation, SAML 1.x.
+- Encrypted assertions (v1.5).
+- HTTP Redirect / Artifact / SOAP bindings (POST only in v1).
+- Single Logout (SLO).
+- Attribute mapping DSL.
+
+## Related work
+
+- `todo/TODO-94a-auth-filter-framework.md` — **HARD prereq.** This module's `SamlAuthFilter extends AuthFilter` from TODO-94a; nothing to plug into without it. TODO-94a provides the chain orchestration, role aggregation, and request wrapping. This module ships only the SAML-specific validation + filter glue.
+- `todo/TODO-94c-oauth-module.md` — sibling. No hard dep between TODO-94b and TODO-94c (both depend on TODO-94a; neither depends on the other). Can land in parallel.
+- `todo/FINISHED-69-authn-guards-jwt-apikey.md` — **soft dep / pattern source.** Reuses FINISHED-69's `TokenValidator` SPI, `AuthenticationException` (with `wwwAuthenticate(...)`), and `ClaimsPrincipal` types verbatim. Mirrors FINISHED-69's `juneau-rest-server-jwt` module-isolation pattern (`provided`-scope third-party dep, containment check, parent-POM + distrib wiring).
+- `juneau-rest/juneau-rest-server-jwt/pom.xml` — the structural template this module's POM mirrors end-to-end.
+- `juneau-rest/juneau-rest-server-jwt/src/main/java/org/apache/juneau/rest/auth/jwt/JwtTokenValidator.java` — the design template for `SamlAssertionValidator` (builder shape, mandatory-check enforcement, algorithm allowlist, clock-skew cap).
diff --git a/todo/TODO-94c-oauth-module.md b/todo/TODO-94c-oauth-module.md
new file mode 100644
index 0000000000..1111b6c6a0
--- /dev/null
+++ b/todo/TODO-94c-oauth-module.md
@@ -0,0 +1,391 @@
+# TODO-94c: `juneau-rest-server-oauth` — OAuth 2.0 / OIDC integration module
+
+Source: promoted from `TODO.md` on 2026-05-25 during `/todo expand 94` (multi-file split per AGENTS.md letter-suffix precedent — see FINISHED-16a/b/c).
+
+**Hard dependency: TODO-94a (auth filter framework) must land first.** TODO-94a provides the `AuthFilter` SPI, `AuthFilterChain`, `AuthResult`, and `AuthenticatedRequestWrapper` that this module's `OAuthFilter` plugs into.
+
+**Soft dependency: FINISHED-69 — reused, not reimplemented.** For OAuth access tokens that happen to be JWTs (the dominant case under OIDC), this module delegates verification to FINISHED-69's `JwtTokenValidator` in `juneau-rest-server-jwt`. We do NOT reimplement JWT verification here.
+
+## Goal
+
+Ship a new opt-in Maven module `juneau-rest-server-oauth` covering the **resource-server-side** of the OAuth 2.0 / OIDC ecosystem — the side that *accepts* OAuth-issued access tokens on protected endpoints, validates them (either via opaque-token introspection per RFC 7662 or JWT verification), and exposes the authenticated subject + scopes to Juneau code. Plus a curated set of **flow helpers** for service-to-service clients that need to *acquire* tokens (authorization-code with PKCE, cl [...]
+
+Mirrors FINISHED-69's `juneau-rest-server-jwt` module isolation pattern: built on the JDK `java.net.http.HttpClient` for all back-channel calls; no Nimbus / Spring Security at the module boundary. The only OAuth-flavored third-party surface is `juneau-rest-server-jwt`'s nimbus path, accessed via TODO-94c's optional dep on the JWT module (`provided` scope — consumers opt in if they want JWT access tokens; opaque-token-only consumers skip it).
+
+End-state developer experience:
+
+```java
+// Resource-server side: protect /api/* with bearer-token validation.
+@Rest(path="/api")
+public class ApiResource extends RestServlet {
+
+ @Bean
+ public AuthFilterChain authFilters(BeanStore bs) {
+ // Discover endpoints from the IdP's OIDC metadata.
+ var oidc = OidcDiscoveryClient.create()
+ .issuer(URI.create("https://login.example.com/realms/api"))
+ .build()
+ .discover();
+
+ // For JWT access tokens (the OIDC default): delegate to FINISHED-69's JwtTokenValidator.
+ var jwtValidator = JwtTokenValidator.create()
+ .jwksUrl(oidc.jwksUrl())
+ .issuer(oidc.issuer().toString())
+ .audience("api.example.com")
+ .build();
+
+ // For opaque tokens (RFC 7662 introspection):
+ var opaqueValidator = OAuthIntrospectionValidator.create()
+ .introspectionEndpoint(oidc.introspectionEndpoint())
+ .clientId("api-server")
+ .clientSecret(envSecret("OAUTH_CLIENT_SECRET"))
+ .build();
+
+ return AuthFilterChain.create(bs)
+ .append(OAuthFilter.create()
+ .pattern("/api/*")
+ .validator(jwtValidator) // OR opaqueValidator; or both via two filters
+ .build())
+ .build();
+ }
+}
+
+// Client side: acquire a token via client-credentials.
+var token = OAuthClientCredentialsFlow.create()
+ .tokenEndpoint(URI.create("https://login.example.com/realms/api/protocol/openid-connect/token"))
+ .clientId("worker-service")
+ .clientSecret(envSecret("OAUTH_CLIENT_SECRET"))
+ .scope("read:orders write:orders")
+ .build()
+ .acquire();
+restClient.bearerToken(token.accessToken()).get("/api/orders").run();
+```
+
+## Why now
+
+- **Direct sibling of TODO-94b (SAML).** Both land on TODO-94a's filter framework; both extend FINISHED-69's `TokenValidator` SPI; both follow the `juneau-rest-server-jwt` module-isolation precedent. Together they cover the three dominant enterprise AuthN formats (JWT — FINISHED-69; SAML — TODO-94b; OAuth/OIDC — TODO-94c).
+- **OAuth 2.0 / OIDC is the dominant token-issuance protocol for modern services.** Every major IdP — Okta, Auth0, Keycloak, Azure AD, Cognito, Google — speaks it. Today a Juneau user accepting OAuth tokens either uses FINISHED-69's `JwtTokenValidator` directly (works for JWT access tokens but skips the OAuth client-flow story) or reaches for Spring Security's OAuth client. A first-class Juneau module closes both gaps.
+- **JDK `java.net.http.HttpClient` covers the entire back-channel surface.** Token endpoint, introspection endpoint, JWKS fetch, OIDC discovery — all are simple HTTPS GET/POST with JSON responses. No HTTP-client dep needed for the OAuth flow paths; the JWKS path is already covered by FINISHED-69's nimbus integration when JWT validation is in play.
+
+## Research findings (verified 2026-05-25)
+
+Significant facts shaping the design:
+
+1. **OAuth 2.0 standard surface area we care about:**
+ - **RFC 6749** — OAuth 2.0 framework: authorization-code, client-credentials, resource-owner password-credentials, refresh-token, implicit (deprecated). v1 ships all *except* implicit.
+ - **RFC 7636** — PKCE (Proof Key for Code Exchange). Mandatory for authorization-code in modern OAuth profiles.
+ - **RFC 7662** — Token introspection. The opaque-token validation path.
+ - **RFC 6750** — Bearer token usage (`Authorization: Bearer <token>`). Already covered by FINISHED-69's `BearerTokenGuard` extraction logic.
+ - **RFC 8414** — OAuth 2.0 Authorization Server Metadata (`/.well-known/oauth-authorization-server`). Companion to OIDC's `/.well-known/openid-configuration`.
+ - **RFC 8628** — Device authorization grant. Listed in scope-options as "defer to follow-on TODO unless trivially small"; current take: device-code requires browser-redirect coordination that doesn't fit the v1 "this is a resource-server + back-channel-client" charter cleanly. Defer.
+
+2. **OIDC standard surface area:**
+ - **OIDC Core 1.0** — ID tokens (a JWT shape), `userinfo` endpoint, scopes (`openid`, `profile`, `email`), `nonce` claim for replay protection.
+ - **OIDC Discovery 1.0** — `/.well-known/openid-configuration` endpoint returns JSON listing every IdP endpoint + capability flag. Drastically reduces config burden.
+ - **OIDC RP (Relying Party) Login Flow** — the user-facing "log in with Google/Okta" interactive flow. **Significantly larger than v1's resource-server charter** — covers session management, OIDC nonce verification, ID-token + access-token correlation, userinfo fetch, optional dynamic client registration. v1 ships the *building blocks* (discovery, JWT validation, authorization-code flow) but does NOT ship the end-to-end RP. See Open question 3.
+
+3. **JWT vs. opaque tokens.** OAuth 2.0 access tokens are spec-opaque (the resource server treats them as bearer strings). In practice:
+ - **JWT access tokens** — most modern IdPs (Okta, Auth0, Keycloak, Azure AD, Cognito) issue JWTs by default. Verification is local + cacheable JWKS fetch; zero per-request IdP round-trip. **TODO-94c delegates to FINISHED-69's `JwtTokenValidator` via the optional `juneau-rest-server-jwt` provided-scope dep.**
+ - **Opaque access tokens** — Google's Workspace tokens are the most famous example; some on-prem IdPs configure for opaque to keep token contents private. Verification requires an introspection round-trip per request (RFC 7662 POST to the IdP's introspection endpoint with `Authorization: Basic <client_id:client_secret>`). **TODO-94c ships `OAuthIntrospectionValidator` directly on the JDK `HttpClient`.**
+
+4. **JDK `java.net.http.HttpClient` is sufficient for every back-channel call.** Token endpoint POST (form-urlencoded body, JSON response), introspection POST (form body, JSON response), discovery GET (JSON response), JWKS GET (JSON response). No third-party HTTP client needed; the JDK's `HttpClient` (since JDK 11) covers timeouts, async, HTTP/2, basic auth, and TLS out of the box.
+
+5. **JSON parsing for OAuth/OIDC responses.** Token endpoint responses are tiny JSON objects (`access_token`, `token_type`, `expires_in`, `refresh_token`, `scope`). Introspection responses are similar (`active`, `sub`, `exp`, `scope`, etc.). Discovery responses are larger but still pure JSON. **Reuse `juneau-marshall`'s JSON parser** for everything — it's already a hard dep of `juneau-rest-server`. No new JSON-parser dep.
+
+6. **FINISHED-69's `JwtTokenValidator` is reusable as-is.** Its builder takes `jwksUrl(URI)`, `issuer(String)`, `audience(String)`, `algorithms(...)`, `clockSkew(Duration)`, `clock(Clock)`. The validator returns a `ClaimsPrincipal`. TODO-94c's `OAuthFilter` simply accepts a `TokenValidator` (FINISHED-69's SPI); users plug in either the JWT validator from the JWT module or this module's `OAuthIntrospectionValidator`.
+
+7. **Token cache design.** Both introspection and client-credentials flows benefit from per-token caching:
+ - **Introspection cache** — same opaque token validated within the cache window short-circuits the IdP round-trip. Default TTL bounded by `min(token's exp, configured-ttl)`; LRU bounded by `maxEntries`.
+ - **Client-credentials token cache** — a service acquiring tokens for back-channel calls should reuse them until `exp - skew`, not re-acquire on every call. Same shape.
+ Both cache SPIs are pluggable so consumers can swap an in-memory default for Redis / Caffeine / etc.
+
+8. **No HTTP-client surface conflict with `juneau-rest-client`.** `juneau-rest-client` exists for *user* HTTP calls; using it for the framework's OAuth back-channel would couple the OAuth module to the REST client's lifecycle + transitive deps. The JDK `HttpClient` keeps the boundary clean.
+
+## Resolved decisions
+
+1. **Build on `java.net.http.HttpClient` for ALL back-channel.** No `juneau-rest-client` dep; no Apache HttpClient; no OkHttp. Per-flow / per-validator builders accept an optional `httpClient(HttpClient)` so users who need custom HTTP behavior (proxies, custom SSL, timeouts) wire their own.
+
+2. **Reuse FINISHED-69's `juneau-rest-server-jwt` for JWT access-token validation; do NOT reimplement.** TODO-94c declares `juneau-rest-server-jwt` as a `provided`-scope dep so consumers who want JWT access tokens add both modules (and the nimbus dep) at runtime. Opaque-token-only consumers skip the JWT module entirely — TODO-94c's `OAuthFilter` accepts ANY `TokenValidator`. Containment: `mvn dependency:tree` on `juneau-rest-server-oauth` MUST NOT pull nimbus transitively; nimbus only su [...]
+
+3. **No Spring Security / Spring OAuth deps.** Same isolation discipline as FINISHED-69 and TODO-94b. Spring users who want Spring Security's OAuth client keep using it; this module is the Juneau-native peer.
+
+4. **JSON parsing via `juneau-marshall` (existing hard dep of `juneau-rest-server`).** No new JSON-parser dep.
+
+5. **Token cache SPI is pluggable; ship a bounded-LRU in-memory default.** `TokenCache` interface with `get(String key) -> Optional<CachedToken>` / `put(String key, CachedToken, Duration ttl)`. Default impl: `LinkedHashMap`-backed with `accessOrder=true` (LRU) + a max-entries cap (default 1000; configurable) + per-entry TTL eviction on `get`. Pluggable so a Redis / Caffeine impl drops in for distributed deployments.
+
+6. **`OAuthIntrospectionValidator implements TokenValidator`** (FINISHED-69's SPI). On `validate(String token)`: cache lookup first; on miss, POST to introspection endpoint with `Authorization: Basic <client_id:client_secret>` + form body `token=<token>&token_type_hint=access_token`; parse the JSON response; if `"active": false`, throw `AuthenticationException`; on `"active": true`, build a `ClaimsPrincipal` from the response fields (`sub` → `Principal.getName()`; `scope`, `client_id`, ` [...]
+
+7. **`OAuthFilter extends AuthFilter`** (TODO-94a's SPI). Pulls `Authorization: Bearer <token>` from the request (reuses FINISHED-69's extraction logic verbatim — same parser); delegates to the configured `TokenValidator`; wraps the result in an `AuthResult` with roles extracted from a configurable claim (default `scope` split on whitespace per RFC 6749 §3.3, mapped 1:1 into the role set).
+
+8. **OIDC discovery is a separate utility, not auto-fetched.** `OidcDiscoveryClient` is its own type; users call `.discover()` explicitly to get an `OidcMetadata` record. The metadata record's getters (`tokenEndpoint()`, `jwksUrl()`, `introspectionEndpoint()`, etc.) feed the validator and flow-helper builders. **Rationale:** discovery is a one-time startup call; baking it into the validator's lazy-init path would mean every test setup also pays the discovery cost + needs network. Explici [...]
+
+9. **Flow helpers are stateless value types.** Each flow type (`OAuthClientCredentialsFlow`, `OAuthAuthorizationCodeFlow`, `OAuthResourceOwnerFlow`, `OAuthRefreshTokenFlow`) is a builder-built object with an `acquire()` (or `exchange()`) method returning an `OAuthToken` record (`accessToken`, `tokenType`, `expiresAt`, `refreshToken Optional<...>`, `scope Optional<...>`). No mutable state on the flow objects themselves.
+
+## Architecture
+
+### Resource-server side (validation)
+
+```mermaid
+flowchart TB
+ subgraph wire [HTTP request]
+ Req["GET /api/orders<br/>Authorization: Bearer eyJ..."]
+ end
+ subgraph oauth [juneau-rest-server-oauth]
+ Filter[OAuthFilter<br/>extends AuthFilter — TODO-94a]
+ Switch{Validator<br/>type?}
+ Intr[OAuthIntrospectionValidator<br/>implements TokenValidator — FINISHED-69]
+ Cache[TokenCache<br/>bounded LRU default]
+ Http[java.net.http.HttpClient<br/>POST introspect endpoint]
+ end
+ subgraph jwt [juneau-rest-server-jwt — FINISHED-69, provided-scope dep]
+ Jwt[JwtTokenValidator<br/>implements TokenValidator]
+ end
+ subgraph downstream [TODO-94a chain]
+ Chain[AuthFilterChain]
+ Wrap[AuthenticatedRequestWrapper]
+ Op["@RestGet handler<br/>(@Auth ClaimsPrincipal p)"]
+ end
+
+ Req --> Filter
+ Filter --> Switch
+ Switch -->|"opaque token"| Intr
+ Intr --> Cache
+ Cache -->|"miss"| Http
+ Http -->|"active: true + claims"| Cache
+ Cache -->|"hit or refreshed"| Intr
+ Intr -->|"ClaimsPrincipal"| Filter
+ Switch -->|"JWT token"| Jwt
+ Jwt -->|"ClaimsPrincipal"| Filter
+ Filter -->|"AuthResult<br/>roles = scope split"| Chain
+ Chain --> Wrap --> Op
+
+ classDef new fill:#cdf,stroke:#06c,color:#000
+ classDef finished fill:#cfc,stroke:#0a0,color:#000
+ classDef framework fill:#fec,stroke:#c60,color:#000
+ class Filter,Intr,Cache,Http new
+ class Jwt finished
+ class Chain,Wrap,Op framework
+```
+
+### Client side (token acquisition flows)
+
+```mermaid
+flowchart TB
+ subgraph client [Service client code]
+ Calls[Application code]
+ end
+ subgraph flows [juneau-rest-server-oauth — flow helpers]
+ AC[OAuthAuthorizationCodeFlow<br/>+ PKCE]
+ CC[OAuthClientCredentialsFlow]
+ RO[OAuthResourceOwnerFlow<br/>discouraged; documented warning]
+ RT[OAuthRefreshTokenFlow]
+ TC[TokenCache<br/>shared with validator side]
+ HC[java.net.http.HttpClient<br/>POST token endpoint]
+ end
+ subgraph idp [Identity Provider]
+ TE[Token endpoint]
+ end
+
+ Calls --> AC
+ Calls --> CC
+ Calls --> RO
+ Calls --> RT
+ AC --> TC --> HC
+ CC --> TC --> HC
+ RO --> HC
+ RT --> HC
+ HC --> TE
+ TE -->|"OAuthToken<br/>(accessToken, expiresAt, refreshToken?)"| HC
+ HC -->|"cache when applicable"| TC
+ TC -->|"OAuthToken"| Calls
+
+ classDef new fill:#cdf,stroke:#06c,color:#000
+ classDef discourage fill:#fcc,stroke:#c00,color:#000
+ class AC,CC,RT,TC,HC new
+ class RO discourage
+```
+
+### OIDC discovery
+
+```mermaid
+flowchart LR
+ App[Startup code] -->|"issuer URL"| Disc[OidcDiscoveryClient.discover]
+ Disc -->|"GET /.well-known/<br/>openid-configuration"| IdP[(IdP)]
+ IdP -->|"JSON metadata"| Disc
+ Disc -->|"OidcMetadata record"| App
+ App -->|"tokenEndpoint, jwksUrl,<br/>introspectionEndpoint, issuer"| Builders[Validator + Flow builders]
+```
+
+## Scope
+
+**In scope (v1):**
+
+- New Maven module `juneau-rest/juneau-rest-server-oauth/` with POM mirroring `juneau-rest-server-jwt` (parent `juneau-rest`, `bundle` packaging, OSGi manifest, jacoco wiring, source-jar attach).
+- POM deps:
+ - Hard dep: `juneau-rest-server` (transitively pulls TODO-94a's filter framework types + FINISHED-69's `TokenValidator` / `ClaimsPrincipal` / `AuthenticationException`).
+ - **`provided` scope**: `juneau-rest-server-jwt` (consumers who want JWT access tokens add it + the nimbus dep at runtime; opaque-token-only consumers don't pay this cost).
+ - No HTTP-client dep — JDK `java.net.http.HttpClient` only.
+ - No JSON-parser dep — `juneau-marshall` already transitively present.
+- **`org.apache.juneau.rest.auth.oauth.OAuthIntrospectionValidator implements TokenValidator`** (FINISHED-69 SPI):
+ - Builder accepts `introspectionEndpoint(URI)`, `clientId(String)`, `clientSecret(String)` (or `clientSecretSupplier(Supplier<String>)` for rotation), `httpClient(HttpClient)` (optional), `tokenCache(TokenCache)` (optional; defaults to bounded LRU), `cacheTtl(Duration)` (default 5 min, max 1h; capped by token's `exp` if shorter), `clock(Clock)` (default `Clock.systemUTC()`), `requiredScopes(String...)` (optional — extra check that the token's `scope` claim covers these).
+ - `validate(String token)`:
+ 1. Cache lookup; if hit + not expired, return cached `ClaimsPrincipal`.
+ 2. POST to introspection endpoint with `Authorization: Basic <base64(clientId:clientSecret)>` + form body `token=<token>&token_type_hint=access_token`.
+ 3. Parse JSON response.
+ 4. If `"active": false`, throw `AuthenticationException("Token inactive")` with `WWW-Authenticate: Bearer realm="<realm>", error="invalid_token"`.
+ 5. If `requiredScopes` set and `scope` claim doesn't cover them, throw `AuthenticationException("Required scope missing")` with `WWW-Authenticate: Bearer realm="...", error="insufficient_scope"`.
+ 6. Build `ClaimsPrincipal` from response fields; cache; return.
+- **`org.apache.juneau.rest.auth.oauth.OAuthFilter extends AuthFilter`** (TODO-94a SPI):
+ - Builder accepts standard `AuthFilter` shape + `validator(TokenValidator)` + `rolesClaim(String)` (default `"scope"`; values whitespace-split per RFC 6749 §3.3) + `realm(String)` (default `"api"`).
+ - `authenticate(req)`:
+ 1. Extract `Authorization: Bearer <token>` (reuse FINISHED-69's extraction logic; same parser).
+ 2. If absent / malformed, return empty (filter doesn't apply).
+ 3. Delegate to `validator.validate(token)`; throw on `AuthenticationException`.
+ 4. Build `AuthResult` from the returned `Principal` + roles extracted from the configured `rolesClaim`.
+- **Flow helpers** in `org.apache.juneau.rest.auth.oauth.flow`:
+ - **`OAuthClientCredentialsFlow`** — `tokenEndpoint(URI)`, `clientId(String)`, `clientSecret(String)` (or supplier), `scope(String...)` (joined with spaces per spec), `httpClient(HttpClient)` (optional). `acquire()` returns `OAuthToken`. Cached per `(clientId, scope)` key when `tokenCache(TokenCache)` is supplied.
+ - **`OAuthAuthorizationCodeFlow`** — `tokenEndpoint(URI)`, `authorizationEndpoint(URI)` (for the URL generator), `clientId(String)`, `clientSecret(Optional<String>)` (public clients omit), `redirectUri(URI)`, `scope(String...)`, `httpClient(HttpClient)` (optional). Provides `buildAuthorizationUrl(state, pkceChallenge)` (PKCE S256 mandatory) and `exchange(code, pkceVerifier)` returning `OAuthToken`. The flow itself does NOT manage state/PKCE storage — that's the caller's responsibilit [...]
+ - **`OAuthResourceOwnerFlow`** — `tokenEndpoint(URI)`, `clientId(String)`, `clientSecret(String)`, `username(String)`, `password(String)`, `scope(String...)`, `httpClient(HttpClient)` (optional). `acquire()` returns `OAuthToken`. **Discouragement notice**: javadoc + topic-page warning that this grant type was removed from OAuth 2.1; legitimate use limited to first-party trusted clients that already have the user's credentials. Filed under `@Deprecated(since = "9.5.0")` from day-1 to [...]
+ - **`OAuthRefreshTokenFlow`** — `tokenEndpoint(URI)`, `clientId(String)`, `clientSecret(Optional<String>)`, `refreshToken(String)`, `scope(String...)` (optional narrowing), `httpClient(HttpClient)` (optional). `acquire()` returns `OAuthToken` with a potentially-rotated refresh token.
+- **`org.apache.juneau.rest.auth.oauth.OAuthToken`** record: `accessToken (String)`, `tokenType (String)`, `expiresAt (Instant)`, `refreshToken (Optional<String>)`, `scope (Optional<Set<String>>)`, `idToken (Optional<String>)`. Immutable.
+- **OIDC discovery** in `org.apache.juneau.rest.auth.oauth.oidc`:
+ - `OidcDiscoveryClient` — `.issuer(URI)`, `.httpClient(HttpClient)`, `.build().discover() -> OidcMetadata`. Fetches `<issuer>/.well-known/openid-configuration`. Cached per-instance (one-shot — re-create for refresh).
+ - `OidcMetadata` record — getters for the standard OIDC + OAuth metadata fields the validators/flows need (`issuer`, `tokenEndpoint`, `authorizationEndpoint`, `introspectionEndpoint`, `jwksUrl`, `userinfoEndpoint`, `endSessionEndpoint`, `supportedScopes`, etc.). Unknown fields preserved as `Map<String, Object> extras()` for IdP-specific extensions.
+- **`org.apache.juneau.rest.auth.oauth.TokenCache`** SPI + default bounded-LRU impl `BoundedLruTokenCache` (default 1000 entries, configurable). Pluggable so Redis/Caffeine impls drop in.
+- **Tests** in `juneau-utest/src/test/java/org/apache/juneau/rest/auth/oauth/`:
+ - `OAuthIntrospectionValidator_HappyPath_Test`
+ - `OAuthIntrospectionValidator_Inactive_Test`
+ - `OAuthIntrospectionValidator_InsufficientScope_Test`
+ - `OAuthIntrospectionValidator_Cache_Test` (cache hit / miss / TTL eviction / per-entry exp cap)
+ - `OAuthIntrospectionValidator_Builder_Test`
+ - `OAuthFilter_Test`
+ - `OAuthFilter_JwtValidator_IntegrationTest` (delegates to `juneau-rest-server-jwt`)
+ - `OAuthClientCredentialsFlow_Test` (with `OAuthClientCredentialsFlow_Cache_Test`)
+ - `OAuthAuthorizationCodeFlow_Test` (PKCE generation + auth-URL building + code-exchange happy path)
+ - `OAuthResourceOwnerFlow_Test` (happy path + the `@Deprecated` warning round-trip)
+ - `OAuthRefreshTokenFlow_Test` (refresh + refresh-token rotation)
+ - `OidcDiscoveryClient_Test` (fetch + parse + unknown-field preservation in `extras()`)
+ - `BoundedLruTokenCache_Test`
+ - **Containment check** — `mvn -pl juneau-rest/juneau-rest-server dependency:tree | grep -i nimbus` returns empty (TODO-94c does NOT add nimbus to the upstream tree; nimbus only surfaces if the consumer pulls the JWT module too).
+- Module-level test deps in `juneau-utest/pom.xml` (test scope only): `juneau-rest-server-oauth` + `juneau-rest-server-jwt` (for the JWT-delegating filter test) + `nimbus-jose-jwt` (test scope — required by `juneau-rest-server-jwt`'s tests). Fixtures: a stub IdP fronting `WireMock`-style HTTP stubs or a thin `HttpClient`-mock layer.
+- **Docs**: new topic page `juneau-docs/pages/topics/OAuthAuthSupport.md`. Release-notes entry `### juneau-rest-server-oauth (new module)`.
+
+**Explicitly out of scope (v1):**
+
+- **Device-code flow (RFC 8628).** Browser-redirect coordination doesn't fit the resource-server + back-channel-client v1 charter cleanly. Defer to follow-on TODO.
+- **OAuth 1.x.** Deprecated; no demand.
+- **Implicit flow.** Deprecated in OAuth 2.1; security flaws around access-token-in-URL fragment.
+- **Custom grant types** beyond the four standard flows (e.g. JWT-bearer-grant RFC 7523, SAML2-bearer-grant RFC 7522). File as follow-ons if requested.
+- **End-to-end OIDC Relying-Party (RP) login flow.** Discovery, JWT validation, and authorization-code flow are in scope; the *session-management + nonce-correlation + userinfo-fetch + ID-token-claims-into-session* glue that turns those into a "Log in with Google" button is its own non-trivial design. See Open question 3 for whether this changes.
+- **Dynamic client registration (RFC 7591).** Niche; manual client provisioning is the dominant practice. Defer.
+- **PAR (Pushed Authorization Requests, RFC 9126).** Modern but not yet ubiquitous. Defer to a v1.5 if real-world demand surfaces.
+- **mTLS-bound tokens (RFC 8705) / DPoP (RFC 9449).** Sender-constrained token shapes; orthogonal to the bearer-token v1 surface.
+- **OIDC dynamic-key-rotation listening** (refresh JWKS on `kid` miss). FINISHED-69's `JwksCache` already handles TTL-driven refresh + graceful-degradation; on-`kid`-miss eager refresh is a v1.5 enhancement.
+
+## Implementation plan
+
+### Phase 0 — confirm seams (read-only)
+
+1. Confirm TODO-94a has landed and `AuthFilter` / `AuthFilterChain` / `AuthResult` / `AuthenticatedRequestWrapper` are stable.
+2. Confirm FINISHED-69's `TokenValidator` / `ClaimsPrincipal` / `AuthenticationException` are stable and that `JwtTokenValidator` in `juneau-rest-server-jwt` is consumable as a normal `TokenValidator` (it should be — the JWT module's whole point was being a drop-in `TokenValidator`).
+3. Confirm `juneau-marshall`'s JSON parser handles the introspection / discovery / token-endpoint JSON shapes cleanly (single-level objects with mixed string / number / boolean / array values; no surprises).
+4. Confirm JDK `java.net.http.HttpClient` is available in the target JDK version (yes — JDK 17 is the project floor; `HttpClient` since JDK 11).
+5. Confirm containment: nothing in `juneau-rest-server-oauth`'s own POM transitively pulls nimbus.
+
+### Phase 1 — module skeleton + POM + containment check
+
+1. New module `juneau-rest/juneau-rest-server-oauth/` with `pom.xml` mirroring `juneau-rest-server-jwt`.
+2. `provided`-scope dep on `juneau-rest-server-jwt`. No nimbus dep at the OAuth module's own POM.
+3. Module registered in `juneau-rest/pom.xml` `<modules>` + `juneau-distrib/pom.xml` `<artifactItem>` entries.
+4. Containment check passes.
+
+### Phase 2 — `OAuthIntrospectionValidator` + `TokenCache` SPI + bounded-LRU default
+
+1. Validator + builder + cache SPI + default impl.
+2. Tests:
+ - `OAuthIntrospectionValidator_HappyPath_Test`
+ - `OAuthIntrospectionValidator_Inactive_Test`
+ - `OAuthIntrospectionValidator_InsufficientScope_Test`
+ - `OAuthIntrospectionValidator_Cache_Test`
+ - `OAuthIntrospectionValidator_Builder_Test`
+ - `BoundedLruTokenCache_Test`
+
+### Phase 3 — `OAuthFilter` + JWT delegation integration
+
+1. `OAuthFilter` extending TODO-94a's `AuthFilter`.
+2. Tests:
+ - `OAuthFilter_Test` (happy path with introspection validator)
+ - `OAuthFilter_JwtValidator_IntegrationTest` (filter wired to FINISHED-69's `JwtTokenValidator`; confirms the cross-module composition works)
+
+### Phase 4 — flow helpers (client side)
+
+1. `OAuthToken` record.
+2. `OAuthClientCredentialsFlow` + `OAuthAuthorizationCodeFlow` + `OAuthResourceOwnerFlow` (`@Deprecated`) + `OAuthRefreshTokenFlow`.
+3. Tests for each flow.
+
+### Phase 5 — OIDC discovery
+
+1. `OidcDiscoveryClient` + `OidcMetadata` record.
+2. Tests: `OidcDiscoveryClient_Test` (happy path + unknown-field preservation + endpoint extraction).
+
+### Phase 6 — docs + release notes
+
+1. Release-notes entry under `### juneau-rest-server-oauth (new module)`. Include Maven coordinates, the `provided`-scope JWT-module note, and the JDK `HttpClient` minimal-deps callout.
+2. New topic page `juneau-docs/pages/topics/OAuthAuthSupport.md` covering: resource-server-side filter + validator wiring, JWT-vs-opaque token decision matrix, the four flow helpers (with the `OAuthResourceOwnerFlow` discouragement warning prominent), OIDC discovery walkthrough, token-cache configuration.
+3. Cross-link from TODO-94a's `AuthFilterFramework.md` and FINISHED-69's `AuthGuards.md` + `JwtTokenValidator` javadoc.
+
+## Acceptance criteria
+
+- [ ] New module `juneau-rest/juneau-rest-server-oauth` builds and tests pass.
+- [ ] No nimbus / Spring deps at the OAuth module's POM boundary; containment check confirms.
+- [ ] `OAuthIntrospectionValidator implements TokenValidator` (FINISHED-69 SPI) verified by reflection in a test.
+- [ ] `OAuthFilter extends AuthFilter` (TODO-94a SPI) verified.
+- [ ] Filter + JWT-validator delegation works end-to-end (proves the soft-dep on FINISHED-69's JWT module).
+- [ ] All four flow helpers compile-time-verified: `OAuthClientCredentialsFlow`, `OAuthAuthorizationCodeFlow` (PKCE S256 mandatory), `OAuthResourceOwnerFlow` (with `@Deprecated`), `OAuthRefreshTokenFlow`.
+- [ ] OIDC discovery returns a populated `OidcMetadata` against a stub IdP fixture.
+- [ ] Bounded-LRU token cache enforces both max-entries cap AND per-entry TTL, with eviction tests covering both.
+- [ ] Coverage ≥ 85% on the OAuth module (network-bound paths exercised through HttpClient mocks / stub-IdP fixtures).
+- [ ] Full `./scripts/test.py` green.
+
+## Open questions
+
+1. **Token-cache TTL default + LRU bound.** Plan picks 5 min default TTL (capped by token's `exp` when shorter), max TTL 1h, default LRU 1000 entries. **Are these defaults right?** 5 min TTL means a revoked token still works for up to 5 min — acceptable for most setups, dangerous for high-security ones. **Alternative**: shorter default (60s) + clearer documentation that operators should tune up if their introspection endpoint can't handle the QPS. Confirm before Phase 2.
+
+2. **Bundle a default introspection-endpoint client or require consumer wiring?** Plan picks "bundled by default" — the `OAuthIntrospectionValidator.Builder` accepts `introspectionEndpoint(URI)` + `clientId(String)` + `clientSecret(String)` and constructs an internal `HttpClient`-backed call. Alternative: require the user to supply an `IntrospectionClient` they built themselves. **Recommend: bundled default** with the optional `httpClient(HttpClient)` escape hatch for custom HTTP behavio [...]
+
+3. **OIDC RP (Relying-Party) login flow — in v1 or deferred?** v1 plan ships the building blocks (discovery, JWT validation, authorization-code flow with PKCE) but does NOT ship the end-to-end "Log in with Google" RP. The RP layer would add: session-cookie management, nonce generation+storage+verification, ID-token claims → session, userinfo fetch, state CSRF protection, OIDC-specific error handling. **Trade-off:** in-scope = ~500 LOC + non-trivial session-storage SPI; defer = users comp [...]
+
+4. **`OAuthResourceOwnerFlow` ship-or-skip.** OAuth 2.1 has removed this grant type. We're shipping it anyway because (a) some IdPs still require it for legacy client migrations, and (b) it's tiny (one POST). **Confirm**: ship-with-`@Deprecated`-since-9.5.0 (current plan) vs. don't-ship-at-all (force users who need it to construct the HttpClient call manually). Recommend: ship-with-warning so the migration story is "use Juneau's helper but heed the IDE warning" rather than "go write your [...]
+
+5. **Device-code flow (RFC 8628) — confirm defer.** Current plan defers. The original TODO bullet said "defer to a follow-on TODO unless trivially small". Device-code is ~100 LOC of polling logic + the user-experience of "show this code to the user and wait for them to enter it on another device"; the latter doesn't really belong in a framework module. **Confirm defer.**
+
+6. **`requiredScopes` enforcement on the validator vs. the filter.** Plan puts the check on `OAuthIntrospectionValidator.Builder.requiredScopes(...)`. Could also live on `OAuthFilter.Builder.requiredScopes(...)` (since scope semantics are an AuthZ concern, and AuthZ traditionally sits closer to the filter/op layer than the validator). **Recommend: keep on the validator** so the JWT path (FINISHED-69's `JwtTokenValidator` — which doesn't have a `requiredScopes` setting today) and the intr [...]
+
+7. **JWKS-on-kid-miss eager refresh — coordinate with FINISHED-69 or defer entirely?** FINISHED-69's `JwksCache` refreshes on TTL only; if an IdP rotates keys outside the TTL window and the cached key set doesn't contain the new `kid`, validation fails until the next TTL expiry. The OAuth module hits this same path when validating JWTs. **Should TODO-94c land an enhancement to FINISHED-69 to add `kid`-miss eager refresh, or defer that to a future TODO touching FINISHED-69 specifically?** [...]
+
+## Risk notes
+
+- **OAuth implementations vary wildly between IdPs.** Spec compliance is unevenly enforced; some IdPs return `expires_in` as a string, some lowercase scope values, some omit `token_type` (assumed `Bearer`). Mitigation: defensive parsing of IdP responses; explicit IdP-compatibility test matrix in the docs (call out tested-against Keycloak, Okta, Auth0, Azure AD); document the workarounds the validator/flow helpers ship with.
+- **Token-cache memory bound is the implementer's responsibility.** A naïve `Map<String, CachedToken>` with no size cap would leak memory under a steady stream of unique tokens (e.g. a misbehaving client cycling tokens). Mitigation: bounded LRU is mandatory in the default impl; document the trade-off (LRU bound vs. miss rate) clearly.
+- **Introspection endpoint outage stalls every request.** If the IdP's introspection endpoint goes down, every uncached token fails validation. Mitigation: bounded cache + graceful-degradation option (configurable: serve stale on introspection failure vs. fail-closed). Defaults fail-closed (security-safe default); operators opt in to stale-tolerance.
+- **PKCE implementation correctness.** The S256 challenge construction (`base64url(sha256(verifier))`) is easy to get wrong in subtle ways (e.g. forgetting URL-safe base64; padding handling). Mitigation: code-review gate; comprehensive `OAuthAuthorizationCodeFlow_Test` against known-good vector from RFC 7636 §4.
+- **Client-secret handling.** Validators / flows take `clientSecret(String)` — secrets in plain `String` linger in the heap and may be picked up by heap dumps. Mitigation: `clientSecretSupplier(Supplier<String>)` overload so users can pull secrets from a secret manager on demand without holding them; document the trade-off; do NOT bundle a default secret-manager integration in v1.
+- **Authorization-code state/PKCE storage.** TODO-94c's `OAuthAuthorizationCodeFlow` does NOT manage state or PKCE storage — that's the caller's job. **Risk**: callers will get this wrong (storing PKCE in a query string, not validating state correctly). Mitigation: javadoc + topic-page guidance; the topic page ships a worked example showing the storage pattern correctly.
+- **Logging of tokens.** Never log access / refresh tokens. Mitigation: code-review gate; tests assert no token substring appears in any logged-message capture; `OAuthIntrospectionValidator`'s diagnostic exceptions echo only the response shape, never the token.
+
+## Out of scope (recap)
+
+- Device-code flow (RFC 8628).
+- Implicit flow, OAuth 1.x, custom grant types.
+- End-to-end OIDC RP login flow (only the building blocks ship).
+- Dynamic client registration, PAR, mTLS-bound / DPoP tokens.
+- JWKS-on-kid-miss eager refresh (defer to a separate TODO touching FINISHED-69's JWKS code).
+
+## Related work
+
+- `todo/TODO-94a-auth-filter-framework.md` — **HARD prereq.** This module's `OAuthFilter extends AuthFilter` from TODO-94a; chain orchestration, role aggregation, request wrapping all live there.
+- `todo/TODO-94b-saml-module.md` — sibling. No hard dep between TODO-94b and TODO-94c (both depend on TODO-94a only); can land in parallel.
+- `todo/FINISHED-69-authn-guards-jwt-apikey.md` — **soft dep.** Reuses FINISHED-69's `TokenValidator` / `AuthenticationException` / `ClaimsPrincipal` SPIs verbatim. For JWT access tokens, delegates to FINISHED-69's `JwtTokenValidator` via a `provided`-scope dep on `juneau-rest-server-jwt`. Mirrors FINISHED-69's `juneau-rest-server-jwt` module-isolation pattern.
+- `juneau-rest/juneau-rest-server-jwt/` — `provided`-scope optional dep; consumers opt in for JWT access-token support; opaque-token-only consumers skip it. The OAuth module's POM declares this dep at `provided` scope; containment check confirms `juneau-rest-server-oauth` does NOT transitively pull nimbus.
+- `juneau-rest/juneau-rest-server-jwt/src/main/java/org/apache/juneau/rest/auth/jwt/JwtTokenValidator.java` — the design template for `OAuthIntrospectionValidator` (builder shape, `TokenValidator` impl, claim mapping).
+- `juneau-rest/juneau-rest-server-jwt/src/main/java/org/apache/juneau/rest/auth/jwt/JwksCache.java` — the cache-design template for `BoundedLruTokenCache` (bounded, TTL-driven, graceful-degradation-aware).
diff --git a/todo/TODO.md b/todo/TODO.md
index fe53a1f81f..58514cc669 100644
--- a/todo/TODO.md
+++ b/todo/TODO.md
@@ -1,66 +1,65 @@
# TODO
-## Execution order (re-evaluated 2026-05-25)
-
-Four foundational TODOs (TODO-73, TODO-81, TODO-69) and four mixin packs (TODO-74–77) have landed. **TODO-20 (rest debug rethink) was un-parked 2026-05-25** with a hard-break decision + source-of-truth nested-annotation pattern added to the plan; it is now the next-in-flight item ahead of TODO-78. Plans for TODO-71, TODO-82–84, TODO-85–87, and TODO-89 are fleshed out (2026-05-24). TODO-37 (agent instruction consolidation) remains parked.
+Live work plan for the Juneau 9.5.0 development cycle. Completed work is tracked separately in [`FINISHED.md`](FINISHED.md) — items move there when they land (and are removed from this file). The detailed per-TODO archives live alongside in `todo/FINISHED-<id>-<slug>.md`.
-### Completed foundations + mixin family
+## Execution order (re-evaluated 2026-05-25)
-1. ~~**TODO-73** — Runtime-overridable `@Rest(paths=...)`. Foundational; unblocked TODO-74–78.~~ ✅ done — see `todo/FINISHED-73-rest-paths-runtime-override.md`.
-2. ~~**TODO-81** — Mixin sub-`RestContext` inheritance.~~ ✅ done — see `todo/FINISHED-81-mixin-sub-context-inheritance.md`.
-3. ~~**TODO-74** — API-docs mixin pack (Swagger, Swagger-UI, OpenAPI, Redoc).~~ ✅ done — see `todo/FINISHED-74-mixin-api-docs.md`.
-4. ~~**TODO-75** — Static-files mixin (`BasicStaticFilesResource`).~~ ✅ done — see `todo/FINISHED-75-mixin-static-files.md`.
-5. ~~**TODO-76** — Convention-endpoints pack (favicon / SEO / version / well-known).~~ ✅ done — see `todo/FINISHED-76-mixin-convention-endpoints.md`.
-6. ~~**TODO-77** — Ops/introspection pack (echo / admin / route-index).~~ ✅ done — see `todo/FINISHED-77-mixin-ops-introspection.md`. Landed `org.apache.juneau.rest.guard.DenyAllGuard` as the secure-by-default placeholder for `BasicAdminResource`; TODO-69 just needs to register its `BearerTokenGuard` / `ApiKeyGuard` into the host `RestGuardList` to unlock the admin paths (no source change to the mixin).
+**TODO-79 (`@Value` annotation + Spring Boot `application.yaml` bridge) is the next-in-flight item — pulled forward from Phase G** after a 2026-05-25 plan expansion added Phase 6 (internal adoption audit; scoped user-facing per OQA). TODO-78 (JSP) and view siblings remain queued behind it. Plans for TODO-71, TODO-82–84, TODO-85–87, and TODO-89 are fleshed out (2026-05-24). TODO-37 (agent instruction consolidation) remains parked. See [`FINISHED.md`](FINISHED.md) for the work already land [...]
### Live execution order (next, in dependency order)
-**Phase A — auth (completed):**
-
-7. ~~**TODO-69** — AuthN guards + isolated `juneau-rest-server-jwt` sub-module.~~ ✅ done — see `todo/FINISHED-69-authn-guards-jwt-apikey.md`.
+**Phase A — `@Value` annotation + config bridge (next in flight):**
-**Phase B — debug rethink (next in flight):**
+1. **TODO-79** — Juneau `@Value` annotation + `${...}` shortcut + Spring Boot `application.yaml` bridge for the Config API. Phases 1–4 implement the annotation + `BeanInstantiator` wiring + `${...}` tokenizer shortcut + `Config`/Spring `Environment` `PropertySource` auto-registration. Phase 5 docs/release-notes. **Phase 6 (added 2026-05-25)** runs an internal adoption audit, scoped **user-facing per OQA** (5–15 migrations cap; framework-internal pass deferred to TODO-92). Plan: `todo/TOD [...]
-8. ~~**TODO-20** — Rest debug rethink. Collapses five `@Rest`/`@RestOp` debug attributes + `DebugEnablement` + parallel `CallLogger` rule lists into a single `DebugConfig` bean + a typed `@Debug` annotation. **Hard break** (no deprecation cycle; migration notes in `juneau-docs/pages/topics/23.01.V9.5-migration-guide.md`). **Source-of-truth pattern** — `@Debug` is nested as `@Rest(debug=@Debug(...))` and `@RestOp(debug=@Debug(...))` so the `@Rest`/`@RestOp` annotation is the canonical cap [...]
+**Phase B — view infrastructure (hard prereq for Phase C):**
-**Phase C — view infrastructure (hard prereq for Phase D):**
+2. **TODO-78** — JSP module (`juneau-rest-server-view-jsp`). Introduces the generic `View` interface in core `juneau-rest-server` and the `ResponseProcessor`-based renderer pattern that TODO-82/83/84 build on. Engine-agnostic POM (Option B) stance baked in. HARD prereq for TODO-82/83/84.
-9. **TODO-78** — JSP module (`juneau-rest-server-view-jsp`). Introduces the generic `View` interface in core `juneau-rest-server` and the `ResponseProcessor`-based renderer pattern that TODO-82/83/84 build on. Engine-agnostic POM (Option B) stance baked in. HARD prereq for TODO-82/83/84.
+**Phase C — view module siblings (parallelizable after TODO-78 lands; no inter-sibling deps):**
-**Phase D — view module siblings (parallelizable after TODO-78 lands; no inter-sibling deps):**
+3. **TODO-82** — Thymeleaf view module. Highest priority of the three (Spring Boot's default web view; biggest existing-user-base migration path). Plan: `todo/TODO-82-view-module-thymeleaf.md`.
+4. **TODO-83** — Mustache view module. Smallest surface area, lowest risk. Plan: `todo/TODO-83-view-module-mustache.md`.
+5. **TODO-84** — FreeMarker view module. Apache-family alignment bonus. Plan: `todo/TODO-84-view-module-freemarker.md`.
-10. **TODO-82** — Thymeleaf view module. Highest priority of the three (Spring Boot's default web view; biggest existing-user-base migration path). Plan: `todo/TODO-82-view-module-thymeleaf.md`.
-11. **TODO-83** — Mustache view module. Smallest surface area, lowest risk. Plan: `todo/TODO-83-view-module-mustache.md`.
-12. **TODO-84** — FreeMarker view module. Apache-family alignment bonus. Plan: `todo/TODO-84-view-module-freemarker.md`.
+**Phase D — application showcase tier:**
-**Phase E — application showcase tier:**
-
-13. **TODO-85** — `juneau-microservice-jetty-starter`. Standalone, no hard deps; can land any time after FINISHED-74/75/76/77 (which it bundles). Plan: `todo/TODO-85-microservice-jetty-starter.md`.
-14. **TODO-86** — `juneau-petstore-jetty` sample app. Soft deps on TODO-85 (starter fallback to raw `juneau-microservice-jetty`), TODO-69 (auth fallback to `DenyAllGuard`), TODO-82 (preferred view engine: Thymeleaf, fallback to TODO-78 JSP). Defines the shared `juneau-petstore-core` module consumed by TODO-87. Plan: `todo/TODO-86-petstore-jetty-app.md`.
-15. **TODO-87** — `juneau-petstore-springboot` sample app. HARD dep on `juneau-petstore-core` from TODO-86; should land alongside or immediately after TODO-86 as a coherent landing. Plan: `todo/TODO-87-petstore-springboot-app.md`.
+6. **TODO-85** — `juneau-microservice-jetty-starter`. Standalone, no hard deps; can land any time after FINISHED-74/75/76/77 (which it bundles). Plan: `todo/TODO-85-microservice-jetty-starter.md`.
+7. **TODO-86** — `juneau-petstore-jetty` sample app. Soft deps on TODO-85 (starter fallback to raw `juneau-microservice-jetty`), FINISHED-69 (auth fallback to `DenyAllGuard`), TODO-82 (preferred view engine: Thymeleaf, fallback to TODO-78 JSP). Defines the shared `juneau-petstore-core` module consumed by TODO-87. Plan: `todo/TODO-86-petstore-jetty-app.md`.
+8. **TODO-87** — `juneau-petstore-springboot` sample app. HARD dep on `juneau-petstore-core` from TODO-86; should land alongside or immediately after TODO-86 as a coherent landing. Plan: `todo/TODO-87-petstore-springboot-app.md`.
> **Open question for TODO-86/87** (surfaced by planning worker): factor REST resource classes into a third sibling `juneau-petstore-rest` module so both sample apps consume identical resource classes? Worth resolving before either starts implementation.
-**Phase F — quality-of-life follow-ons (parallelizable, any order, anytime after Phase A):**
+**Phase E — quality-of-life follow-ons (parallelizable, any order, anytime):**
+
+9. **TODO-89** — `RateLimitGuard.Storage.snapshot()` SPI + `BasicAdminResource` enrichment. Small (~30 LOC + 2 test files), closes a known carry-over from FINISHED-77 (`"buckets": []` placeholder). Plan: `todo/TODO-89-ratelimit-storage-snapshot-spi.md`.
+10. **TODO-71** — Doc-site script + Docusaurus search swap. Mostly already done (planning worker found `juneau-docs/scripts/build-docs.py` + `.github/workflows/deploy-docs.yml.disabled` already in place); this TODO is now a cutover/cleanup + the Algolia → `@easyops-cn/docusaurus-search-local` swap. Plan: `todo/TODO-71-docs-site-script-search-swap.md`.
+11. **TODO-88** — YAML parser buffer-underflow on large OpenAPI 3.1 documents. Latent parser bug in `juneau-marshall`; opportunistic. Plan file TBD.
-16. **TODO-89** — `RateLimitGuard.Storage.snapshot()` SPI + `BasicAdminResource` enrichment. Small (~30 LOC + 2 test files), closes a known carry-over from FINISHED-77 (`"buckets": []` placeholder). Plan: `todo/TODO-89-ratelimit-storage-snapshot-spi.md`.
-17. **TODO-71** — Doc-site script + Docusaurus search swap. Mostly already done (planning worker found `juneau-docs/scripts/build-docs.py` + `.github/workflows/deploy-docs.yml.disabled` already in place); this TODO is now a cutover/cleanup + the Algolia → `@easyops-cn/docusaurus-search-local` swap. Plan: `todo/TODO-71-docs-site-script-search-swap.md`.
-18. **TODO-88** — YAML parser buffer-underflow on large OpenAPI 3.1 documents. Latent parser bug in `juneau-marshall`; opportunistic. Plan file TBD.
+**Phase F — server-feature track (independent; can interleave anywhere):**
-**Phase G — server-feature track (independent; can interleave anywhere after Phase A):**
+12. **TODO-67** — Observability (Micrometer + OpenTelemetry). Plan: `todo/TODO-67-observability-micrometer-otel.md`.
+13. **TODO-68** — Bean Validation (Jakarta Validation 3.x). Plan: `todo/TODO-68-bean-validation-integration.md`.
+14. **TODO-70** — `CompletableFuture<?>` return-type + virtual-thread per-request dispatch. Plan: `todo/TODO-70-async-completablefuture-virtual-threads.md`.
+15. **TODO-92** — `@Value` framework-internal adoption pass — follow-on to TODO-79 Phase 6 (which is scoped user-facing only). Refactors framework-internal config readers (`Microservice` bootstrap, `RestContext.Builder` defaults, FINISHED-20's `DebugConfig` system-property defaults, FINISHED-69's `JwtTokenValidator` JWKS TTL, etc.) to flow through a `BeanInstantiator`-resolved seam so they can carry `@Value`. Bigger refactor than Phase 6; deliberately sequenced independently to keep TODO [...]
+16. **TODO-95** — Per-RestContext `@Value("${cfg-key}")` resolution against `@Rest(config=...)` Configs — follow-on to FINISHED-79's perf-regression cleanup (the dropped `RestContext.build()` → `Settings.get().addSource(...)` bridge that leaked `ConfigPropertySource` instances into the process-wide `Settings` list because `MockRestClient` caches `RestContext` instances statically and never invokes `destroy()`). Re-introduce per-resource config-driven `@Value` resolution by routing throug [...]
+17. **TODO-94a** — Auth filter framework. Pluggable servlet-filter chain in `JettyMicroservice` (URL-pattern-matched via `UrlPathMatcher`, multiple-overlapping auth options, role aggregation via `HttpServletRequestWrapper`, `@Guard` integration through `req.isUserInRole(...)`). Adds the missing `addFilter(...)` surface to `JettyServerComponent`. Reuses every FINISHED-69 type (`TokenValidator`, `ApiKeyStore`, `AuthenticationException`, `ClaimsPrincipal`, `@Auth`, `RestServerConstants.PRIN [...]
+18. **TODO-94b** — `juneau-rest-server-saml` module. SAML 2.0 assertion validation: `SamlAssertionValidator implements TokenValidator` + `SamlAuthFilter extends AuthFilter`, mandatory checks (signature / issuer / audience / NotBefore-NotOnOrAfter / subject confirmation), `opensaml` 5.x in `provided` scope. HARD dep on TODO-94a; soft dep on FINISHED-69 (SPI shape + `juneau-rest-server-jwt` packaging precedent). Plan: `todo/TODO-94b-saml-module.md`.
+19. **TODO-94c** — `juneau-rest-server-oauth` module. OAuth 2.0 / OIDC integration: `OAuthIntrospectionValidator` (RFC 7662) + `OAuthFilter` + flow helpers (authorization-code-with-PKCE, client-credentials, resource-owner, refresh-token) + OIDC discovery; JDK `java.net.http.HttpClient` only; reuses FINISHED-69's `JwtTokenValidator` for JWT access tokens via `provided`-scope dep on `juneau-rest-server-jwt`. HARD dep on TODO-94a; soft dep on FINISHED-69. Plan: `todo/TODO-94c-oauth-module.md`.
-19. **TODO-67** — Observability (Micrometer + OpenTelemetry). Plan: `todo/TODO-67-observability-micrometer-otel.md`.
-20. **TODO-68** — Bean Validation (Jakarta Validation 3.x). Plan: `todo/TODO-68-bean-validation-integration.md`.
-21. **TODO-70** — `CompletableFuture<?>` return-type + virtual-thread per-request dispatch. Plan: `todo/TODO-70-async-completablefuture-virtual-threads.md`.
-22. **TODO-79** — Juneau `@Value` annotation + Spring Boot `application.yaml` bridge for the Config API. Plan: `todo/TODO-79-value-annotation-config-bridge.md`.
+> **Parallelization note for TODO-94b / TODO-94c**: parallelizable after TODO-94a lands; no inter-sibling deps (SAML and OAuth implementations don't depend on each other).
### Parked / unscheduled
- **TODO-37** — Agent instruction consolidation (unscoped).
+### Release gate (run when cutting 9.5.0)
+
+- **TODO-93** — Final pre-release cleanup pass. Deliberately deferred until the release branch is being cut, since most tasks are stable-state quality checks that need the rest of 9.5.0 to be feature-complete first. See `## Items` bullet for the full task list. **Do not start before all other in-flight TODOs above have landed.**
+
### Natural review seams
-Foundations (TODO-73 + TODO-81 + TODO-69) → mixin family (TODO-74–77) → debug rethink (TODO-20) → view infrastructure + siblings (TODO-78 + TODO-82/83/84) → application showcase (TODO-85/86/87) → quality-of-life (TODO-89 + TODO-71 + TODO-88) → server-feature track (TODO-67 + TODO-68 + TODO-70 + TODO-79).
+`@Value` + config bridge (TODO-79) → view infrastructure + siblings (TODO-78 + TODO-82/83/84) → application showcase (TODO-85/86/87) → quality-of-life (TODO-89 + TODO-71 + TODO-88) → server-feature track (TODO-67 + TODO-68 + TODO-70 + TODO-92 + TODO-95).
## Items
@@ -76,6 +75,8 @@ Foundations (TODO-73 + TODO-81 + TODO-69) → mixin family (TODO-74–77) → de
- [TODO-78] JSP servlet support module (`juneau-rest-server-view-jsp`) — new module shipping `BasicJspResource` mixin + `JspViewRenderer`; isolates Apache Jasper / `jakarta.servlet.jsp.*` / JSTL deps from core. See `todo/TODO-78-mixin-jsp-module.md`.
+- [TODO-79] Juneau `@Value` annotation + `${xxx}` shortcut in `VarResolver` + Spring Boot `application.yaml`/`application.properties` bridge for the Config API. Adds a declarative config-read annotation on bean fields, setters, and constructor parameters (analog to Spring's `@Value` but evaluated through Juneau's `Settings`/`VarResolver`/`Config` pipeline), a `${...}` tokenizer shortcut that resolves through the same `VarResolver` chain as `$P{...}`, and a `juneau-rest-server-springboot` [...]
+
- [TODO-82] Thymeleaf view module (`juneau-rest-server-view-thymeleaf`) — sibling to TODO-78's JSP module. New Maven module shipping `BasicThymeleafResource` mixin + `ThymeleafViewRenderer` + `ThymeleafView` impl of the `View` interface introduced by TODO-78. High priority since Thymeleaf is Spring Boot's default web view technology; large existing user base for Spring-Boot-on-Juneau migrations. Same engine-agnostic POM stance as TODO-78 (Option B): bridge module declares Thymeleaf core [...]
- [TODO-83] Mustache view module (`juneau-rest-server-view-mustache`) — sibling to TODO-78's JSP module. New Maven module shipping `BasicMustacheResource` mixin + `MustacheViewRenderer` + `MustacheView` impl of the `View` interface introduced by TODO-78. Logic-less templates; common choice for content authored by non-Java developers. Same engine-agnostic POM stance as TODO-78 (Option B): bridge declares the Mustache API in `provided` scope; example supplies the concrete impl (resolved de [...]
@@ -84,7 +85,7 @@ Foundations (TODO-73 + TODO-81 + TODO-69) → mixin family (TODO-74–77) → de
- [TODO-85] New `juneau-microservice-jetty-starter` module — zero-config quick-start for `JettyMicroservice`, conceptually analogous to Spring Boot's `spring-boot-starter-web`. Sits on top of the existing `juneau-microservice-jetty` runtime and bundles the dependency surface a new user typically wants (microservice-jetty + rest-server + the default marshall stack + sensible config defaults + a default `application.cfg`/`jetty.xml` baseline served from the JAR). Goal: `pom.xml` adds one d [...]
-- [TODO-86] New `juneau-petstore-jetty` sample application — a self-contained reference app deployed on top of `JettyMicroservice` (preferably via the TODO-85 starter once it lands) that exercises a wide cross-section of Juneau features so prospective users have one canonical place to read "how a real Juneau service is structured". Feature coverage: CRUD REST resources composed with the API-docs mixin pack (FINISHED-74), static-files mixin (FINISHED-75), convention endpoints (FINISHED-76 [...]
+- [TODO-86] New `juneau-petstore-jetty` sample application — a self-contained reference app deployed on top of `JettyMicroservice` (preferably via the TODO-85 starter once it lands) that exercises a wide cross-section of Juneau features so prospective users have one canonical place to read "how a real Juneau service is structured". Feature coverage: CRUD REST resources composed with the API-docs mixin pack (FINISHED-74), static-files mixin (FINISHED-75), convention endpoints (FINISHED-76 [...]
- [TODO-87] New `juneau-petstore-springboot` sample application — identical domain + feature coverage as TODO-86, but deployed on Spring Boot via `BasicSpringRestServlet` + `ServletRegistrationBean` + `SpringBeanStore` (NOT `JuneauRestInitializer` — that class does not exist in the codebase; the plan file documents the correction). Mounted into a `@SpringBootApplication` so `mvn spring-boot:run` (or `java -jar`) brings up the same pet-store API with the same six API-docs URLs, same view- [...]
@@ -92,3 +93,15 @@ Foundations (TODO-73 + TODO-81 + TODO-69) → mixin family (TODO-74–77) → de
- [TODO-88] YAML parser buffer-underflow on large OpenAPI 3.1 documents — `OpenApiYamlRoundTrip_Test#c01` currently asserts against the small OpenAPI mount via `noInherit={"mixins"}` + `mixins=BasicOpenApiResource.class` because round-tripping the full post-FINISHED-74 `BasicRestServlet` mixin surface (six api-docs URLs, full schema set) through the YAML parser throws `java.io.IOException: Buffer underflow`. Surfaced during FINISHED-74's `apiFormat` removal but the root cause is a separa [...]
+- [TODO-92] `@Value` framework-internal adoption pass — follow-on to TODO-79 Phase 6 (which is scoped user-facing per OQA 2026-05-25). Refactors framework-internal config readers that today hand-roll lookups in static initializers or un-injected constructors (notably `juneau-microservice/Microservice.java` bootstrap, `RestContext.Builder` defaults, FINISHED-20's `DebugConfig` system-property defaults, FINISHED-69's `JwtTokenValidator` JWKS TTL default) to route through a `BeanInstantiato [...]
+
+- [TODO-95] Per-RestContext `@Value("${cfg-key}")` resolution against `@Rest(config=...)` Configs — follow-on to FINISHED-79's perf-regression cleanup (deferred from the dropped `RestContext.build()` → `Settings.get().addSource(...)` bridge). Re-introduce per-resource config-driven `@Value` resolution by routing through the per-RestContext `BeanStore` (or a `ThreadLocal<RestContext>` set during request scope) instead of mutating the process-wide `Settings` singleton. Architectural goal: [...]
+
+- [TODO-94a] Auth filter framework — pluggable servlet-filter chain in `JettyMicroservice` (adds the missing `addFilter(...)` surface to `JettyServerComponent`) with `UrlPathMatcher`-driven matching, first-success short-circuit + role aggregation across overlapping filters, and `HttpServletRequestWrapper`-mediated visibility into `RestRequest.getUserPrincipal()` / `isUserInRole(...)` so downstream `RoleBasedRestGuard` / `@Auth Principal` consumers see filter-resolved identities without c [...]
+
+- [TODO-94b] `juneau-rest-server-saml` — new opt-in Maven module shipping `SamlAssertionValidator implements TokenValidator` (FINISHED-69 SPI) + `SamlAuthFilter extends AuthFilter` (TODO-94a SPI) for consumer-side SAML 2.0 assertion validation (HTTP POST binding v1). Mandatory checks: signature, issuer, audience, NotBefore/NotOnOrAfter time-window, subject confirmation, signature-algorithm allowlist. Mirrors FINISHED-69's `juneau-rest-server-jwt` module isolation (`opensaml` 5.x declared [...]
+
+- [TODO-94c] `juneau-rest-server-oauth` — new opt-in Maven module shipping the resource-server side of OAuth 2.0 / OIDC: `OAuthIntrospectionValidator` (RFC 7662 opaque-token introspection with a bounded-LRU `TokenCache` SPI), `OAuthFilter extends AuthFilter` (TODO-94a SPI), a curated set of client-side flow helpers (authorization-code-with-PKCE per RFC 7636, client-credentials, resource-owner password-credentials with `@Deprecated`-since-9.5.0, refresh-token), and OIDC discovery via `/.w [...]
+
+- [TODO-93] Final pre-release cleanup pass — execute when the 9.5.0 release branch is being cut, **not before**. Five tasks: (1) **Utils sweep** — find places in the codebase where ad-hoc utility logic should be using shared `Utils.*` helpers and migrate the call sites; (2) **FQCN cleanup** — replace fully-qualified class names with regular imports where the FQCN was not required for disambiguation; (3) **Full SonarQube scan + fixes** — run `scripts/sonarqube.py` across every module, add [...]
+