Default logger middleware (#33)

* feat: wip on default logger middleware * ci: update go version to 1.21 * feat: fix test * feat: wip in recovery middleware * feat: wip logging middleware * feat: improve recovery middleware tests * feat: remove Context.Ctx method to reduce api surface & small optimisation * feat: rename context to cTx in to avoid the inconvenient rename of context package to netcontext * feat: add test for logger middleware * feat: improve test coverage * feat: improve test coverage * feat: implement Context.ClientIP as well as multi ClientIPStrategy * feat: use min builtin function * ci: update actions * ci: update actions * ci: update actions * feat: improve test coverage * feat: improving documentation * feat: improving documentation * feat: improving documentation * feat: improving documentation * feat: improving test coverage * feat: improve docs and naming * feat: improve docs and naming * docs: add proper credit * docs: fix documentation * docs: fix documentation
tigerwill90 · Jun 27, 2024 · 74b75c6 · 74b75c6
1 parent 670e306
commit 74b75c6
Show file tree

Hide file tree

Showing 25 changed files with 3,670 additions and 170 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -9,16 +9,16 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '>=1.19' ]
+        go: [ '>=1.21' ]
     steps:
       - name: Set up Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.go }}
           cache: false
 
       - name: Check out code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Run tests
         run: go test -v -coverprofile=coverage.txt -covermode=atomic ./...
@@ -27,24 +27,25 @@ jobs:
         run: go test -v -race -run TestDataRace -count=10 ./...
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
-          flags: coverage.txt
+          files: ./coverage.txt
+          token: ${{ secrets.CODECOV_TOKEN }}
   lint:
     name: Lint Fox
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '>=1.19' ]
+        go: [ '>=1.21' ]
     steps:
       - name: Set up Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.go }}
           cache: false
 
       - name: Check out code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Run linter
-        uses: golangci/golangci-lint-action@v3
+        uses: golangci/golangci-lint-action@v6
diff --git a/README.md b/README.md
@@ -40,6 +40,8 @@ or missing trailing slash, at no extra cost.
 **Automatic OPTIONS replies:** Inspired from [httprouter](https://github.com/julienschmidt/httprouter), the router has built-in native
 support for [OPTIONS requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS).
 
+**Client IP Derivation:** Accurately determine the "real" client IP address using best practices tailored to your network topology.
+
 Of course, you can also register custom `NotFound` and `MethodNotAllowed` handlers.
 
 ## Getting started
@@ -484,6 +486,55 @@ f := fox.New(
 )
 ````
 
+## Client IP Derivation
+The `WithClientIPStrategy` option allows you to set up strategies to resolve the client IP address based on your 
+use case and network topology. Accurately determining the client IP is hard, particularly in environments with proxies or 
+load balancers. For example, the leftmost IP in the `X-Forwarded-For` header is commonly used and is often regarded as the 
+"closest to the client" and "most real," but it can be easily spoofed. Therefore, you should absolutely avoid using it 
+for any security-related purposes, such as request throttling.
+
+The strategy used must be chosen and tuned for your network configuration. This should result in the strategy never returning 
+an error and if it does, it should be treated as an application issue or a misconfiguration, rather than defaulting to an 
+untrustworthy IP.
+
+The sub-package `github.com/tigerwill90/fox/strategy` provides a set of best practices strategies that should cover most use cases.
+
+````go
+f := fox.New(
+    fox.DefaultOptions(),
+    fox.WithClientIPStrategy(
+        // We are behind one or many trusted proxies that have all private-space IP addresses.
+        strategy.NewRightmostNonPrivate(fox.HeaderXForwardedFor),
+    ),
+)
+
+f.MustHandle(http.MethodGet, "/foo/bar", func(c fox.Context) {
+    ipAddr, err := c.ClientIP()
+        if err != nil {
+            // If the current strategy is not able to derive the client IP, an error
+            // will be returned rather than falling back on an untrustworthy IP. It
+            // should be treated as an application issue or a misconfiguration.
+            panic(err)
+        }
+    fmt.Println(ipAddr.String())
+})
+````
+
+It is also possible to create a chain with multiple strategies that attempt to derive the client IP, stopping when the first one succeeds.
+
+````go
+f := fox.New(
+    fox.DefaultOptions(),
+    fox.WithClientIPStrategy(strategy.NewChain(
+        strategy.NewLeftmostNonPrivate(fox.HeaderXForwardedFor),
+        strategy.NewRemoteAddr(),
+    )),
+)
+````
+
+Note that there is no "sane" default strategy, so calling `Context.ClientIP` without a strategy configured will return an `ErrNoClientIPStrategy`.
+
+See this [blog post](https://adam-p.ca/blog/2022/03/x-forwarded-for/) for general guidance on choosing a strategy that fit your needs.
 ## Benchmark
 The primary goal of Fox is to be a lightweight, high performance router which allow routes modification at runtime.
 The following benchmarks attempt to compare Fox to various popular alternatives, including both fully-featured web frameworks
@@ -623,7 +674,7 @@ BenchmarkPat_GithubAll               424           2899405 ns/op         1843501
 - [x] [Update route syntax](https://github.com/tigerwill90/fox/pull/10#issue-1643728309) @v0.6.0
 - [x] [Route overlapping](https://github.com/tigerwill90/fox/pull/9#issue-1642887919) @v0.7.0
 - [x] [Route overlapping (catch-all and params)](https://github.com/tigerwill90/fox/pull/24#issue-1784686061) @v0.10.0
-- [x] [Ignore trailing slash](https://github.com/tigerwill90/fox/pull/32) @v0.14.0
+- [x] [Ignore trailing slash](https://github.com/tigerwill90/fox/pull/32), [Builtin Logger Middleware](https://github.com/tigerwill90/fox/pull/33), [Client IP Derivation](https://github.com/tigerwill90/fox/pull/33) @v0.14.0
 - [ ] Improving performance and polishing
 
 ## Contributions