Class StaticFiles

java.lang.Object
com.soklet.StaticFiles

@ThreadSafe public final class StaticFiles extends Object
Helper for serving files from an explicitly trusted, immutable root directory. The builder requires trustedImmutableRoot(true): only the application operator may control the root, its ancestors, links, and files, and they must remain unchanged while the helper or its responses are in use. Upload directories and other attacker-writable trees are not supported.

Delivery uses public NIO APIs, with SecureDirectoryStream where available and a checked pathname fallback otherwise (including macOS Java 21 and Windows). Providers without file keys use creation time, size, and modification time to detect observed replacement. Checks reject observed changes; they do not make concurrent mutation safe. Public Java APIs cannot bind regular-file attributes to an opened channel, and copying bytes does not close that identity race. No JDK internals, native-access flags, or retained directory descriptors are used.

The resolved root identity is captured at construction. Rebuild the helper when intentionally switching deployment roots, after in-flight responses have completed. Search-only directories use checked pathname access when public secure-directory handles cannot be acquired.

Author:
Mark Allen
  • Method Details

    • withRoot

      Begins configuration for serving files under root.

      Relative roots are resolved against the JVM's current working directory when the builder is built. Production deployments should generally pass an absolute path.

      File matching follows the underlying filesystem's case-sensitivity and Unicode normalization rules. Production deployments that need portable behavior across operating systems should standardize on ASCII-safe asset names.

      Parameters:
      root - the static-file root directory
      Returns:
      a builder for static-file responses
    • marshaledResponseFor

      Produces a marshaled response for relativePath, if the request targets a safe, readable file under the configured root.

      Returns Optional.empty() for HTTP methods other than HttpMethod.GET and HttpMethod.HEAD, unsafe path input, directories without a configured index file, unreadable files, and missing files. Once a path resolves, non-200 file responses such as 206, 304, 412, and 416 are returned inside the optional. Root-relative input is limited to 4,096 UTF-8 bytes, 256 path segments, and 255 UTF-8 bytes per segment. These portable input limits apply on every filesystem; providers may impose stricter limits, whose unclassified failures propagate as I/O errors.

      Resolvers receive the resolved file path after index-file resolution, not the original relativePath.

      Parameters:
      relativePath - the root-relative file path
      request - the incoming request
      Returns:
      the marshaled response, if a static file was resolved
      Throws:
      UncheckedIOException - if filesystem access fails for a reason other than a missing, inaccessible, or changed file, including a provider that cannot open files without following links