@ryusenkei/maezae 0.12.0 → 0.13.0

package/README.md

@@ -31,6 +31,34 @@ const client = createDeliveryClient((path, init) =>
 );
 ```
 
+## 回数の制限
+
+- 対象は公開のエンドポイント（`https://api.maezae.app/<媒体>/content/v1/…`）だけ。上限は媒体と API の鍵ごとに1分で600回で、データセンターごとの近似で数える
+- 数えるのは、CMS がキャッシュから返せずに DB で計算する要求だけ。キャッシュから返す応答と、`If-None-Match` に対する304は数えない
+- 上限を超えると429（`code: "rate_limited"`）を返す。`Retry-After` の秒数だけ待ってから再試行する
+- 呼び出しを減らす方法: 1ページの取得を `prefetch`（`/bundle`）で1回にまとめ、接続を `cachedDelivery` で包む
+
+## 接続のキャッシュ（0.13.0 から）
+
+`cachedDelivery` は同じパスとクエリの取得を保持し、配信 API への呼び出しを減らす
+
+- 保持から `freshSec` 秒（既定は30）は呼び出さずに返す。過ぎたら前回の ETag で再検証し、304は回数の制限に数えない
+- 429・5xx・接続の失敗のときは、保持した値を `x-stale: 1` つきで返す
+- 下書き（`drafts`）・GET 以外・`prefetch` の `ifNoneMatch` を付けた取得は保持しない
+- 保持の場所: Workers は `caches.default`（データセンターごとに共有）、ほかの実行環境は `memoryDeliveryCache()`
+- `origin` はキーの前半で、媒体ごとに別の値にする
+
+```ts
+import { cachedDelivery, createDeliveryClient } from '@ryusenkei/maezae/delivery';
+
+const origin = 'https://<媒体>.maezae.app';
+const delivery = (path: string, init?: RequestInit) =>
+  fetch(`https://api.maezae.app/<媒体>${path}`, { ...init, headers: { ...init?.headers, authorization: `Bearer ${env.CMS_API_KEY}` } });
+const client = createDeliveryClient(cachedDelivery(delivery, { cache: caches.default, origin }));
+```
+
+公開の操作の反映は、CMS の側の遅れに加えて最大で `freshSec` 秒遅れる
+
 ## プレビュー
 
 - CMS は媒体のサイトのオリジンへ、公開のページと同じパスで署名つきのリクエストを送信

package/dist/delivery.js

@@ -1,4 +1,96 @@
 import { a as optionsOf, l as cropRect, o as typeOf, p as createClock, t as pagePathOf, u as croppedHotspot } from "./page-BnwHL-LC.js";
+// src/delivery/cache.ts
+/** 保持した日時（ミリ秒）を置く内部のヘッダー */
+const CACHED_AT = "x-maezae-cached-at";
+/** 失敗のときに返せるように保持する期間（秒） */
+const KEEP_SEC = 86400;
+const withHeaders = (res, body, set, drop = []) => {
+	const headers = new Headers(res.headers);
+	for (const k of drop) headers.delete(k);
+	for (const [k, v] of Object.entries(set)) headers.set(k, v);
+	return new Response(body, {
+		status: res.status,
+		statusText: res.statusText,
+		headers
+	});
+};
+/**
+* 保持つきの配信 API の接続（createDeliveryClient に渡す）
+* - origin: キーの前半（媒体ごとに別の値、例: https://<媒体>.maezae.app）。同じ保持の場所を複数の媒体で使っても混ざらない
+* - freshSec: 呼び出さずに返す秒数（既定は30、CMS のキャッシュの区切りと同じ）
+*/
+function cachedDelivery(delivery, { cache, origin, freshSec = 30 }) {
+	const store = async (key, res, body) => {
+		try {
+			await cache.put(key, withHeaders(res, body, {
+				[CACHED_AT]: String(Date.now()),
+				"cache-control": `max-age=${KEEP_SEC}`
+			}));
+		} catch {}
+	};
+	const fromCache = (res, body, extra = {}) => withHeaders(res, body, extra, [CACHED_AT, "cache-control"]);
+	return async (path, init = {}) => {
+		const headers = new Headers(init.headers);
+		const key = `${origin}${path}`;
+		if ((init.method ?? "GET").toUpperCase() !== "GET" || headers.has("if-none-match") || new URL(key).searchParams.get("drafts") === "1") return delivery(path, init);
+		const cached = await cache.match(key).catch(() => null) ?? null;
+		if (cached && Date.now() - Number(cached.headers.get(CACHED_AT)) < freshSec * 1e3) return fromCache(cached, cached.body);
+		const etag = cached?.headers.get("etag");
+		if (etag) headers.set("if-none-match", etag);
+		let res;
+		try {
+			res = await delivery(path, {
+				...init,
+				headers
+			});
+		} catch (e) {
+			if (cached) return fromCache(cached, cached.body, { "x-stale": "1" });
+			throw e;
+		}
+		if (res.status === 304 && cached) {
+			const body = await cached.text();
+			await store(key, cached, body);
+			return fromCache(cached, body);
+		}
+		if (res.status === 200 && !res.headers.has("x-partial") && !res.headers.has("x-stale")) {
+			const body = await res.text();
+			await store(key, res, body);
+			return fromCache(res, body);
+		}
+		if (cached && (res.status === 429 || res.status >= 500)) {
+			await res.body?.cancel();
+			return fromCache(cached, cached.body, { "x-stale": "1" });
+		}
+		return res;
+	};
+}
+/** メモリの保持の場所（Workers 以外の実行環境向け、maxEntries を超えたら最も古く使用したものから破棄） */
+function memoryDeliveryCache(maxEntries = 500) {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		match: async (key) => {
+			const v = entries.get(key);
+			if (!v) return null;
+			entries.delete(key);
+			entries.set(key, v);
+			return new Response(v.body, {
+				status: v.status,
+				headers: v.headers
+			});
+		},
+		put: async (key, res) => {
+			entries.delete(key);
+			const headers = [];
+			res.headers.forEach((v, k) => headers.push([k, v]));
+			entries.set(key, {
+				status: res.status,
+				headers,
+				body: await res.text()
+			});
+			if (entries.size > maxEntries) entries.delete(entries.keys().next().value);
+		}
+	};
+}
 // src/delivery/query.ts
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** in の値の検査（コンマを含む値はクエリで区切れない） */
@@ -306,4 +398,4 @@ function createDeliveryClock(timeZone) {
 		})
 	};
 }
-export { DELIVERY_PATH, DeliveryError, createDeliveryClient, createDeliveryClock, deliveredImageUrl, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, optionLabels, pagePath, parseMediaPath, subPath, withImageParams };
+export { DELIVERY_PATH, DeliveryError, cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, subPath, withImageParams };

package/dist/types/sdk/src/delivery/cache.d.ts

@@ -0,0 +1,18 @@
+import type { Delivery } from './client.js';
+/** Cache API と同じ形の保持の場所（key は URL） */
+export type DeliveryCache = Readonly<{
+    match(key: string): Promise<Response | null | undefined>;
+    put(key: string, response: Response): Promise<void>;
+}>;
+/**
+ * 保持つきの配信 API の接続（createDeliveryClient に渡す）
+ * - origin: キーの前半（媒体ごとに別の値、例: https://<媒体>.maezae.app）。同じ保持の場所を複数の媒体で使っても混ざらない
+ * - freshSec: 呼び出さずに返す秒数（既定は30、CMS のキャッシュの区切りと同じ）
+ */
+export declare function cachedDelivery(delivery: Delivery, { cache, origin, freshSec }: {
+    cache: DeliveryCache;
+    origin: string;
+    freshSec?: number;
+}): Delivery;
+/** メモリの保持の場所（Workers 以外の実行環境向け、maxEntries を超えたら最も古く使用したものから破棄） */
+export declare function memoryDeliveryCache(maxEntries?: number): DeliveryCache;

package/dist/types/sdk/src/delivery/index.d.ts

@@ -1,3 +1,4 @@
+export { cachedDelivery, memoryDeliveryCache, type DeliveryCache } from './cache.js';
 export { createDeliveryClient, DELIVERY_PATH, DeliveryError, subPath, type BundleResult, type Delivery, type DeliveryClient, type Prefetched } from './client.js';
 export { deliveredImageUrl, mediaOf, type ImageUrl, type MediaOf } from './media.js';
 export { imageParamsOf, parseMediaPath, withImageParams, type ImageParams, type MediaPath } from '../../../model/src/index.js';

package/dist/types/sdk/src/delivery.d.ts

@@ -1,2 +1,2 @@
-export { createDeliveryClient, createDeliveryClock, deliveredImageUrl, DELIVERY_PATH, DeliveryError, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, optionLabels, pagePath, parseMediaPath, subPath, withImageParams } from './delivery/index.js';
-export type { BundleResult, DeliveredAsset, Delivery, DeliveryClient, DeliveryClock, FieldValue, ImageParams, ImageUrl, Item, ItemMeta, ItemOf, ListFilter, ListQuery, MediaOf, MediaPath, Page, Prefetched } from './delivery/index.js';
+export { cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, DELIVERY_PATH, DeliveryError, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, subPath, withImageParams } from './delivery/index.js';
+export type { BundleResult, DeliveredAsset, Delivery, DeliveryCache, DeliveryClient, DeliveryClock, FieldValue, ImageParams, ImageUrl, Item, ItemMeta, ItemOf, ListFilter, ListQuery, MediaOf, MediaPath, Page, Prefetched } from './delivery/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryusenkei/maezae",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "maezae の導入先のサイト向けの SDK（配信 API の取得・本文の型・プレビューの署名・手元の開発の配信 API）",
   "license": "UNLICENSED",
   "author": "RYUSENKEI",