Refactoring and additions

2025-02-27 22:44:18 +01:00
parent 06e6bfa13d
commit 8912f7e738
11 changed files with 152 additions and 26 deletions
@@ -0,0 +1,73 @@
+---
+banner_title: "Flash - Dynamic File Server"
+banner_description: "Learn how to serve files in a dynamic context."
+---
+
+# 📁 Dynamic File Server
+
+Sometimes we need to serve files in a dynamic context, in this sense a static file server is limiting.
+Imagine we have a frontend application that is compiled down to a single `index.html` file, and we want to serve it with Flash
+alongside it's javascript and css bundles. The way these compiled applications work is that they rely heavily on
+client-side routing, so when the user navigates to a different page, the frontend application will try to fetch the
+corresponding file from the server. This is where a dynamic file server comes in handy, as no route is pre-registered.
+
+::: warning
+The dynamic file server relies heavily on the concept of dynamic handlers, which are handlers that will resolve for
+any subpath of the endpoint they are registered to (see [Handler Types](/flash/handlers) for more info).
+:::
+
+## Usage
+
+To serve static files in Flash, you need to call the `server.serveDynamic()` method with the endpoint path and an instance of `DynamicFileServerConfig`.
+The configuration object is instanced like so :
+
+```java
+DynamicFileServerConfiguration(
+    boolean enableFileWatcher,
+    String destinationPath,
+    String dynamicEntrypoint,
+    SourceType sourceType
+)
+```
+
+- `enableFileWatcher` : If set to `true`, the server will watch for changes in the served files and reload them automatically.
+- `destinationPath` : The path to the directory containing the files to be served.
+- `dynamicEntrypoint` : The path to the file that will be served when the client navigates to the endpoint eg. `index.html`.
+- `sourceType` : The type of source to serve files from. It can be either `FILESYSTEM` or `RESOURCESTREAM`.
+
+Registering the dynamic file server is as simple as calling the `server.serveDynamic()` method with the desired path and configuration object:
+
+```java
+public class Example {
+    public static void main(String[] args) {
+        FlashServer server = new FlashServer(8080);
+
+        server.serveDynamic("/*", new DynamicFileServerConfiguration(
+            true,
+            "path/to/my/files",
+            "index.html",
+            SourceType.FILESYSTEM
+        ));
+    }
+}
+```
+
+Now you can access the files (or frontend) in the specified directory by navigating to `http://localhost:8080/<file-name>`.
+
+Similarly, you can serve the same content from the jar's resources folder by setting the `sourceType` to `RESOURCESTREAM`:
+
+```java
+public class Example {
+    public static void main(String[] args) {
+        FlashServer server = new FlashServer(8080);
+
+        server.serveStatic("/static", new DynamicFileServerConfiguration(
+            true,
+            "path/to/my/files",
+            "index.html",
+            SourceType.RESOURCESTREAM
+        ));
+    }
+}
+```
+
@@ -0,0 +1,70 @@
+---
+banner_title: "Flash - Static File Server"
+banner_description: "Learn how to serve static files in Flash."
+---
+
+# 📁 Static File Server
+
+Flash provides a built-in static file server that allows you to serve static files such with autoresolving MIME types and caching.
+
+::: warning
+The static file server pre-registers literal routes for every file in the specified target directory.
+Creating/deleting files in the target directory will trigger the internal route registry to update accordingly.
+If you are planning to serve a compiled frontend application with a client-side router (think of react-router-dom),
+it is reccomended to use the Dynamic File Server instead, 
+:::
+
+## Usage
+
+To serve static files in Flash, you need to call the `server.serveStatic()` method with the endpoint path and an instance of `StaticFileServerConfig`.
+The configuration object is instanced like so :
+
+```java
+public StaticFileServerConfiguration(
+    boolean enableFileWatcher,
+    boolean enableIndexRedirect,
+    String destinationPath,
+    SourceType sourceType
+)
+```
+
+- `enableFileWatcher` : If set to `true`, the server will watch for changes in the served files and reload them automatically.
+- `enableIndexRedirect` : If set to `true`, the server will redirect requests to directories to the `index.html` file.
+- `destinationPath` : The path to the directory containing the files to be served.
+- `sourceType` : The type of source to serve files from. It can be either `FILESYSTEM` or `RESOURCESTREAM`.
+
+Registering the static file server is as simple as calling the `server.serveStatic()` method with the desired path and configuration object:
+
+```java
+public class Example {
+    public static void main(String[] args) {
+        FlashServer server = new FlashServer(8080);
+
+        server.serveStatic("/static", new StaticFileServerConfiguration(
+            true,
+            true,
+            "path/to/static/files",
+            SourceType.FILESYSTEM
+        ));
+    }
+}
+```
+
+Now you can access the files in the specified directory by navigating to `http://localhost:8080/static/<file-name>`.
+
+Similarly, you can serve files from the jar's resources folder by setting the `sourceType` to `RESOURCESTREAM`:
+
+```java
+public class Example {
+    public static void main(String[] args) {
+        FlashServer server = new FlashServer(8080);
+
+        server.serveStatic("/static", new StaticFileServerConfiguration(
+            true,
+            true,
+            "path/to/static/files",
+            SourceType.RESOURCESTREAM
+        ));
+    }
+}
+```