/*
 * 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 java.time.format.DateTimeFormatter.*;
import static java.time.temporal.ChronoUnit.*;
import static org.apache.juneau.commons.httppart.HttpPartType.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;

import java.io.*;
import java.nio.charset.*;
import java.time.*;
import java.util.*;
import java.util.regex.*;

import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.httppart.*;
import org.apache.juneau.http.*;
import org.apache.juneau.http.header.*;
import org.apache.juneau.http.response.*;
import org.apache.juneau.httppart.bean.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.encoders.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.marshaller.*;
import org.apache.juneau.marshall.oapi.*;
import org.apache.juneau.marshall.serializer.*;
import org.apache.juneau.rest.server.httppart.*;
import org.apache.juneau.rest.server.sse.*;
import org.apache.juneau.rest.server.util.*;

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

/**
 * Represents an HTTP response for a REST resource.
 *
 * <p>
 *    The {@link RestResponse} object is an extension of the <l>HttpServletResponse</l> class
 *    with various built-in convenience methods for use in building REST interfaces.
 *    It can be accessed by passing it as a parameter on your REST Java method:
 * </p>
 *
 * <p class='bjava'>
 *    <ja>@RestPost</ja>(...)
 *    <jk>public</jk> Object myMethod(RestResponse <jv>res</jv>) {...}
 * </p>
 *
 * <p>
 *    The primary methods on this class are:
 * </p>
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestResponse}
 *    <ul class='spaced-list'>
 *       <li>Methods for setting response headers:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestResponse#addHeader(HttpHeader) addHeader(HttpHeader)}
 *          <li class='jm'>{@link RestResponse#addHeader(String,String) addHeader(String,String)}
 *          <li class='jm'>{@link RestResponse#containsHeader(String) containsHeader(String)}
 *          <li class='jm'>{@link RestResponse#getHeader(String) getHeader(String)}
 *          <li class='jm'>{@link RestResponse#setCharacterEncoding(String) setCharacterEncoding(String)}
 *          <li class='jm'>{@link RestResponse#setContentType(String) setContentType(String)}
 *          <li class='jm'>{@link RestResponse#setHeader(HttpHeader) setHeader(HttpHeader)}
 *          <li class='jm'>{@link RestResponse#setHeader(HttpPartSchema,String,Object) setHeader(HttpPartSchema,String,Object)}
 *          <li class='jm'>{@link RestResponse#setHeader(String,Object) setHeader(String,Object)}
 *          <li class='jm'>{@link RestResponse#setHeader(String,String) setHeader(String,String)}
 *          <li class='jm'>{@link RestResponse#setMaxHeaderLength(int) setMaxHeaderLength(int)}
 *          <li class='jm'>{@link RestResponse#setSafeHeaders() setSafeHeaders()}
 *          <li class='jm'>{@link RestResponse#setUnsafeHeaders() setUnsafeHeaders()}
 *          <li class='jm'>{@link RestResponse#downloadAs(String) downloadAs(String)}
 *          <li class='jm'>{@link RestResponse#eTag(String) eTag(String)}
 *          <li class='jm'>{@link RestResponse#eTag(EntityTag) eTag(EntityTag)}
 *          <li class='jm'>{@link RestResponse#lastModified(Instant) lastModified(Instant)}
 *          <li class='jm'>{@link RestResponse#lastModified(ZonedDateTime) lastModified(ZonedDateTime)}
 *          <li class='jm'>{@link RestResponse#cacheControl(String) cacheControl(String)}
 *          <li class='jm'>{@link RestResponse#cacheControl(CacheControl.Builder) cacheControl(CacheControl.Builder)}
 *       </ul>
 *       <li>Methods for setting response bodies:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestResponse#flushBuffer() flushBuffer()}
 *          <li class='jm'>{@link RestResponse#getDirectWriter(String) getDirectWriter(String)}
 *          <li class='jm'>{@link RestResponse#getNegotiatedOutputStream() getNegotiatedOutputStream()}
 *          <li class='jm'>{@link RestResponse#getNegotiatedWriter() getNegotiatedWriter()}
 *          <li class='jm'>{@link RestResponse#getSerializerMatch() getSerializerMatch()}
 *          <li class='jm'>{@link RestResponse#getWriter() getWriter()}
 *          <li class='jm'>{@link RestResponse#sendPlainText(String) sendPlainText(String)}
 *          <li class='jm'>{@link RestResponse#sendRedirect(String) sendRedirect(String)}
 *          <li class='jm'>{@link RestResponse#sendSafeRedirect(String,String...) sendSafeRedirect(String,String...)}
 *          <li class='jm'>{@link RestResponse#setContentSchema(HttpPartSchema) setContentSchema(HttpPartSchema)}
 *          <li class='jm'>{@link RestResponse#setContent(Object) setContent(Object)}
 *          <li class='jm'>{@link RestResponse#setSerializer(Serializer) setSerializer(Serializer)}
 *          <li class='jm'>{@link RestResponse#setResponseBeanMeta(ResponseBeanMeta) setResponseBeanMeta(ResponseBeanMeta)}
 *          <li class='jm'>{@link RestResponse#setException(Throwable) setException(Throwable)}
 *       </ul>
 *       <li>Other:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestResponse#getAttributes() getAttributes()}
 *          <li class='jm'>{@link RestResponse#getContext() getContext()}
 *          <li class='jm'>{@link RestResponse#getOpContext() getOpContext()}
 *          <li class='jm'>{@link RestResponse#setAttribute(String,Object) setAttribute(String,Object)}
 *          <li class='jm'>{@link RestResponse#setNoTrace() setNoTrace()}
 *          <li class='jm'>{@link RestResponse#setStatus(int) setStatus(int)}
 *       </ul>
 *    </ul>
 * </ul>
 *
 */
@SuppressWarnings({
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., HEADER_ContentType)
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S2789", // The Optional content field is null until setContent() is called, and null (not Optional.empty()) means 'never set'; getRawOutput() null-checks it.
   "java:S3776", // Mainly getNegotiatedOutputStream(), whose Accept-Encoding negotiation nests several conditions.
   "resource" // HttpServletResponseWrapper is managed by servlet container
})
public class RestResponse extends HttpServletResponseWrapper {

   private static final String HEADER_ContentType = "Content-Type";
   private static final Pattern ENCODING_DISABLED_PATTERN = Pattern.compile("(identity|\\*)\\s*;\\s*q\\s*=\\s*(0(?!\\.)|0\\.0)");

   private final HttpServletResponse inner;
   private final RestRequest request;

   private Optional<Object> content;  // The POJO being sent to the output.
   private ServletOutputStream sos;
   private FinishableServletOutputStream os;
   private FinishablePrintWriter w;
   private ResponseBeanMeta responseBeanMeta;
   private final RestOpContext opContext;
   private Optional<HttpPartSchema> contentSchema;
   private Serializer serializer;
   private Optional<SerializerMatch> serializerMatch;
   private boolean safeHeaders = true;
   private int maxHeaderLength = 8096;

   /**
    * Constructor.
    */
   @SuppressWarnings({
      "java:S112" // throws Exception intentional - callback/lifecycle method
   })
   RestResponse(RestOpContext opContext, RestSession session, RestRequest req) throws Exception {
      super(session.getResponse());

      inner = session.getResponse();
      request = req;

      this.opContext = opContext;
      responseBeanMeta = opContext.getResponseMeta();

      var context = session.getContext();

      try {
         var passThroughHeaders = request.getHeaderParam("x-response-headers").orElse(null);
         if (nn(passThroughHeaders)) {
            var m = context.getPartParser().getPartSession().read(HEADER, null, passThroughHeaders, MarshallingContext.DEFAULT.getClassMeta(JsonMap.class));
            for (var e : m.entrySet())
               addHeader(e.getKey(), resolveUris(e.getValue()));
         }
      } catch (Exception e1) {
         throw new BadRequest(e1, "Invalid format for header 'x-response-headers'.  Must be in URL-encoded format.");
      }

      // Find acceptable charset
      var h = request.getHeaderParam("accept-charset").orElse(null);
      Charset charset = null;
      if (h == null)
         charset = opContext.getDefaultCharset();
      else
         for (var r : StringRanges.of(h).toList()) {
            if (r.getQValue() > 0) {
               if (eq(r.getName(), "*"))
                  charset = opContext.getDefaultCharset();
               else if (Charset.isSupported(r.getName()))
                  charset = Charset.forName(r.getName());
               if (nn(charset))
                  break;
            }
         }

      request.getContext().getDefaultResponseHeaders().forEach(x -> addHeader(x.getName(), resolveCspNonce(maybeResolveUris(x.getName(), x.getValue()))));  // Done this way to avoid list/array copy.

      opContext.getDefaultResponseHeaders().forEach(x -> addHeader(x.getName(), resolveCspNonce(maybeResolveUris(x.getName(), x.getValue()))));

      if (charset == null)
         throw new NotAcceptable("No supported charsets in header 'Accept-Charset': '%s'", request.getHeaderParam("Accept-Charset").orElse(null));
      inner.setCharacterEncoding(charset.name());

   }

   /**
    * Adds a response header.
    *
    * <p>
    * Any previous header values are preserved.
    *
    * <p>
    * Value is added at the end of the headers.
    *
    * <p>
    * If the header is a {@link HttpUriHeader}, the URI will be resolved using the {@link RestRequest#getUriResolver()} object.
    *
    * <p>
    * Note that per <a class='doclink' href='https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2'>RFC2616</a>,
    * only headers defined as comma-delimited lists [i.e., #(values)] should be defined as multiple message header fields.
    *
    * @param header The header.
    *    <br>Can be <jk>null</jk> (ignored).
    * @return This object.
    */
   public RestResponse addHeader(HttpHeader header) {
      if (header == null) {
         // Do nothing.
      } else if (header instanceof HttpUriHeader header2) {
         addHeader(header2.getName(), resolveUris(header2.getValue()));
      } else {
         addHeader(header.getName(), header.getValue());
      }
      return this;
   }

   /**
    * Adds a response header with the given name and value.
    *
    * <p>
    * This method allows response headers to have multiple values.
    *
    * <p>
    * A no-op of either the name or value is <jk>null</jk>.
    *
    * <p>
    * Note that per <a class='doclink' href='https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2'>RFC2616</a>,
    * only headers defined as comma-delimited lists [i.e., #(values)] should be defined as multiple message header fields.
    *
    * @param name The header name.
    * @param value The header value.
    */
   @Override
   public void addHeader(String name, String value) {
      if (nn(name) && nn(value)) {
         if (eqic(name, HEADER_ContentType))
            setHeader(name, value);
         else {
            if (safeHeaders)
               value = stripInvalidHttpHeaderChars(value);
            value = abbreviate(value, maxHeaderLength);
            inner.addHeader(name, value);
         }
      }
   }

   /**
    * Forces any content in the buffer to be written to the client.
    *
    * <p>
    * A call to this method automatically commits the response, meaning the status code and headers will be written.
    *
    * @throws IOException If an I/O error occurred.
    */
   @Override
   public void flushBuffer() throws IOException {
      if (nn(w))
         w.flush();
      if (nn(os))
         os.flush();
      inner.flushBuffer();
   }

   /**
    * Shortcut for calling <c>getRequest().getAttributes()</c>.
    *
    * @return The request attributes object.
    */
   public RequestAttributes getAttributes() { return request.getAttributes(); }

   /**
    * Wrapper around {@link #getCharacterEncoding()} that converts the value to a {@link Charset}.
    *
    * @return The request character encoding converted to a {@link Charset}, or <jk>null</jk> if no character encoding is set.
    */
   public Charset getCharset() {
      var s = getCharacterEncoding();
      return s == null ? null : Charset.forName(s);
   }

   /**
    * Returns the output that was set by calling {@link #setContent(Object)}.
    *
    * <p>
    * If it's null, then {@link #setContent(Object)} wasn't called.
    * <br>If it contains an empty, then <c>setObject(<jk>null</jk>)</c> was called.
    * <br>Otherwise, {@link #setContent(Object)} was called with a non-null value.
    *
    * @return The output object, or <jk>null</jk> if {@link #setContent(Object)} was never called.
    */
   public Optional<Object> getContent() { return content; }

   /**
    * Returns this value cast to the specified class.
    *
    * @param <T> The class to cast to.
    * @param c The class to cast to.
    *    <br>Must not be <jk>null</jk>.
    * @return This value cast to the specified class, or <jk>null</jk> if the object doesn't exist or isn't the specified type.
    */
   @SuppressWarnings({
      "unchecked" // Type erasure requires unchecked cast
   })
   public <T> T getContent(Class<T> c) {
      if (isContentOfType(c))
         return (T)getRawOutput();
      return null;
   }

   /**
    * Returns the schema of the response content.
    *
    * @return The schema of the response content, never <jk>null</jk>.
    */
   public Optional<HttpPartSchema> getContentSchema() {
      if (nn(contentSchema))
         return contentSchema;
      if (nn(responseBeanMeta))
         contentSchema = o(responseBeanMeta.getSchema());
      else {
         var rbm = opContext.getResponseBeanMeta(getContent(Object.class));
         if (nn(rbm))
            contentSchema = o(rbm.getSchema());
         else
            contentSchema = oe();
      }
      return contentSchema;
   }

   /**
    * Returns access to the inner {@link RestContext} of the class of this method.
    *
    * @return The {@link RestContext} of this class.  Never <jk>null</jk>.
    */
   public RestContext getContext() { return request.getContext(); }

   /**
    * Convenience method meant to be used when rendering directly to a browser with no buffering.
    *
    * <p>
    * Sets the header <js>"x-content-type-options=nosniff"</js> so that output is rendered immediately on IE and Chrome
    * without any buffering for content-type sniffing.
    *
    * <p>
    * This can be useful if you want to render a streaming 'console' on a web page.
    *
    * @param contentType The value to set as the <c>Content-Type</c> on the response.
    * @return The raw writer.
    * @throws IOException Thrown by underlying stream.
    */
   public PrintWriter getDirectWriter(String contentType) throws IOException {
      setContentType(contentType);
      setHeader("X-Content-Type-Options", "nosniff");
      setHeader("Content-Encoding", "identity");
      return getWriter(true, true);
   }

   /**
    * Returns the wrapped servlet response.
    *
    * @return The wrapped servlet response.
    */
   public HttpServletResponse getHttpServletResponse() { return inner; }

   /**
    * Returns the <c>Content-Type</c> header stripped of the charset attribute if present.
    *
    * @return The <c>media-type</c> portion of the <c>Content-Type</c> header.
    */
   public MediaType getMediaType() { return MediaType.of(getContentType()); }

   /**
    * Equivalent to {@link HttpServletResponse#getOutputStream()}, except wraps the output stream if an {@link Encoder}
    * was found that matched the <c>Accept-Encoding</c> header.
    *
    * @return A negotiated output stream.
    * @throws NotAcceptable If unsupported Accept-Encoding value specified.
    * @throws IOException Thrown by underlying stream.
    */
   public FinishableServletOutputStream getNegotiatedOutputStream() throws NotAcceptable, IOException {
      if (os == null) {
         Encoder encoder = null;
         var encoders = request.getOpContext().getEncoders();

         var ae = request.getHeaderParam("Accept-Encoding").orElse(null);
         if (ine(ae)) {
            var match = encoders.getEncoderMatch(ae);
            if (match == null) {
               // Identity should always match unless "identity;q=0" or "*;q=0" is specified.
               if (ENCODING_DISABLED_PATTERN.matcher(ae).find()) {
                  throw new NotAcceptable("Unsupported encoding in request header 'Accept-Encoding': '%s'\n\tSupported codings: %s", ae, Json5.of(encoders.getSupportedEncodings()));
               }
            } else {
               encoder = match.getEncoder();
               var encoding = match.getEncoding();

               // Some clients don't recognize identity as an encoding, so don't set it.
               if (neq(encoding, "identity"))
                  setHeader("content-encoding", encoding);
            }
         }
         var sos2 = getOutputStream();
         os = new FinishableServletOutputStream(encoder == null ? sos2 : encoder.getOutputStream(sos2));
      }
      return os;
   }

   /**
    * Equivalent to {@link HttpServletResponse#getWriter()}, except wraps the output stream if an {@link Encoder} was
    * found that matched the <c>Accept-Encoding</c> header and sets the <c>Content-Encoding</c>
    * header to the appropriate value.
    *
    * @return The negotiated writer.
    * @throws NotAcceptable If unsupported charset in request header Accept-Charset.
    * @throws IOException Thrown by underlying stream.
    */
   public FinishablePrintWriter getNegotiatedWriter() throws NotAcceptable, IOException { return getWriter(false, false); }

   /**
    * Returns access to the inner {@link RestOpContext} of this method.
    *
    * @return The {@link RestOpContext} of this method.  Never <jk>null</jk>.
    */
   public RestOpContext getOpContext() { return request.getOpContext(); }

   /**
    * Returns a ServletOutputStream suitable for writing binary data in the response.
    *
    * <p>
    * The servlet container does not encode the binary data.
    *
    * <p>
    * Calling <c>flush()</c> on the ServletOutputStream commits the response.
    * Either this method or <c>getWriter</c> may be called to write the content, not both, except when reset has been called.
    *
    * @return The stream.
    * @throws IOException If stream could not be accessed.
    */
   @Override
   public ServletOutputStream getOutputStream() throws IOException {
      if (sos == null)
         sos = inner.getOutputStream();
      return sos;
   }

   /**
    * Returns <jk>true</jk> if {@link #getOutputStream()} has been called.
    *
    * @return <jk>true</jk> if {@link #getOutputStream()} has been called.
    */
   public boolean getOutputStreamCalled() { return nn(sos); }

   /**
    * Returns the metadata about this response.
    *
    * @return
    *    The metadata about this response.
    *    <br>Can be <jk>null</jk> if the response method has no {@link Response @Response} metadata (or was explicitly cleared).
    */
   public ResponseBeanMeta getResponseBeanMeta() { return responseBeanMeta; }

   /**
    * Returns the matching serializer and media type for this response.
    *
    * @return The matching serializer, never <jk>null</jk>.
    */
   public Optional<SerializerMatch> getSerializerMatch() {
      if (nn(serializerMatch))
         return serializerMatch;
      if (nn(serializer)) {
         serializerMatch = o(new SerializerMatch(getMediaType(), serializer));
      } else {
         serializerMatch = opContext.getSerializers().getSerializerMatch(request.getHeaderParam("Accept").orElse("*/*"));
      }
      return serializerMatch;
   }

   /**
    * Returns the writer to the response content.
    *
    * <p>
    * This methods bypasses any specified encoders and returns a regular unbuffered writer.
    * Use the {@link #getNegotiatedWriter()} method if you want to use the matched encoder (if any).
    *
    * @return The writer.
    * @throws IOException If writer could not be accessed.
    */
   @Override
   public PrintWriter getWriter() throws IOException { return getWriter(true, false); }

   /**
    * Returns <jk>true</jk> if the response contains output.
    *
    * <p>
    * This implies {@link #setContent(Object)} has been called on this object.
    *
    * <p>
    * Note that this also returns <jk>true</jk> even if {@link #setContent(Object)} was called with a <jk>null</jk>
    * value as this means the response contains an output value of <jk>null</jk> as opposed to no value at all.
    *
    * @return <jk>true</jk> if the response contains output.
    */
   public boolean hasContent() {
      return nn(content);
   }

   /**
    * Returns <jk>true</jk> if this response object is of the specified type.
    *
    * @param c The type to check against.
    *    <br>Must not be <jk>null</jk>.
    * @return <jk>true</jk> if this response object is of the specified type.
    */
   public boolean isContentOfType(Class<?> c) {
      return c.isInstance(getRawOutput());
   }

   /**
    * Sets the output to a plain-text message regardless of the content type.
    *
    * @param text The output text to send.
    *    <br>Must not be <jk>null</jk>.
    * @return This object.
    * @throws IOException If a problem occurred trying to write to the writer.
    */
   public RestResponse sendPlainText(String text) throws IOException {
      setContentType("text/plain");
      getNegotiatedWriter().write(text);
      return this;
   }

   /**
    * Creates a fluent Server-Sent Events helper for this response.
    *
    * @return The SSE response helper.
    * @throws IOException If the writer could not be created.
    */
   public SseResponseSupport sse() throws IOException {
      return new SseResponseSupport(this);
   }

   /**
    * Redirects to the specified URI.
    *
    * <p>
    * Relative URIs are always interpreted as relative to the context root.
    * This is similar to how WAS handles redirect requests, and is different from how Tomcat handles redirect requests.
    *
    * <p>
    * This method forwards <c>uri</c> to the container as-is.  If the target is built from request input (e.g.
    * a query parameter or header value), a caller can steer users to an arbitrary external site; use
    * {@link #sendSafeRedirect(String,String...) sendSafeRedirect(String,String...)} instead in that case, which
    * validates the target is either relative or points at an allow-listed host.
    *
    * @param uri The redirection URL.
    * @throws IOException If an input or output exception occurs
    */
   @Override
   public void sendRedirect(String uri) throws IOException {
      var c = (uri.isEmpty() ? 0 : uri.charAt(0));
      if (c != '/' && uri.indexOf("://") == -1)
         uri = request.getContextPath() + '/' + uri;
      inner.sendRedirect(uri);
   }

   /**
    * Redirects to the specified URI, but only if it's a relative path (interpreted per {@link #sendRedirect(String)
    * sendRedirect(String)}) or an absolute/protocol-relative URI whose host matches one of <c>allowedHosts</c>.
    *
    * <p>
    * Intended for use when the redirect target is derived from request input rather than a fixed, trusted
    * literal, so that input can't be used to redirect a user to an arbitrary external site.
    *
    * @param uri The redirection URL.
    * @param allowedHosts The hosts (case-insensitive) an absolute or protocol-relative <c>uri</c> is allowed to target.  Ignored for relative URIs.
    * @throws IOException If an input or output exception occurs.
    * @throws BadRequest If <c>uri</c> is absolute or protocol-relative and its host isn't in <c>allowedHosts</c>.
    */
   public void sendSafeRedirect(String uri, String...allowedHosts) throws IOException {
      if (! isSafeRedirectUri(uri, allowedHosts))
         throw new BadRequest("Redirect target '%s' is not a relative path or an allowed host.", uri);
      sendRedirect(uri);
   }

   /**
    * Returns <jk>true</jk> if <c>uri</c> is safe to pass to {@link #sendRedirect(String) sendRedirect(String)}
    * without risk of redirecting to an unintended external site: either a relative path, or an absolute/
    * protocol-relative URI whose host is in <c>allowedHosts</c>.
    *
    * @param uri The candidate redirection URL.
    * @param allowedHosts The hosts (case-insensitive) an absolute or protocol-relative <c>uri</c> is allowed to target.
    * @return <jk>true</jk> if the URI is safe to redirect to.
    */
   static boolean isSafeRedirectUri(String uri, String...allowedHosts) {
      if (ie(uri))
         return true;
      if (uri.charAt(0) == '/' && ! uri.startsWith("//"))
         return true;
      if (uri.indexOf("://") == -1 && ! uri.startsWith("//"))
         return true;
      String host;
      try {
         host = new java.net.URI(uri.startsWith("//") ? "http:" + uri : uri).getHost();
      } catch (java.net.URISyntaxException e) {
         return false;
      }
      if (host == null || allowedHosts == null)
         return false;
      for (var h : allowedHosts)
         if (eqic(host, h))
            return true;
      return false;
   }

   /**
    * Shortcut for calling <c>getRequest().setAttribute(String,Object)</c>.
    *
    * @param name The property name.
    * @param value The property value.
    * @return This object.
    */
   public RestResponse setAttribute(String name, Object value) {
      request.setAttribute(name, value);
      return this;
   }

   /**
    * Sets the HTTP output on the response.
    *
    * <p>
    * The object type can be anything allowed by the registered response handlers.
    *
    * <p>
    * Calling this method is functionally equivalent to returning the object in the REST Java method.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>(<js>"/example2/{personId}"</js>)
    *    <jk>public void</jk> doGet(RestResponse <jv>res</jv>, <ja>@Path</ja> UUID <jv>personId</jv>) {
    *       Person <jv>person</jv> = getPersonById(<jv>personId</jv>);
    *       <jv>res</jv>.setContent(<jv>person</jv>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Calling this method with a <jk>null</jk> value is NOT the same as not calling this method at all.
    *       <br>A <jk>null</jk> output value means we want to serialize <jk>null</jk> as a response (e.g. as a JSON <c>null</c>).
    *       <br>Not calling this method or returning a value means you're handing the response yourself via the underlying stream or writer.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='ja'>{@link Rest#responseProcessors()}
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpAnnotatedMethods">@RestOp-Annotated Method</a>
    * </ul>
    *
    * @param output The output to serialize to the connection.
    * @return This object.
    */
   public RestResponse setContent(Object output) {
      this.content = o(output);
      return this;
   }

   /**
    * Specifies the schema for the response content.
    *
    * <p>
    * Used by schema-aware serializers such as {@link OpenApiSerializer}.  Ignored by other serializers.
    *
    * @param schema The content schema
    *    <br>Can be <jk>null</jk> (clears any previously-set schema).
    * @return This object.
    */
   public RestResponse setContentSchema(HttpPartSchema schema) {
      this.contentSchema = o(schema);
      return this;
   }

   /**
    * Forces the {@link Serializer} used to serialize the response body set via {@link #setContent(Object)} (or an
    * equivalent return from the REST method), instead of choosing one from the <c>Accept</c> header.
    *
    * <p>
    * {@link org.apache.juneau.rest.server.processor.SerializedPojoProcessor} uses {@link #getSerializerMatch()}, which
    * returns a {@link SerializerMatch} built from this serializer when non-<jk>null</jk>.
    *
    * <p>
    * <c>Content-Type</c> is still applied by the response processor: it prefers {@link #getMediaType()} if set, then
    * the match media type, then {@link Serializer#getResponseContentType()}. Call {@link #setContentType(String)} (or
    * another header setter) if you need a specific type before serialization runs.
    *
    * @param value The serializer to use. Can be <jk>null</jk> to clear the override and use normal <c>Accept</c>
    *    negotiation on the next {@link #getSerializerMatch()} call.
    * @return This object.
    */
   public RestResponse setSerializer(Serializer value) {
      serializer = value;
      serializerMatch = null;
      return this;
   }

   /**
    * Returns the captured (bounded) response body bytes for debug logging.
    *
    * <p>
    * Populated by the two-phase debug pipeline only when the resolved logger is loggable at
    * {@link java.util.logging.Level#FINEST FINEST}; otherwise returns <jk>null</jk>. The captured copy is capped at the
    * formatter's body cap (default 8&nbsp;KB); use {@link #getCachedContentLength()} for the full byte count.
    *
    * @return The captured response body bytes, or <jk>null</jk> if body caching was not installed.
    */
   public byte[] getCachedContent() {
      return inner instanceof CachingHttpServletResponse c ? c.getContent() : null;
   }

   /**
    * Returns the total number of response body bytes written, including any beyond the capture cap.
    *
    * @return The total response body length in bytes, or {@code -1} if body caching was not installed.
    */
   public long getCachedContentLength() {
      return inner instanceof CachingHttpServletResponse c ? c.getTotalLength() : -1;
   }

   /**
    * Sets the <js>"Exception"</js> attribute to the specified throwable.
    *
    * <p>
    * This exception is surfaced by the debug pipeline as the {@code thrown} of the emitted log record.
    *
    * @param t The attribute value.
    * @return This object.
    */
   public RestResponse setException(Throwable t) {
      request.setException(t);
      return this;
   }

   /**
    * Sets a response header.
    *
    * <p>
    * Any previous header values are removed.
    *
    * <p>
    * Value is added at the end of the headers.
    *
    * @param header The header.
    *    <br>Can be <jk>null</jk> (ignored).
    * @return This object.
    */
   public RestResponse setHeader(HttpHeader header) {
      if (header == null) {
         // Do nothing.
      } else if (header instanceof HttpUriHeader header2) {
         setHeader(header2.getName(), resolveUris(header2.getValue()));
      } else {
         var v = header.getValue();
         if (nn(v) && v.indexOf("://") != -1)
            v = resolveUris(v);
         setHeader(header.getName(), v);
      }
      return this;
   }

   /**
    * Sets <l>Content-Disposition</l> to <js>attachment</js> so browsers typically download the body, using the given
    * suggested file name (quoted {@code filename} parameter).
    *
    * <p>
    * Shorthand for {@link #setHeader(HttpHeader) setHeader}({@link ContentDisposition#attachment(String)
    * ContentDisposition.attachment(filename)}).
    * </p>
    *
    * <h5 class='figure'>Example</h5>
    * <p class='bjava'>
    *    <jv>res</jv>.downloadAs(<js>"example.pdf"</js>).setContent(<jv>pdfBytes</jv>);
    * </p>
    *
    * @param filename Suggested download name. Must not be <jk>null</jk>, blank, or contain CR/LF.
    * @return This object.
    * @throws IllegalArgumentException If {@code filename} is invalid.
    * @see ContentDisposition#attachment(String)
    */
   public RestResponse downloadAs(String filename) {
      return setHeader(ContentDisposition.attachment(filename));
   }

   /**
    * Sets the <c>ETag</c> response header to the supplied wire value.
    *
    * <p>
    * The value is validated through {@link EntityTag#of(Object)} — strong tags must be quoted
    * (<c>"v1"</c>), weak tags must be prefixed with <c>W/</c> (<c>W/"v1"</c>), and the wildcard
    * <c>*</c> is accepted. The header is serialized in canonical form (re-quoted for strong tags,
    * <c>W/</c>-prefixed for weak tags).
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jv>res</jv>.eTag(<js>"\"v42\""</js>);  <jc>// ETag: "v42"</jc>
    *    <jv>res</jv>.eTag(<js>"W/\"v42\""</js>);  <jc>// ETag: W/"v42"</jc>
    * </p>
    *
    * @param value The entity-tag wire value. Must not be <jk>null</jk>; must match the
    *    {@code entity-tag} grammar per RFC 7232 §2.3.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is malformed.
    * @see RestRequest#checkPreconditions(RestResponse)
    */
   public RestResponse eTag(String value) {
      return eTag(EntityTag.of(value));
   }

   /**
    * Sets the <c>ETag</c> response header to the canonical wire form of the supplied {@link EntityTag}.
    *
    * @param value The entity tag. Must not be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
    */
   public RestResponse eTag(EntityTag value) {
      reqnn("value", value);
      return setHeader(ETag.of(value.toString()));
   }

   /**
    * Sets the <c>Last-Modified</c> response header to the supplied instant formatted as an
    * <a class='doclink' href='https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1'>RFC 7231 IMF-fixdate</a>.
    *
    * <p>
    * The instant is rendered in GMT regardless of the JVM's default timezone. The fractional-second
    * portion is truncated, matching the per-spec one-second resolution of HTTP-date timestamps.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jv>res</jv>.lastModified(Instant.<jsm>parse</jsm>(<js>"2026-05-22T00:00:00Z"</js>));
    *    <jc>// Last-Modified: Fri, 22 May 2026 00:00:00 GMT</jc>
    * </p>
    *
    * @param value The last-modified timestamp. Must not be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
    * @see RestRequest#checkPreconditions(RestResponse)
    */
   public RestResponse lastModified(Instant value) {
      reqnn("value", value);
      return lastModified(value.atZone(ZoneOffset.UTC));
   }

   /**
    * Sets the <c>Last-Modified</c> response header to the supplied date-time formatted as an
    * <a class='doclink' href='https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1'>RFC 7231 IMF-fixdate</a>.
    *
    * <p>
    * The supplied date-time is converted to GMT and truncated to whole seconds before formatting.
    *
    * @param value The last-modified timestamp. Must not be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
    */
   public RestResponse lastModified(ZonedDateTime value) {
      reqnn("value", value);
      var z = value.withZoneSameInstant(ZoneOffset.UTC).truncatedTo(SECONDS);
      return setHeader(LastModified.of(RFC_1123_DATE_TIME.format(z)));
   }

   /**
    * Sets the <c>Cache-Control</c> response header to the supplied directive string.
    *
    * <p>
    * The value is written verbatim — the caller is responsible for supplying a comma-separated
    * directive list per <a class='doclink' href='https://www.rfc-editor.org/rfc/rfc9111#name-cache-control'>RFC
    * 9111 §5.2</a>.
    *
    * @param value The directive list (e.g. <js>"public, max-age=3600"</js>). Must not be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
    * @see #cacheControl(CacheControl.Builder)
    */
   public RestResponse cacheControl(String value) {
      reqnn("value", value);
      return setHeader(CacheControl.of(value));
   }

   /**
    * Sets the <c>Cache-Control</c> response header from a {@link org.apache.juneau.http.header.CacheControl.Builder CacheControl.Builder}.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jv>res</jv>.cacheControl(CacheControl.<jsm>create</jsm>().publicCache().maxAge(3600));
    *    <jc>// Cache-Control: public, max-age=3600</jc>
    * </p>
    *
    * @param value The builder. Must not be <jk>null</jk>.
    * @return This object.
    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
    */
   public RestResponse cacheControl(CacheControl.Builder value) {
      reqnn("value", value);
      return cacheControl(value.build());
   }

   /**
    * Sets a header on the request.
    *
    * @param schema
    *    The schema to use to serialize the header, or <jk>null</jk> to use the default schema.
    * @param name The header name.
    * @param value The header value.
    *    <ul>
    *       <li>Can be any POJO.
    *       <li>Converted to a string using the specified part serializer.
    *    </ul>
    * @return This object.
    * @throws SchemaValidationException Header failed schema validation.
    * @throws SerializeException Header could not be serialized.
    */
   public RestResponse setHeader(HttpPartSchema schema, String name, Object value) throws SchemaValidationException, SerializeException {
      setHeader(name, request.getPartSerializerSession().write(HEADER, schema, value));
      return this;
   }

   /**
    * Sets a header on the request.
    *
    * @param name The header name.
    * @param value The header value.
    *    <ul>
    *       <li>Can be any POJO.
    *       <li>Converted to a string using the specified part serializer.
    *    </ul>
    * @return This object.
    * @throws SchemaValidationException Header failed schema validation.
    * @throws SerializeException Header could not be serialized.
    */
   public RestResponse setHeader(String name, Object value) throws SchemaValidationException, SerializeException {
      setHeader(name, request.getPartSerializerSession().write(HEADER, null, value));
      return this;
   }

   /**
    * Sets a response header with the given name and value.
    *
    * <p>
    * If the header had already been set, the new value overwrites the previous one.
    *
    * <p>
    * The {@link #containsHeader(String)} method can be used to test for the presence of a header before setting its value.
    *
    * @param name The header name.
    * @param value The header value.
    */
   @Override
   public void setHeader(String name, String value) {

      // Jetty doesn't set the content type correctly if set through this method.
      // Tomcat/WAS does.
      if (eqic(name, HEADER_ContentType)) {
         inner.setContentType(value);
         ContentType ct = ContentType.of(value);
         if (nn(ct) && nn(ct.getParameter("charset")))
            inner.setCharacterEncoding(ct.getParameter("charset"));
      } else {
         if (safeHeaders)
            value = stripInvalidHttpHeaderChars(value);
         value = abbreviate(value, maxHeaderLength);
         inner.setHeader(name, value);
      }
   }

   /**
    * Specifies the maximum length for header values.
    *
    * <p>
    * Header values that exceed this length will get truncated.
    *
    * @param value The new value for this setting.  The default is <c>8096</c>.
    * @return This object.
    */
   public RestResponse setMaxHeaderLength(int value) {
      maxHeaderLength = value;
      return this;
   }

   /**
    * Shortcut for calling <c>setNoTrace(<jk>true</jk>)</c>.
    *
    * @return This object.
    */
   public RestResponse setNoTrace() {
      return setNoTrace(true);
   }

   /**
    * Sets the <js>"NoTrace"</js> attribute to the specified boolean.
    *
    * <p>
    * This flag tells the framework not to trace the current request: the access-log record for the call is still
    * emitted, but without the exception's stack trace.  A <c>No-Trace: true</c> request header has the same effect; when both are present, the attribute wins.
    *
    * @param b The attribute value.
    * @return This object.
    */
   public RestResponse setNoTrace(Boolean b) {
      request.setNoTrace(b);
      return this;
   }

   /**
    * Sets metadata about this response.
    *
    * @param rbm The metadata about this response.
    *    <br>Can be <jk>null</jk> (clears the metadata).
    * @return This object.
    */
   public RestResponse setResponseBeanMeta(ResponseBeanMeta rbm) {
      this.responseBeanMeta = rbm;
      return this;
   }

   /**
    * Enables safe-header mode.
    *
    * <p>
    * When enabled (the default), invalid characters such as CTRL characters (including a raw CR or LF that
    * could otherwise be used to inject an additional header or split the response) are stripped from header
    * values via {@link org.apache.juneau.commons.utils.StringUtils#stripInvalidHttpHeaderChars(String)
    * StringUtils.stripInvalidHttpHeaderChars(String)} before they get set. This is a no-op call retained for
    * apps that called it explicitly before this became the default; see {@link #setUnsafeHeaders()} to opt
    * back out.
    *
    * @return This object.
    */
   public RestResponse setSafeHeaders() {
      this.safeHeaders = true;
      return this;
   }

   /**
    * Disables safe-header mode, restoring the pre-hardening behavior of passing header values through to the
    * underlying {@link HttpServletResponse} verbatim (aside from the usual {@link #setMaxHeaderLength(int)}
    * truncation).
    *
    * <p>
    * Only call this for a header value the application has already validated itself; most servlet containers
    * reject a raw CR/LF in a header value outright regardless of this setting, but other control characters may
    * still pass through once safe-header mode is off.
    *
    * @return This object.
    */
   public RestResponse setUnsafeHeaders() {
      this.safeHeaders = false;
      return this;
   }

   private Object getRawOutput() { return content == null ? null : content.orElse(null); }

   private FinishablePrintWriter getWriter(boolean raw, boolean autoflush) throws NotAcceptable, IOException {
      if (nn(w))
         return w;

      // If plain text requested, override it now.
      if (request.isPlainText())
         setHeader(HEADER_ContentType, "text/plain");

      try {
         OutputStream out = (raw ? getOutputStream() : getNegotiatedOutputStream());
         w = new FinishablePrintWriter(out, getCharacterEncoding(), autoflush);
         return w;
      } catch (@SuppressWarnings("unused") UnsupportedEncodingException e) {
         var ce = getCharacterEncoding();
         setCharacterEncoding("UTF-8");
         throw new NotAcceptable("Unsupported charset in request header 'Accept-Charset': '%s'", ce);
      }
   }

   private String resolveUris(Object value) {
      var s = s(value);
      return request.getUriResolver().resolve(s);
   }

   private String maybeResolveUris(String name, Object value) {
      return isUriBearingHeader(name) ? resolveUris(value) : s(value);
   }

   /**
    * If a (Content-Security-Policy) header value contains a nonce placeholder, mints a single per-response nonce
    * (cached as a request attribute so the serializer stamps the SAME value onto inline {@code <script>}/{@code <style>}
    * tags) and substitutes it into the value.  Returns the value unchanged when no placeholder is present, so this is
    * a no-op for every non-CSP header and for CSP headers that don't use a nonce.
    *
    * @param value The already-URI-resolved header value. May be <jk>null</jk>.
    * @return The header value with any nonce placeholder resolved.
    */
   private String resolveCspNonce(String value) {
      if (value == null || ! value.contains(ContentSecurityPolicy.Builder.NONCE_PLACEHOLDER))
         return value;
      var nonce = request.getAttribute(RestRequest.CSP_NONCE_ATTR).as(String.class).orElse(null);
      if (nonce == null) {
         nonce = ContentSecurityPolicy.Builder.generateNonce();
         request.setAttribute(RestRequest.CSP_NONCE_ATTR, nonce);
      }
      return ContentSecurityPolicy.Builder.resolveNonce(value, nonce);
   }

   private static boolean isUriBearingHeader(String name) {
      if (name == null)
         return false;
      return eqic(name, "Location")
         || eqic(name, "Content-Location")
         || eqic(name, "Referer");
   }
}