Class StaticFiles.Builder

java.lang.Object
com.soklet.StaticFiles.Builder
Enclosing class:
StaticFiles

@NotThreadSafe public static final class StaticFiles.Builder extends Object
Builder for StaticFiles instances.
Author:
Mark Allen
  • Method Details

    • trustedImmutableRoot

      Declares that the root, its ancestors, links, and files are controlled exclusively by the application operator and remain unchanged while this helper or its responses are in use.

      This declaration is required on every platform. It does not set filesystem permissions or freeze files. Do not enable it for uploads, tenant-writable directories, or any tree that untrusted code can mutate. Public NIO checks cannot exclude all path-replacement races. Passing false or null withdraws the declaration and makes build() fail closed. Deploy a new helper for a new immutable asset tree.

      Parameters:
      trustedImmutableRoot - true to accept the immutable-root contract
      Returns:
      this builder
    • indexFileNames

      Sets the index file names to try when a request path resolves to a directory.

      Names are tried in list order. Each name must be a single file name, not a path; blank names, ., .., path separators, control characters, Windows drive paths, and UNC-style paths are rejected when the builder is built.

      Each call replaces the complete previously configured list; it does not append. Passing null or an empty list clears the index file names.

      Parameters:
      indexFileNames - the replacement index file names, or null to clear them
      Returns:
      this builder
    • mimeTypeResolver

      Sets the resolver used to produce Content-Type values.

      The configured resolver fully replaces the default resolver. Soklet's default resolver uses a curated deterministic set of common web-asset extensions, returns Optional.empty() for unknown extensions, and does not call Files.probeContentType(Path). Applications that need OS-level MIME database behavior can configure a resolver that calls Files.probeContentType(...) directly.

      Parameters:
      mimeTypeResolver - the resolver to use, or null to restore the default resolver
      Returns:
      this builder
    • entityTagResolver

      Sets the resolver used to produce ETag values.

      Passing null restores the default weak metadata-based resolver.

      Parameters:
      entityTagResolver - the resolver to use, or null to restore the default resolver
      Returns:
      this builder
    • accessResolver

      Sets the resolver used to decide whether resolved files are served, denied, or hidden.

      The access resolver runs after path safety, index-file resolution, symlink policy, readability, regular-file checks, and attribute reads, but before MIME, validator, cache-control, extra-header, and range-request resolvers. It receives the resolved file path, not the original request path.

      Parameters:
      accessResolver - the resolver to use, or null to restore the allow-all default
      Returns:
      this builder
    • lastModifiedResolver

      Sets the resolver used to produce Last-Modified values.

      Passing null restores the default resolver, which uses the file attributes read for the response.

      Parameters:
      lastModifiedResolver - the resolver to use, or null to restore the default resolver
      Returns:
      this builder
    • cacheControlResolver

      Sets the resolver used to produce Cache-Control values.

      Passing null restores the disabled resolver, which omits Cache-Control.

      Parameters:
      cacheControlResolver - the resolver to use, or null to omit Cache-Control
      Returns:
      this builder
    • headersResolver

      Sets the resolver used to produce extra response headers.

      Passing null restores the disabled resolver, which emits no extra headers. Managed file headers cannot be supplied here; see StaticFiles.HeadersResolver for the controlled names and dedicated resolver alternatives.

      Parameters:
      headersResolver - the resolver to use, or null to omit extra headers
      Returns:
      this builder
    • rangeRequestsResolver

      Sets the resolver used to decide whether byte range requests are honored.

      Passing null restores the default resolver, which enables range requests.

      Parameters:
      rangeRequestsResolver - the resolver to use, or null to enable range requests
      Returns:
      this builder
    • followSymlinks

      Sets whether symbolic links are followed while resolving static-file paths.

      Passing null restores the default of false. When disabled, any symbolic-link component under the static root causes the candidate path to be hidden. Enabling this option resolves links inside the configured root. Links that resolve outside the root are hidden. The required trusted immutable-root contract applies to links and their targets too; observed replacement links are rejected during delivery.

      Parameters:
      followSymlinks - true to follow symlinks, false to reject them, or null for the default
      Returns:
      this builder
    • build

      Builds the static-file helper.

      The configured root is validated as a directory when this method is called. With followSymlinks enabled it is resolved to a real path; otherwise a symbolic-link root is rejected. The resolved root identity is captured without retaining an open directory handle. Both modes require trustedImmutableRoot(Boolean) to be explicitly set to true and a provider with stable file identities. Rebuild the helper when intentionally switching deployment roots, after in-flight responses have completed. Pass the root's Path.toRealPath(LinkOption...) value explicitly to use its resolved directory without enabling symlink traversal.

      Returns:
      the configured static-file helper