@httpland/reporting-middleware

reporting-middleware

HTTP reporting middleware.

Compliant with Reporting API v1 and Reporting API v0.

Middleware

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

reportingEndpoints

Middleware adds the Reporting-Endpoints header to the response.

import {
  type Handler,
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = reportingEndpoints({
  default: "https://test.test/report",
});
const response = await middleware(request, handler);

assert(response.headers.has("reporting-endpoints"));

yield:

Reporting-Endpoints: default="https://test.test/report"

Endpoints

Specifying endpoints is mandatory.

Endpoints must be specified as pairs consisting of key and value.

The key is the endpoint-name and the value is the endpoint-url.

The following formats are supported:

• Record
• Entries

The result of serialization is the same for both formats.

Record

Supports record format.

import {
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";

const middleware = reportingEndpoints({
  default: "https://test.test/report",
  csp: "https://test.test/csp",
});

Serialized as an ordered map.

Note that the order of the properties is reflected as is.

Entries

Supports entires format (an array of entry).

import {
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";

const middleware = reportingEndpoints([
  ["default", "https://test.test/report"],
  ["csp", "https://test.test/csp"],
]);

Serialization error

If serialization fails, an error may be thrown.

Cases that throw an error are as follows:

• Key is invalid <member-key>
• Value is invalid <URI-reference>

import { reportingEndpoints } from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() =>
  reportingEndpoints({ "<member-key>": "<invalid:URI-reference>" })
);
assertThrows(() =>
  reportingEndpoints({ "<invalid:member-key>": "<URI-reference>" })
);

Conditions

Middleware will execute if all of the following conditions are met:

• Reporting-Endpoints header does not exist in response

Effects

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

• HTTP Headers
  • Reporting-Endpoints

reportTo

Middleware adds the Report-To header to the response.

import {
  type Handler,
  reportTo,
} from "https://deno.land/x/reporting_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = reportTo([
  {
    endpoints: [{ url: "https://test.test/report" }],
    max_age: 86400,
  },
]);
const response = await middleware(request, handler);

assert(response.headers.has("report-to"));

yield:

Report-To: {"endpoints",[{"url":"https://test.test/report"}],"max_age":86400}

Endpoint group

The middleware factory requires an array of endpoint group.

Endpoint group is a structure with the following fields:

Name	Type	Required	Description
endpoints	Endpoint[]	✅	Endpoint list.
max_age	number	✅	Endpoint group’s lifetime
group	string	-	Endpoint group name.
include_subdomains	boolean	-	Whether to enable this endpoint group for all subdomains of the current origin host.

Endpoint

Endpoint is following structure:

Name	Type	Required	Description
url	string	✅	The location of the endpoint.
priority	number	-	Number that defines which failover class the endpoint belongs to.
weight	number	-	Number that defines load balancing for the failover class that the endpoint belongs to.

Serialization error

The endpoint group array is serialized.

If serialization fails, an error may be thrown.

Cases that throw an error are as follows:

• Numeric field is not a non-negative integer

import { reportTo } from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => reportTo([{ max_age: NaN, endpoints: [] }]));
assertThrows(() =>
  reportTo([{
    max_age: 0,
    endpoints: [{ url: "https://test.test/report", priority: 1.2 }],
  }])
);

Conditions

Middleware will execute if all of the following conditions are met:

• Report-To header does not exist in response

Effects

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

• HTTP Headers
  • Report-To

API

All APIs can be found in the deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license