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

import static org.apache.juneau.commons.utils.Shorts.*;

import java.io.*;

import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.http.response.*;
import org.apache.juneau.rest.server.*;
import org.apache.juneau.rest.server.processor.*;
import org.apache.juneau.rest.server.view.*;

import freemarker.template.*;

/**
 * {@link ResponseProcessor} that detects {@link FreemarkerView}-typed return values and asks the
 * configured {@link freemarker.template.Configuration} to render them directly onto the response writer.
 *
 * <p>
 * Auto-registered by {@link FreemarkerMixin} via
 * {@link Rest#responseProcessors() @Rest(responseProcessors=...)}
 * &mdash; callers who add the mixin don't need to wire up this class explicitly. Callers who want
 * to handle {@code FreemarkerView} returns <i>without</i> adopting the mixin can add this class
 * to their own
 * {@link Rest#responseProcessors() responseProcessors} list.
 *
 * <h5 class='section'>Behavior:</h5>
 *
 * <ol class='spaced-list'>
 *    <li>Inspect the response content. If the value is not a {@link FreemarkerView}, return
 *       {@link ResponseProcessor#NEXT NEXT} so the rest of the chain runs.
 *    <li>Read the active {@link FreemarkerMixin} from the {@code RestContext} bean store
 *       to discover the {@link freemarker.template.Configuration} (lazy default if no configuration bean is
 *       registered) and the optional template-suffix knob.
 *    <li>Apply every entry from {@link FreemarkerView#getResponseHeaders()} via
 *       {@link jakarta.servlet.http.HttpServletResponse#setHeader(String, String)
 *       res.setHeader(...)}.
 *    <li>Default {@code Content-Type} to {@code text/html;charset=UTF-8} if the caller did not set
 *       one explicitly. FreeMarker's bridge-default {@code Configuration} uses
 *       {@code HTMLOutputFormat} so HTML is the natural target; an explicit caller header wins.
 *    <li>Call {@code configuration.getTemplate(templateName).process(view.getAttributes(),
 *       res.getWriter())} to stream the rendered output.
 *    <li>When no FreeMarker engine is on the classpath, the {@link freemarker.template.Configuration}-typed import
 *       here fails to load at first use and surfaces {@link #NO_ENGINE_DIAGNOSTIC} naming the
 *       missing dependency.
 * </ol>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='jc'>{@link FreemarkerMixin}
 *    <li class='jc'>{@link FreemarkerView}
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ResponseProcessors">Response Processors</a>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/FreemarkerViewSupport">FreeMarker View Support</a>
 * </ul>
 *
 * @since 10.0.0
 */
@SuppressWarnings({
   "resource" // Closeables here are framework-managed and not owned/closed by this class; not a real leak.
})
public class FreemarkerViewRenderer implements ViewRenderer {

   /** Default {@code Content-Type} applied when the view does not specify one explicitly. */
   public static final String DEFAULT_CONTENT_TYPE = "text/html;charset=UTF-8";

   /**
    * Diagnostic message emitted when no FreeMarker engine can be found on the classpath at
    * render-time.
    *
    * <p>
    * Public so tests and consumer apps can pattern-match against the message text without
    * depending on internal string literals.
    */
   public static final String NO_ENGINE_DIAGNOSTIC = """
      No Apache FreeMarker engine is available on the classpath. Add:
        - org.freemarker:freemarker                       (FreeMarker engine core)
      Or, for Spring Boot:
        - org.springframework.boot:spring-boot-starter-freemarker
          (autoconfigures a freemarker.template.Configuration bean the bridge picks up).
      Or register a custom @Bean freemarker.template.Configuration with whatever loaders /
      encodings / output formats you need.
      See https://juneau.apache.org/docs/topics/FreemarkerViewSupport for the full matrix.""";

   // Lazily-created fallback used when no FreemarkerMixin bean is registered.  Cached (double-checked) so
   // the bridge-default Configuration and its template cache are built once instead of rebuilt per render.
   // Created lazily (not eagerly) so a missing FreeMarker engine still surfaces at render time as
   // NO_ENGINE_DIAGNOSTIC rather than during RestContext construction.
   @SuppressWarnings({
      "java:S3077" // volatile is required here for correct double-checked-locking safe-publication of the lazily-built fallback FreemarkerMixin in fallbackMixin(); the reference is publish-once (fully constructed before assignment, immutable thereafter) and never compound-mutated.
   })
   private volatile FreemarkerMixin fallbackMixin;

   @Override /* Overridden from ResponseProcessor */
   public int process(RestOpSession opSession) throws IOException, BasicHttpException {
      var req = opSession.getRequest();
      var res = opSession.getResponse();

      var content = res.getContent(Object.class);
      if (! (content instanceof FreemarkerView content2))
         return NEXT;

      // Resolve the bridge resource (carries Configuration + cached default + templateSuffix).
      // Fall back to a cached FreemarkerMixin when the renderer is used standalone
      // without the mixin.
      var bridge = findMixin(req.getContext().getBeanStore());

      // Apply caller-supplied response headers first so a caller-provided Content-Type wins
      // over the bridge's default below.
      content2.getResponseHeaders().forEach(res::setHeader);
      if (! res.containsHeader("Content-Type"))
         res.setHeader("Content-Type", DEFAULT_CONTENT_TYPE);

      // Apply the same traversal gate the raw /freemarker/* mount uses so a typed-View template name
      // assembled from user input (e.g. FreemarkerView.of(userInput)) cannot escape the configured base
      // path via '../' segments.  Mirrors the JSP bridge's typed-View gate.
      String safeName;
      try {
         safeName = gateTemplateName(bridge.getBasePath(), content2.getTemplateName());
      } catch (IllegalArgumentException ex) {
         throw new InternalServerError(ex, "FreeMarker template name escapes configured base path: '%s'", content2.getTemplateName());
      }

      var templateName = bridge.applyTemplateSuffix(safeName);
      try {
         var cfg = bridge.resolveConfiguration(req);
         var template = cfg.getTemplate(templateName);
         // Expose the in-flight request to FreeMarker TemplateDirectiveModels (e.g. <@page toolkit=...>)
         // for the duration of the render; always cleared so open() never leaks on the thread.
         try {
            FreemarkerRenderScope.open(req);
            if (hasMustConsume(content2)) {
               // Buffer first, so a failed adoption check can never follow output that is already committed.
               var buffer = new StringWriter();
               template.process(content2.getAttributes(), buffer);
               checkConsumed(content2, templateName);
               res.getWriter().write(buffer.toString());
            } else {
               template.process(content2.getAttributes(), res.getWriter());
            }
            res.getWriter().flush();
            return FINISHED;
         } finally {
            FreemarkerRenderScope.close();
         }
      } catch (LinkageError ex) {
         throw new InternalServerError(ex, NO_ENGINE_DIAGNOSTIC);
      } catch (IOException ex) {
         throw ex;
      } catch (TemplateException | RuntimeException ex) {
         // Surface the deepest cause's message in the response body.  FreeMarker's DEBUG exception handler only
         // writes a diagnostic to the *output writer* it was rendering into; a directive that throws while a
         // parent directive (e.g. <@page>) is capturing its body into a throwaway buffer therefore leaves no
         // trace in the response.  Appending the root-cause message makes the diagnostic deterministic
         // regardless of which buffer FreeMarker happened to be writing to.
         throw new InternalServerError(ex, "FreeMarker render failed for '%s': %s", templateName, rootMessage(ex));
      }
   }

   private static boolean hasMustConsume(FreemarkerView view) {
      for (var v : view.getAttributes().values())
         if (v instanceof FreemarkerView.MustConsume)
            return true;
      return false;
   }

   // A MustConsume attribute that was never adopted means the template never reached the directive meant to consume
   // it, which would otherwise drop the attribute silently.  The message is carried as the deepest cause so it
   // reaches the response body undecorated, as rootMessage() unwraps it.
   private static void checkConsumed(FreemarkerView view, String templateName) throws TemplateModelException {
      for (var v : view.getAttributes().values()) {
         if (v instanceof FreemarkerView.MustConsume mc && ! mc.consumed()) {
            var msg = mc.notConsumedMessage(templateName);
            throw new TemplateModelException(msg, new IllegalArgumentException(msg));
         }
      }
   }

   // Walks to the deepest cause and returns its message (falling back to the simple class name when the message
   // is null), so a nested-directive diagnostic reaches the HTTP response body even when FreeMarker's exception
   // handler wrote it into a discarded capture buffer.
   static String rootMessage(Throwable t) {
      var c = t;
      while (c.getCause() != null && c.getCause() != c)
         c = c.getCause();
      var m = c.getMessage();
      return m == null ? c.getClass().getSimpleName() : m;
   }

   // Rejects '../'-style traversal in a typed-View template name using the same virtual-path gate the raw
   // mount applies, returning the configuration-relative template name.  Delegates to the shared
   // FileUtils.resolveVirtualPathSafely + FreemarkerDispatcher.stripBasePath used by the raw render path.
   static String gateTemplateName(String basePath, String templateName) {
      var resolved = FileUtils.resolveVirtualPathSafely(basePath, templateName);
      return FreemarkerDispatcher.stripBasePath(basePath, resolved);
   }

   // The exact FreemarkerMixin bean, else a bean of any registered subtype; two different beans fail loud.
   private FreemarkerMixin findMixin(WritableBeanStore store) {
      FreemarkerMixin found = store.getBean(FreemarkerMixin.class).orElse(null);
      for (var t : FreemarkerMixin.registeredSubtypes()) {
         var b = store.getBean(t).orElse(null);
         if (b == null || b == found)
            continue;
         if (found != null)
            throw new IllegalStateException(f(
               "Found more than one FreemarkerMixin bean ('%s' and '%s'); declare exactly one.",
               found.getClass().getSimpleName(), b.getClass().getSimpleName()));
         found = b;
      }
      return found != null ? found : fallbackMixin();
   }

   // Returns the cached fallback mixin, creating it once (double-checked) on first standalone render.
   private FreemarkerMixin fallbackMixin() {
      var local = fallbackMixin;
      if (local == null) {
         synchronized (this) {
            local = fallbackMixin;
            if (local == null) {
               local = new FreemarkerMixin();
               fallbackMixin = local;
            }
         }
      }
      return local;
   }
}