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

import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;

import java.io.*;
import java.nio.file.*;
import java.time.*;
import java.util.*;
import java.util.stream.*;

import org.apache.juneau.bean.*;
import org.apache.juneau.commons.*;
import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.config.*;
import org.apache.juneau.http.*;
import org.apache.juneau.http.Path;
import org.apache.juneau.http.classic.response.*;
import org.apache.juneau.marshall.html.*;
import org.apache.juneau.rest.server.*;
import org.apache.juneau.rest.server.beans.*;
import org.apache.juneau.rest.server.servlet.*;

/**
 * REST resource that allows access to a file system directory.
 *
 * <p>
 * The root directory is specified in one of two ways:
 * <ul class='spaced-list'>
 *    <li>
 *       Specifying the location via a <l>DirectoryResource.rootDir</l> property.
 *    <li>
 *       Overriding the {@link #getRootDir()} method.
 * </ul>
 *
 * <p>
 * Files are listed with <l>view</l> and <l>download</l> links, which reach the {@code VIEW} and {@code DOWNLOAD}
 * operations through {@code ?method=}.  Both are declared {@link RestOp#read() read=true}.  Deleting a file needs a real
 * {@code DELETE}, for example:
 * <p class='bcode'>
 *    curl -X DELETE http://localhost:10000/&lt;mount-path&gt;/foo.txt
 * </p>
 *
 * <p>
 * Read/write access control is handled through the following properties:
 * <ul class='spaced-list'>
 *    <li>
 *       <l>DirectoryResource.allowViews</l> - If <jk>true</jk>, allows view and download access to files.
 *    <li>
 *       <l>DirectoryResource.allowUploads</l> - If <jk>true</jk>, allows files to be created or overwritten.
 *    <li>
 *       <l>DirectoryResource.allowDeletes</l> - If <jk>true</jk>, allows files to be deleted.
 * </ul>
 *
 * <p>
 * <b>Note:</b> the {@code method} query parameter is accepted only for {@code HEAD}, {@code OPTIONS} and the two read
 * verbs {@code VIEW} and {@code DOWNLOAD}, so a link can view or download a file but never change one.  A subclass that
 * widens {@code allowedMethodParams} still can't turn a {@code GET} into a write: the router refuses any override of a
 * {@code GET} to a method that is not a read.  Uploads and deletes still change files, so put the resource behind a
 * CSRF boundary before mounting it anywhere a browser can reach.  A boundary judges a {@code ?method=VIEW} or
 * {@code ?method=DOWNLOAD} link as a write and refuses it, so behind one the listing's links stop working; send real
 * {@code VIEW} or {@code DOWNLOAD} requests instead.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauMicroservice">juneau-microservice</a>
 * </ul>
 *
 * @serial exclude
 */
@Rest(
   title="File System Explorer",
   messages="nls/DirectoryResource",
   allowedMethodParams="HEAD,OPTIONS,VIEW,DOWNLOAD"
)
@HtmlDocConfig(
   navlinks={
      "up: request:/..",
      "api: servlet:/api"
   }
)
@HtmlConfig(uriAnchorText="PROPERTY_NAME")
@SuppressWarnings({
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., DIRECTORY_RESOURCE_rootDir)
   "resource" // Streams returned to servlet container; lifecycle managed by the container
})
public class DirectoryResource extends BasicRestServlet {

   /** File action link. */
   @Response
   @Schema(description = "File action")
   public static class Action extends LinkString {

      /**
       * Constructor.
       *
       * @param name Action name.
       * @param uri Action URI.
       * @param uriArgs URI format arguments.
       */
      public Action(String name, String uri, Object...uriArgs) {
         super(name, uri, uriArgs);
      }

      /** {@inheritDoc} */
      @Override /* Overridden from LinkString */
      public Action setName(String value) {
         super.setName(value);
         return this;
      }

      /** {@inheritDoc} */
      @Override /* Overridden from LinkString */
      public Action setUri(java.net.URI value) {
         super.setUri(value);
         return this;
      }

      /** {@inheritDoc} */
      @Override /* Overridden from LinkString */
      public Action setUri(String value) {
         super.setUri(value);
         return this;
      }

      /** {@inheritDoc} */
      @Override /* Overridden from LinkString */
      public Action setUri(String value, Object...args) {
         super.setUri(value, args);
         return this;
      }
   }

   /** File or directory details for REST response. */
   @Response
   @Schema(description = "File or directory details")
   @BeanType(properties = "type,name,size,lastModified,actions,files")
   public class FileResource {
      private final File f;
      private final String path;
      private final String uri;
      private final boolean includeChildren;

      /**
       * Constructor.
       *
       * @param f The file or directory.
       * @param path The path.
       * @param includeChildren Whether to include child files.
       */
      public FileResource(File f, String path, boolean includeChildren) {
         this.f = f;
         this.path = path;
         this.uri = "servlet:/" + (path == null ? "" : path);
         this.includeChildren = includeChildren;
      }

      /**
       * Returns available actions for this file (view, download).
       *
       * @return The list of actions.
       */
      @Html(format = HtmlFormat.HTML_CDC)
      public List<Action> getActions() {
         List<Action> l = list();
         if (allowViews && f.canRead() && ! f.isDirectory()) {
            l.add(new Action("view", uri + "?method=VIEW"));
            l.add(new Action("download", uri + "?method=DOWNLOAD"));
         }
         return l;
      }

      /**
       * Returns child files when this is a directory and includeChildren is <jk>true</jk>.
       *
       * @return Child files, or <jk>null</jk> when this is a file or includeChildren is false.
       */
      @SuppressWarnings({
         "java:S1168"     // Intentional null when file or !includeChildren.
      })
      public Set<FileResource> getFiles() {
         if (f.isFile() || ! includeChildren)
            return null;
         return Arrays.stream(f.listFiles())
            .map(fc -> new FileResource(fc, (nn(path) ? (path + '/') : "") + urlEncode(fc.getName()), false))
            .collect(Collectors.toCollection(() -> new TreeSet<>(new FileResourceComparator())));
      }

      /**
       * Returns the last modified date of the file.
       *
       * @return The last modified date as an {@link Instant}.
       */
      public Instant getLastModified() { return Instant.ofEpochMilli(f.lastModified()); }

      /**
       * Returns the file name as a link.
       *
       * @return The name as a link.
       */
      public LinkString getName() { return new LinkString(f.getName(), uri); }

      /**
       * Returns the file size, or number of items for directories.
       *
       * @return The size.
       */
      public long getSize() { return f.isDirectory() ? f.listFiles().length : f.length(); }

      /**
       * Returns the type: "dir" or "file".
       *
       * @return The type.
       */
      public String getType() { return (f.isDirectory() ? "dir" : "file"); }
   }

   @Response
   @Schema(type = "string", format = "binary", description = "Contents of file")
   static class FileContents extends FileInputStream {

      /**
       * Constructor.
       *
       * @param file The file to read.
       * @throws FileNotFoundException If the file is not found.
       */
      public FileContents(File file) throws FileNotFoundException {
         super(file);
      }
   }

   /** Comparator for sorting file resources (directories before files, then by name). */
   static class FileResourceComparator implements Comparator<FileResource>, Serializable {
      private static final long serialVersionUID = 1L;

      /** {@inheritDoc} */
      @Override /* Overridden from Comparator */
      public int compare(FileResource o1, FileResource o2) {
         int c = o1.getType().compareTo(o2.getType());
         return c != 0 ? c : o1.getName().compareTo(o2.getName());
      }
   }

   @Response
   @Schema(description = "Redirect to root page on success")
   static class RedirectToRoot extends SeeOtherRoot {}

   private static final long serialVersionUID = 1L;
   private final File rootDir;     // The root directory

   // Properties enabled through servlet init parameters
   final boolean allowDeletes;
   final boolean allowUploads;
   final boolean allowViews;

   /**
    * Constructor.
    *
    * @param c The microservice configuration.
    */
   public DirectoryResource(Config c) {
      rootDir = new File(c.get("DirectoryResource.rootDir.s").orElse("."));
      allowViews = c.get("DirectoryResource.allowViews.b").asBoolean().orElse(false);
      allowDeletes = c.get("DirectoryResource.allowDeletes.b").asBoolean().orElse(false);
      allowUploads = c.get("DirectoryResource.allowUploads.b").asBoolean().orElse(false);
   }
   /**
    * Deletes a file on the file system.
    *
    * @param path The file path.
    * @return Redirect to root on success.
    * @throws MethodNotAllowed If deletes are not enabled.
    */
   @RestDelete(
      path="/*",
      summary="Delete file",
      description="Delete a file on the file system."
   )
   public RedirectToRoot deleteFile(@Path("/*") String path) throws MethodNotAllowed {
      deleteFile(getFile(path));
      return new RedirectToRoot();
   }

   /**
    * Downloads the contents of a file.
    *
    * @param res The response.
    * @param path The file path.
    * @return The file contents stream.
    * @throws NotFound If the file is not found.
    * @throws MethodNotAllowed If views are not enabled.
    */
   @RestOp(
      method="DOWNLOAD",
      path="/*",
      read=true,
      summary="Download file",
      description="Download the contents of a file.\nContent-Type is set to 'application/octet-stream'."
   )
   public FileContents downloadFile(RestResponse res, @Path("/*") String path) throws NotFound, MethodNotAllowed {
      if (! allowViews)
         throw new MethodNotAllowed("DOWNLOAD not enabled");

      res.setContentType("application/octet-stream");
      try {
         return new FileContents(getFile(path));
      } catch (@SuppressWarnings("unused") FileNotFoundException e) {
         throw new NotFound("File not found");
      }
   }

   /**
    * Returns information about the specified file or directory.
    *
    * @param req The request.
    * @param path The file path.
    * @return The file or directory details.
    * @throws NotFound If the file is not found.
    * @throws Exception If an error occurs.
    */
   @RestGet(
      path="/*",
      summary="View information on file or directory",
      description="Returns information about the specified file or directory."
   )
   @HtmlDocConfig(
      nav={"<h5>Folder:  $RA{fullPath}</h5>"}
   )
   @SuppressWarnings({
      "java:S112" // throws Exception intentional - callback/lifecycle method
   })
   public FileResource getFile(RestRequest req, @Path("/*") String path) throws NotFound, Exception {

      var dir = getFile(path);
      req.setAttribute("fullPath", dir.getAbsolutePath());

      return new FileResource(dir, path, true);
   }

   /**
    * Adds or overwrites a file on the file system.
    *
    * @param is The file contents.
    * @param path The file path.
    * @return Redirect to root on success.
    * @throws InternalServerError If the write fails.
    */
   @RestPut(
      path="/*",
      summary="Add or replace file",
      description="Add or overwrite a file on the file system."
   )
   public RedirectToRoot updateFile(
      @Content @Schema(type="string",format="binary") InputStream is,
      @Path("/*") String path
   ) throws InternalServerError {

      if (! allowUploads)
         throw new MethodNotAllowed("PUT not enabled");

      var f = getFileForUpload(path);

      try (var os = new BufferedOutputStream(new FileOutputStream(f))) {
         pipe(is, os);
      } catch (IOException e) {
         throw new InternalServerError(e);
      }

      return new RedirectToRoot();
   }

   /**
    * Views the contents of a file.
    *
    * @param res The response.
    * @param path The file path.
    * @return The file contents stream.
    * @throws NotFound If the file is not found.
    * @throws MethodNotAllowed If views are not enabled.
    */
   @RestOp(
      method="VIEW",
      path="/*",
      read=true,
      summary="View contents of file",
      description="View the contents of a file.\nContent-Type is set to 'text/plain'."
   )
   public FileContents viewFile(RestResponse res, @Path("/*") String path) throws NotFound, MethodNotAllowed {
      if (! allowViews)
         throw new MethodNotAllowed("VIEW not enabled");

      res.setContentType("text/plain");
      try {
         return new FileContents(getFile(path));
      } catch (@SuppressWarnings("unused") FileNotFoundException e) {
         throw new NotFound("File not found");
      }
   }

   private void deleteFile(File f) {
      if (! allowDeletes)
         throw new MethodNotAllowed("DELETE not enabled");
      if (f.isDirectory()) {
         var files = f.listFiles();
         if (nn(files)) {
            for (var fc : files)
               deleteFile(fc);
         }
      }
      try {
         Files.delete(f.toPath());
      } catch (@SuppressWarnings("unused") IOException e) {
         throw new Forbidden("Could not delete file %s", f.getAbsolutePath());
      }
   }

   /**
    * Resolves a request path against {@link #rootDir} with a canonical-path boundary check
    * so {@code ..} segments, absolute paths, and symlink-out cannot escape the configured root.
    *
    * <p>
    * The check is intentionally applied at this single funnel because every public operation on
    * this resource (view, download, delete, upload, info) resolves the user-supplied path through
    * this method. Delegates to {@link FileUtils#resolveSafely(File, String)} — the canonical
    * shared implementation; the caller-layer mapping is: boundary violation → 403 (Forbidden),
    * non-existent target → 404 (NotFound).
    */
   private File getFile(String path) throws NotFound {
      try {
         return FileUtils.resolveSafely(rootDir, path)
            .orElseThrow(() -> new NotFound("File not found."));
      } catch (IllegalArgumentException e) {
         throw new Forbidden(e.getMessage());
      }
   }

   /**
    * Upload-path variant of {@link #getFile(String)} that allows the target file to not yet exist
    * (so {@code PUT /new-file.txt} can create a new file) while still enforcing the boundary check
    * by resolving the parent directory through {@link FileUtils#resolveSafely(File, String)}.
    *
    * <p>
    * If the target itself exists, returns it directly (overwrite path). Otherwise, resolves the
    * parent directory (which must exist and be inside the root), then appends the requested
    * filename. The parent's existence requirement prevents implicit directory creation via PUT.
    */
   private File getFileForUpload(String path) throws NotFound {
      try {
         var existing = FileUtils.resolveSafely(rootDir, path);
         if (existing.isPresent())
            return existing.get();
         var parentPath = "";
         var name = path == null ? "" : path;
         var slash = name.lastIndexOf('/');
         if (slash >= 0) {
            parentPath = name.substring(0, slash);
            name = name.substring(slash + 1);
         }
         if (name.isEmpty())
            throw new NotFound("File not found.");
         var parent = FileUtils.resolveSafely(rootDir, parentPath)
            .orElseThrow(() -> new NotFound("File not found."));
         return new File(parent, name);
      } catch (IllegalArgumentException e) {
         throw new Forbidden(e.getMessage());
      }
   }

   /**
    * Returns the root directory.
    *
    * @return The root directory.
    */
   protected File getRootDir() { return rootDir; }
}