compression-middleware



HTTP compression middleware.

Compresses HTTP Content(body).

Compliant with
RFC 9110, 8.4. Content-Encoding
and
RFC 9110, 12.5.3. Accept-Encoding
.

Middleware

For a definition of Universal HTTP middleware, see the
http-middleware project.

Usage

Middleware convert message body and adds the Content-Encoding header to the
response.

Also, safely add Accept-Encoding to the Vary header in response.

``ts
import { compression } from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const middleware = compression();
const request = new Request("test:", {
headers: {
"accept-encoding": "deflate;q=0.5, gzip;q=1.0",
},
});

const response = await middleware(
request,
() => new Response(""),
);

assertEquals(await response.text(), "");
assertEquals(response.headers.get("content-encoding"), "gzip");
`

yield:

`http
Content-Encoding:
Vary: accept-encoding
`

Built-in encoding

Middleware supports the following encodings by default:

- gzip
- deflate

Additional encoding

You can add supported encoding.

There are two ways to add encodings:

- Encoding map
- Encoder list

In either style, the result is the same.

When encoding is added, a shallow merge is performed in favor of user-defined.

Encoding map

Encoding map defines a map of encoding formats and
encode functions .

Example of adding brotli encoding:

`ts
import {
compression,
type Encode,
type EncodingMap,
} from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";

declare const encodeBr: Encode;
const encodingMap: EncodingMap = { br: encodeBr };

const middleware = compression(encodingMap);
`

Encoder list

Encoder list defines a list of Encoder.

Encoder is a following structured object:

| Name | Type | Description |
| -------- | --------------------- | ---------------- |
| encoding | string | Encoding format. |
| encode | Encode | Encode stream. |

Example of adding brotli encoding:

`ts
import {
compression,
type Encode,
type Encoder,
} from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";

declare const encodeBr: Encode;
const Br: Encoder = { encoding: "br", encode: encodeBr };

const middleware = compression([Br]);
`

Encode API

Encode is an API for converting content.

`ts
interface Encode {
(stream: ReadableStream): BodyInit | Promise;
}
`

Compressible

Filter media types to be compressed according to the following
specifications:

> If the media type includes an inherent encoding, such as a data format that is
> always compressed, then that encoding would not be restated in
> Content-Encoding even if it happens to be the same algorithm as one of the
> content codings.

Determine from the Content-Type response header whether the representation is
compressible.

For example, image media such as image/jpag is not compressible because it is
already compressed.

Content-Length

If the Response has a Content-Length header, compression may cause the actual
content length to deviate.

In that case, the Content-Length is recalculated.

`ts
import { compression } from "https://deno.land/x/compression_middleware@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
const middleware = compression();

const response = await middleware(
request,
() =>
new Response("", { headers: { "content-length": "" } }),
);

assertEquals(await response.text(), "");
assertEquals(response.headers.get("content-length"), "");
`

Effects

Middleware may make changes to the following elements of the HTTP message.

- HTTP Content
- HTTP Headers
- Content-Encoding
- Vary
- Content-Length

Conditions

Middleware is executed if all of the following conditions are met:

- Encoding matches Accept-Encoding header in request
- Content-Type header exists in response
- Content-Encoding header does not exists in response
- Cache-Control header does not have no-transform` directive in response
- Response body exists
- Response body is readable
- Response body is compressible

API

All APIs can be found in the
deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license