/*
 * 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.server;

import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.httppart.HttpPartType.*;
import static org.apache.juneau.commons.reflect.AnnotationTraversal.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.StringUtils.isNotEmpty;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;
import static org.apache.juneau.rest.server.util.RestUtils.*;

import java.lang.annotation.*;
import java.lang.reflect.Method;
import java.nio.charset.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.function.*;
import java.util.logging.*;
import java.util.stream.*;

import org.apache.juneau.commons.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.lang.*;
import org.apache.juneau.commons.logging.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.svl.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.http.*;
import org.apache.juneau.http.header.*;
import org.apache.juneau.http.part.*;
import org.apache.juneau.http.response.*;
import org.apache.juneau.httppart.bean.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.encoders.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.jsonschema.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.serializer.*;
import org.apache.juneau.rest.common.utils.*;
import org.apache.juneau.rest.server.converter.*;
import org.apache.juneau.rest.server.guard.*;
import org.apache.juneau.rest.server.httppart.*;
import org.apache.juneau.rest.server.matcher.*;
import org.apache.juneau.rest.server.util.*;

import jakarta.servlet.*;
import jakarta.servlet.http.*;

/**
 * Represents a single Java servlet/resource method annotated with {@link RestOp @RestOp}.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>This class is thread safe and reusable.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpContext">RestOpContext</a>
 * </ul>
 */
@SuppressWarnings({
   "java:S112", // throws Exception intentional - callback/lifecycle methods throughout this class
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S1200", // High coupling is intentional in this central operation context aggregator.
   "java:S3776", // Branching is inherent to the RestOpContext constructor and compareTo(), which resolve many annotation-driven settings and ordering keys.
   "java:S6539", // RestOpContext intentionally centralizes op wiring and annotation resolution.
   "rawtypes", // Raw types necessary for generic type handling.
   "resource", // op-level BasicBeanStores are short-lived scratch stores; the long-lived opBeanStore field is owned and closed by the parent RestContext via its bean-store hierarchy.
   "unchecked" // Cast is safe: type parameter is verified by caller context.
})
public class RestOpContext extends Context implements Comparable<RestOpContext> {

   // Argument name constants for req*

   private static final AnnotationProvider AP = AnnotationProvider.INSTANCE;

   /**
    * Env-driven default charset for this operation, populated by {@link ClassInfo#inject(Object, BeanStore)}
    * before the {@link #defaultCharset} memoizer fires; resolved from {@code RestContext.defaultCharset} or
    * {@code "UTF-8"}.
    */
   @Value("${RestContext.defaultCharset:UTF-8}")
   private String defaultCharsetName;

   /**
    * Env-driven default max-input string for this operation, populated by {@link ClassInfo#inject(Object, BeanStore)}
    * before the {@link #maxInput} memoizer fires; resolved from {@code RestContext.maxInput} or
    * {@code "1000000"} &mdash; matching the {@code @Rest}-level fallback in
    * {@link org.apache.juneau.rest.server.config.DefaultConfig DefaultConfig} so an operation that falls all the
    * way through to this last-resort default doesn't end up with a substantially larger effective ceiling than
    * the class-level default.
    */
   @Value("${RestContext.maxInput:1000000}")
   private String defaultMaxInputString;

   /**
    * Internal construction-time state holder.
    */
   static class Builder extends Context.Builder {

      private final Method restMethod;
      private final RestContext restContext;
      private final Supplier<Object> restResourceSupplier;

      Builder(Method method, RestContext context) {
         this(method, context, null);
      }

      Builder(Method method, RestContext context, Supplier<Object> resourceSupplier) {

         this.restContext = context;
         this.restMethod = method;
         this.restResourceSupplier = resourceSupplier == null ? context::getResource : resourceSupplier;

         var ap = context.getMarshallingContext().getAnnotationProvider();
         var mi = MethodInfo.of(context.getResourceClass(), method);
         var resourceClass = ClassInfo.of(context.getResourceClass());

         try {
            var vr = context.getVarResolver();
            var vrs = vr.createSession();

            // Parent-to-child merge: class-level annotations (parent class chain) applied first, then method-level
            // (matching-methods chain, return type, package). Method annotations thus override class annotations
            // for the same property. LinkedHashSet deduplicates while preserving order.
            //
            // For a mixin op (the op's context is a mixin sub-context), the host's class-level @ContextApply
            // config (e.g. @HtmlDocConfig, @SerializerConfig) is prepended ahead of the mixin class's own class
            // annotations, so the effective precedence is method > mixin-class > host-class. This is the
            // op-level counterpart of the context-level inheritance walk and is gated by @Rest(noInherit) on
            // the mixin. For non-mixin contexts the host stream is empty (no behavior change).
            var hostClassAnnotations = context.getInheritedHostClassAnnotations(ap);
            var declaringClassAnnotations = rstream(ap.find(resourceClass, SELF, PARENTS));
            var methodAnnotations = rstream(ap.find(mi, SELF, MATCHING_METHODS, RETURN_TYPE, PACKAGE));
            var allAnnotationsSet = new LinkedHashSet<AnnotationInfo<?>>();
            hostClassAnnotations.forEach(allAnnotationsSet::add);
            declaringClassAnnotations.forEach(allAnnotationsSet::add);
            methodAnnotations.forEach(allAnnotationsSet::add);
            var work = AnnotationWorkList.of(vrs, allAnnotationsSet.stream().filter(CONTEXT_APPLY_FILTER));

            apply(work);

         } catch (Exception e) {
            throw new InternalServerError(e);
         }
      }

      @Override /* Overridden from Context.Builder<?> */
      public Builder copy() {
         throw new NoSuchMethodError("Not implemented.");
      }
   }

   private static HttpPartSerializer createPartSerializer(Class<? extends HttpPartSerializer> c, HttpPartSerializer defaultSerializer) {
      return c == null
         ? defaultSerializer
         : BeanInstantiator.of(HttpPartSerializer.class).type(c).fallback(() -> defaultSerializer).run();
   }

   private final WritableBeanStore opBeanStore;
   protected final Map<Class<?>,ResponseBeanMeta> responseBeanMetas = new ConcurrentHashMap<>();
   protected final Map<Class<?>,ResponsePartMeta> headerPartMetas = new ConcurrentHashMap<>();
   protected final Method method;
   protected final MethodInfo mi;
   protected final RestContext context;
   private final Supplier<Object> resourceSupplier;

   // The annotation work-list produced during construction.
   private final AnnotationWorkList appliedAnnotations;

   private RestContext restContext() { return context; }

   /**
    * Returns the {@link RestContext} that owns this operation context.
    *
    * <p>
    * For operations declared directly on the host resource class, returns the host context. For operations
    * registered through a {@code @Rest(mixins=...)} mixin, returns the per-mixin sub-context (parent-linked
    * to the host's context via {@link RestContext#getParentContext()}). Callers can use this to identify
    * whether the operation was contributed by a mixin (via {@link RestContext#isMixinContext()}).
    *
    * @return The owning {@link RestContext} for this operation.
    * @since 10.0.0
    */
   public RestContext getContext() { return context; }

   private Method method() { return method; }
   private MethodInfo methodInfo() { return mi; }
   private AnnotationWorkList appliedAnnotations() { return appliedAnnotations; }
   private BeanStore beanStore() { return context.getBeanStore(); }
   private WritableBeanStore opBeanStore() { return opBeanStore; }
   private Object resource() { return resourceSupplier.get(); }
   private VarResolver varResolver() { return context.getVarResolver(); }

   //-----------------------------------------------------------------------------------------------------------------
   // Memoized fields
   //-----------------------------------------------------------------------------------------------------------------

   /** Effective allowed parser session-option keys for this operation. */
   private final Memoizer<SortedSet<String>> allowedParserOptions = memoizer(() -> {
      var l = new ArrayList<String>();
      var p = "allowedParserOptions";
      if (isInherited(p))
         l.addAll(restContext().getAllowedParserOptions());
      getRestOpAnnotations().stream()
         .flatMap(ai -> resolveCdl(ai.getStringArray(p).orElse(EMPTY_STRING_ARRAY)))
         .forEach(l::add);
      return u(treeSetCi(removeNegations(l)));
   });

   /** Effective allowed serializer session-option keys for this operation. */
   private final Memoizer<SortedSet<String>> allowedSerializerOptions = memoizer(() -> {
      var l = new ArrayList<String>();
      var p = "allowedSerializerOptions";
      if (isInherited(p))
         l.addAll(restContext().getAllowedSerializerOptions());
      getRestOpAnnotations().stream()
         .flatMap(ai -> resolveCdl(ai.getStringArray(p).orElse(EMPTY_STRING_ARRAY)))
         .forEach(l::add);
      return u(treeSetCi(removeNegations(l)));
   });

   /** The {@link MarshallingContext} for this operation (op-level annotations applied on top of the parent context). */
   private final Memoizer<MarshallingContext> marshallingContext = memoizer(() -> {
      var aa = appliedAnnotations();
      var parent = restContext().getBeanContextBuilder();
      if (!parent.canApply(aa))
         return restContext().getMarshallingContext();
      Holder<MarshallingContext.Builder> v = Holder.of(parent.copy());
      v.get().apply(aa);
      var bs = new BasicBeanStore(beanStore())
         .addBean(Method.class, method())
         .addBean(MarshallingContext.Builder.class, v.get());
      bs.createBeanFromMethod(MarshallingContext.class, resource(), this::matchesInjectScope)
         .ifPresent(x -> v.get().impl(x));
      return v.get().build();
   });

   /**
    * The per-operation logger for debug capture.
    *
    * <p>
    * A hierarchical child of the <b>host</b> resource's {@linkplain RestContext#getLogger() resolved logger}
    * ({@code <hostLoggerName>.<methodName>}) so an operator can raise the debug level for a single operation
    * without affecting its siblings (JUL parent-level inheritance). Deriving from the resolved logger &mdash;
    * rather than the raw resource class name &mdash; means a bean-store {@code RichLogger} override on the host
    * (see {@link RestContext#getLogger()}) is honored: the op logger is a true JUL child of whatever logger the
    * host actually resolves to, not a same-named-but-unrelated sibling.
    *
    * <p>
    * For an operation contributed by a composed {@linkplain Rest#mixins() mixin}, the host is the <b>host /
    * top-level resource</b> &mdash; not the mixin class &mdash; so raising the host resource's JUL level cascades
    * to its mixin-served operations, and the same mixin composed into different hosts resolves to distinct,
    * host-isolated loggers.  Non-mixin operations (including child resources, which are their own resources)
    * resolve to their own resource's logger as before.
    */
   private final Memoizer<RichLogger> logger = memoizer(() ->
      RichLogger.getLogger(hostRestContext().getLogger().getName() + "." + getJavaMethod().getName()));

   /**
    * Returns the host / top-level resource context for logger naming.
    *
    * <p>
    * When this operation's context originates from a {@linkplain RestContext#isMixinContext() mixin sub-context},
    * walks up the {@linkplain RestContext#getParentContext() parent-context} linkage past any composed mixin
    * sub-contexts to the host resource that composed the mixin.  Non-mixin contexts (including child resources)
    * return their own context unchanged.
    *
    * @return The host resource context.
    */
   private RestContext hostRestContext() {
      var rc = restContext();
      while (rc.isMixinContext() && rc.getParentContext() != null)
         rc = rc.getParentContext();
      return rc;
   }

   /**
    * The response-converter array for this operation.
    *
    * <p>
    * Walks the {@code @Rest(converters)} class chain (parent-to-child) followed by the
    * {@code @RestOp(converters)} method chain (parent-to-child). Op-level
    * {@code noInherit={"converters"}} cuts off the class-chain contribution. An
    * {@code @Bean RestConverterList} bean (either as a name-anonymous bean in the bean store
    * or as a {@code @Bean} method whose {@code methodScope} matches this operation's method
    * name) REPLACES the entire annotation-derived list.
    */
   private final Memoizer<RestConverter[]> converters = memoizer(() -> {
      var bs = beanStore();
      var b = RestConverterList.create(bs);
      if (isInherited("converters"))
         restContext().getRestAnnotationsForProperty("converters")
            .forEach(ai -> b.append(ai.inner().converters()));
      getRestOpAnnotationsForProperty("converters")
         .forEach(ai -> ai.getClassArray("converters", RestConverter.class).ifPresent(classes -> {
            for (var c : classes)
               b.append(classArray(c));
         }));
      var override = bs.createBeanFromMethod(RestConverterList.class, resource(), this::matchesInjectScope).orElse(null);
      if (override == null)
         override = bs.getBean(RestConverterList.class).orElse(null);
      return (nn(override) ? override : b.build()).asArray();
   });

   /** The effective default {@link Charset} for this operation, resolved from op annotations, context, or env. */
   private final Memoizer<Charset> defaultCharset = memoizer(() -> {
      var v = findOpString("defaultCharset");
      if (v.isPresent())
         return Charset.forName(v.get());
      if (isInherited("defaultCharset")) {
         var rv = restContext().mergeReplacedStringAttribute("defaultCharset", null);
         if (ine(rv))
            return Charset.forName(rv);
      }
      return Charset.forName(defaultCharsetName);
   });

   /**
    * The default request attribute map for this operation.
    *
    * <p>
    * Starts with the class-level value (which already incorporates
    * {@code @Rest(defaultRequestAttributes)}), then walks the {@code @RestOp}/verb chain
    * (parent-to-child) and adds each entry — {@link NamedAttributeMap#add} uses put-semantics so
    * child entries override parent entries by name. An
    * {@code @Bean(name="defaultRequestAttributes") NamedAttributeMap} bean (matching this
    * operation's method scope) REPLACES the entire result.
    */
   private final Memoizer<NamedAttributeMap> defaultRequestAttributes = memoizer(() -> {
      var v = Holder.of(restContext().getDefaultRequestAttributes().copy());
      getRestOpAnnotationsForProperty("defaultRequestAttributes").forEach(ai -> {
         for (var s : ai.getStringArray("defaultRequestAttributes").orElse(EMPTY_STRING_ARRAY))
            v.get().add(BasicNamedAttribute.ofPair(s));
      });
      beanStore().createBeanFromMethod(NamedAttributeMap.class, resource(), x -> matchesInjectScope(x, "defaultRequestAttributes"))
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The default request form-data parts for this operation.
    *
    * <p>
    * Walks the {@code @RestOp}/verb chain (parent-to-child); each {@code defaultRequestFormData}
    * entry is applied with {@link PartList#setDefault} (first-in-chain wins per name).
    * Method-parameter {@link FormData @FormData} annotations with a
    * {@link Schema#default_()}/{@link Schema#df()} default are folded in last (also
    * {@code setDefault} = first wins). An {@code @Bean(name="defaultRequestFormData") PartList}
    * bean (matching this operation's method scope) REPLACES the entire result.
    */
   private final Memoizer<HttpPartList> defaultRequestFormData = memoizer(() -> {
      var v = Holder.of(HttpPartList.create());
      getRestOpAnnotationsForProperty("defaultRequestFormData").forEach(ai -> {
         for (var s : ai.getStringArray("defaultRequestFormData").orElse(EMPTY_STRING_ARRAY))
            v.get().setDefault(HttpStringPart.ofPair(s));
      });
      processParameterDefaults((paramAnn, def) -> {
         if (paramAnn instanceof FormData paramAnn2) {
            try {
               v.get().setDefault(HttpStringPart.of(firstNonEmpty(paramAnn2.name(), paramAnn2.value()), toPartValue(parseIfJson(def))));
            } catch (ParseException e) {
               throw new ConfigException(e, "Malformed @FormData annotation");
            }
         }
      });
      beanStore().createBeanFromMethod(HttpPartList.class, resource(), x -> matchesInjectScope(x, "defaultRequestFormData"))
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The default request headers for this operation.
    *
    * <p>
    * Starts with the class-level value (which already incorporates
    * {@code @Rest(defaultRequestHeaders|defaultAccept|defaultContentType)}), then walks the
    * {@code @RestOp}/verb chain (parent-to-child); each annotation's {@code defaultRequestHeaders}
    * entries plus its {@code defaultAccept} / {@code defaultContentType} (folded into
    * {@code Accept} / {@code Content-Type} headers) are applied with {@link HeaderList#setDefault}
    * (first-in-chain wins per name — class-level beats op-level beats later op-level entries).
    *
    * <p>
    * Method-parameter {@link Header @Header} annotations with a
    * {@link Schema#default_()}/{@link Schema#df()} default are folded in last via
    * {@link HeaderList#set} (overrides any prior entry with the same name). An
    * {@code @Bean(name="defaultRequestHeaders") HeaderList} bean (matching this operation's
    * method scope) REPLACES the entire result.
    */
   private final Memoizer<HttpHeaderList> defaultRequestHeaders = memoizer(() -> {
      var v = Holder.of(restContext().getDefaultRequestHeaders().copy());
      getRestOpAnnotationsForProperty("defaultRequestHeaders").forEach(ai -> {
         for (var s : ai.getStringArray("defaultRequestHeaders").orElse(EMPTY_STRING_ARRAY))
            v.get().setDefault(HttpStringHeader.ofPair(s));
         ai.getString("defaultAccept").filter(s -> !s.isEmpty()).ifPresent(s -> v.get().setDefault(Accept.of(s)));
         ai.getString("defaultContentType").filter(s -> !s.isEmpty()).ifPresent(s -> v.get().setDefault(ContentType.of(s)));
      });
      processParameterDefaults((paramAnn, def) -> {
         if (paramAnn instanceof Header paramAnn2) {
            try {
               v.get().set(HttpStringHeader.of(firstNonEmpty(paramAnn2.name(), paramAnn2.value()), toPartValue(parseIfJson(def))));
            } catch (ParseException e) {
               throw new ConfigException(e, "Malformed @Header annotation");
            }
         }
      });
      beanStore().createBeanFromMethod(HttpHeaderList.class, resource(), x -> matchesInjectScope(x, "defaultRequestHeaders"))
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The default request query-data parts for this operation.
    *
    * <p>
    * Walks the {@code @RestOp}/verb chain (parent-to-child); each {@code defaultRequestQueryData}
    * entry is applied with {@link PartList#setDefault} (first-in-chain wins per name).
    * Method-parameter {@link Query @Query} annotations with a
    * {@link Schema#default_()}/{@link Schema#df()} default are folded in last (also
    * {@code setDefault} = first wins). An {@code @Bean(name="defaultRequestQueryData") PartList}
    * bean (matching this operation's method scope) REPLACES the entire result.
    */
   private final Memoizer<HttpPartList> defaultRequestQueryData = memoizer(() -> {
      var v = Holder.of(HttpPartList.create());
      getRestOpAnnotationsForProperty("defaultRequestQueryData").forEach(ai -> {
         for (var s : ai.getStringArray("defaultRequestQueryData").orElse(EMPTY_STRING_ARRAY))
            v.get().setDefault(HttpStringPart.ofPair(s));
      });
      processParameterDefaults((paramAnn, def) -> {
         if (paramAnn instanceof Query paramAnn2) {
            try {
               v.get().setDefault(HttpStringPart.of(firstNonEmpty(paramAnn2.name(), paramAnn2.value()), toPartValue(parseIfJson(def))));
            } catch (ParseException e) {
               throw new ConfigException(e, "Malformed @Query annotation");
            }
         }
      });
      beanStore().createBeanFromMethod(HttpPartList.class, resource(), x -> matchesInjectScope(x, "defaultRequestQueryData"))
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The default response headers for this operation.
    *
    * <p>
    * Starts with the class-level value (which already incorporates
    * {@code @Rest(defaultResponseHeaders)}), then walks the {@code @RestOp}/verb chain
    * (parent-to-child); each annotation's {@code defaultResponseHeaders} entries are applied with
    * {@link HeaderList#setDefault} (first-in-chain wins per name). An
    * {@code @Bean(name="defaultResponseHeaders") HeaderList} bean (matching this operation's
    * method scope) REPLACES the entire result.
    */
   private final Memoizer<HttpHeaderList> defaultResponseHeaders = memoizer(() -> {
      var v = Holder.of(restContext().getDefaultResponseHeaders().copy());
      getRestOpAnnotationsForProperty("defaultResponseHeaders").forEach(ai -> {
         for (var s : ai.getStringArray("defaultResponseHeaders").orElse(EMPTY_STRING_ARRAY))
            v.get().setDefault(HttpStringHeader.ofPair(s));
      });
      beanStore().createBeanFromMethod(HttpHeaderList.class, resource(), x -> matchesInjectScope(x, "defaultResponseHeaders"))
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The encoder group for this operation.
    *
    * <p>
    * Walks the {@code @RestOp(encoders)} chain (parent-to-child); each non-empty {@code encoders()}
    * array REPLACES the inherited set (with {@link Inherit} as a sentinel that re-injects the prior
    * set's entries at the specified position — matches the legacy {@code EncoderSet.Builder.set(...)}
    * semantics). Falls through to the class-level {@link RestContext#getEncoders()} when no op
    * annotation declares encoders. An {@code @Bean EncoderSet} bean (matching this operation's
    * method scope) REPLACES the result entirely.
    */
   private final Memoizer<EncoderSet> encoders = memoizer(() -> {
      var bs = beanStore();
      var b = restContext().getEncodersBuilder().copy();
      getRestOpAnnotationsForProperty("encoders").forEach(ai -> {
         var c = ai.getClassArray("encoders", Encoder.class).orElse(null);
         if (nn(c) && c.length > 0)
            b.set(c);
      });
      var v = Holder.of(b.build());
      bs.createBeanFromMethod(EncoderSet.class, resource(), this::matchesInjectScope)
         .ifPresent(v::set);
      return v.get();
   });

   /**
    * The request-guard array for this operation. <b>Cross-bucket memoizer</b> — folds three
    * annotation attributes ({@code guards}, {@code roleGuard}, {@code rolesDeclared}) into a
    * single effective {@link RestGuardList}.
    *
    * <p>
    * Walk order: class {@code @Rest} chain (parent-to-child, gated by op-level
    * {@code noInherit={"guards"}}), then op {@code @RestOp} chain (parent-to-child). Concretely:
    * <ul>
    *    <li>Each annotation contributes its {@code guards()} classes (appended in chain order).
    *    <li>Each annotation contributes its {@code rolesDeclared()} CDL into a single role-name set.
    *    <li>Each annotation contributes its {@code roleGuard()} string (when non-blank). Each
    *       non-blank {@code roleGuard} becomes a {@link RoleBasedRestGuard} appended to the list,
    *       using the accumulated {@code rolesDeclared} set as its allow-list.
    * </ul>
    *
    * <p>
    * An {@code @Bean RestGuardList} bean (via the bean store or an {@code @Bean} method
    * with matching {@code methodScope}) REPLACES the entire annotation-derived list.
    */
   private final Memoizer<RestGuard[]> guards = memoizer(() -> {
      var bs = beanStore();
      var b = RestGuardList.create(bs);
      var rolesDeclaredSet = new LinkedHashSet<String>();
      var roleGuardStrs = new ArrayList<String>();

      Consumer<AnnotationInfo<?>> walk = ai -> {
         ai.getClassArray("guards", RestGuard.class).ifPresent(classes -> {
            for (var c : classes)
               b.append(classArray(c));
         });
         // rolesDeclared is a single CDL string (not an array) on every annotation in the chain.
         ai.getString("rolesDeclared").filter(StringUtils::isNotBlank)
            .ifPresent(s -> resolveCdl(s).forEach(rolesDeclaredSet::add));
         ai.getString("roleGuard").filter(StringUtils::isNotBlank).ifPresent(roleGuardStrs::add);
      };

      if (isInherited("guards"))
         restContext().getRestAnnotationsForProperty("guards").forEach(walk::accept);
      getRestOpAnnotationsForProperty("guards").forEach(walk);

      // When no @Rest/@RestOp(rolesDeclared) is set, pass null so RoleBasedRestGuard
      // infers role names from the expression itself (legacy semantics — an empty
      // declared-role set would silently never match).
      var declaredRoles = rolesDeclaredSet.isEmpty() ? null : rolesDeclaredSet;
      for (var rg : roleGuardStrs) {
         try {
            b.append(new RoleBasedRestGuard(declaredRoles, rg));
         } catch (java.text.ParseException e) {
            throw toRex(e);
         }
      }

      var override = bs.createBeanFromMethod(RestGuardList.class, resource(), this::matchesInjectScope).orElse(null);
      if (override == null)
         override = bs.getBean(RestGuardList.class).orElse(null);
      return (nn(override) ? override : b.build()).asArray();
   });

   /** The depth of the declaring class in the inheritance chain. */
   private final Memoizer<Integer> hierarchyDepth = memoizer(() -> {
      int hierarchyDepthTemp = 0;
      var sc = method().getDeclaringClass().getSuperclass();
      while (nn(sc)) {
         hierarchyDepthTemp++;
         sc = sc.getSuperclass();
      }
      return hierarchyDepthTemp;
   });

   /**
    * The {@code @RestOp}-group annotation that supplies this operation's HTTP method.
    *
    * <p>
    * Walks {@code @RestOp}-group annotations child-to-parent; verb-specific annotations
    * ({@link RestGet}, etc.) imply their fixed verb. Empty when no annotation declares a verb, in which case the
    * verb is inferred from the Java method name.
    */
   private final Memoizer<Optional<AnnotationInfo<?>>> httpMethodSource = memoizer(() -> {
      var vr = varResolver();
      for (var ai : getRestOpAnnotations())
         if (ine(httpMethodFromAnnotation(ai.inner(), vr)))
            return o(ai);
      return oe();
   });

   /**
    * The HTTP method string for this operation (e.g. {@code "GET"}, {@code "*"}).
    *
    * <p>
    * Taken from {@link #httpMethodSource}. Falls back to {@link HttpUtils#detectHttpMethod} when no annotation
    * declares a verb.
    */
   private final Memoizer<String> httpMethod = memoizer(() ->
      normalizeHttpMethod(httpMethodSource.get()
         .map(ai -> httpMethodFromAnnotation(ai.inner(), varResolver()))
         .orElseGet(() -> HttpUtils.detectHttpMethod(method(), true, "GET"))));

   /**
    * Whether this operation is declared {@link RestOp#read() read=true}.
    *
    * <p>
    * Read from the annotation that supplies the HTTP method, so the verb and its read declaration travel together.
    * When the verb is inferred, it comes from the nearest {@link RestOp @RestOp}. A {@code read=true} on an
    * overridden annotation that names its own verb is replaced along with that verb. One on another
    * {@link RestOp @RestOp} that names no verb would be silently ignored, so it fails the operation.
    */
   private final Memoizer<Boolean> read = memoizer(() -> {
      var vr = varResolver();
      var annotations = getRestOpAnnotations();
      var source = httpMethodSource.get()
         .orElseGet(() -> annotations.stream().filter(x -> x.inner() instanceof RestOp).findFirst().orElse(null));
      for (var ai : annotations) {
         // An annotation that names its own verb but was overridden by a nearer one is replaced along with its read.
         // One that names no verb would have its read silently ignored, so that is refused.
         if (ai != source && ai.inner() instanceof RestOp a2 && a2.read() && ! ine(httpMethodFromAnnotation(a2, vr)))
            throw new InternalServerError(
               "Operation '" + method().getDeclaringClass().getSimpleName() + "." + method().getName()
               + "' declares @RestOp(read=true) on an annotation that does not supply its method '" + getHttpMethod() + "'."
               + " The read declaration is taken only from the annotation that names the method."
               + " Move read=true to that annotation, or remove it.");
      }
      return nn(source) && source.inner() instanceof RestOp a2 && a2.read();
   });

   /** The JSON-Schema generator for this operation (op-level annotations applied on top of the parent). */
   private final Memoizer<JsonSchemaGenerator> jsonSchemaGenerator = memoizer(() -> {
      var aa = appliedAnnotations();
      var parent = restContext().getJsonSchemaGeneratorBuilder();
      if (!parent.canApply(aa))
         return restContext().getJsonSchemaGenerator();
      Holder<JsonSchemaGenerator.Builder> v = Holder.of(parent.copy());
      v.get().apply(aa);
      var bs = new BasicBeanStore(beanStore())
         .addBean(Method.class, method())
         .addBean(JsonSchemaGenerator.Builder.class, v.get());
      bs.createBeanFromMethod(JsonSchemaGenerator.class, resource(), this::matchesInjectScope)
         .ifPresent(x -> v.get().impl(x));
      return v.get().build();
   });

   /**
    * The request-matcher list for this operation. <b>Cross-bucket memoizer</b> — folds
    * {@code matchers} and {@code clientVersion} (both op-level only) into a single effective
    * {@link RestMatcherList}.
    *
    * <p>
    * Walks the {@code @RestOp}/verb annotation chain (parent-to-child, gated by op-level
    * {@code noInherit={"matchers"}}). Each annotation contributes its {@code matchers()} classes
    * (appended in chain order). The final non-blank {@code clientVersion()} (most-derived wins)
    * appends a single {@link ClientVersionMatcher} keyed off the resource's client-version header.
    * An {@code @Bean RestMatcherList} bean (via the bean store or an {@code @Bean}
    * method with matching {@code methodScope}) REPLACES the entire annotation-derived list.
    */
   private final Memoizer<RestMatcherList> matchersList = memoizer(() -> {
      var bs = beanStore();
      var b = RestMatcherList.create(bs);
      var clientVersion = new String[]{null};

      getRestOpAnnotationsForProperty("matchers").forEach(ai -> {
         ai.getClassArray("matchers", RestMatcher.class).ifPresent(classes -> {
            for (var c : classes)
               b.append(classArray(c));
         });
         ai.getString("clientVersion").filter(StringUtils::isNotBlank).ifPresent(s -> clientVersion[0] = s);
      });

      if (nn(clientVersion[0]))
         b.append(new ClientVersionMatcher(restContext().getClientVersionHeader(), MethodInfo.of(method())));

      var override = bs.createBeanFromMethod(RestMatcherList.class, resource(), this::matchesInjectScope).orElse(null);
      if (override == null)
         override = bs.getBean(RestMatcherList.class).orElse(null);
      return nn(override) ? override : b.build();
   });

   /** The invoker for the operation method itself. */
   private final Memoizer<RestOpInvoker> methodInvoker = memoizer(() ->
      new RestOpInvoker(method(), restContext().findRestOperationArgs(method(), opBeanStore()), restContext().getMethodExecStats(method()), this::resource)
   );

   /** The effective max-input byte limit for this operation. */
   private final Memoizer<Long> maxInput = memoizer(() -> {
      var v = findOpString("maxInput");
      if (v.isPresent())
         return parseLongWithSuffix(v.get());
      if (isInherited("maxInput")) {
         var rv = restContext().mergeReplacedStringAttribute("maxInput", null);
         if (ine(rv))
            return parseLongWithSuffix(rv);
      }
      return parseLongWithSuffix(defaultMaxInputString);
   });

   /**
    * Whether this operation emits RFC 7807 {@code application/problem+json} responses.
    *
    * <p>
    * Tri-state semantics on the {@code @RestOp}-group annotations:
    * <ul>
    *    <li>{@code "true"} &mdash; opt this operation in.
    *    <li>{@code "false"} &mdash; opt this operation out (overrides an opted-in resource).
    *    <li>{@code ""} (default) &mdash; inherit from the resource-level {@code @Rest(problemDetails)}.
    * </ul>
    */
   private final Memoizer<Boolean> problemDetails = memoizer(() -> {
      var v = findOpString("problemDetails");
      if (v.isPresent())
         return Boolean.parseBoolean(v.get());
      if (isInherited("problemDetails"))
         return restContext().isProblemDetails();
      return false;
   });

   /**
    * Whether REST-driven serializer/parser debug behavior is enabled for this operation.
    *
    * <p>
    * Tri-state semantics on the {@code @RestOp}-group annotations:
    * <ul>
    *    <li>{@code "true"} &mdash; opt this operation in.
    *    <li>{@code "false"} &mdash; opt this operation out (overrides an opted-in resource).
    *    <li>{@code ""} (default) &mdash; inherit from the resource-level {@code @Rest(debugMarshalling)}.
    * </ul>
    */
   private final Memoizer<Boolean> debugMarshalling = memoizer(() -> {
      var v = findOpString("debugMarshalling");
      if (v.isPresent())
         return Boolean.parseBoolean(v.get());
      if (isInherited("debugMarshalling"))
         return restContext().isDebugMarshalling();
      return false;
   });

   /**
    * Whether this operation opts into per-request virtual-thread dispatch on Java 21+.
    *
    * <p>
    * Tri-state semantics on {@code @RestOp}-group annotations: {@code "true"} enables, {@code "false"} disables
    * (overrides an opted-in resource), and {@code ""} (default) inherits from {@code @Rest(virtualThreads)}. Honored
    * only when the resource-level {@link RestContext#getVirtualThreadExecutor()} is non-{@code null} (Java 21+).
    */
   private final Memoizer<Boolean> virtualThreadsEnabled = memoizer(() -> {
      var v = findOpString("virtualThreads");
      if (v.isPresent())
         return Boolean.parseBoolean(v.get());
      if (isInherited("virtualThreads"))
         return restContext().isVirtualThreadsEnabled();
      return false;
   });

   /**
    * Configurable async-response timeout (milliseconds) for this operation; {@code -1} when neither the op
    * annotation nor the resource declares a value (so {@code AsyncResponseProcessor}'s 30-second default applies).
    */
   private final Memoizer<Long> asyncTimeoutMillis = memoizer(() -> {
      var v = findOpString("asyncTimeoutMillis");
      if (v.isPresent()) {
         try {
            return Long.parseLong(v.get().trim());
         } catch (NumberFormatException nfe) {
            return -1L;
         }
      }
      if (isInherited("asyncTimeoutMillis"))
         return restContext().getAsyncTimeoutMillis();
      return -1L;
   });

   /**
    * Per-op async-completion executor: op-level bean name overrides {@code @Rest}-level, then both are
    * resolved against the resource's bean store. {@code null} when unset (natural completion thread).
    */
   private final Memoizer<Executor> asyncCompletionExecutor = memoizer(() -> {
      var v = findOpString("asyncCompletionExecutor");
      if (v.isPresent()) {
         var name = v.get();
         var bs = beanStore();
         var resolved = bs.getBean(Executor.class, name);
         if (resolved.isEmpty())
            resolved = bs.getBean(ExecutorService.class, name).map(e -> (Executor) e);
         if (resolved.isEmpty())
            throw new IllegalStateException(
               "@RestOp(asyncCompletionExecutor) on " + restContext().getResourceClass().getName()
                  + "#" + method().getName() + " references bean name '" + name + "' but no Executor"
                  + " (or ExecutorService) bean with that name is registered in the resource's bean store.");
         return resolved.get();
      }
      if (isInherited("asyncCompletionExecutor"))
         return restContext().getAsyncCompletionExecutor();
      return null;
   });

   /**
    * Effective per-op observability state, resolving verb / {@code @RestOp} annotation override first,
    * then falling back to the resource-level {@code @Rest(observability)} attribute.
    *
    * <ul class='values'>
    *    <li>{@code "true"} &mdash; strict opt-in; this operation requires a wired backend.
    *    <li>{@code "false"} &mdash; explicit opt-out; the observability block is short-circuited.
    *    <li>{@code null} &mdash; default inherit behavior; a missing backend silently falls back to NoOp.
    * </ul>
    */
   private final Memoizer<String> observabilityAttr = memoizer(() -> {
      var v = findOpString("observability");
      if (v.isPresent())
         return v.get();
      if (isInherited("observability"))
         return restContext().getObservabilityAttribute();
      return null;
   });

   /**
    * Per-op metric name override from {@code @RestOp(metricName)}.
    * Empty string (default) means the recorder uses its own default name derivation.
    */
   private final Memoizer<String> metricName = memoizer(() ->
      findOpString("metricName").orElse(""));

   /**
    * Per-op additional metric tags from {@code @RestOp(metricTags)}.
    * Format: comma-separated {@code key=value} pairs. Empty string (default) means no additional tags.
    */
   private final Memoizer<String> metricTags = memoizer(() ->
      findOpString("metricTags").orElse(""));

   /** Aggregated {@code noInherit} keys from all RestOp-group annotations on this operation. */
   private final Memoizer<SortedSet<String>> noInheritOp = memoizer(() -> {
      var l = getRestOpAnnotations().stream()
         .map(ai -> ai.getStringArray("noInherit").orElse(StringUtils.EMPTY_STRING_ARRAY))
         .flatMap(this::resolveCdl)
         .toList();
      return u(treeSetCi(l));
   });

   /** The optional (non-required) matchers extracted from {@link #matchersList}. */
   private final Memoizer<RestMatcher[]> optionalMatchers = memoizer(() -> matchersList.get().getOptionalEntries());

   /** The invokers for context-level post-call lifecycle methods. */
   private final Memoizer<RestOpInvoker[]> postCallMethods = memoizer(() ->
      restContext().getPostCallMethods().stream().map(x -> new RestOpInvoker(x, restContext().findRestOperationArgs(x, opBeanStore()), restContext().getMethodExecStats(x), this::resource)).toArray(RestOpInvoker[]::new)
   );

   /** The invokers for context-level pre-call lifecycle methods. */
   private final Memoizer<RestOpInvoker[]> preCallMethods = memoizer(() ->
      restContext().getPreCallMethods().stream().map(x -> new RestOpInvoker(x, restContext().findRestOperationArgs(x, opBeanStore()), restContext().getMethodExecStats(x), this::resource)).toArray(RestOpInvoker[]::new)
   );

   /**
    * The parser group for this operation.
    *
    * <p>
    * Walks the {@code @RestOp(parsers)} chain (parent-to-child); the most-derived non-empty
    * {@code parsers()} array REPLACES the entire inherited set. Falls through to the class-level
    * {@link RestContext#getParsers()} when no op annotation declares parsers. An
    * {@code @Bean ParserSet} bean (matching this operation's method scope) REPLACES the result.
    */
   private final Memoizer<ParserSet> parsers = memoizer(() -> {
      var aa = appliedAnnotations();
      var bs = beanStore();
      var pb = restContext().getParsersBuilder();
      var b = pb.copy();
      if (pb.canApply(aa))
         b.apply(aa);
      getRestOpAnnotationsForProperty("parsers").forEach(ai -> {
         var c = ai.getClassArray("parsers", Object.class).orElse(null);
         if (nn(c) && c.length > 0)
            b.set(c);
      });
      var result = Holder.of(b.build());
      bs.createBeanFromMethod(ParserSet.class, resource(), this::matchesInjectScope)
         .ifPresent(result::set);
      return result.get();
   });

   /** The HTTP part parser for this operation (op-level creator applied on top of the parent). */
   private final Memoizer<HttpPartParser> partParser = memoizer(() -> {
      var aa = appliedAnnotations();
      var parent = restContext().getPartParserCreator();
      if (!parent.canApply(aa))
         return restContext().getPartParser();
      Holder<HttpPartParser.Creator> v = Holder.of(parent.copy());
      v.get().apply(aa);
      var bs = new BasicBeanStore(beanStore())
         .addBean(Method.class, method())
         .addBean(HttpPartParser.Creator.class, v.get());
      bs.createBeanFromMethod(HttpPartParser.class, resource(), this::matchesInjectScope)
         .ifPresent(x -> v.get().impl(x));
      return v.get().create();
   });

   /** The HTTP part serializer for this operation (op-level creator applied on top of the parent). */
   private final Memoizer<HttpPartSerializer> partSerializer = memoizer(() -> {
      var aa = appliedAnnotations();
      var parent = restContext().getPartSerializerCreator();
      if (!parent.canApply(aa))
         return restContext().getPartSerializer();
      Holder<HttpPartSerializer.Creator> v = Holder.of(parent.copy());
      v.get().apply(aa);
      var bs = new BasicBeanStore(beanStore())
         .addBean(Method.class, method())
         .addBean(HttpPartSerializer.Creator.class, v.get());
      bs.createBeanFromMethod(HttpPartSerializer.class, resource(), this::matchesInjectScope)
         .ifPresent(x -> v.get().impl(x));
      return v.get().create();
   });

   /**
    * The URL path matchers for this operation.
    *
    * <p>
    * Walks the {@code @RestOp}/verb annotation chain (parent-to-child) and collects each
    * annotation's {@code path[]} array plus its {@code value()} (the conventional shortcut form on
    * {@link RestGet @RestGet}/{@link RestPost @RestPost}/etc., or the {@code "METHOD path"} pair on
    * {@link RestOp @RestOp}). When no explicit paths are declared, the operation method name (with
    * the verb prefix stripped where applicable) is auto-detected via {@link HttpUtils#detectHttpPath}.
    * For RRPC operations with no explicit path, a trailing {@code "/*"} is appended so the matcher
    * matches anything below the method's URL.
    * {@code noInherit={"path"}} cuts off any further parent-chain contribution. A
    * {@code @Bean UrlPathMatcherList} bean (matching this operation's method scope) REPLACES
    * the entire result.
    *
    * <p>
    * SVL variables (e.g. {@code $S{key,default}} or the shorthand {@code ${key:default}}) in path
    * strings are resolved via the host {@link RestContext}'s {@link VarResolver} before being
    * compiled into {@link UrlPathMatcher} patterns &mdash; this closes the asymmetry with class-level
    * {@link Rest#path() @Rest(path)} / {@link Rest#paths() @Rest(paths)}, which are also
    * SVL-resolved. Strings that contain no SVL markers pass through unchanged, so this is a strict
    * superset of the previous behavior. Path strings whose entire SVL resolution yields an empty
    * string are skipped (matching how empty pieces are dropped from the post-comma-split pipeline at
    * the class level &mdash; see {@code RestContext#splitPathsValue}). Unresolved variables (no
    * registered {@link Var}) pass through to {@link UrlPathMatcher#of} as the literal {@code ${...}}
    * placeholder, which then fails predictably at routing time. The auto-detected fallback path
    * (derived from the method name via {@link HttpUtils#detectHttpPath}) is intentionally
    * <i>not</i> SVL-resolved &mdash; it is framework-derived, not user input.
    */
   private final Memoizer<UrlPathMatcher[]> pathMatchers = memoizer(() -> {
      var v = Holder.of(UrlPathMatcherList.create());
      var vr = varResolver();
      // Use a single VarResolverSession + explicit compile(...) / .resolve(session) per path
      // so the framework hot path exercises the compiled-template seam explicitly.
      // Each distinct path string is tokenized once into a VarTemplate, then resolved against
      // this session. If we ever switch to per-request dynamic path resolution, the seam is
      // already in place — only the .resolve(session) call moves to the request handler.
      var session = vr.createSession();
      getRestOpAnnotationsForProperty("path").forEach(ai -> {
         for (var p : ai.getStringArray("path").orElse(StringUtils.EMPTY_STRING_ARRAY)) {
            var resolved = vr.compile(p).resolve(session);
            if (!resolved.isEmpty())
               v.get().add(UrlPathMatcher.of(resolved));
         }
         // On verb annotations (@RestGet/@RestPost/etc.) value() is always the path. On @RestOp,
         // value() is "[METHOD] [path]" where the leading method token is optional — only when a
         // space is present does the trailing token represent a path. To keep this loop annotation-
         // agnostic, we apply the @RestOp space-split rule only when an @RestOp annotation is in
         // play (i.e. the annotation type matches), and otherwise treat value() as a plain path.
         // SVL is applied AFTER the space-split rule so a resolved path can never be misinterpreted
         // as a "METHOD path" pair (the method token is structural, not user-overridable via SVL).
         ai.getString("value").filter(StringUtils::isNotBlank).map(String::trim).ifPresent(s -> {
            if (ai.inner() instanceof RestOp) {
               var i = s.indexOf(' ');
               if (i != -1) {
                  var resolved = vr.compile(s.substring(i).trim()).resolve(session);
                  if (!resolved.isEmpty())
                     v.get().add(UrlPathMatcher.of(resolved));
               }
            } else {
               var resolved = vr.compile(s).resolve(session);
               if (!resolved.isEmpty())
                  v.get().add(UrlPathMatcher.of(resolved));
            }
         });
      });

      if (v.get().isEmpty()) {
         var methodInfo2 = MethodInfo.of(method());
         String httpMethod2 = null;
         if (methodInfo2.hasAnnotation(RestGet.class))
            httpMethod2 = "get";
         else if (methodInfo2.hasAnnotation(RestPut.class))
            httpMethod2 = "put";
         else if (methodInfo2.hasAnnotation(RestPost.class))
            httpMethod2 = "post";
         else if (methodInfo2.hasAnnotation(RestDelete.class))
            httpMethod2 = "delete";
         else if (methodInfo2.hasAnnotation(RestOp.class)) {
            // @formatter:off
            httpMethod2 = AP.find(RestOp.class, methodInfo2)
               .stream()
               .map(x -> x.inner().method())
               .filter(Shorts::ine)
               .findFirst()
               .orElse(null);
            // @formatter:on
         }

         var p = HttpUtils.detectHttpPath(method(), httpMethod2);

         // RRPC operations match anything below the method's URL when no explicit path is supplied
         if (eqic("RRPC", httpMethod2) && ! p.endsWith("/*"))
            p += "/*";

         v.get().add(UrlPathMatcher.of(p));
      }

      beanStore().createBeanFromMethod(UrlPathMatcherList.class, resource(), this::matchesInjectScope, v.get())
         .ifPresent(v::set);

      // @Mixin(path/paths) re-mount: when this op belongs to a mixin sub-context whose host @Mixin declared a
      // mount prefix, re-mount every matcher under each host-chosen prefix.  Reuses the pathToken normalization
      // (via RestContext.getMixinMountPrefixes) so override input forms (bare / leading-slash / trailing /*)
      // all collapse to one clean prefix.  Build-time only.
      var prefixes = restContext().getMixinMountPrefixes();
      if (! prefixes.isEmpty()) {
         var remounted = UrlPathMatcherList.create();
         for (var prefix : prefixes)
            for (var pm : v.get().asArray())
               remounted.add(UrlPathMatcher.of(prefixPath(prefix, pm.toString())));
         v.set(remounted);
      }

      return v.get().asArray();
   });

   /**
    * Prepends a host-chosen mixin mount prefix to an op path pattern.
    *
    * <p>
    * {@code prefix} is a bare token (no slashes — already normalized by {@code RestContext.getMixinMountPrefixes}).
    * The original pattern keeps its leading slash and any trailing {@code /*}; e.g. prefix {@code "admin"} +
    * pattern {@code /info} &rarr; {@code /admin/info}, and prefix {@code "admin"} + {@code /loggers/*} &rarr;
    * {@code /admin/loggers/*}.
    *
    * @param prefix The normalized mount-prefix token.
    * @param pattern The original op path pattern.
    * @return The prefixed pattern.
    */
   private static String prefixPath(String prefix, String pattern) {
      var p = pattern.startsWith("/") ? pattern : "/" + pattern;
      return "/" + prefix + p;
   }

   /** The required matchers extracted from {@link #matchersList}. */
   private final Memoizer<RestMatcher[]> requiredMatchers = memoizer(() -> matchersList.get().getRequiredEntries());

   // Immutable, cached views over the routing arrays returned by the public getters.  Built once (memoized) so
   // there is zero per-call allocation on the routing hot path and no live-array exposure to callers.  Internal
   // hot-path code reads the private array memoizers directly; these views exist only for the public API surface.
   private final Memoizer<List<UrlPathMatcher>> pathMatchersView = memoizer(() -> List.of(pathMatchers.get()));
   private final Memoizer<List<RestMatcher>> optionalMatchersView = memoizer(() -> List.of(optionalMatchers.get()));
   private final Memoizer<List<RestMatcher>> requiredMatchersView = memoizer(() -> List.of(requiredMatchers.get()));

   /** The computed response metadata for this operation method. */
   private final Memoizer<ResponseBeanMeta> responseMeta = memoizer(() -> ResponseBeanMeta.create(methodInfo(), appliedAnnotations()));

   /**
    * All {@link RestOp}-group annotations on this method, in child-to-parent order.
    *
    * <p>
    * Uses the same {@link MethodInfo} as the annotation traversal in the {@link Builder}, so
    * method-level metadata (e.g. {@code noInherit}) resolves consistently when the implementation
    * class differs from the method's declaring class.
    */
   private final Memoizer<List<AnnotationInfo<?>>> restOpAnnotations = memoizer(() -> {
      var methodInfo = MethodInfo.of(restContext().getResourceClass(), method()).accessible();
      return restContext().getAnnotationProvider().find(methodInfo, SELF, MATCHING_METHODS).stream()
         .filter(ai -> ai.isInGroup(RestOp.class))
         .toList();
   });

   /**
    * The serializer group for this operation.
    *
    * <p>
    * Walks the {@code @RestOp(serializers)} chain (parent-to-child); the most-derived non-empty
    * {@code serializers()} array REPLACES the entire inherited set. Falls through to the class-level
    * {@link RestContext#getSerializers()} when no op annotation declares serializers. An
    * {@code @Bean SerializerSet} bean (matching this operation's method scope) REPLACES the result.
    */
   private final Memoizer<SerializerSet> serializers = memoizer(() -> {
      var aa = appliedAnnotations();
      var bs = beanStore();
      var sb = restContext().getSerializersBuilder();
      var b = sb.copy();
      if (sb.canApply(aa))
         b.apply(aa);
      getRestOpAnnotationsForProperty("serializers").forEach(ai -> {
         var c = ai.getClassArray("serializers", Serializer.class).orElse(null);
         if (nn(c) && c.length > 0)
            b.set(c);
      });
      var result = Holder.of(b.build());
      bs.createBeanFromMethod(SerializerSet.class, resource(), this::matchesInjectScope)
         .ifPresent(result::set);
      return result.get();
   });

   /**
    * The supported response accept types for this operation.
    *
    * <p>
    * Walks op-level {@code @RestOp}-group annotations for {@code produces} (and, when
    * {@code noInherit} does not block it, the class-level {@code @Rest(produces)} hierarchy).
    * Falls back to the supported media types of the operation's {@link SerializerSet}.
    */
   private final Memoizer<List<MediaType>> supportedAcceptTypes = memoizer(() -> {
      var result = collectAnnotationMediaTypes("produces");
      if (result.isEmpty())
         return u(getSerializers().getSupportedMediaTypes());
      return u(result);
   });

   /**
    * The supported request content types for this operation.
    *
    * <p>
    * Walks op-level {@code @RestOp}-group annotations for {@code consumes} (and, when
    * {@code noInherit} does not block it, the class-level {@code @Rest(consumes)} hierarchy).
    * Falls back to the supported content types of the operation's {@link ParserSet}.
    */
   private final Memoizer<List<MediaType>> supportedContentTypes = memoizer(() -> {
      var result = collectAnnotationMediaTypes("consumes");
      if (result.isEmpty())
         return u(getParsers().getSupportedMediaTypes());
      return u(result);
   });

   /**
    * Iterates over each parameter annotation on the operation method, computing the parameter's
    * {@link Schema#default_()}/{@link Schema#df()} string (joined-non-blank-first) and dispatching
    * each annotation+default pair to the supplied callback.
    */
   private void processParameterDefaults(BiConsumer<Annotation,String> callback) {
      for (var aa : method.getParameterAnnotations()) {
         String def = null;
         for (var a : aa) {
            if (a instanceof Schema a2)
               def = joinnlFirstNonEmptyArray(a2.default_(), a2.df());
         }
         if (def == null)
            continue;
         for (var a : aa)
            callback.accept(a, def);
      }
   }

   /**
    * Returns {@code true} if the given method has a {@code @Bean} annotation whose
    * {@code methodScope} includes this operation's method name (or {@code "*"}).
    *
    * <p>
    * Used by op-level memoizers when scanning the resource class for {@code @Bean}-supplied
    * composite-bean overrides ({@code RestConverterList}, {@code RestGuardList}, etc.). This is the
    * {@link RestOpContext}-scope peer of {@link Builder#matches(MethodInfo)} — kept in sync with that
    * one.
    */
   private boolean matchesInjectScope(MethodInfo annotated) {
      var a = annotated.getAnnotations(Bean.class).findFirst().map(AnnotationInfo::inner).orElse(null);
      if (a != null) {
         for (var n : a.methodScope()) {
            if (eq(n, "*") || method.getName().equals(n))
               return true;
         }
      }
      return false;
   }

   /**
    * Same as {@link #matchesInjectScope(MethodInfo)} but additionally requires the
    * {@link Bean#name()} attribute to equal {@code beanName}.
    *
    * <p>
    * Used for named composite-bean overrides ({@code defaultRequestHeaders}, {@code defaultResponseHeaders},
    * etc.) where the bean type alone is ambiguous (e.g. {@link HeaderList} appears as both request and
    * response headers).
    */
   private boolean matchesInjectScope(MethodInfo annotated, String beanName) {
      var a = annotated.getAnnotations(Bean.class).findFirst().map(AnnotationInfo::inner).orElse(null);
      if (a != null) {
         if (! BeanAnnotation.name(a).equals(beanName))
            return false;
         for (var n : a.methodScope()) {
            if (eq(n, "*") || method.getName().equals(n))
               return true;
         }
      }
      return false;
   }

   private Stream<String> resolveCdl(String...values) {
      if (values == null || values.length == 0)
         return Stream.empty();
      return Arrays.stream(values)
         .filter(Objects::nonNull)
         .map(s -> context.getVarResolver().resolve(s))
         .map(StringUtils::split)
         .flatMap(Collection::stream)
         .map(String::trim)
         .filter(StringUtils::isNotBlank);
   }

   /**
    * Returns all {@link RestOp}-group annotations on this operation method, in child-to-parent order.
    *
    * @return An unmodifiable list, never {@code null}.
    */
   public List<AnnotationInfo<?>> getRestOpAnnotations() {
      return restOpAnnotations.get();
   }

   /**
    * Returns the {@link RestOp}-group annotations on this method for the specified property,
    * in <b>parent-to-child</b> order, with op-level {@code noInherit} cutoff applied.
    *
    * <p>
    * Mirrors {@link RestContext#getRestAnnotationsForProperty(String)} but for the op-level chain. Used by
    * op-level memoizers ({@link #converters}, {@link #guards}, {@link #matchersList},
    * {@link #encoders}, etc.) when accumulating values from each {@code @RestOp} / {@code @RestGet} /
    * {@code @RestPut} / {@code @RestPost} / {@code @RestDelete} / {@code @RestPatch} / {@code @RestOptions}
    * annotation in the method-override chain.
    *
    * @param name The annotation property name (e.g. {@code "converters"}, {@code "guards"}).
    * @return A stream of {@link AnnotationInfo} entries in parent-to-child order, never {@code null}.
    */
   Stream<AnnotationInfo<?>> getRestOpAnnotationsForProperty(String name) {
      var annotations = getRestOpAnnotations();
      var cutoff = annotations.size();
      for (var i = 0; i < annotations.size(); i++) {
         if (resolveCdl(annotations.get(i).getStringArray("noInherit").orElse(StringUtils.EMPTY_STRING_ARRAY)).anyMatch(name::equalsIgnoreCase)) {
            cutoff = i + 1;
            break;
         }
      }
      return rstream(annotations.subList(0, cutoff));
   }

   /**
    * Returns {@code true} if context-level values for the given property should be merged.
    *
    * @param property The annotation attribute name (e.g. {@code "allowedParserOptions"},
    *    {@code "defaultCharset"}, {@code "maxInput"}).
    * @return {@code true} if {@code noInherit} does not contain this property.
    */
   protected boolean isInherited(String property) {
      return !noInheritOp.get().contains(property);
   }

   /**
    * Returns the parser session-option keys allowed for this operation.
    *
    * @return An unmodifiable case-insensitive sorted set, never {@code null}.
    */
   public SortedSet<String> getAllowedParserOptions() {
      return allowedParserOptions.get();
   }

   /**
    * Returns the serializer session-option keys allowed for this operation.
    *
    * @return An unmodifiable case-insensitive sorted set, never {@code null}.
    */
   public SortedSet<String> getAllowedSerializerOptions() {
      return allowedSerializerOptions.get();
   }

   /**
    * Startup-fail: validates that when the effective observability attribute for this op is {@code "true"},
    * at least one real backend ({@link org.apache.juneau.rest.server.metrics.MetricsRecorder} or
    * {@link org.apache.juneau.rest.server.tracing.TracerHook}) is registered.
    *
    * <p>
    * Called once during construction.  The resource-level check in {@link RestContext#checkObservabilityBackendPresent()}
    * already fires for {@code @Rest(observability="true")}; this companion fires for individual
    * {@code @RestOp(observability="true")} overrides that elevate a single op into strict mode.
    */
   private void checkOpObservabilityBackendPresent() {
      var attr = observabilityAttr.get();
      if (neqic("true", attr))
         return;
      var bs = beanStore();
      var recorder = bs.getBean(org.apache.juneau.rest.server.metrics.MetricsRecorder.class).orElse(null);
      var tracer = bs.getBean(org.apache.juneau.rest.server.tracing.TracerHook.class).orElse(null);
      boolean hasRecorder = recorder != null && !(recorder instanceof org.apache.juneau.rest.server.metrics.NoOpMetricsRecorder);
      boolean hasTracer = tracer != null && !(tracer instanceof org.apache.juneau.rest.server.tracing.NoOpTracerHook);
      if (!hasRecorder && !hasTracer)
         throw new InternalServerError(
            "@RestOp(observability=\"true\") is set on " + context.getResourceClass().getSimpleName() + "." + method.getName()
            + " but no MetricsRecorder or TracerHook @Bean is registered. "
            + "Either wire a backend or change observability to \"\" (inherit) or \"false\" (opt-out).");
   }

   /**
    * Returns the first non-blank, SVL-resolved value of the given attribute across all
    * {@code @RestOp}-group annotations on this method (child-to-parent order).
    *
    * @param attr The annotation attribute name (e.g. {@code "defaultCharset"}).
    * @return The resolved string, or empty if no annotation defines it.
    */
   private Optional<String> findOpString(String attr) {
      var vr = varResolver();
      for (var ai : getRestOpAnnotations()) {
         var s = ai.getString(attr).orElse("");
         if (!s.isEmpty()) {
            var resolved = vr.resolve(s);
            if (!resolved.isEmpty())
               return o(resolved);
         }
      }
      return oe();
   }

   private List<MediaType> collectAnnotationMediaTypes(String attr) {
      var result = new ArrayList<MediaType>();
      var vr = varResolver();
      // Class-level @Rest(consumes|produces) first (when inheritance is allowed), then op-level overrides append.
      if (isInherited(attr)) {
         for (var ai : restContext().getRestAnnotations())
            appendResolvedMediaTypes(ai, attr, vr, result);
      }
      for (var ai : getRestOpAnnotations())
         appendResolvedMediaTypes(ai, attr, vr, result);
      return result;
   }

   private static void appendResolvedMediaTypes(AnnotationInfo<?> ai, String attr, VarResolver vr, List<MediaType> result) {
      var arr = ai.getStringArray(attr).orElse(null);
      if (arr == null)
         return;
      for (var s : arr) {
         if (isNotEmpty(s)) {
            var resolved = vr.resolve(s);
            if (!resolved.isEmpty())
               result.add(MediaType.of(resolved));
         }
      }
   }

   private static String httpMethodFromAnnotation(Annotation a, VarResolver vr) {
      if (a instanceof RestGet)
         return "get";
      if (a instanceof RestPut)
         return "put";
      if (a instanceof RestPost)
         return "post";
      if (a instanceof RestDelete)
         return "delete";
      if (a instanceof RestPatch)
         return "patch";
      if (a instanceof RestOptions)
         return "options";
      if (a instanceof RestOp a2) {
         var m = vr.resolve(a2.method());
         if (ine(m))
            return m;
         var s = vr.resolve(a2.value());
         if (s != null) {
            s = s.trim();
            if (!s.isEmpty()) {
               var i = s.indexOf(' ');
               return i == -1 ? s : s.substring(0, i).trim();
            }
         }
      }
      return null;
   }

   private static String normalizeHttpMethod(String v) {
      if (eqic("METHOD", v))
         return "*";
      return ucr(v);
   }

   /**
    * 2-arg positional context constructor.
    *
    * <p>
    * All operation-level configuration is resolved from {@link RestOp}-group annotations on the method and
    * inherited from the parent {@link RestContext}.
    *
    * @param method The Java method this context represents. Must not be <jk>null</jk>.
    * @param context The owning {@link RestContext}. Must not be <jk>null</jk>.
    * @throws ServletException If context could not be created.
    * @since 9.2.1
    */
   public RestOpContext(java.lang.reflect.Method method, RestContext context) throws ServletException {
      this(new Builder(method, context));
   }

   /**
    * 3-arg positional context constructor.
    *
    * @param method The Java method this context represents. Must not be <jk>null</jk>.
    * @param context The owning {@link RestContext}. Must not be <jk>null</jk>.
    * @param resourceSupplier Supplier that returns the invocation target for this operation.
    * @throws ServletException If context could not be created.
    */
   public RestOpContext(java.lang.reflect.Method method, RestContext context, Supplier<Object> resourceSupplier) throws ServletException {
      this(new Builder(method, context, resourceSupplier));
   }

   /**
    * Context constructor.
    *
    * @param builder The builder for this object.
    * @throws ServletException If context could not be created.
    */
   private RestOpContext(Builder builder) throws ServletException {
      super(builder);

      try {
         // Capture the annotation work-list before the builder becomes eligible for GC.
         appliedAnnotations = builder.getApplied();

         context = builder.restContext;
         method = builder.restMethod;
         resourceSupplier = builder.restResourceSupplier;

         mi = MethodInfo.of(method).accessible();

         var bs = new BasicBeanStore(context.getBootstrapBeanStore());
         bs.addBean(RestOpContext.class, this);
         bs.addBean(Method.class, method);
         bs.addBean(AnnotationWorkList.class, appliedAnnotations);
         opBeanStore = bs;

         bs.add(MarshallingContext.class, getMarshallingContext());
         bs.add(RestConverter[].class, getConverters());
         bs.add(EncoderSet.class, getEncoders());
         bs.add(RestGuard[].class, getGuards());
         bs.add(JsonSchemaGenerator.class, getJsonSchemaGenerator());
         bs.add(ParserSet.class, getParsers());
         bs.add(HttpPartParser.class, getPartParser());
         bs.add(HttpPartSerializer.class, getPartSerializer());
         bs.add(SerializerSet.class, getSerializers());

      // Inject @Value-annotated env-driven defaults onto this RestOpContext instance so that the
      // memoizer lambdas (defaultCharset, maxInput) read fully resolved values when first invoked.
      ClassInfo.of(this).inject(this, bs);

      // Startup-fail check: if this op (or its resource) declares observability="true" but neither
      // MetricsRecorder nor TracerHook is wired, fail fast with a precise error.
      checkOpObservabilityBackendPresent();

      // The 6 formerly-eager scalar fields are now memoized; no eagerness needed here.
      // Pre-warm httpMethod so it is in the memoizer cache for immediate use by compareTo/match.
      httpMethod.get();

      // Fail servlet init (not the first request) if a concrete @Request bean parameter has a getter with no matching
      // setter or no public no-arg constructor; the arg is rebuilt lazily with the invoker.
      for (var pi : mi.getParameters())
         org.apache.juneau.rest.server.arg.RequestBeanArg.create(pi, appliedAnnotations);

         var pm = pathMatchers.get();
         bs.add(UrlPathMatcher[].class, pm);
         bs.addBean(UrlPathMatcher.class, pm.length > 0 ? pm[0] : null);

      } catch (Exception e) {
         throw new ServletException(e);
      }
   }

   /*
    * compareTo() method is used to keep SimpleMethods ordered in the RestCallRouter list.
    * It maintains the order in which matches are made during requests.
    */
   @Override /* Overridden from Comparable */
   public int compareTo(RestOpContext o) {
      int c;

      var pm = pathMatchers.get();
      var opm = o.pathMatchers.get();
      for (int i = 0; i < Math.min(pm.length, opm.length); i++) {
         c = pm[i].compareTo(opm[i]);
         if (c != 0)
            return c;
      }

      c = cmp(o.hierarchyDepth.get(), hierarchyDepth.get());
      if (c != 0)
         return c;

      c = cmp(o.requiredMatchers.get().length, requiredMatchers.get().length);
      if (c != 0)
         return c;

      c = cmp(o.optionalMatchers.get().length, optionalMatchers.get().length);
      if (c != 0)
         return c;

      c = cmp(o.getGuards().length, getGuards().length);

      if (c != 0)
         return c;

      c = cmp(method.getName(), o.method.getName());
      if (c != 0)
         return c;

      c = cmp(method.getParameterCount(), o.method.getParameterCount());
      if (c != 0)
         return c;

      for (var i = 0; i < method.getParameterCount(); i++) {
         c = cmp(method.getParameterTypes()[i].getName(), o.method.getParameterTypes()[i].getName());
         if (c != 0)
            return c;
      }

      c = cmp(method.getReturnType().getName(), o.method.getReturnType().getName());
      if (c != 0)
         return c;

      // Declaring-class tie-breaker: keeps compareTo consistent with equals()/hashCode() (which key off method
      // identity) for two ops whose methods share the same signature but differ by declaring class.  Only affects
      // ordering that was previously a zero-tie, so it makes tie-break stability deterministic rather than changing
      // any non-tied dispatch precedence.
      c = cmp(method.getDeclaringClass().getName(), o.method.getDeclaringClass().getName());
      if (c != 0)
         return c;

      return 0;
   }

   @Override /* Overridden from Context */
   public Context.Builder copy() {
      throw uoex();
   }

   /**
    * Creates a {@link RestRequest} object based on the specified incoming {@link HttpServletRequest} object.
    *
    * @param session The current REST call.
    * @return The wrapped request object.
    * @throws Exception If any errors occur trying to interpret the request.
    */
   public RestRequest createRequest(RestSession session) throws Exception {
      return new RestRequest(this, session);
   }

   /**
    * Creates a {@link RestResponse} object based on the specified incoming {@link HttpServletResponse} object
    * and the request returned by {@link #createRequest(RestSession)}.
    *
    * @param session The current REST call.
    * @param req The REST request.
    * @return The wrapped response object.
    * @throws Exception If any errors occur trying to interpret the request or response.
    */
   public RestResponse createResponse(RestSession session, RestRequest req) throws Exception {
      return new RestResponse(this, session, req);
   }

   /**
    * Creates a new REST operation session.
    *
    * @param session The REST session.
    * @return A new REST operation session.
    * @throws Exception If op session could not be created.
    */
   public RestOpSession.Builder createSession(RestSession session) throws Exception {
      var b = RestOpSession.create(this, session);
      if (getLogger().isLoggable(Level.FINEST))
         session.installCapture();
      return b;
   }

   @Override /* Overridden from Object */
   public boolean equals(Object o) {
      return (o instanceof RestOpContext o2) && eq(this, o2, (x, y) -> eq(x.method, y.method));
   }

   /**
    * Returns the marshalling context associated with this context.
    *
    * @return The marshalling context associated with this context.
    */
   public MarshallingContext getMarshallingContext() { return marshallingContext.get(); }

   /**
    * Returns the default charset.
    *
    * @return The default charset.  Never <jk>null</jk>.
    */
   public Charset getDefaultCharset() { return defaultCharset.get(); }

   /**
    * Returns the default request attributes.
    *
    * @return The default request attributes.  Never <jk>null</jk>.
    */
   public NamedAttributeMap getDefaultRequestAttributes() { return defaultRequestAttributes.get(); }

   /**
    * Returns the default form data parameters.
    *
    * @return The default form data parameters.  Never <jk>null</jk>.
    */
   public HttpPartList getDefaultRequestFormData() { return defaultRequestFormData.get(); }

   /**
    * Returns the default request headers.
    *
    * @return The default request headers.  Never <jk>null</jk>.
    */
   public HttpHeaderList getDefaultRequestHeaders() { return defaultRequestHeaders.get(); }

   /**
    * Returns the default request query parameters.
    *
    * @return The default request query parameters.  Never <jk>null</jk>.
    */
   public HttpPartList getDefaultRequestQueryData() { return defaultRequestQueryData.get(); }

   /**
    * Returns the default response headers.
    *
    * @return The default response headers.  Never <jk>null</jk>.
    */
   public HttpHeaderList getDefaultResponseHeaders() { return defaultResponseHeaders.get(); }

   /**
    * Returns the compression encoders to use for this method.
    *
    * @return The compression encoders to use for this method.
    */
   public EncoderSet getEncoders() { return encoders.get(); }

   /**
    * Returns the HTTP method name (e.g. <js>"GET"</js>).
    *
    * @return The HTTP method name.
    */
   public String getHttpMethod() { return httpMethod.get(); }

   /**
    * Returns whether this operation is declared {@link RestOp#read() read=true}.
    *
    * <p>
    * A read operation may be reached by overriding a safe request (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c>,
    * <c>TRACE</c>) to its custom method.
    *
    * @return <jk>true</jk> if this operation is declared a read.
    * @throws InternalServerError If <c>read=<jk>true</jk></c> is declared on an inherited <ja>@RestOp</ja> that names
    *    no method.
    * @since 10.0.0
    */
   public boolean isRead() { return read.get(); }

   /**
    * Returns the underlying Java method that this context belongs to.
    *
    * @return The underlying Java method that this context belongs to.
    */
   public Method getJavaMethod() { return method; }

   /**
    * Returns the JSON-Schema generator applicable to this Java method.
    *
    * @return The JSON-Schema generator applicable to this Java method.
    */
   public JsonSchemaGenerator getJsonSchemaGenerator() { return jsonSchemaGenerator.get(); }

   /**
    * Returns the max number of bytes to process in the input content.
    *
    * @return The max number of bytes to process in the input content.
    */
   public long getMaxInput() { return maxInput.get(); }

   /**
    * Returns whether this operation emits RFC 7807 {@code application/problem+json} responses.
    *
    * <p>
    * Tri-state inheritance semantics: an explicit {@code "true"} or {@code "false"} on the operation annotation
    * wins; otherwise the value is inherited from {@link RestContext#isProblemDetails()} (resource-level
    * {@code @Rest(problemDetails)}).
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='ja'>{@link Rest#problemDetails()}
    *    <li class='ja'>{@link RestOp#problemDetails()}
    * </ul>
    *
    * @return <jk>true</jk> if RFC 7807 problem-details responses are enabled on this operation.
    */
   public boolean isProblemDetails() { return problemDetails.get(); }

   /**
    * Returns whether REST-driven serializer/parser debug behavior is enabled for this operation.
    *
    * <p>
    * Resolved via the tri-state {@code @RestOp}-group {@code debugMarshalling} attribute ({@code "true"} wins,
    * {@code "false"} opts out, {@code ""} inherits the resource-level {@code @Rest(debugMarshalling)}), independent
    * of the JUL logger level.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='ja'>{@link Rest#debugMarshalling()}
    *    <li class='ja'>{@link RestOp#debugMarshalling()}
    * </ul>
    *
    * @return <jk>true</jk> if REST-driven marshalling debug is enabled for this operation.
    */
   public boolean isDebugMarshalling() { return debugMarshalling.get(); }

   /**
    * Returns whether this operation opts into per-request virtual-thread dispatch on Java 21+.
    *
    * <p>
    * The op-level {@code @RestOp(virtualThreads)} value (when non-blank) wins; otherwise the value is inherited
    * from {@link RestContext#isVirtualThreadsEnabled()} (resource-level {@code @Rest(virtualThreads)}). Honored
    * only when the resource-level {@link RestContext#getVirtualThreadExecutor()} is non-{@code null} (Java 21+).
    *
    * @return <jk>true</jk> if virtual-thread dispatch is configured on this operation.
    */
   public boolean isVirtualThreadsEnabled() { return virtualThreadsEnabled.get(); }

   /**
    * Returns whether the observability block is enabled for this operation.
    *
    * <p>
    * Returns {@code false} when the effective resolved attribute is {@code "false"} (explicit opt-out).
    * Returns {@code true} in all other cases ({@code "true"} strict opt-in or empty/null default).
    *
    * <p>
    * Note: the default behavior (empty/null attribute) still runs the observability block, but silently
    * falls back to {@link org.apache.juneau.rest.server.metrics.NoOpMetricsRecorder} when no backend is wired.
    * Only {@code "false"} completely short-circuits the block.
    *
    * @return <jk>false</jk> when this operation has explicitly opted out of observability.
    * @see RestOp#observability()
    * @see Rest#observability()
    */
   public boolean isObservabilityEnabled() {
      var v = observabilityAttr.get();
      return neqic("false", v);
   }

   /**
    * Returns the per-op metric name override from {@code @RestOp(metricName)}.
    *
    * @return The metric name override, or an empty string when not set.
    * @see RestOp#metricName()
    */
   public String getMetricName() { return metricName.get(); }

   /**
    * Returns the per-op additional metric tags from {@code @RestOp(metricTags)}.
    *
    * @return The tags string (comma-separated {@code key=value} pairs), or empty string when not set.
    * @see RestOp#metricTags()
    */
   public String getMetricTags() { return metricTags.get(); }

   /**
    * Returns the configured async-response timeout (milliseconds) for this operation, or {@code -1} when no
    * value was supplied at the op or resource level — in which case the default 30-second fallback applies in
    * {@link org.apache.juneau.rest.server.processor.AsyncResponseProcessor}.
    *
    * @return The async timeout in milliseconds, or {@code -1} when unset.
    */
   public long getAsyncTimeoutMillis() { return asyncTimeoutMillis.get(); }

   /**
    * Returns the effective {@link Executor} for routing
    * {@link CompletableFuture} completion callbacks on this operation, or
    * {@code null} when neither the op nor the resource configures an executor (natural completion thread).
    *
    * @return The executor, or {@code null} if no async-completion executor is configured.
    * @since 10.0.0
    */
   public Executor getAsyncCompletionExecutor() { return asyncCompletionExecutor.get(); }

   /**
    * Returns the parsers to use for this method.
    *
    * @return The parsers to use for this method.
    */
   public ParserSet getParsers() { return parsers.get(); }

   /**
    * Bean property getter:  <property>partParser</property>.
    *
    * @return The value of the <property>partParser</property> property on this bean, or <jk>null</jk> if it is not set.
    */
   public HttpPartParser getPartParser() { return partParser.get(); }

   /**
    * Bean property getter:  <property>partSerializer</property>.
    *
    * @return The value of the <property>partSerializer</property> property on this bean, or <jk>null</jk> if it is not set.
    */
   public HttpPartSerializer getPartSerializer() { return partSerializer.get(); }

   /**
    * Returns the path pattern for this method.
    *
    * @return The path pattern.
    */
   public String getPathPattern() { return pathMatchers.get()[0].toString(); }

   /**
    * Returns the URL path matchers for this operation.
    *
    * @return The URL path matchers for this operation.
    *    <br>Never <jk>null</jk>.
    *    <br>The returned list is an immutable, cached view.
    */
   public List<UrlPathMatcher> getPathMatchers() { return pathMatchersView.get(); }

   /**
    * Returns the optional matchers for this operation.
    *
    * @return The optional matchers for this operation.
    *    <br>Never <jk>null</jk>.
    *    <br>The returned list is an immutable, cached view.
    */
   public List<RestMatcher> getOptionalMatchers() { return optionalMatchersView.get(); }

   /**
    * Returns the required matchers for this operation.
    *
    * @return The required matchers for this operation.
    *    <br>Never <jk>null</jk>.
    *    <br>The returned list is an immutable, cached view.
    */
   public List<RestMatcher> getRequiredMatchers() { return requiredMatchersView.get(); }

   /**
    * Returns the per-operation logger used for debug capture.
    *
    * <p>
    * A hierarchical child of the host resource's resolved logger ({@code <hostLoggerName>.<methodName>}) &mdash;
    * see the {@code logger} memoizer for how the host's bean-store-overridden {@link RichLogger} (if any) is
    * honored.
    *
    * @return The per-operation logger.
    *    <br>Never <jk>null</jk>.
    */
   public RichLogger getLogger() { return logger.get(); }

   /**
    * Returns metadata about the specified response object if it's annotated with {@link Response @Response}.
    *
    * @param o The response POJO.  Can be <jk>null</jk> (returns <jk>null</jk>).
    * @return Metadata about the specified response object, or <jk>null</jk> if it's not annotated with {@link Response @Response}.
    */
   public ResponseBeanMeta getResponseBeanMeta(Object o) {
      if (o == null)
         return null;
      var c = o.getClass();
      var rbm = responseBeanMetas.get(c);
      if (rbm == null) {
         rbm = ResponseBeanMeta.create(c, AnnotationWorkList.create());
         if (rbm == null)
            rbm = ResponseBeanMeta.NULL;
         responseBeanMetas.put(c, rbm);
      }
      if (rbm == ResponseBeanMeta.NULL)
         return null;
      return rbm;
   }

   /**
    * Returns metadata about the specified response object if it's annotated with {@link Header @Header}.
    *
    * @param o The response POJO.  Can be <jk>null</jk> (returns <jk>null</jk>).
    * @return Metadata about the specified response object, or <jk>null</jk> if it's not annotated with {@link Header @Header}.
    */
   public ResponsePartMeta getResponseHeaderMeta(Object o) {
      if (o == null)
         return null;
      var c = o.getClass();
      var pm = headerPartMetas.get(c);
      if (pm == null) {
         var a = ClassInfo.of(c).getAnnotations(Header.class).findFirst().map(AnnotationInfo::inner).orElse(null);
         if (nn(a)) {
            var schema = HttpPartSchema.create(a);
         var serializer = createPartSerializer((Class<? extends HttpPartSerializer>)schema.getSerializer(), getPartSerializer());
            pm = new ResponsePartMeta(HEADER, schema, serializer);
         }
         if (pm == null)
            pm = ResponsePartMeta.NULL;
         headerPartMetas.put(c, pm);
      }
      if (pm == ResponsePartMeta.NULL)
         return null;
      return pm;
   }

   /**
    * Returns the response bean meta if this method returns a {@link Response}-annotated bean.
    *
    * @return The response bean meta or <jk>null</jk> if it's not a {@link Response}-annotated bean.
    */
   public ResponseBeanMeta getResponseMeta() { return responseMeta.get(); }

   /**
    * Returns the serializers to use for this method.
    *
    * @return The serializers to use for this method.
    */
   public SerializerSet getSerializers() { return serializers.get(); }

   /**
    * Returns a list of supported accept types.
    *
    * @return An unmodifiable list.
    */
   public List<MediaType> getSupportedAcceptTypes() { return supportedAcceptTypes.get(); }

   /**
    * Returns the list of supported content types.
    *
    * @return An unmodifiable list.
    */
   public List<MediaType> getSupportedContentTypes() { return supportedContentTypes.get(); }

   @Override /* Overridden from Object */
   public int hashCode() {
      return method.hashCode();
   }

   private static String toPartValue(Object value) {
      return value == null ? null : value.toString();
   }

   private UrlPathMatch matchPattern(RestSession call) {
      for (var pp : pathMatchers.get()) {
         var pm = pp.match(call.getUrlPath());
         if (pm != null)
            return pm;
      }
      return null;
   }

   /**
    * Whether this operation's path pattern matches the specified call.
    *
    * <p>
    * Unlike {@link #match(RestSession)}, this neither runs the matchers nor caches the path match on the session, so
    * it can be asked of any operation without disturbing the one about to run.
    *
    * @param session The call to check.
    * @return <jk>true</jk> if the path pattern matches.
    */
   boolean matchesPath(RestSession session) {
      return nn(matchPattern(session));
   }

   /**
    * Identifies if this method can process the specified call.
    *
    * <p>
    * To process the call, the following must be true:
    * <ul>
    *    <li>Path pattern must match.
    *    <li>Matchers (if any) must match.
    * </ul>
    *
    * @param session The call to check.
    * @return
    *    One of the following values:
    *    <ul>
    *       <li><c>0</c> - Path doesn't match.
    *       <li><c>1</c> - Path matched but matchers did not.
    *       <li><c>2</c> - Matches.
    *    </ul>
    */
   protected int match(RestSession session) {

      var pm = matchPattern(session);

      if (pm == null)
         return 0;

      var rm = requiredMatchers.get();
      var om = optionalMatchers.get();
      if (rm.length == 0 && om.length == 0) {
         session.urlPathMatch(pm);  // Cache so we don't have to recalculate.
         return 2;
      }

      try {
         var req = session.getRequest();

         // If the method implements matchers, test them.
         for (var m : rm)
            if (! m.matches(req))
               return 1;
         if (om.length > 0) {
            var matches = false;
            for (var m : om)
               matches |= m.matches(req);
            if (! matches)
               return 1;
      }

         session.urlPathMatch(pm);  // Cache so we don't have to recalculate.
         return 2;
      } catch (Exception e) {
         throw new InternalServerError(e);
      }
   }

   @Override /* Overridden from Context */
   protected FluentMap<String,Object> properties() {
      return super.properties()
         .a("defaultRequestFormData", getDefaultRequestFormData())
         .a("defaultRequestHeaders", getDefaultRequestHeaders())
         .a("defaultRequestQueryData", getDefaultRequestQueryData())
         .a("httpMethod", getHttpMethod());
   }

   RestConverter[] getConverters() { return converters.get(); }

   RestGuard[] getGuards() { return guards.get(); }

   RestOpInvoker getMethodInvoker() { return methodInvoker.get(); }

   RestOpInvoker[] getPostCallMethods() { return postCallMethods.get(); }

   RestOpInvoker[] getPreCallMethods() { return preCallMethods.get(); }
   
   private static String joinnlFirstNonEmptyArray(String[]...s) {
      for (var ss : s)
         if (ss.length > 0)
            return joinnl(ss);
      return null;
   }

   private static <T> Class<? extends T>[] classArray(Class<? extends T> value) {
      return (Class<? extends T>[])new Class<?>[] { value };
   }


}