feat: initial implementation

.github/workflows/lint.yaml

@@ -0,0 +1,33 @@
+---
+name: Lint Code Base
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Lint Code Base
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: read
+      statuses: write
+
+    steps:
+      -
+        name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      -
+        name: Lint Code Base
+        uses: super-linter/super-linter@v5
+        env:
+          VALIDATE_ALL_CODEBASE: true
+          DEFAULT_BRANCH: main
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yaml

@@ -0,0 +1,27 @@
+---
+name: Tests
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        uses: actions/checkout@v4
+      -
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+      -
+        name: Install Brotli
+        run: |
+          sudo apt-get update
+          sudo apt-get install libbrotli-dev
+      -
+        name: Run tests
+        run: go test -race

.gitignore

@@ -0,0 +1 @@
+caddy

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Install
+
+1. Follow the installation guide in the readme
+2. Set the `CGO_LDFLAGS` and `CGO_CFLAGS` environment variables if necessary.
+3. Run:
+    ```console
+    CGO_ENABLED=1 xcaddy build
+    ```
+
+## Run Tests
+
+```console
+go test
+```

Caddyfile

@@ -0,0 +1,11 @@
+{
+    debug
+}
+
+localhost {
+    log
+    encode br
+    file_server {
+        browse
+    }
+}

LICENSE

@@ -0,0 +1,21 @@
+The MIT license
+
+Copyright (c) 2024-present Kévin Dunglas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,62 @@
+# Caddy Brotli Module
+
+This module for [the Caddy web server](https://caddyserver.com) provides support for [the Brotli compression format](https://en.wikipedia.org/wiki/Brotli).
+
+It uses [the reference implementation of Brotli](https://brotli.org/) (written in C), through [the Go module provided by Google](https://pkg.go.dev/github.com/google/brotli/go/cbrotli).
+
+## Install
+
+1. Install [cbrotli](https://github.com/google/brotli/tree/master/c). On Mac run `brew install brotli`. On Debian and Ubuntu, run `apt install libbrotli-dev`.
+2. Then create your Caddy build:
+    ```console
+    CGO_ENABLED=1 \
+    xcaddy build \
+        --with github.com/dunglas/caddy-cbrotli
+    ```
+
+    On Mac, be sure to adapt the paths in `CGO_LDFLAGS` and `CGO_CFLAGS` according to your Brotli installation:
+
+    ```console
+    CGO_LDFLAGS="-L/opt/homebrew/lib/" \
+    CGO_CFLAGS="-I/opt/homebrew/include/" \
+    CGO_ENABLED=1 \
+    xcaddy build \
+        --with github.com/dunglas/caddy-cbrotli
+    ```
+
+## Usage
+
+Add the `br` value to [the `encode` directive](https://caddyserver.com/docs/caddyfile/directives/encode) in your `Caddyfile`.
+
+Example:
+
+```
+localhost
+
+encode zstd br gzip
+
+file_server
+```
+
+Alternatively, you can configure the quality (from 0 to 11, defaults to 6) and the base 2 logarithm of the sliding window size (from 10 to 24, defaults to auto):
+
+Example:
+
+```
+localhost
+
+encode {
+    br 8 15
+}
+
+file_server
+```
+
+## Cgo
+
+This module depends on [cgo](https://go.dev/blog/cgo).
+If you are looking for a non-cgo (but more CPU-intensive) alternative, see [the `github.com/ueffel/caddy-brotli` module](https://github.com/ueffel/caddy-brotli).
+
+## Credits
+
+Created by [Kévin Dunglas](https://dunglas.dev) and sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop).

brotli.go

@@ -0,0 +1,107 @@
+// Package caddycbrotli provides provides support for the Brotli compression format
+// using a fast and efficient implementation written in C.
+package caddycbrotli
+
+import (
+	"errors"
+	"strconv"
+
+	"github.com/google/brotli/go/cbrotli"
+
+	"github.com/caddyserver/caddy/v2"
+	"github.com/caddyserver/caddy/v2/caddyconfig/caddyfile"
+	"github.com/caddyserver/caddy/v2/modules/caddyhttp/encode"
+)
+
+func init() {
+	caddy.RegisterModule(Br{})
+}
+
+// Br can create Brotli encoders.
+type Br struct {
+	// Quality controls the compression-speed vs compression-density trade-offs.
+	// The higher the quality, the slower the compression. Range is 0 to 11. Defaults to 6.
+	Quality *int `json:"quality,omitempty"`
+	// LGWin is the base 2 logarithm of the sliding window size.
+	// Range is 10 to 24. 0 indicates automatic configuration based on Quality.
+	LGWin int `json:"lgwin,omitempty"`
+}
+
+// CaddyModule returns the Caddy module information.
+func (Br) CaddyModule() caddy.ModuleInfo {
+	return caddy.ModuleInfo{
+		ID:  "http.encoders.br",
+		New: func() caddy.Module { return new(Br) },
+	}
+}
+
+// UnmarshalCaddyfile sets up the handler from Caddyfile tokens.
+func (b *Br) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
+	for d.Next() {
+		if !d.NextArg() {
+			continue
+		}
+		qualityStr := d.Val()
+		quality, err := strconv.Atoi(qualityStr)
+		if err != nil {
+			return err
+		}
+		b.Quality = &quality
+
+		if !d.NextArg() {
+			continue
+		}
+		lgwinStr := d.Val()
+		lgwin, err := strconv.Atoi(lgwinStr)
+		if err != nil {
+			return err
+		}
+		b.LGWin = lgwin
+	}
+
+	return nil
+}
+
+// Validate validates b's configuration.
+func (b Br) Validate() error {
+	if b.LGWin != 0 {
+		if b.LGWin < 10 {
+			return errors.New("logarithm of the sliding window size too low; must be >= 10")
+		}
+		if b.LGWin > 24 {
+			return errors.New("logarithm of the sliding window size too high; must be <= 24")
+		}
+	}
+
+	if b.Quality != nil {
+		if *b.Quality < 0 {
+			return errors.New("quality too low; must be >= 0")
+		}
+		if *b.Quality > 11 {
+			return errors.New("quality too high; must be <= 11")
+		}
+	}
+
+	return nil
+}
+
+// AcceptEncoding returns the name of the encoding as
+// used in the Accept-Encoding request headers.
+func (Br) AcceptEncoding() string { return "br" }
+
+// NewEncoder returns a new Brotli writer.
+func (b Br) NewEncoder() encode.Encoder {
+	q := 6
+	if b.Quality != nil {
+		q = *b.Quality
+	}
+
+	return newEncoder(cbrotli.WriterOptions{Quality: q, LGWin: b.LGWin})
+}
+
+// Interface guards
+var (
+	_ encode.Encoding       = (*Br)(nil)
+	_ caddy.Validator       = (*Br)(nil)
+	_ caddyfile.Unmarshaler = (*Br)(nil)
+)

brotli_test.go

@@ -0,0 +1,56 @@
+package caddycbrotli_test
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/caddyserver/caddy/v2/caddytest"
+	"github.com/google/brotli/go/cbrotli"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBrotli(t *testing.T) {
+	const dummyDoc = `
+<!doctype html>
+<meta charset=utf-8>
+<title>shortest html5</title>
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`
+
+	tester := caddytest.NewTester(t)
+	tester.InitServer(fmt.Sprintf(`
+	{
+		skip_install_trust
+		admin localhost:2999
+		http_port 9080
+		https_port 9443
+	}
+
+	localhost:9080
+	encode br
+	header Content-Type text/html
+	respond <<HTML
+%s
+HTML
+	`, dummyDoc), "caddyfile")
+
+	req, _ := http.NewRequest(http.MethodGet, "http://localhost:9080", nil)
+	req.Header.Add("Accept-Encoding", "br")
+
+	resp := tester.AssertResponseCode(req, http.StatusOK)
+	defer resp.Body.Close()
+
+	assert.Equal(t, "br", resp.Header.Get("Content-Encoding"))
+
+	reader := cbrotli.NewReader(resp.Body)
+	defer reader.Close()
+
+	body, err := io.ReadAll(reader)
+	require.NoError(t, err)
+	assert.Equal(t, dummyDoc, string(body))
+}