Support file server (#1498)

* [enhancement] open branch for static file server

* [enhancement] import lru v2 version

* add basic filter framework for fileserver

* [enhancement] support get file with ttl

* [enhancement] support mmap

* [enhancement] add ttl for mmap

* update filehandler

* [enhancement] add prometheus metrics for cache pool

* [enhancement] support etag

* [enhancement] support Last-Modified

* [enhancement] support set root dir, support hidden files, add tests

* [enhancement] add index file

* [enhancement] support try files

* [enhancement] support rewrite path logic

* [enhancement] support precompressed

* [enhancement] support compress for small file

* [enhancement] support compress for large files

* [enhancement] support cache path parser

* [test] add test to serve files and fix bugs

* [bugfix] registry missing filters

* [doc] add doc for fileserver

* [testing] fix windows path

* [testing] only support extension filter

* [testing] fix test

* add log to test windows path

* [testing] fix test on windows

* log windows path

* [testing] fix test on windows

* log for windows path

* [testing] clean log

---------

Co-authored-by: chen <chen.su1994@outlook.com>

Author: LokiWager

docs/07.Reference/7.02.Filters.md

@@ -1827,6 +1827,94 @@ filters:
 | internalError             | Error occurred during processing the request |
 
 
+## FileServer
+
+Miniuim config example:
+
+```yaml
+name: fileserver-pipeline
+kind: Pipeline
+filters:
+- name: fileserver-filter
+  kind: FileServer
+  root: "/var/www/example"
+```
+
+Complete config example:
+
+```yaml
+name: fileserver-pipeline
+kind: Pipeline
+filters:
+- name: fileserver-filter
+  kind: FileServer
+  root: "/var/www/example"
+  index: ["index.html", "index.txt"]  # default is index.html and index.txt
+  hidden: [".git", "/build", "*/*.conf"]
+  tryFiles: ["{path}", "{path}/", "/index.html", "=404 error message"]
+  rewrite: "^/users/(\d+)$ /users.php?id=$1"
+  precompressed: "gzip br"
+  compress: "gzip"
+  cache:
+    bufferPoolSize: 2 * 1024 * 1024 * 1024  # default is 2GB
+    bufferPoolMaxFileSize: 10 * 1024 * 1024 # default is 10MB
+    bufferPoolTTL: 600                      # default is 600 seconds
+    cacheFileExtensionFilters: 
+    - pattern: ["*.html", "*.css"]
+      etagMaxAge: 3600                      # default is 3600
+    - pattern: ["/usr/*.js"]
+```
+
+
+### Configuration
+
+
+| Name | Type | Description | Required |
+| --- | --- | --- | --- |
+| root | string | The root directory path from which to serve files. | Yes |
+| index | []string | A list of filenames to look for, in order, when a directory is requested. Defaults to `["index.html", "index.txt"]`. | No |
+| hidden | []string | A list of glob patterns for files or directories to hide. Requests for these files will be treated as if they do not exist (404 Not Found). | No |
+| tryFiles | []string | A sequence of files to try serving in order. If the previous file is not found, the next one is tried. Useful for Single-Page Applications (SPAs) or front-controller patterns. Supports placeholders like `{path}` and can end with an error code like `=404`. | No |
+| rewrite | string | A rewrite rule used to internally modify the request URI before file lookups. It uses regular expression matching and capture groups (e.g., `$1`). | No |
+| precompressed | string | A space-separated list of precompressed formats (e.g., `gzip br`). For a request to `/file`, it will check for the existence of `/file.gz`, `/file.br`, etc. | No |
+| compress | string | The compression method (e.g., `gzip`) to use for on-the-fly compression of responses that are not precompressed. | No |
+| cache | [CacheSpec](#fileservercachespec) | A container for configuring caching-related settings. | No |
+
+#### More about hidden rules
+##### 1. Component Patterns (rules without a path separator)
+These patterns (e.g., ".git", "*.log") are matched against each individual name component of the relative path.
+```
+- Rule: ".git"
+- Hides: "/path/to/project/.git", "/path/to/.git/config"
+- Does NOT hide: "/path/to/project/git"
+
+- Rule: "node_modules"
+- Hides: "/path/to/project/node_modules", "/path/to/node_modules/express"
+```
+
+##### 2. Path Patterns (rules with a path separator):
+These patterns are matched against the full absolute path. This matching is done in two ways:
+
+```
+a) As a prefix: If the rule is a prefix of the path, followed by a path separator, it's a match.
+- Rule: "/build"
+- Hides: "/build/app.js", "/build/"
+- Does NOT hide: "/builder/app.js"
+
+b) As a glob pattern: The rule is treated as a glob pattern to be matched against the entire absolute path.
+- Rule: "/*/*/*.conf"
+- Hides: "/etc/nginx/nginx.conf"
+- Does NOT hide: "/etc/nginx.conf"
+```
+
+### Results
+
+| Value | Description |
+| --- | --- |
+| internalError | An internal error occurred within the FileServer system |
+| serverError | A server-side error occurred |
+| clientError | The client's request was blocked |
+| notFound | A required resource could not be found |
 
 ## Common Types
 
@@ -2324,3 +2412,25 @@ template: |
 |------|------|-------------|----------|
 | header | [httpheader.AdaptSpec](#httpheaderadaptspec) | Rules to revise request header    | No       |
 | body   | string   | If provided the body of the original request is replaced by the value of this option. | No       |
+
+
+
+### fileserver.CacheSpec
+
+This configuration is nested under the `cache` field.
+
+| Name | Type | Description | Required |
+| --- | --- | --- | --- |
+| bufferPoolSize | integer | The maximum size of the in-memory cache pool in bytes. Defaults to `2147483648` (2 GB). | No |
+| bufferPoolMaxFileSize | integer | The maximum size in bytes that a single file can be to be cached in the buffer pool. Defaults to `10485760` (10 MB). | No |
+| bufferPoolTTL | integer | The time-to-live (TTL) for items in the cache pool, in seconds. Defaults to `600`. | No |
+| cacheFileExtensionFilters | [][FileExtensionFilter](#fileserverfileextensionfilter) | A list of rules to control `ETag` cache headers based on file patterns. | No |
+
+### fileserver.FileExtensionFilter
+
+This configuration is for each object within the `cacheFileExtensionFilters` array.
+
+| Name | Type | Description | Required |
+| --- | --- | --- | --- |
+| pattern | []string | A list of glob patterns to match files against (e.g., `["*.html", "*.css"]`). | Yes |
+| etagMaxAge | integer | The `max-age` value, in seconds, to set for the `ETag` response header for files matching this pattern. Defaults to `3600`. | No |

go.mod

@@ -31,6 +31,7 @@ require (
 	github.com/gorilla/mux v1.8.0
 	github.com/hashicorp/consul/api v1.26.1
 	github.com/hashicorp/golang-lru v1.0.2
+	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/invopop/jsonschema v0.12.0
 	github.com/invopop/yaml v0.2.0
 	github.com/jackc/pgx/v5 v5.7.5

go.sum

@@ -524,6 +524,8 @@ github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ
 github.com/hashicorp/golang-lru v0.5.1/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
 github.com/hashicorp/golang-lru v1.0.2 h1:dV3g9Z/unq5DpblPpw+Oqcv4dU/1omnb4Ok8iPY6p1c=
 github.com/hashicorp/golang-lru v1.0.2/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/hashicorp/logutils v1.0.0/go.mod h1:QIAnNjmIWmVIIkWDTG1z5v++HQmx9WQRO+LraFDTW64=