Skip to content

Commit 64736df

Browse files
TomokiMiyauciTomokiMiyauci
committed
docs: add READMe
1 parent 3f10d67 commit 64736df

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# compression-middleware
2+
3+
[![deno land](http://img.shields.io/badge/available%20on-deno.land/x-lightgrey.svg?logo=deno)](https://deno.land/x/compression_middleware)
4+
[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/compression_middleware/mod.ts)
5+
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/httpland/compression-middleware)](https://github.com/httpland/compression-middleware/releases)
6+
[![codecov](https://codecov.io/github/httpland/compression-middleware/branch/main/graph/badge.svg)](https://codecov.io/gh/httpland/compression-middleware)
7+
[![GitHub](https://img.shields.io/github/license/httpland/compression-middleware)](https://github.com/httpland/compression-middleware/blob/main/LICENSE)
8+
9+
[![test](https://github.com/httpland/compression-middleware/actions/workflows/test.yaml/badge.svg)](https://github.com/httpland/compression-middleware/actions/workflows/test.yaml)
10+
[![NPM](https://nodei.co/npm/@httpland/compression-middleware.png?mini=true)](https://nodei.co/npm/@httpland/compression-middleware/)
11+
12+
HTTP compression middleware.
13+
14+
Compresses HTTP Content(body).
15+
16+
Compliant with
17+
[RFC 9110, 8.4. Content-Encoding](https://www.rfc-editor.org/rfc/rfc9110.html#section-8.4).
18+
19+
## Middleware
20+
21+
For a definition of Universal HTTP middleware, see the
22+
[http-middleware](https://github.com/httpland/http-middleware) project.
23+
24+
## Usage
25+
26+
Middleware convert message body and adds the `Content-Encoding` header to the
27+
response.
28+
29+
Also, safely add `Accept-Encoding` to the `vary` header in response.
30+
31+
```ts
32+
import { compression } from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";
33+
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
34+
35+
const middleware = compression();
36+
const request = new Request("test:", {
37+
headers: {
38+
"accept-encoding": "deflate;q=0.5, gzip;q=1.0",
39+
},
40+
});
41+
42+
const response = await middleware(
43+
request,
44+
() => new Response("<body>"),
45+
);
46+
47+
assertEquals(await response.text(), "<gzip:body>");
48+
assertEquals(response.headers.get("content-encoding"), "gzip");
49+
```
50+
51+
yield:
52+
53+
```http
54+
Content-Encoding: <encoding>
55+
Vary: accept-encoding
56+
```
57+
58+
## Additional encoding
59+
60+
By default, middleware supports the following encodings:
61+
62+
- gzip
63+
- deflate
64+
65+
You can add supported encoding.
66+
67+
There are two ways to add encodings:
68+
69+
- Encoding map
70+
- Encoder list
71+
72+
In either style, the result is the same.
73+
74+
When encoding is added, a shallow merge is performed in favor of user-defined.
75+
76+
## Encoding map
77+
78+
Encoding map defines a map of encoding formats and
79+
[encode functions](#encode-api) .
80+
81+
Example of adding `brotli` encoding:
82+
83+
```ts
84+
import {
85+
compression,
86+
type Encode,
87+
type EncodingMap,
88+
} from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";
89+
90+
declare const encodeBr: Encode;
91+
const encodingMap: EncodingMap = { br: encodeBr };
92+
93+
const middleware = compression(encodingMap);
94+
```
95+
96+
## Encoder list
97+
98+
Encoder list defines a list of `Encoder`.
99+
100+
`Encoder` is a following structured object:
101+
102+
| Name | Type | Description |
103+
| -------- | --------------------- | ---------------- |
104+
| encoding | `string` | Encoding format. |
105+
| encode | [Encode](#encode-api) | Encode stream. |
106+
107+
Example of adding `brotli` encoding:
108+
109+
```ts
110+
import {
111+
compression,
112+
type Encoder,
113+
type EncodingMap,
114+
} from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";
115+
116+
declare const encodeBr: Encode;
117+
const Br: Encoder = { encoding: "br", encode: encodeBr };
118+
119+
const middleware = compression([Br]);
120+
```
121+
122+
## Encode API
123+
124+
`Encode` is an API for converting content.
125+
126+
```ts
127+
interface Encode {
128+
(stream: ReadableStream<Unit8Array>): BodyInit | Promise<BodyInit>;
129+
}
130+
```
131+
132+
## Compressible
133+
134+
Filter media types to be compressed according to the following
135+
[specifications](https://www.rfc-editor.org/rfc/rfc9110.html#section-8.4-8):
136+
137+
> If the media type includes an inherent encoding, such as a data format that is
138+
> always compressed, then that encoding would not be restated in
139+
> Content-Encoding even if it happens to be the same algorithm as one of the
140+
> content codings.
141+
142+
Determine from the `Content-Type` response header whether the representation is
143+
compressible.
144+
145+
For example, image media such as `image/jpag` is not compressible because it is
146+
already compressed.
147+
148+
## Effects
149+
150+
Middleware may make changes to the following elements of the HTTP message.
151+
152+
- HTTP Content
153+
- HTTP Headers
154+
- Content-Encoding
155+
- Vary
156+
157+
## Conditions
158+
159+
Middleware is executed if all of the following conditions are met:
160+
161+
- Encoding matches `Accept-Encoding` header in request
162+
- `Content-Type` header exists in response
163+
- `Content-Encoding` header does not exists in response
164+
- `Cache-Control` header does not have `no-transform` directive in response
165+
- Response body exists
166+
- Response body is readable
167+
- Response body is [compressible](#compressible)
168+
169+
## License
170+
171+
Copyright © 2023-present [httpland](https://github.com/httpland).
172+
173+
Released under the [MIT](./LICENSE) license

0 commit comments

Comments
 (0)