dcl-ops-lib 9.3.1 → 9.4.0

package/index.d.ts

@@ -23,6 +23,7 @@ export * from "./lambda";
 export * from "./network";
 export * from "./nlb";
 export * from "./prometheus";
+export * from "./rateLimiting";
 export * from "./scheduledTaskBase";
 export * from "./secrets";
 export * from "./slack";

package/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./lambda"), exports);
 __exportStar(require("./network"), exports);
 __exportStar(require("./nlb"), exports);
 __exportStar(require("./prometheus"), exports);
+__exportStar(require("./rateLimiting"), exports);
 __exportStar(require("./scheduledTaskBase"), exports);
 __exportStar(require("./secrets"), exports);
 __exportStar(require("./slack"), exports);

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "dcl-ops-lib",
-  "version": "9.3.1",
+  "version": "9.4.0",
   "scripts": {
     "build": "tsc && cp bin/* . && node test.js",
+    "test": "tsc -p tsconfig.test.json && ENVIRONMENT=dev node bin-test/rateLimiting.test.js",
     "clean": "rm *.d.ts *.js *.js.map"
   },
   "files": [

package/rateLimiting.d.ts

@@ -0,0 +1,84 @@
+import * as cf from "@pulumi/cloudflare";
+export type RateLimitRule = {
+    /** The maximum number of requests allowed within the period. */
+    requestsPerPeriod: number;
+    /** The time window in seconds to count requests (10, 60, 120, 300, or 600). */
+    period: 10 | 60 | 120 | 300 | 600;
+    /** The action to take when the threshold is exceeded. */
+    action: "block" | "challenge" | "managed_challenge" | "js_challenge" | "log";
+    /**
+     * How long (in seconds) to block requests after the threshold is exceeded.
+     * Required when action is "block". Must be >= period. Ignored for other actions.
+     */
+    mitigationTimeout?: number;
+    /**
+     * A Cloudflare Firewall Rules expression to match requests.
+     * The hostname condition is prepended automatically.
+     * Examples:
+     *   - `http.request.uri.path eq "/login"` — matches a single path
+     *   - `http.request.uri.path matches "^/api/"` — matches a path prefix with regex
+     *   - `http.request.uri.path eq "/login" and http.request.method eq "POST"` — path + method
+     *
+     * If not provided, matches all traffic for the domain.
+     * @see https://developers.cloudflare.com/ruleset-engine/rules-language/
+     */
+    expression?: string;
+    /** Optional description for the rule. */
+    description?: string;
+    /**
+     * Whether to count all requests (including those served from CF cache) towards
+     * the rate limit threshold. Defaults to true.
+     *
+     * When false, only requests forwarded to the origin count. An attacker hitting
+     * a cached endpoint would not trigger the rate limit.
+     */
+    countCachedRequests?: boolean;
+};
+export type ServiceRateLimitConfig = {
+    /** The service name, used for resource naming and descriptions. */
+    serviceName: string;
+    /** The public hostname for this service (e.g. "my-service.decentraland.org"). */
+    hostname: string;
+    /** The rate limiting rules for this service. */
+    rules: RateLimitRule[];
+};
+/**
+ * Validates a single rate limit rule and returns a Cloudflare Ruleset rule object.
+ *
+ * @param globalIndex - A unique index across all rules in the ruleset, used for
+ *   resource naming and error messages.
+ * @throws if the rule configuration is invalid.
+ * @internal Exported for testing.
+ */
+export declare function buildRulesetRule(serviceName: string, hostname: string, rule: RateLimitRule, globalIndex: number): {
+    action: string;
+    expression: string;
+    description: string;
+    enabled: boolean;
+    ratelimit: {
+        characteristics: string[];
+        period: 120 | 60 | 10 | 300 | 600;
+        requestsPerPeriod: number;
+        mitigationTimeout: number;
+        requestsToOrigin: boolean;
+    };
+};
+/** @internal Reset module state for testing. */
+export declare function _resetForTesting(): void;
+/**
+ * Creates a single zone-level Cloudflare Ruleset containing rate limiting rules
+ * aggregated from all services. This must be called from a centralized Pulumi
+ * stack — not from individual service stacks — because Cloudflare only supports
+ * one `http_ratelimit` phase ruleset per zone.
+ *
+ * This function must only be called once per Pulumi program. A second call will
+ * throw to prevent silent overwrites of the zone-level ruleset.
+ *
+ * Rules are ordered so that rules with a custom expression (narrower scope) are
+ * evaluated before hostname-only rules (broader scope). Within each group, the
+ * original insertion order is preserved.
+ *
+ * @param services - Array of service rate limiting configurations to aggregate.
+ * @returns The created Ruleset, or undefined if no services have rate limiting rules.
+ */
+export declare function createZoneRateLimitRuleset(services: ServiceRateLimitConfig[]): Promise<cf.Ruleset | undefined>;

package/rateLimiting.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createZoneRateLimitRuleset = exports._resetForTesting = exports.buildRulesetRule = void 0;
+const cf = require("@pulumi/cloudflare");
+const domain_1 = require("./domain");
+const cloudflare_1 = require("./cloudflare");
+const ACTION_MAP = {
+    block: "block",
+    challenge: "challenge",
+    managed_challenge: "managedChallenge",
+    js_challenge: "jsChallenge",
+    log: "log",
+};
+/**
+ * Matches a valid hostname: labels separated by dots, each label alphanumeric
+ * or hyphen (no leading/trailing hyphen), ending in a TLD of 2+ chars.
+ */
+const HOSTNAME_RE = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/i;
+const MAX_RULES_PER_ZONE = 100;
+/**
+ * Validates a single rate limit rule and returns a Cloudflare Ruleset rule object.
+ *
+ * @param globalIndex - A unique index across all rules in the ruleset, used for
+ *   resource naming and error messages.
+ * @throws if the rule configuration is invalid.
+ * @internal Exported for testing.
+ */
+function buildRulesetRule(serviceName, hostname, rule, globalIndex) {
+    if (!hostname || !HOSTNAME_RE.test(hostname)) {
+        throw new Error(`Service "${serviceName}" rate limit rule ${globalIndex}: invalid hostname "${hostname}". ` +
+            `Must be a valid domain (e.g. "my-service.decentraland.org").`);
+    }
+    if (!rule.requestsPerPeriod || rule.requestsPerPeriod < 1) {
+        throw new Error(`Service "${serviceName}" rate limit rule ${globalIndex}: requestsPerPeriod must be >= 1, got ${rule.requestsPerPeriod}.`);
+    }
+    if (rule.action === "block") {
+        if (rule.mitigationTimeout == null) {
+            throw new Error(`Service "${serviceName}" rate limit rule ${globalIndex}: mitigationTimeout is required when action is "block".`);
+        }
+        if (rule.mitigationTimeout < rule.period) {
+            throw new Error(`Service "${serviceName}" rate limit rule ${globalIndex}: mitigationTimeout (${rule.mitigationTimeout}) must be >= period (${rule.period}).`);
+        }
+    }
+    const hostnameCondition = `(http.host eq "${hostname}")`;
+    const expression = rule.expression
+        ? `${hostnameCondition} and (${rule.expression})`
+        : hostnameCondition;
+    return {
+        action: ACTION_MAP[rule.action],
+        expression,
+        description: rule.description || `Rate limit rule ${globalIndex} (auto-created by services-pipeline for ${serviceName})`,
+        enabled: true,
+        ratelimit: {
+            characteristics: ["cf.colo.id", "ip.src"],
+            period: rule.period,
+            requestsPerPeriod: rule.requestsPerPeriod,
+            mitigationTimeout: rule.action === "block" ? rule.mitigationTimeout : 0,
+            requestsToOrigin: rule.countCachedRequests === false,
+        },
+    };
+}
+exports.buildRulesetRule = buildRulesetRule;
+let rulesetCreated = false;
+/** @internal Reset module state for testing. */
+function _resetForTesting() {
+    rulesetCreated = false;
+}
+exports._resetForTesting = _resetForTesting;
+/**
+ * Creates a single zone-level Cloudflare Ruleset containing rate limiting rules
+ * aggregated from all services. This must be called from a centralized Pulumi
+ * stack — not from individual service stacks — because Cloudflare only supports
+ * one `http_ratelimit` phase ruleset per zone.
+ *
+ * This function must only be called once per Pulumi program. A second call will
+ * throw to prevent silent overwrites of the zone-level ruleset.
+ *
+ * Rules are ordered so that rules with a custom expression (narrower scope) are
+ * evaluated before hostname-only rules (broader scope). Within each group, the
+ * original insertion order is preserved.
+ *
+ * @param services - Array of service rate limiting configurations to aggregate.
+ * @returns The created Ruleset, or undefined if no services have rate limiting rules.
+ */
+async function createZoneRateLimitRuleset(services) {
+    if (services.length === 0)
+        return undefined;
+    if (rulesetCreated) {
+        throw new Error("createZoneRateLimitRuleset has already been called in this program. " +
+            "Cloudflare only supports one http_ratelimit phase ruleset per zone.");
+    }
+    rulesetCreated = true;
+    const zoneId = await (0, cloudflare_1.getZoneId)();
+    let globalIndex = 0;
+    const rules = services.flatMap((svc) => svc.rules.map((rule) => buildRulesetRule(svc.serviceName, svc.hostname, rule, globalIndex++)));
+    if (rules.length > MAX_RULES_PER_ZONE) {
+        throw new Error(`Total rate limiting rules (${rules.length}) exceeds the maximum of ${MAX_RULES_PER_ZONE} per zone. ` +
+            `Reduce the number of rules across services.`);
+    }
+    // Sort: rules with a custom expression (narrower scope) first, then
+    // hostname-only rules (broader scope). Preserves relative order within
+    // each group via stable sort.
+    const sorted = rules.sort((a, b) => {
+        const aHasExpr = a.expression.includes(" and ");
+        const bHasExpr = b.expression.includes(" and ");
+        if (aHasExpr === bHasExpr)
+            return 0;
+        return aHasExpr ? -1 : 1;
+    });
+    return new cf.Ruleset(`zone-rate-limits-${domain_1.publicDomain}`, {
+        zoneId,
+        name: `Rate limits for ${domain_1.publicDomain}`,
+        description: `Auto-created by services-pipeline — aggregated rate limiting rules for all services`,
+        kind: "zone",
+        phase: "http_ratelimit",
+        rules: sorted,
+    });
+}
+exports.createZoneRateLimitRuleset = createZoneRateLimitRuleset;
+//# sourceMappingURL=rateLimiting.js.map