@arcjet/decorate 1.0.0-alpha.9 → 1.0.0-beta.10

package/README.md

@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -18,53 +18,79 @@
 
 [Arcjet][arcjet] utilities for decorating responses with information.
 
-## Installation
+- [npm package (`@arcjet/decorate`)](https://www.npmjs.com/package/@arcjet/decorate)
+- [GitHub source code (`decorate/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/decorate)
 
-```shell
-npm install -S @arcjet/decorate
+## 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`][ietf-rate-limit] for
+more info.
+
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/decorate
 ```
 
 ## Example
 
 ```ts
-import arcjet, { fixedWindow } from "@arcjet/next";
+import http from "node:http";
 import { setRateLimitHeaders } from "@arcjet/decorate";
-import { NextApiRequest, NextApiResponse } from "next";
+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: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
+  key: arcjetKey,
   rules: [
-    // Create a fixed window rate limit. Other algorithms are supported.
-    fixedWindow({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      window: "1m", // 1 min fixed window
-      max: 1, // allow a single request
-    }),
+    // Shield protects your app from common attacks.
+    // Use `DRY_RUN` instead of `LIVE` to only log.
+    shield({ mode: "LIVE" }),
   ],
 });
 
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse,
+const server = http.createServer(async function (
+  request: http.IncomingMessage,
+  response: http.ServerResponse,
 ) {
-  const decision = await aj.protect(req);
+  const decision = await aj.protect(request);
 
-  setRateLimitHeaders(res, decision);
+  setRateLimitHeaders(response, decision);
 
   if (decision.isDenied()) {
-    return res.status(429).json({
-      error: "Too Many Requests",
-      reason: decision.reason,
-    });
+    response.writeHead(403, { "Content-Type": "application/json" });
+    response.end(JSON.stringify({ message: "Forbidden" }));
+    return;
   }
 
-  res.status(200).json({ name: "Hello world" });
-}
+  response.writeHead(200, { "Content-Type": "application/json" });
+  response.end(JSON.stringify({ message: "Hello world" }));
+});
+
+server.listen(8000);
 ```
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
 [arcjet]: https://arcjet.com
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[ietf-rate-limit]: https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-08

package/index.d.ts

@@ -1,4 +1,4 @@
-import { ArcjetDecision } from "@arcjet/protocol";
+import type { ArcjetDecision } from "@arcjet/protocol";
 interface HeaderLike {
     has(name: string): boolean;
     get(name: string): string | null;

package/index.js

@@ -1,4 +1,5 @@
-import logger from '@arcjet/logger';
+import format from '@arcjet/sprintf';
+import '@arcjet/protocol';
 
 function isHeaderLike(value) {
     if ("has" in value &&
@@ -89,14 +90,14 @@ function setRateLimitHeaders(value, decision) {
         const policies = new Map();
         for (const reason of rateLimitReasons) {
             if (policies.has(reason.max)) {
-                logger.error("Invalid rate limit policy—two policies should not share the same limit");
+                console.error("Invalid rate limit policy—two policies should not share the same limit");
                 return;
             }
             if (typeof reason.max !== "number" ||
                 typeof reason.window !== "number" ||
                 typeof reason.remaining !== "number" ||
                 typeof reason.reset !== "number") {
-                logger.error("Invalid rate limit encountered: %s", reason);
+                console.error(format("Invalid rate limit encountered: %o", reason));
                 return;
             }
             policies.set(reason.max, reason.window);
@@ -116,7 +117,7 @@ function setRateLimitHeaders(value, decision) {
                 typeof decision.reason.window !== "number" ||
                 typeof decision.reason.remaining !== "number" ||
                 typeof decision.reason.reset !== "number") {
-                logger.error("Invalid rate limit encountered: %s", decision.reason);
+                console.error(format("Invalid rate limit encountered: %o", decision.reason));
                 return;
             }
             limit = toLimitString(decision.reason);
@@ -128,10 +129,10 @@ function setRateLimitHeaders(value, decision) {
     }
     if (isHeaderLike(value)) {
         if (value.has("RateLimit")) {
-            logger.warn("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.get("RateLimit"), limit);
+            console.warn(format("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.get("RateLimit"), limit));
         }
         if (value.has("RateLimit-Policy")) {
-            logger.warn("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.get("RateLimit-Policy"), limit);
+            console.warn(format("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.get("RateLimit-Policy"), limit));
         }
         value.set("RateLimit", limit);
         value.set("RateLimit-Policy", policy);
@@ -140,10 +141,10 @@ function setRateLimitHeaders(value, decision) {
     }
     if (isResponseLike(value)) {
         if (value.headers.has("RateLimit")) {
-            logger.warn("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.headers.get("RateLimit"), limit);
+            console.warn(format("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.headers.get("RateLimit"), limit));
         }
         if (value.headers.has("RateLimit-Policy")) {
-            logger.warn("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.headers.get("RateLimit-Policy"), limit);
+            console.warn(format("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.headers.get("RateLimit-Policy"), limit));
         }
         value.headers.set("RateLimit", limit);
         value.headers.set("RateLimit-Policy", policy);
@@ -152,21 +153,21 @@ function setRateLimitHeaders(value, decision) {
     }
     if (isOutgoingMessageLike(value)) {
         if (value.headersSent) {
-            logger.error("Headers have already been sent—cannot set RateLimit header");
+            console.error("Headers have already been sent—cannot set RateLimit header");
             return;
         }
         if (value.hasHeader("RateLimit")) {
-            logger.warn("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.getHeader("RateLimit"), limit);
+            console.warn(format("Response already contains `RateLimit` header\n  Original: %s\n  New: %s", value.getHeader("RateLimit"), limit));
         }
         if (value.hasHeader("RateLimit-Policy")) {
-            logger.warn("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.getHeader("RateLimit-Policy"), limit);
+            console.warn(format("Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s", value.getHeader("RateLimit-Policy"), limit));
         }
         value.setHeader("RateLimit", limit);
         value.setHeader("RateLimit-Policy", policy);
         // The response was handled
         return;
     }
-    logger.debug("Cannot determine if response is Response or OutgoingMessage type");
+    console.debug("Cannot determine if response is Response or OutgoingMessage type");
 }
 
 export { setRateLimitHeaders };

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@arcjet/decorate",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.10",
   "description": "Arcjet utilities for decorating responses with information",
+  "keywords": [
+    "arcjet",
+    "decore",
+    "utility",
+    "util"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -25,33 +31,29 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "LICENSE",
-    "README.md",
-    "*.js",
-    "*.d.ts",
-    "*.ts",
-    "!*.config.js"
+    "index.d.ts",
+    "index.js"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build",
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
-    "pretest": "npm run build",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
+    "prepublishOnly": "npm run build",
+    "test-api": "node --test",
+    "test-coverage": "node --experimental-test-coverage --test",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/logger": "1.0.0-alpha.9",
-    "@arcjet/protocol": "1.0.0-alpha.9"
+    "@arcjet/protocol": "1.0.0-beta.10",
+    "@arcjet/sprintf": "1.0.0-beta.10"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-alpha.9",
-    "@arcjet/rollup-config": "1.0.0-alpha.9",
-    "@arcjet/tsconfig": "1.0.0-alpha.9",
-    "@jest/globals": "29.7.0",
-    "@rollup/wasm-node": "4.12.0",
+    "@arcjet/eslint-config": "1.0.0-beta.10",
+    "@arcjet/rollup-config": "1.0.0-beta.10",
+    "@arcjet/tsconfig": "1.0.0-beta.10",
+    "@rollup/wasm-node": "4.46.2",
     "@types/node": "18.18.0",
-    "jest": "29.7.0",
-    "typescript": "5.3.3"
+    "eslint": "9.32.0",
+    "typescript": "5.9.2"
   },
   "publishConfig": {
     "access": "public",

package/index.ts

@@ -1,312 +0,0 @@
-import logger from "@arcjet/logger";
-import {
-  ArcjetDecision,
-  ArcjetRateLimitReason,
-  ArcjetReason,
-  ArcjetRuleResult,
-} from "@arcjet/protocol";
-
-interface HeaderLike {
-  has(name: string): boolean;
-  get(name: string): string | null;
-  set(name: string, value: string): void;
-}
-
-interface ResponseLike {
-  // If this is defined, we can expect to be working with a `Response` or
-  // `NextResponse`.
-  headers: HeaderLike;
-}
-
-interface OutgoingMessageLike {
-  headersSent: boolean;
-  hasHeader: (name: string) => boolean;
-  getHeader: (name: string) => number | string | string[] | undefined;
-  setHeader: (
-    name: string,
-    value: number | string | ReadonlyArray<string>,
-  ) => unknown;
-}
-
-export interface ArcjetCanDecorate {
-  // If these are defined, we can expect to be working with `Headers` directly
-  has?: (name: string) => boolean;
-  get?: (name: string) => string | null;
-  set?: (name: string, value: string) => void;
-
-  // If this is defined, we can expect to be working with a `Response` or
-  // `NextResponse`.
-  headers?: HeaderLike;
-
-  // Otherwise, we'll be working with an `http.OutgoingMessage` and we'll need
-  // to use these values.
-  headersSent?: boolean;
-  hasHeader?: (name: string) => boolean;
-  getHeader?: (name: string) => number | string | string[] | undefined;
-  setHeader?: (
-    name: string,
-    value: number | string | ReadonlyArray<string>,
-  ) => unknown;
-}
-
-function isHeaderLike(value: ArcjetCanDecorate): value is HeaderLike {
-  if (
-    "has" in value &&
-    typeof value.has === "function" &&
-    "get" in value &&
-    typeof value.get === "function" &&
-    "set" in value &&
-    typeof value.set === "function"
-  ) {
-    return true;
-  }
-
-  return false;
-}
-
-function isResponseLike(value: ArcjetCanDecorate): value is ResponseLike {
-  if (typeof value.headers === "undefined") {
-    return false;
-  }
-
-  return isHeaderLike(value.headers);
-}
-
-function isOutgoingMessageLike(
-  response: ArcjetCanDecorate,
-): response is OutgoingMessageLike {
-  if (typeof response.headersSent !== "boolean") {
-    return false;
-  }
-
-  if (typeof response.hasHeader !== "function") {
-    return false;
-  }
-
-  if (typeof response.getHeader !== "function") {
-    return false;
-  }
-
-  if (typeof response.setHeader !== "function") {
-    return false;
-  }
-
-  return true;
-}
-
-function sortByLowestMax(
-  [maxA, _windowA]: [number, number],
-  [maxB, _windowB]: [number, number],
-) {
-  return maxA - maxB;
-}
-
-function toPolicyString([max, window]: [number, number]) {
-  return `${max};w=${window}`;
-}
-
-function toLimitString({
-  max,
-  remaining,
-  reset,
-}: {
-  max: number;
-  remaining: number;
-  reset: number;
-}) {
-  return `limit=${max}, remaining=${remaining}, reset=${reset}`;
-}
-
-function extractReason(result: ArcjetRuleResult): ArcjetReason {
-  return result.reason;
-}
-
-function isRateLimitReason(
-  reason: ArcjetReason,
-): reason is ArcjetRateLimitReason {
-  return reason.isRateLimit();
-}
-
-function nearestLimit(
-  current: ArcjetRateLimitReason,
-  next: ArcjetRateLimitReason,
-) {
-  if (current.remaining < next.remaining) {
-    return current;
-  }
-
-  if (current.remaining > next.remaining) {
-    return next;
-  }
-
-  // Reaching here means `remaining` is equal so prioritize closest reset
-  if (current.reset < next.reset) {
-    return current;
-  }
-
-  if (current.reset > next.reset) {
-    return next;
-  }
-
-  // Reaching here means that `remaining` and `reset` are equal, so prioritize
-  // the smallest `max`
-  if (current.max < next.max) {
-    return current;
-  }
-
-  // All else equal, just return the next item in the list
-  return next;
-}
-
-/**
- * Decorates an object with `RateLimit` and `RateLimit-Policy` headers based
- * on an {@link ArcjetDecision} and conforming to the [Rate Limit fields for
- * HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html)
- * draft specification.
- *
- * @param value The object to decorate—must be similar to {@link Headers}, {@link Response} or
- * {@link OutgoingMessage}.
- * @param decision The {@link ArcjetDecision} that was made by calling `protect()` on the SDK.
- */
-export function setRateLimitHeaders(
-  value: ArcjetCanDecorate,
-  decision: ArcjetDecision,
-) {
-  const rateLimitReasons = decision.results
-    .map(extractReason)
-    .filter(isRateLimitReason);
-
-  let policy: string;
-  let limit: string;
-  if (rateLimitReasons.length > 0) {
-    const policies = new Map<number, number>();
-    for (const reason of rateLimitReasons) {
-      if (policies.has(reason.max)) {
-        logger.error(
-          "Invalid rate limit policy—two policies should not share the same limit",
-        );
-        return;
-      }
-
-      if (
-        typeof reason.max !== "number" ||
-        typeof reason.window !== "number" ||
-        typeof reason.remaining !== "number" ||
-        typeof reason.reset !== "number"
-      ) {
-        logger.error("Invalid rate limit encountered: %s", reason);
-        return;
-      }
-
-      policies.set(reason.max, reason.window);
-    }
-
-    const rl = rateLimitReasons.reduce(nearestLimit);
-
-    limit = toLimitString(rl);
-    policy = Array.from(policies.entries())
-      .sort(sortByLowestMax)
-      .map(toPolicyString)
-      .join(", ");
-  } else {
-    // For cached decisions, we may not have rule results, but we'd still have
-    // the top-level reason.
-    if (isRateLimitReason(decision.reason)) {
-      if (
-        typeof decision.reason.max !== "number" ||
-        typeof decision.reason.window !== "number" ||
-        typeof decision.reason.remaining !== "number" ||
-        typeof decision.reason.reset !== "number"
-      ) {
-        logger.error("Invalid rate limit encountered: %s", decision.reason);
-        return;
-      }
-
-      limit = toLimitString(decision.reason);
-      policy = toPolicyString([decision.reason.max, decision.reason.window]);
-    } else {
-      return;
-    }
-  }
-
-  if (isHeaderLike(value)) {
-    if (value.has("RateLimit")) {
-      logger.warn(
-        "Response already contains `RateLimit` header\n  Original: %s\n  New: %s",
-        value.get("RateLimit"),
-        limit,
-      );
-    }
-    if (value.has("RateLimit-Policy")) {
-      logger.warn(
-        "Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s",
-        value.get("RateLimit-Policy"),
-        limit,
-      );
-    }
-
-    value.set("RateLimit", limit);
-    value.set("RateLimit-Policy", policy);
-
-    // The response was handled
-    return;
-  }
-
-  if (isResponseLike(value)) {
-    if (value.headers.has("RateLimit")) {
-      logger.warn(
-        "Response already contains `RateLimit` header\n  Original: %s\n  New: %s",
-        value.headers.get("RateLimit"),
-        limit,
-      );
-    }
-    if (value.headers.has("RateLimit-Policy")) {
-      logger.warn(
-        "Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s",
-        value.headers.get("RateLimit-Policy"),
-        limit,
-      );
-    }
-
-    value.headers.set("RateLimit", limit);
-    value.headers.set("RateLimit-Policy", policy);
-
-    // The response was handled
-    return;
-  }
-
-  if (isOutgoingMessageLike(value)) {
-    if (value.headersSent) {
-      logger.error(
-        "Headers have already been sent—cannot set RateLimit header",
-      );
-      return;
-    }
-
-    if (value.hasHeader("RateLimit")) {
-      logger.warn(
-        "Response already contains `RateLimit` header\n  Original: %s\n  New: %s",
-        value.getHeader("RateLimit"),
-        limit,
-      );
-    }
-
-    if (value.hasHeader("RateLimit-Policy")) {
-      logger.warn(
-        "Response already contains `RateLimit-Policy` header\n  Original: %s\n  New: %s",
-        value.getHeader("RateLimit-Policy"),
-        limit,
-      );
-    }
-
-    value.setHeader("RateLimit", limit);
-    value.setHeader("RateLimit-Policy", policy);
-
-    // The response was handled
-    return;
-  }
-
-  logger.debug(
-    "Cannot determine if response is Response or OutgoingMessage type",
-  );
-}