hd-garden 0.5.0 → 0.5.2

package/worker/og/README.md

@@ -0,0 +1,59 @@
+# 链接卡片刷新（可选）
+
+文章里的链接卡片在构建时就已经完整：标题、简介和本地配图都写进了静态页面，不开 JavaScript 也能看。这个 Worker 只做一件事：读者打开文章时，悄悄问一下对方页面现在的标题和简介，有变化就换上新的文字。配图始终用构建时下载到站内的那张，不会从对方网站直接加载。
+
+## Worker 部署说明
+
+### 1. 目录和入口
+
+- 目录：`worker/og/`，CI 不会部署它，需要时手动部署。
+- 入口：`worker/og/index.mjs`（`wrangler.toml` 里的 `main`），请求处理逻辑在 `handler.mjs`，抓取和解析页面用的是与构建共用的 `scripts/link-meta-core.mjs`。
+
+```bash
+npx wrangler deploy --config worker/og/wrangler.toml
+```
+
+部署后得到 `https://garden-og.<你的子域>.workers.dev`。
+
+### 2. 变量和绑定
+
+在 `wrangler.toml` 的 `[vars]` 里设置：
+
+| 变量 | 作用 | 默认 |
+|---|---|---|
+| `SITE_ORIGIN` | 站点地址，Worker 从 `${SITE_ORIGIN}/link-allowlist.json` 读取允许的网址 | `https://hedon.top` |
+| `ALLOWED_ORIGINS` | 允许调用的页面来源，逗号分隔；其他来源一律 403 | 同 `SITE_ORIGIN` |
+| `ALLOW_LOCALHOST` | 设为 `"1"` 时也接受 `http://localhost:*` 和 `http://127.0.0.1:*`，方便本地预览 | `"1"` |
+| `RATE_PER_MINUTE` | 每个 IP 每分钟最多请求次数，超出返回 429 | `30` |
+
+可选绑定 `RATE_LIMITER`：Cloudflare 的限流绑定（`wrangler.toml` 里有注释掉的示例），跨实例共享计数。不配置时按单个实例内存计数。
+
+缓存用 Workers 自带的边缘缓存（`caches.default`），不需要 KV 绑定：读到的结果缓存 24 小时，读取失败缓存 10 分钟，这段时间内不会再去请求对方网站。
+
+### 3. 允许名单从哪来，怎么更新
+
+- 站点每次 `garden build` 时生成 `public/link-allowlist.json`，内容是已发布文章里所有写了 `{card}` 的链接。它随站点一起部署，不需要提交到仓库。
+- Worker 不内置名单，运行时从站点读取：每个实例最多 5 分钟重新拉一次，Cloudflare 对这份文件的缓存也是 5 分钟。
+- 所以新文章发布后，最迟约 10 分钟 Worker 就认得新链接，**不需要重新部署 Worker**。只有改了变量或 Worker 代码时才需要重新部署。
+- 名单拉取失败时沿用上一份；一份都没有时拒绝所有网址。
+
+### 4. 站点里在哪里填 Worker 地址
+
+在站点仓库（例如 garden-blog）的 `site.config.yaml` 里：
+
+```yaml
+linkPreview:
+  worker: https://garden-og.<你的子域>.workers.dev
+```
+
+不写这一项，页面就不会请求 Worker，卡片保持构建时的内容。只有包含 `{card}` 的文章页面才会加载刷新脚本。
+
+## 它会拒绝什么
+
+- 不是来自 `ALLOWED_ORIGINS`（以及开启 `ALLOW_LOCALHOST` 时的 `http://localhost:*`）的请求。
+- 不在站点 `/link-allowlist.json` 里的网址。
+- 指向本机、内网、链接本地地址或非 80/443 端口的网址；跳转到这些地址的也一样，每一跳都会重新检查。
+- 不是 HTML 的页面、超过 1 MB 或 5 秒没读完的页面。
+- 同一个 IP 每分钟超过 `RATE_PER_MINUTE` 次的请求。
+
+浏览器端每张卡片的请求各自 6 秒超时，一张卡片慢不会影响其他卡片；离开页面时所有请求一起取消。Worker 出错或不可用时，页面保持构建时的内容。

package/worker/og/handler.mjs

@@ -0,0 +1,147 @@
+/**
+ * Link card refresh (layer 2). The article's cards are complete at build time;
+ * this Worker only lets a reader's browser pick up a newer title or
+ * description for a card URL the site already lists.
+ *
+ * Guards: only GET from the site's own origins; only URLs in the site's
+ * published allowlist; only public http(s) hosts, redirects re-checked; HTML
+ * only, at most 1 MB, 5 s; a per-IP request budget; results cached for a day,
+ * failures for ten minutes. It never
+ * returns a remote image URL: cards keep their build-time local picture.
+ */
+import { fetchPageMeta } from "../../scripts/link-meta-core.mjs";
+
+export const DEFAULTS = {
+  allowedOrigins: ["https://hedon.top"],
+  allowLocalhost: true,
+  allowlistTtlMs: 5 * 60 * 1000,
+  resultTtlSeconds: 24 * 60 * 60,
+  // A page that could not be read is not tried again for this long.
+  failureTtlSeconds: 10 * 60,
+  timeoutMs: 5000,
+  maxBytes: 1024 * 1024,
+  ratePerMinute: 30,
+};
+
+const LOCAL_ORIGIN = /^http:\/\/(localhost|127\.0\.0\.1)(:\d{1,5})?$/u;
+
+export function originAllowed(origin, { allowedOrigins, allowLocalhost }) {
+  if (!origin) return false;
+  if (allowedOrigins.includes(origin)) return true;
+  return allowLocalhost && LOCAL_ORIGIN.test(origin);
+}
+
+/** Fixed one-minute windows per key. Good enough inside one isolate. */
+export function createRateLimiter({ perMinute, now = () => Date.now() }) {
+  const windows = new Map();
+  return (key) => {
+    const minute = Math.floor(now() / 60000);
+    const entry = windows.get(key);
+    if (!entry || entry.minute !== minute) {
+      if (windows.size > 10000) windows.clear();
+      windows.set(key, { minute, count: 1 });
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= perMinute;
+  };
+}
+
+/** Normalise what the reader asked for, so `?url=` variations share a cache entry. */
+export function normaliseTarget(raw) {
+  try {
+    const url = new URL(raw);
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return "";
+  }
+}
+
+const json = (body, status, headers = {}) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "x-content-type-options": "nosniff", ...headers },
+  });
+
+/**
+ * Build the request handler. Everything outside is injected: `fetch` for the
+ * target pages, `loadAllowlist` for the site's list, `cache` (get/put by key)
+ * and `limit` (true when the IP may go on).
+ */
+export function createHandler({
+  fetch: fetcher,
+  loadAllowlist,
+  cache = null,
+  limit,
+  options = {},
+  now = () => Date.now(),
+}) {
+  const config = { ...DEFAULTS, ...options };
+  const limiter = limit ?? createRateLimiter({ perMinute: config.ratePerMinute, now });
+  let allowlist = null;
+  let allowlistAt = 0;
+
+  const currentAllowlist = async () => {
+    if (allowlist && now() - allowlistAt < config.allowlistTtlMs) return allowlist;
+    try {
+      const list = await loadAllowlist();
+      allowlist = new Set((Array.isArray(list) ? list : list?.urls ?? []).map(normaliseTarget).filter(Boolean));
+      allowlistAt = now();
+    } catch {
+      // Keep the last good list; with none, nothing is allowed.
+      allowlist ??= new Set();
+    }
+    return allowlist;
+  };
+
+  return async function handle(request, { ip = "" } = {}) {
+    const origin = request.headers.get("origin") ?? "";
+    if (!originAllowed(origin, config)) return json({ error: "origin not allowed" }, 403);
+    const cors = {
+      "access-control-allow-origin": origin,
+      "access-control-allow-methods": "GET, OPTIONS",
+      "access-control-max-age": "86400",
+      vary: "Origin",
+    };
+    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: cors });
+    if (request.method !== "GET") return json({ error: "method not allowed" }, 405, { ...cors, allow: "GET, OPTIONS" });
+
+    if (!(await limiter(ip || "unknown"))) return json({ error: "too many requests" }, 429, { ...cors, "retry-after": "60" });
+
+    const target = normaliseTarget(new URL(request.url).searchParams.get("url") ?? "");
+    if (!target) return json({ error: "missing url" }, 400, cors);
+    if (!(await currentAllowlist()).has(target)) return json({ error: "url not listed" }, 403, cors);
+
+    const cacheKey = `og:${target}`;
+    const cached = await cache?.get(cacheKey);
+    if (cached) return json(cached, 200, { ...cors, "cache-control": "public, max-age=3600", "x-cache": "hit" });
+
+    const failureKey = `og-fail:${target}`;
+    const failed = await cache?.get(failureKey);
+    if (failed) return json(failed, 502, { ...cors, "x-cache": "hit" });
+    const fail = async (body) => {
+      await cache?.put(failureKey, body, config.failureTtlSeconds);
+      return json(body, 502, { ...cors, "x-cache": "miss" });
+    };
+
+    let meta;
+    try {
+      meta = await fetchPageMeta(target, { fetch: fetcher, timeoutMs: config.timeoutMs, maxBytes: config.maxBytes });
+    } catch (error) {
+      return fail({ error: "could not read page", detail: String(error?.message ?? error).slice(0, 120) });
+    }
+    if (!meta.title) return fail({ error: "no title" });
+    // Text only. Pictures stay the local copies made at build time.
+    const body = Object.fromEntries(Object.entries({
+      url: target,
+      title: meta.title,
+      description: meta.description,
+      siteName: meta.siteName,
+      author: meta.author,
+      publishedTime: meta.publishedTime,
+    }).filter(([, value]) => value));
+    await cache?.put(cacheKey, body, config.resultTtlSeconds);
+    return json(body, 200, { ...cors, "cache-control": "public, max-age=3600", "x-cache": "miss" });
+  };
+}

package/worker/og/index.mjs

@@ -0,0 +1,61 @@
+/**
+ * Cloudflare Worker entry for link card refresh. See README.md.
+ *
+ * Vars: SITE_ORIGIN (where /link-allowlist.json lives), ALLOWED_ORIGINS
+ * (comma separated), ALLOW_LOCALHOST ("1" to accept http://localhost:*),
+ * RATE_PER_MINUTE. Optional binding: RATE_LIMITER (Workers rate limiting).
+ */
+import { createHandler, DEFAULTS } from "./handler.mjs";
+
+let handler;
+let handlerEnv;
+
+function edgeCache() {
+  const store = globalThis.caches?.default;
+  if (!store) return null;
+  const keyUrl = (key) => `https://og-cache.internal/${encodeURIComponent(key)}`;
+  return {
+    async get(key) {
+      const hit = await store.match(keyUrl(key));
+      return hit ? hit.json() : null;
+    },
+    async put(key, value, ttl) {
+      await store.put(keyUrl(key), new Response(JSON.stringify(value), {
+        headers: { "content-type": "application/json", "cache-control": `public, max-age=${ttl}` },
+      }));
+    },
+  };
+}
+
+function build(env) {
+  const siteOrigin = String(env.SITE_ORIGIN ?? "https://hedon.top").replace(/\/+$/u, "");
+  const allowedOrigins = String(env.ALLOWED_ORIGINS ?? siteOrigin).split(",").map((value) => value.trim()).filter(Boolean);
+  const binding = env.RATE_LIMITER;
+  return createHandler({
+    fetch: (url, init) => fetch(url, init),
+    loadAllowlist: async () => {
+      const response = await fetch(`${siteOrigin}/link-allowlist.json`, { cf: { cacheTtl: 300 } });
+      if (!response.ok) throw new Error(`allowlist HTTP ${response.status}`);
+      return response.json();
+    },
+    cache: edgeCache(),
+    limit: binding ? async (key) => (await binding.limit({ key })).success : undefined,
+    options: {
+      allowedOrigins,
+      allowLocalhost: env.ALLOW_LOCALHOST === "1",
+      ratePerMinute: Number(env.RATE_PER_MINUTE) || DEFAULTS.ratePerMinute,
+    },
+  });
+}
+
+const worker = {
+  async fetch(request, env) {
+    if (!handler || handlerEnv !== env) {
+      handler = build(env);
+      handlerEnv = env;
+    }
+    return handler(request, { ip: request.headers.get("cf-connecting-ip") ?? "" });
+  },
+};
+
+export default worker;

package/worker/og/wrangler.toml

@@ -0,0 +1,18 @@
+# Link card refresh Worker. Not deployed by CI; deploy by hand when wanted:
+#   npx wrangler deploy --config worker/og/wrangler.toml
+name = "garden-og"
+main = "index.mjs"
+compatibility_date = "2026-10-01"
+workers_dev = true
+
+[vars]
+SITE_ORIGIN = "https://hedon.top"
+ALLOWED_ORIGINS = "https://hedon.top"
+ALLOW_LOCALHOST = "1"
+RATE_PER_MINUTE = "30"
+
+# Optional: Cloudflare's rate limiting binding, shared across isolates.
+# [[ratelimits]]
+# name = "RATE_LIMITER"
+# namespace_id = "1001"
+# simple = { limit = 30, period = 60 }