pingap-plugin 0.16.0

Plugin for pingap
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# accept_encoding

Rewrites the client's `Accept-Encoding` header into a canonical form before the
request is routed, so upstreams and the cache see a small, predictable set of
values instead of whatever the browser happened to send.

Two problems this solves:

- **Cache fragmentation.** `gzip, deflate, br` and `br, gzip` are the same thing
  to an origin but different cache variants. Rewriting both to `br` collapses
  them.
- **Unwanted encodings.** An upstream that supports zstd may produce responses
  Pingap would rather compress itself, or that a middlebox cannot handle.

- **Step:** `early_request` (fixed — it must run before routing and caching)
- **Registered as:** `accept_encoding`

## Configuration

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `category` | string | — | Must be `accept_encoding`. |
| `encodings` | string \| string[] | `""` | Encodings to keep, **in priority order**: a comma-separated string (`"zstd, br, gzip"`) or a list (`["zstd", "br", "gzip"]`). |
| `only_one_encoding` | bool | `false` | Keep only the first encoding the client actually accepts. |

The output header is built by walking `encodings` in order and keeping those the
client listed, so the resulting order is yours, not the client's. Matching is
done on comma/`;` token boundaries and honours `q=0`, so `x-gzip` does not match
`gzip` and `gzip;q=0` is treated as "not acceptable".

If the client sent no `Accept-Encoding` at all the plugin does nothing. If none
of the configured encodings are acceptable, the header is removed entirely.

## Examples

Prefer zstd, then brotli, then gzip, and forward only the best one:

```toml
[plugins.acceptEncoding]
category = "accept_encoding"
encodings = "zstd, br, gzip"
only_one_encoding = true
```

| Client sends | Forwarded |
| --- | --- |
| `gzip, deflate, br` | `br` |
| `zstd, gzip` | `zstd` |
| `deflate` | *(header removed)* |
| `br;q=0, gzip` | `gzip` |

Keep the full ordered list instead (useful when the upstream picks):

```toml
[plugins.acceptEncoding]
category = "accept_encoding"
encodings = "br, gzip"
```

`gzip, br` from the client becomes `br, gzip`.

## Usage notes

- Pair this with [`cache`](cache.md) and add `Accept-Encoding` to the cache key
  headers; the normalised value keeps the number of variants bounded.
- When [`compression`](compression.md) does the compressing, list only the
  encodings Pingap is configured to produce.