@riebeckite/analytics-cloudflare 0.0.3 → 0.0.6

package/README.md

@@ -1,69 +1,96 @@
-# @riebeckite/analytics-cloudflare
-
-Independent Cloudflare Worker runtime for `@riebeckite/plugin-analytics`. The
-generic plugin contains only browser configuration and analytics contracts; this
-package owns Worker bindings and storage.
-
-## Architecture
-
-`createWorker` is the presentation boundary for a dedicated Worker runtime. It
-validates HTTP input, calls the generic `AnalyticsProvider` contract through the
-runtime-owned `AnalyticsStorage` boundary, and maps unsupported reads to HTTP
-errors. D1 and KV live in infrastructure and are never imported by
-`@riebeckite/plugin-analytics`. The site's only public setting remains the
-generic plugin's `collectorUrl`; bindings and storage selection stay in this
-Worker.
-
-## Choose exactly one storage adapter
-
-- **`D1AnalyticsStorage`**: atomic SQLite upserts into UTC daily aggregate
-  buckets. It supports capture, content page-view totals, popular-content
-  ranking, and date-bucket time ranges. It stores no raw event log. A range is
-  bucket-based: bounds select entire UTC days, not exact sub-day event windows.
-- **`KvAnalyticsStorage`**: minimal best-effort total capture only. KV lacks
-  atomic increment and aggregate listing, so concurrent writes can be lost and
-  `content_page_views` / `popular_content` deliberately throw
-  `UnsupportedAnalyticsQueryError` (the Worker returns `501`). Do not use it
-  for reporting.
-
-There is no default adapter. Bind and construct exactly one in the Worker.
-
-```ts
-import { createWorker, D1AnalyticsStorage } from "@riebeckite/analytics-cloudflare";
-
-export interface Env { ANALYTICS_DB: D1Database; }
-export default { fetch: (request: Request, env: Env) =>
-  createWorker({ storage: new D1AnalyticsStorage(env.ANALYTICS_DB), cors: { allowedOrigins: ["https://www.example.com"] } }).fetch(request),
-};
-```
-
-The Worker binding is constructed per request because `env` exists only in
-`fetch`.
-
-## Endpoints and validation
-
-- `POST /events` accepts only JSON `page_view` payloads with an ISO timestamp,
-  a 1–160 character safe content ID (`[A-Za-z0-9._:-]` after the first
-  alphanumeric character), optional bounded path and language, and no unknown
-  fields. Bodies are limited to 8 KiB.
-- `GET /content/:contentId/page-views?from=&to=` and `GET /popular?limit=&from=&to=`
-  are available only when storage advertises the corresponding capability.
-
-Origin access is deny-by-default. Set explicit `allowedOrigins`; use `"any"`
-only for a consciously public collector. No request IP, cookies, user-agent,
-or fingerprinting data is read or stored. The accepted `path` and `lang` are
-contextual metadata and D1 does not persist them.
-
-## D1 schema and deployment
-
-Workers must not migrate D1 during a request. Apply the included schema before
-deploying:
-
-```sh
-pnpm exec wrangler d1 execute ANALYTICS_DB --file node_modules/@riebeckite/analytics-cloudflare/migrations/0001_analytics_page_views.sql
-pnpm exec wrangler deploy
-```
-
-Copy either `templates/analytics-cloudflare/d1` or `kv` into a separate Worker
-repository/directory. It has its own `main` and must not replace a static
-Riebeckite site's `wrangler.jsonc` or main entry.
+# @riebeckite/analytics-cloudflare
+
+Independent Cloudflare Worker runtime for `@riebeckite/plugin-analytics`. The
+generic plugin contains only browser configuration and analytics contracts; this
+package owns Worker bindings and storage.
+
+[日本語](./README_ja.md)
+
+## Architecture
+
+`createWorker` is the presentation boundary for a dedicated Worker runtime. It
+validates HTTP input, calls the generic `AnalyticsProvider` contract through the
+runtime-owned `AnalyticsStorage` boundary, and maps unsupported reads to HTTP
+errors. D1 and KV live in infrastructure and are never imported by
+`@riebeckite/plugin-analytics`. The site's only public setting remains the
+generic plugin's `collectorUrl`; bindings and storage selection stay in this
+Worker.
+
+## Choose exactly one storage adapter
+
+- **`D1AnalyticsStorage`**: atomic SQLite upserts into UTC daily aggregate
+  buckets. It supports capture, content page-view totals, popular-content
+  ranking, and date-bucket time ranges. It stores no raw event log. A range is
+  bucket-based: bounds select entire UTC days, not exact sub-day event windows.
+- **`KvAnalyticsStorage`**: minimal best-effort total capture only. KV lacks
+  atomic increment and aggregate listing, so concurrent writes can be lost and
+  `content_page_views` / `popular_content` deliberately throw
+  `UnsupportedAnalyticsQueryError` (the Worker returns `501`). Do not use it
+  for reporting.
+
+There is no default adapter. Bind and construct exactly one in the Worker.
+
+```ts
+import { createWorker, D1AnalyticsStorage } from "@riebeckite/analytics-cloudflare";
+
+export interface Env { ANALYTICS_DB: D1Database; }
+export default { fetch: (request: Request, env: Env) =>
+  createWorker({ storage: new D1AnalyticsStorage(env.ANALYTICS_DB), cors: { allowedOrigins: ["https://www.example.com"] } }).fetch(request),
+};
+```
+
+The Worker binding is constructed per request because `env` exists only in
+`fetch`.
+
+## Rate limiting is a mitigation, not authentication
+
+Origin checking is not authentication: any client can forge an allowed `Origin`
+and POST fabricated `page_view` events. The optional `rateLimit` boundary adds a
+fixed-window limit per connecting IP and returns HTTP `429` once exceeded.
+
+- **`D1AnalyticsRateLimiter` / `d1RateLimiter(db, { maxRequests, windowMs })`**:
+  an atomic, isolate-shared D1 counter. Apply
+  `migrations/0002_analytics_rate_limits.sql` before deploying.
+- **`MemoryAnalyticsRateLimiter`**: process-local counters for tests and local
+  development. Worker isolates are short-lived and not shared, so this does not
+  limit a distributed client across isolates. Use D1 for production.
+
+Rate limiting only reduces abuse from a single client; it never fully prevents
+fabricated or distributed page views. Treat collected analytics as untrusted.
+
+```ts
+rateLimit: new D1AnalyticsRateLimiter(env.ANALYTICS_DB, {
+  maxRequests: 60,
+  windowMs: 60_000,
+}),
+```
+
+## Endpoints and validation
+
+- `POST /events` accepts only JSON `page_view` payloads with an ISO timestamp,
+  a 1–160 character trimmed content ID without control characters, optional
+  bounded path and language, and no unknown fields. Bodies are limited to 8 KiB.
+  When a rate limiter is configured, a client over its window limit gets `429`.
+- `GET /content/:contentId/page-views?from=&to=` and `GET /popular?limit=&from=&to=`
+  are available only when storage advertises the corresponding capability.
+
+Origin access is deny-by-default. Set explicit `allowedOrigins`; use `"any"`
+only for a consciously public collector. `path` and `lang` are contextual
+metadata and D1 does not persist them. When a rate limiter is configured, the
+connecting IP (`CF-Connecting-IP`) is read as the rate-limit key; the D1
+limiter stores that key only for the active window.
+
+## D1 schema and deployment
+
+Workers must not migrate D1 during a request. Apply the included schema before
+deploying:
+
+```sh
+pnpm exec wrangler d1 execute ANALYTICS_DB --file node_modules/@riebeckite/analytics-cloudflare/migrations/0001_analytics_page_views.sql
+pnpm exec wrangler d1 execute ANALYTICS_DB --file node_modules/@riebeckite/analytics-cloudflare/migrations/0002_analytics_rate_limits.sql
+pnpm exec wrangler deploy
+```
+
+Copy either `templates/analytics-cloudflare/d1` or `kv` into a separate Worker
+repository/directory. It has its own `main` and must not replace a static
+Riebeckite site's `wrangler.jsonc` or main entry.

package/README_ja.md

@@ -1,16 +1,27 @@
-# @riebeckite/analytics-cloudflare
-
-`@riebeckite/plugin-analytics` のための独立した Cloudflare Worker 実行環境です。汎用プラグインには Cloudflare 固有コードを含めません。
-
-## ストレージは必ず一つ選ぶ
-
-- **D1**: UTC 日単位で集計し、原子的な upsert、コンテンツ別 PV、人気記事、日バケット単位の期間指定に対応します。生イベントは保存しません。時刻境界は日単位であり、サブ日精度ではありません。
-- **KV**: 最小のベストエフォート集計のみです。原子的な加算や集計検索がないため、同時書き込みで欠損し得ます。読み取り API は対応能力として宣言せず、`UnsupportedAnalyticsQueryError` / HTTP 501 を返します。レポーティング用途には D1 を使ってください。
-
-既定アダプターはありません。テンプレートの D1 または KV を一つだけ選び、静的サイト用の `wrangler.jsonc` や main は変更しません。
-
-## プライバシーと検証
-
-`POST /events` は 8 KiB 以下の JSON `page_view` だけを受け入れ、安全な content ID、ISO 時刻、長さを制限した `path` / `lang` を検証します。IP、Cookie、User-Agent、フィンガープリントは読まず保存しません。Origin は既定で拒否されるため、許可するサイト Origin を明示してください。
-
-D1 スキーマはリクエスト中に実行せず、デプロイ前に `migrations/0001_analytics_page_views.sql` を `wrangler d1 execute` で明示適用してください。詳しい設定は各テンプレートの README を参照してください。
+# @riebeckite/analytics-cloudflare
+
+`@riebeckite/plugin-analytics` のための独立した Cloudflare Worker 実行環境です。汎用プラグインには Cloudflare 固有コードを含めません。
+
+[English](./README.md)
+
+## ストレージは必ず一つ選ぶ
+
+- **D1**: UTC 日単位で集計し、原子的な upsert、コンテンツ別 PV、人気記事、日バケット単位の期間指定に対応します。生イベントは保存しません。時刻境界は日単位であり、サブ日精度ではありません。
+- **KV**: 最小のベストエフォート集計のみです。原子的な加算や集計検索がないため、同時書き込みで欠損し得ます。読み取り API は対応能力として宣言せず、`UnsupportedAnalyticsQueryError` / HTTP 501 を返します。レポーティング用途には D1 を使ってください。
+
+既定アダプターはありません。テンプレートの D1 または KV を一つだけ選び、静的サイト用の `wrangler.jsonc` や main は変更しません。
+
+## レート制限は緩和策であり、認証ではない
+
+Origin は認証ではないため、許可された `Origin` を偽装して `page_view` を直接 POST できます。任意の `rateLimit` 境界を渡すと、接続元 IP ごとの固定時間窓で回数を制限し、超過時に HTTP 429 を返します。
+
+- **`D1AnalyticsRateLimiter` / `d1RateLimiter(db, { maxRequests, windowMs })`**: D1 に原子的なカウンターを持ち、isolate 間で共有します。デプロイ前に `migrations/0002_analytics_rate_limits.sql` を適用してください。
+- **`MemoryAnalyticsRateLimiter`**: テストとローカル開発向けのプロセス内カウンターです。Worker の isolate は短命で共有されないため、分散したクライアントは制限できません。本番は D1 を使ってください。
+
+レート制限は単一クライアントからの濫用を減らすだけで、偽造や分散アクセスを完全には防げません。収集した計測は信頼できないデータとして扱ってください。
+
+## プライバシーと検証
+
+`POST /events` は 8 KiB 以下の JSON `page_view` だけを受け入れ、安全な content ID、ISO 時刻、長さを制限した `path` / `lang` を検証します。Cookie、User-Agent、フィンガープリントは読み取りも保存もしません。Origin は既定で拒否されるため、許可するサイト Origin を明示してください。レート制限を設定した場合に限り、接続元 IP（`CF-Connecting-IP`）をレート制限キーとして読み取ります。D1 版はそのキーを有効な時間窓のあいだだけ保存します。
+
+D1 スキーマはリクエスト中に実行せず、デプロイ前に `migrations/0001_analytics_page_views.sql` と `migrations/0002_analytics_rate_limits.sql` を `wrangler d1 execute` で明示適用してください。詳しい設定は各テンプレートの README を参照してください。

package/dist/index.d.ts

@@ -1,7 +1,12 @@
+export type { AnalyticsRateLimiter } from "./src/domain/analytics/rate_limit.js";
 export type { AnalyticsStorage } from "./src/domain/analytics/storage.js";
+export type { D1AnalyticsRateLimiterOptions } from "./src/infrastructure/d1/d1_analytics_rate_limiter.js";
+export { D1AnalyticsRateLimiter, d1RateLimiter, } from "./src/infrastructure/d1/d1_analytics_rate_limiter.js";
 export { D1AnalyticsStorage, d1Storage, } from "./src/infrastructure/d1/d1_analytics_storage.js";
 export type { D1Database } from "./src/infrastructure/d1/d1_types.js";
 export type { KvNamespace } from "./src/infrastructure/kv/kv_analytics_storage.js";
 export { KvAnalyticsStorage, kvStorage, } from "./src/infrastructure/kv/kv_analytics_storage.js";
+export type { MemoryAnalyticsRateLimiterOptions } from "./src/infrastructure/memory/memory_rate_limiter.js";
+export { MemoryAnalyticsRateLimiter } from "./src/infrastructure/memory/memory_rate_limiter.js";
 export type { AnalyticsCorsOptions, AnalyticsWorker, AnalyticsWorkerOptions, } from "./src/presentation/worker/create_worker.js";
 export { createWorker } from "./src/presentation/worker/create_worker.js";

package/dist/index.js

@@ -1,3 +1,50 @@
+// src/domain/analytics/rate_limit.ts
+function assertRateLimitPolicy(policy) {
+  if (!Number.isInteger(policy.maxRequests) || policy.maxRequests < 1)
+    throw new RangeError("rate limit maxRequests must be a positive integer");
+  if (!Number.isInteger(policy.windowMs) || policy.windowMs < 1)
+    throw new RangeError("rate limit windowMs must be a positive integer");
+}
+function rateLimitWindowStart(now, windowMs) {
+  return Math.floor(now / windowMs) * windowMs;
+}
+function rateLimitOutcome(hits, maxRequests) {
+  return hits <= maxRequests ? "allowed" : "limited";
+}
+
+// src/infrastructure/d1/d1_analytics_rate_limiter.ts
+var D1AnalyticsRateLimiter = class {
+  constructor(database, options) {
+    this.database = database;
+    this.options = options;
+    assertRateLimitPolicy(options);
+    this.#now = options.now ?? Date.now;
+  }
+  database;
+  options;
+  #now;
+  async check(key) {
+    const windowStart = rateLimitWindowStart(
+      this.#now(),
+      this.options.windowMs
+    );
+    const result = await this.database.prepare(
+      `INSERT INTO analytics_rate_limits (bucket_key, window_start, hits)
+         VALUES (?, ?, 1)
+         ON CONFLICT(bucket_key, window_start)
+         DO UPDATE SET hits = hits + 1
+         RETURNING hits`
+    ).bind(key, windowStart).all();
+    return rateLimitOutcome(
+      Number(result.results?.[0]?.hits ?? 0),
+      this.options.maxRequests
+    );
+  }
+};
+function d1RateLimiter(database, options) {
+  return new D1AnalyticsRateLimiter(database, options);
+}
+
 // src/infrastructure/d1/d1_analytics_storage.ts
 import { assertAnalyticsQuerySupported } from "@riebeckite/plugin-analytics";
 var D1AnalyticsStorage = class {
@@ -105,6 +152,25 @@ function isPageView2(event) {
   return event.type === "page_view";
 }
 
+// src/infrastructure/memory/memory_rate_limiter.ts
+var MemoryAnalyticsRateLimiter = class {
+  constructor(options) {
+    this.options = options;
+    assertRateLimitPolicy(options);
+    this.#now = options.now ?? Date.now;
+  }
+  options;
+  #now;
+  #windows = /* @__PURE__ */ new Map();
+  async check(key) {
+    const start = rateLimitWindowStart(this.#now(), this.options.windowMs);
+    const current = this.#windows.get(key);
+    const hits = current?.start === start ? current.hits + 1 : 1;
+    this.#windows.set(key, { start, hits });
+    return rateLimitOutcome(hits, this.options.maxRequests);
+  }
+};
+
 // src/presentation/worker/create_worker.ts
 var MAX_BODY_BYTES = 8192;
 var MAX_CONTENT_ID_LENGTH = 160;
@@ -121,7 +187,12 @@ function createWorker(options) {
       }
       const url = new URL(request.url);
       if (request.method === "POST" && url.pathname === "/events") {
-        return captureEvent(request, options.storage, corsHeaders);
+        return captureEvent(
+          request,
+          options.storage,
+          options.rateLimit,
+          corsHeaders
+        );
       }
       if (request.method === "GET" && url.pathname === "/popular") {
         return queryPopular(url, options.storage, corsHeaders);
@@ -136,7 +207,7 @@ function createWorker(options) {
     }
   };
 }
-async function captureEvent(request, storage, headers) {
+async function captureEvent(request, storage, rateLimit, headers) {
   if (!request.headers.get("content-type")?.includes("application/json")) {
     return json({ error: "unsupported_media_type" }, 415, headers);
   }
@@ -156,9 +227,17 @@ async function captureEvent(request, storage, headers) {
   }
   const event = validateEvent(value);
   if (!event) return json({ error: "invalid_event" }, 400, headers);
+  if (rateLimit) {
+    const outcome = await rateLimit.check(clientIp(request));
+    if (outcome === "limited")
+      return json({ error: "rate_limited" }, 429, headers);
+  }
   await storage.capture(event);
   return new Response(null, { status: 204, headers });
 }
+function clientIp(request) {
+  return request.headers.get("cf-connecting-ip") ?? "unknown";
+}
 async function queryContent(contentId, url, storage, headers) {
   if (!isContentId(contentId))
     return json({ error: "invalid_content_id" }, 400, headers);
@@ -281,9 +360,12 @@ function isIsoDate(value) {
   return typeof value === "string" && value.length <= 40 && !Number.isNaN(Date.parse(value));
 }
 export {
+  D1AnalyticsRateLimiter,
   D1AnalyticsStorage,
   KvAnalyticsStorage,
+  MemoryAnalyticsRateLimiter,
   createWorker,
+  d1RateLimiter,
   d1Storage,
   kvStorage
 };

package/dist/src/domain/analytics/rate_limit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Runtime-owned rate-limit boundary for the analytics collector.
+ *
+ * Origin checks are not authentication, so a client can forge an allowed
+ * `Origin` and POST fabricated events. Rate limiting reduces that abuse from a
+ * single client key; it is a mitigation, not complete prevention, and never
+ * makes collected analytics authorization data.
+ */
+export type AnalyticsRateLimitOutcome = "allowed" | "limited";
+export interface AnalyticsRateLimiter {
+    /** Records one attempt for `key` and reports whether it may proceed. */
+    check(key: string): Promise<AnalyticsRateLimitOutcome>;
+}
+export interface AnalyticsRateLimitPolicy {
+    /** Maximum accepted attempts per key inside one window. */
+    readonly maxRequests: number;
+    /** Window length in milliseconds. */
+    readonly windowMs: number;
+}
+/** Rejects policies that would silently disable limiting (zero or non-integer). */
+export declare function assertRateLimitPolicy(policy: AnalyticsRateLimitPolicy): void;
+/** Fixed-window bucket start for `now` in epoch milliseconds. */
+export declare function rateLimitWindowStart(now: number, windowMs: number): number;
+/** Maps the hit count inside the current window to an outcome. */
+export declare function rateLimitOutcome(hits: number, maxRequests: number): AnalyticsRateLimitOutcome;

package/dist/src/infrastructure/d1/d1_analytics_rate_limiter.d.ts

@@ -0,0 +1,22 @@
+import { type AnalyticsRateLimiter, type AnalyticsRateLimitOutcome, type AnalyticsRateLimitPolicy } from "../../domain/analytics/rate_limit.js";
+import type { D1Database } from "./d1_types.js";
+export type D1AnalyticsRateLimiterOptions = AnalyticsRateLimitPolicy & Readonly<{
+    /** Clock injection for deterministic tests. Defaults to `Date.now`. */
+    now?: () => number;
+}>;
+/**
+ * D1-backed fixed-window limiter shared across Worker isolates.
+ *
+ * The connecting IP is stored as the bucket key for the active window only.
+ * Expired rows are never read again, but D1 has no TTL; prune old rows
+ * periodically (for example from a scheduled Worker) if retention matters.
+ */
+export declare class D1AnalyticsRateLimiter implements AnalyticsRateLimiter {
+    #private;
+    private readonly database;
+    private readonly options;
+    constructor(database: D1Database, options: D1AnalyticsRateLimiterOptions);
+    check(key: string): Promise<AnalyticsRateLimitOutcome>;
+}
+/** Creates a D1-backed analytics rate limiter from a Worker binding. */
+export declare function d1RateLimiter(database: D1Database, options: D1AnalyticsRateLimiterOptions): AnalyticsRateLimiter;

package/dist/src/infrastructure/memory/memory_rate_limiter.d.ts

@@ -0,0 +1,18 @@
+import { type AnalyticsRateLimiter, type AnalyticsRateLimitOutcome, type AnalyticsRateLimitPolicy } from "../../domain/analytics/rate_limit.js";
+export type MemoryAnalyticsRateLimiterOptions = AnalyticsRateLimitPolicy & Readonly<{
+    /** Clock injection for deterministic tests. Defaults to `Date.now`. */
+    now?: () => number;
+}>;
+/**
+ * Process-local fixed-window limiter for tests and local development.
+ *
+ * In Cloudflare Workers this state lives in one isolate only: it is lost on cold
+ * starts and is not shared across isolates or locations, so it is a best-effort
+ * mitigation. Use `D1AnalyticsRateLimiter` for a shared, durable counter.
+ */
+export declare class MemoryAnalyticsRateLimiter implements AnalyticsRateLimiter {
+    #private;
+    private readonly options;
+    constructor(options: MemoryAnalyticsRateLimiterOptions);
+    check(key: string): Promise<AnalyticsRateLimitOutcome>;
+}

package/dist/src/presentation/worker/create_worker.d.ts

@@ -1,3 +1,4 @@
+import type { AnalyticsRateLimiter } from "../../domain/analytics/rate_limit.js";
 import type { AnalyticsStorage } from "../../domain/analytics/storage.js";
 export type AnalyticsCorsOptions = Readonly<{
     /** Explicit browser origins, or "any" for a deliberately public collector. */
@@ -9,6 +10,12 @@ export type AnalyticsWorkerOptions = Readonly<{
     /** One explicitly selected runtime storage adapter. No default is provided. */
     storage: AnalyticsStorage;
     cors?: AnalyticsCorsOptions;
+    /**
+     * Optional per-client-IP limiter applied to `POST /events`. Rate limiting is
+     * a mitigation for event forgery, not authentication; see the domain
+     * `AnalyticsRateLimiter` contract.
+     */
+    rateLimit?: AnalyticsRateLimiter;
 }>;
 export type AnalyticsWorker = Readonly<{
     fetch(request: Request): Promise<Response>;

package/migrations/0002_analytics_rate_limits.sql

@@ -0,0 +1,10 @@
+-- Apply explicitly with: wrangler d1 execute <DATABASE_NAME> --file migrations/0002_analytics_rate_limits.sql
+-- D1 Workers cannot safely run schema migration during request handling.
+-- The connecting IP is stored as bucket_key for the active window only.
+-- D1 has no TTL; prune expired rows periodically if retention matters.
+CREATE TABLE IF NOT EXISTS analytics_rate_limits (
+  bucket_key TEXT NOT NULL,
+  window_start INTEGER NOT NULL,
+  hits INTEGER NOT NULL DEFAULT 0 CHECK (hits >= 0),
+  PRIMARY KEY (bucket_key, window_start)
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/analytics-cloudflare",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,10 @@
     }
   },
   "dependencies": {
-    "@riebeckite/plugin-analytics": "0.0.3"
+    "@riebeckite/plugin-analytics": "0.0.6"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4"
   },
   "publishConfig": {
     "access": "public"