update static plugin docs (#194)

Author: Ethan-Arrowood

docs/technical-details/reference/components/built-in-extensions.md

@@ -5,6 +5,7 @@ Harper provides extended features using built-in extensions. They do **not** nee
 For more information read the [Components, Applications, and Extensions](../../../developers/applications/) documentation section.
 
 - [Built-In Extensions](#built-in-extensions)
+  - [dataLoader](#dataloader)
   - [fastifyRoutes](#fastifyroutes)
   - [graphql](#graphql)
   - [graphqlSchema](#graphqlschema)
@@ -13,6 +14,13 @@ For more information read the [Components, Applications, and Extensions](../../.
   - [rest](#rest)
   - [roles](#roles)
   - [static](#static)
+    - [Options](#options)
+    - [Examples](#examples)
+      - [Basic Static File Serving](#basic-static-file-serving)
+      - [Enable automatic `index.html` serving](#enable-automatic-indexhtml-serving)
+      - [Enable automatic `.html` extension matching](#enable-automatic-html-extension-matching)
+      - [Provide a custom `404 Not Found` page](#provide-a-custom-404-not-found-page)
+      - [Fully customize not found response](#fully-customize-not-found-response)
 
 ## dataLoader
 
@@ -150,35 +158,158 @@ roles:
 
 ## static
 
-Specify files to serve statically from the Harper HTTP endpoint.
+Serve static files via HTTP.
 
-Use the [Resource Extension](./extensions.md#resource-extension) configuration options [`files` and `urlPath`](./extensions.md#resource-extension-configuration) to specify the files to be served.
+The `static` plugin serves static files based on the `files` and `urlPath` [plugin configuration options](./plugins.md#configuration). It supports additional features via other options (detailed below), but the core to the plugin is to statically serve the files matched by the `files` pattern. The plugin will serve files relative to the longest non-ambiguous path within the pattern. The `urlPath` can be specified to customize the URL path that the files are served from, otherwise they match the file pattern. For example, given an application directory structure:
 
-As specified by Harper's Resource Extension docs, the `files` option can be any glob pattern or a glob options object. This extension will serve all files matching the pattern, so make sure to be specific.
+```
+my-app/
+├─ site/
+│  ├─ index.html
+│  ├─ about.html
+│  ├─ blog/
+│     ├─ post-1.html
+│     ├─ post-2.html
+├─ config.yaml
+```
 
-To serve the entire `web` directory, specify `files: 'web/**'`.
+The `static` plugin can be configured to serve the `site/` directory by specifying:
 
-To serve only the html files within `web`, specify `files: 'web/*.html'` or `files: 'web/**/*.html'`.
+```yaml
+static:
+  files: 'site/**'
+```
 
-The `urlPath` option is the base URL path entries will be resolved to. For example, a `urlPath: 'static'` will serve all files resolved from `files` to the URL path `localhost/static/`.
+Then you could access the files relative to the `site` directory, thus `GET localhost:9926/index.html` would return the contents of `site/index.html`, and `GET localhost:9926/blog/post-1.html` would return the contents of `site/blog/post-1.html`.
 
-Given the `config.yaml`:
+You can use the `urlPath` option to serve the files from a different URL path, for example:
 
 ```yaml
 static:
-  files: 'web/*.html'
-  urlPath: 'static'
+  files: 'site/**'
+  urlPath: 'app'
 ```
 
-And the file directory structure:
+Now, `GET localhost:9926/app/index.html` would return the contents of `site/index.html`, and `GET localhost:9926/app/blog/post-1.html` would return the contents of `site/blog/post-1.html`.
+
+Moreover, if the `site/` directory was nested another level, such as:
 
 ```
-component/
-├─ web/
-│  ├─ index.html
-│  ├─ blog.html
+my-app/
+├─ site/
+│  ├─ pages/
+│     ├─ index.html
+│     ├─ about.html
+│     ├─ blog/
+│        ├─ post-1.html
+│        ├─ post-2.html
+│  ├─ cache-info/
+│     ├─ index.json
+│     ├─ about.json
+│     ├─ ...
 ├─ config.yaml
+```
+
+Now a pattern such as `site/pages/**` will match all files within the `pages` directory (including subdirectories) so a request to `GET localhost:9926/index.html` will return the contents of `site/pages/index.html`, and `GET localhost:9926/blog/post-1.html` will return the contents of `site/pages/blog/post-1.html`.
+
+Because this plugin is implemented using the new [Plugin API](./plugins.md), it automatically updates to application changes. From updating the `config.yaml` to adding, removing, or modifying files, everything is handled automatically and Harper should **not** require a restart.
+
+### Options
+
+In addition to the general Plugin configuration options (`files`, `urlPath`, and `timeout`), this plugin supports the following configuration options:
+
+- **extensions** - `string[]` - _optional_ - An array of file extensions to try and serve when an exact path is not found. For example, `['html']` and the path `/site/page-1` will match `/site/page-1.html`.
+- **fallthrough** - `boolean` - _optional_ - If `true`, the plugin will fall through to the next handler if the requested file is not found. Make sure to disable this option if you want to customize the 404 Not Found response with the `notFound` option. Defaults to `true`.
+- **index** - `boolean` - _optional_ - If `true`, the plugin will serve an `index.html` file if it exists in the directory specified by the `files` pattern. Defaults to `false`.
+- **notFound** - `string | { file: string; statusCode: number }` - _optional_ - Specify a custom file to be returned for 404 Not Found responses. If you want to specify a different statusCode when a given path cannot be found, use the object form and specify the `file` and `statusCode` properties (this is particularly useful for SPAs).
+
+### Examples
+
+The `static` plugin can be configured in various ways to provide different behaviors. Here are some common examples:
+
+#### Basic Static File Serving
+
+Serve all files contained within the `static/` directory as is.
+
+```yaml
+static:
+  files: 'static/**'
+```
+
+Requests must match the file names exactly (relative to the `static/` directory).
+
+#### Enable automatic `index.html` serving
+
+Serve all files contained within the `static/` directory, and automatically serve an `index.html` file if it exists in the directory.
+
+```yaml
+static:
+  files: 'static/**'
+  index: true
+```
+
+Now given a directory structure like:
 
 ```
+my-app/
+├─ static/
+│  ├─ index.html
+│  ├─ blog/
+│     ├─ index.html
+│     ├─ post-1.html
+```
+
+Requests would map like:
+
+```
+GET / -> static/index.html
+GET /blog -> static/blog/index.html
+GET /blog/post-1.html -> static/blog/post-1.html
+```
+
+#### Enable automatic `.html` extension matching
+
+Expanding on the previous example, if you specify the `extensions` option, the plugin will automatically try to match the requested path with the specified extensions.
+
+```yaml
+static:
+  files: 'static/**'
+  index: true
+  extensions: ['html']
+```
+
+Now with the same directory structure, requests would map like:
+
+```
+GET / -> static/index.html
+GET /blog -> static/blog/index.html
+GET /blog/post-1 -> static/blog/post-1.html
+```
+
+#### Provide a custom `404 Not Found` page
+
+Sometimes when a `404 Not Found` response is not sufficient, and you want to provide a custom page or resource, you can use the `notFound` option to specify a custom file to be returned when a requested path is not found.
+
+```yaml
+static:
+  files: 'static/**'
+  notFound: 'static/404.html'
+```
+
+Now if a request is made to a path that does not exist, such as `/non-existent`, the plugin will return the contents of `static/404.html` with a `404` status code.
+
+#### Fully customize not found response
+
+Most common in SPAs relying on client-side routing, you may want to override the default `404` status code when a path is not found.
+
+You can do this by specifying the `notFound` option as an object with a `file` and `statusCode` property.
+
+```yaml
+static:
+  files: 'static/**'
+  notFound:
+    file: 'static/index.html'
+    statusCode: 200
+```
 
-The HTML files will be available at `localhost/static/index.html` and `localhost/static/blog.html` respectively.
+Now if a request is made to a path that does not exist, such as `/non-existent`, the plugin will return the contents of `static/index.html` with a `200` status code. This is particularly useful for SPAs where you want to serve the main application file regardless of the requested path.