Class StaticFiles
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumAccess outcome for a resolved static file.static interfaceResolves whether a resolved static file should be served, denied, or hidden.static final classBuilder forStaticFilesinstances.static interfaceResolvesCache-Controlvalues for static-file responses.static interfaceResolvesETagvalues for static-file responses.static interfaceResolves extra response headers for static-file responses.static interfaceResolvesLast-Modifiedvalues for static-file responses.static interfaceResolves whether byte range requests are honored for static-file responses. -
Method Summary
Modifier and TypeMethodDescriptionmarshaledResponseFor(@NonNull String relativePath, @NonNull Request request) Produces a marshaled response forrelativePath, if the request targets a safe, readable file under the configured root.static @NonNull StaticFiles.BuilderBegins configuration for serving files underroot.
-
Method Details
-
withRoot
Begins configuration for serving files underroot.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
public @NonNull Optional<@NonNull MarshaledResponse> marshaledResponseFor(@NonNull String relativePath, @NonNull Request request) Produces a marshaled response forrelativePath, if the request targets a safe, readable file under the configured root.Returns
Optional.empty()for HTTP methods other thanHttpMethod.GETandHttpMethod.HEAD, unsafe path input, directories without a configured index file, unreadable files, and missing files. Once a path resolves, non-200file responses such as206,304,412, and416are 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 pathrequest- 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
-