@arcjet/decorate

Arcjet utilities for decorating responses with information.

• npm package (@arcjet/decorate)
• GitHub source code (decorate/ in arcjet/arcjet-js)

What is this?

This is a utility that lets you decorate responses based on Arcjet decisions. It currently supports experimental rate limit headers.

When should I use this?

You can use this package if you use the rate limit rule and want to set experimental RateLimit-Policy and RateLimit headers. See RateLimit header fields for HTTP on ietf.org for more info.

Install

This package is ESM only. Install with npm in Node.js:

npm install @arcjet/decorate

Use

import http from "node:http";
import { setRateLimitHeaders } from "@arcjet/decorate";
import arcjet, { shield } from "@arcjet/node";

// Get your Arcjet key at <https://app.arcjet.com>.
// Set it as an environment variable instead of hard coding it.
const arcjetKey = process.env.ARCJET_KEY;

if (!arcjetKey) {
  throw new Error("Cannot find `ARCJET_KEY` environment variable");
}

const aj = arcjet({
  key: arcjetKey,
  rules: [
    // Shield protects your app from common attacks.
    // Use `DRY_RUN` instead of `LIVE` to only log.
    shield({ mode: "LIVE" }),
  ],
});

const server = http.createServer(async function (
  request: http.IncomingMessage,
  response: http.ServerResponse,
) {
  const decision = await aj.protect(request);

  setRateLimitHeaders(response, decision);

  if (decision.isDenied()) {
    response.writeHead(403, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ message: "Forbidden" }));
    return;
  }

  response.writeHead(200, { "Content-Type": "application/json" });
  response.end(JSON.stringify({ message: "Hello world" }));
});

server.listen(8000);

API

This package exports the identifier setRateLimitHeaders. There is no default export.

This package exports the TypeScript type ArcjetCanDecorate.

ArcjetCanDecorate

This type represents a value that you can decorate with rate limit headers. It can be anything that looks like Headers (Fetch), OutgoingMessage (Node.js), or Response (Fetch).

Type

type ArcjetCanDecorate = HeaderLike | OutgoingMessageLike | ResponseLike;

setRateLimitHeaders(value, decision)

Decorates a response with rate limit headers based on an Arcjet decision. It sets RateLimit-Policy and RateLimit headers that conform to the Rate Limit fields for HTTP draft specification.

Parameters

• value (ArcjetCanDecorate) — the response or headers object to decorate
• decision (ArcjetDecision) — the decision returned from protect()

Returns

Nothing (undefined).

License

Apache License, Version 2.0 © Arcjet Labs, Inc.