[musingfox]

Adds an opt-in log of the links produced by GET /?url=, so a deployment's owner can look up links they shared later.

Behaviour

• Off by default. cloudflare.config.ts declares the KV binding SHARED_LINKS only when the build variable LOG_SHARED_LINKS is exactly 1. Without it the config has no storage binding, and Deploy-button copies still need no setup.
• One record per successful conversion, including raw=1. Each put runs in ctx.waitUntil with a 90-day expirationTtl. The key starts with an ISO timestamp so that a KV list returns records in time order. The value is the cleaned URL. The metadata holds { url, at, raw? }, and drops url when the metadata would exceed 1,024 bytes.
• The response never changes. Responses are identical with no binding, when put throws or rejects, and when put never settles.
• Share redirects (GET /<host>/<path>), /media/ and failed conversions write nothing.

Specs

• New: docs/spec/shared-links-logged-to-kv-at-conversion.md. Its verify runs test/shared-links-logged-to-kv-at-conversion.test.ts. Each of eight deliberate mutations turned at least one test red, and the commit message for 9437913 lists them.
• docs/spec/free-plan-bindings-only.md gains one exception for this opt-in KV. The default config still declares no storage binding, and test/config.test.ts is unchanged.

Verification

• bun run check passes on every commit: 576 tests, with typecheck clean.
• On 2026-10-16 a probe Workers Builds run confirmed that build variables reach the deploy command and the Node process it starts. The build log printed PROBE_VAR=1 and NODE_SEES=1.

Out of scope

• Any interface for reading the log.
• Deploy-button copies that rename the Worker fail, because cloudflare.config.ts hard-codes name, although Workers Builds passes WRANGLER_CI_OVERRIDE_NAME. I'll fix this separately.

🤖 Generated with Claude Code

Summary by CodeRabbit

• 新功能
  • 可選擇記錄成功產生的分享連結，資料保留 90 天；啟用後不會延遲或影響轉換回應。
  • 可透過部署設定啟用此功能；未啟用時不記錄。
• 文件
  • 更新設定與部署說明，並新增分享連結記錄規格。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: musingfox/better-link/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 53d3a795-e07f-4aed-8b98-816626f34971

📥 Commits

Reviewing files that changed from the base of the PR and between c33cfc9 and cb59ea1.

📒 Files selected for processing: 14

• .coderabbit.yaml
• ARCHITECTURE.md
• CLAUDE.md
• README.md
• README.zh-TW.md
• cloudflare.config.ts
• docs/spec/fail-open-to-original.md
• docs/spec/free-plan-bindings-only.md
• docs/spec/shared-links-logged-to-kv-at-conversion.md
• docs/spec/tracking-params-cleaned-at-conversion.md
• src/index.ts
• src/shared-link-log.ts
• test/shared-links-logged-to-kv-at-conversion.test.ts
• test/support/fake-kv.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

新增可選的分享連結 KV 記錄。建置變數 LOG_SHARED_LINKS=1 會啟用 SHARED_LINKS 綁定。成功轉換時，worker 透過 ctx.waitUntil 排程記錄；文件與測試也涵蓋設定、寫入格式及失敗處理。

Changes: 分享連結記錄

Layer / File(s)	Summary
選擇性 KV 綁定與規格 cloudflare.config.ts, docs/spec/*, README.md, README.zh-TW.md, CLAUDE.md, .coderabbit.yaml	新增 shared-links-logged-to-kv-at-conversion 規格。LOG_SHARED_LINKS=1 時設定 SHARED_LINKS 綁定；文件說明部署設定及 90 天保存期限。
轉換流程與 KV 寫入 src/index.ts, src/shared-link-log.ts, ARCHITECTURE.md	根路徑轉換將 env 與 ctx 傳入 convert。成功轉換時，logSharedLink 以時間戳和 UUID 組成 key，排程寫入 URL、TTL 與 metadata。metadata 超過 1,024 UTF-8 bytes 時不包含 URL。
記錄行為測試與測試支援 test/shared-links-logged-to-kv-at-conversion.test.ts, test/support/fake-kv.ts, ARCHITECTURE.md	測試涵蓋設定啟用條件、寫入內容、失敗情境、回應行為，以及不記錄的路徑。fakeKv 可模擬同步錯誤、Promise 拒絕與未完成的寫入。

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant fetch
  participant convert
  participant logSharedLink
  participant ExecutionContext
  participant SHARED_LINKS
  fetch->>convert: 傳入 requestUrl、env、ctx
  convert->>logSharedLink: 傳入清理後 URL 與 raw 模式
  logSharedLink->>ExecutionContext: waitUntil 排程 KV 寫入
  ExecutionContext->>SHARED_LINKS: put URL、TTL 與 metadata

Loading

Merge Risk: ⚪ Minimal · up to cb59e

The change adds opt-in logging of shared links to KV. Responses are unaffected when the binding is absent or a write fails or hangs. No actionable merge-blocking risk remains.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 5 files. (9 skipped: 9…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		標題準確描述此變更的主要內容：將分享連結記錄至可選的 KV namespace。

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 5 files. (9 skipped: 9 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[musingfox]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.