Files
pages/docs/design/ja/feeds.md
T
Anya Tokugawa bfed3d20f5
Build and publish container images / images (push) Failing after 6m7s
feat(feeds): cache FreshRSS subscriptions and category navigation
2026-11-08 04:48:55 +09:00

255 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 15. RSSビューア・FreshRSS・newsboat
状態:内蔵簡易reader、FreshRSS読取connector、共通viewer、Wiki保存・タスク化、ダッシュボードを実装。
OPMLの確認付き追加取り込み・書出し、FreshRSS購読・カテゴリのnavigationも実装済み。FreshRSSへの書戻しは残件。本番反映と実FreshRSSへの接続は未実施。
既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。
2026-11-08:利用者指定のサブプロジェクト順で最初に実施する。内蔵readerは簡易利用の
正本、本格運用はFreshRSSを正本とする。実環境の接続先・版・資格情報は別途指定する。
## 正本と責務
| モード | 正本 | PagesWikiの役割 | 範囲 |
| --- | --- | --- | --- |
| 内蔵簡易reader | PagesWikiの購読・フォルダ・既読・star | feed取得、保持上限内の記事保存、閲覧とWiki保存 | 個人の簡易利用。外部reader向け同期サーバーや高度なルール機能は初期範囲外 |
| FreshRSS連携 | FreshRSSの購読・フォルダ・記事・既読・star | 表示用cache、連携UI、Wiki保存・タスク化 | 本格運用。PagesWikiは独立した購読・既読の正本を重ねない |
| newsboat等のclient | 接続先FreshRSS | PagesWikiと同じ正本を使う別clientとして扱う | PagesWiki経由の代理同期やnewsboatのDB共有は行わない |
FreshRSSにはGoogle Reader互換APIがあり、APIの有効化と専用passwordを使います。newsboatにはFreshRSS連携が用意され、カテゴリのtag化やstar操作を扱えます。[FreshRSS公式API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)、[newsboat公式マニュアル](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)。
本格運用は **FreshRSSを正本、PagesWikiとnewsboatをそのclient** とする構成を採用します。
内蔵簡易readerも別providerとして提供し、共通の一覧・保存UIを使用します。FreshRSSを
PagesWiki全体の必須依存にはせず、外部サービスの新設・接続は設定時の明示操作とします。
sourceは一つのproviderに束縛し、記事キーはDomain/所有者/source UUID/remote IDで
区別します。同じURLの記事でも別sourceの既読を自動統合しません。FreshRSSのcacheは
再取得可能な派生データですが、内蔵の購読・状態は正本として保全対象にします。
FreshRSS停止時は取得済みcacheと鮮度・接続状態を示し、内蔵正本へ自動切替しません。
外部操作の未送信状態は正本と区別し、成功していない既読・starを同期済みと表示しません。
内蔵からFreshRSSへの移行はOPML等による明示的なexport/importとし、初期版では既読・star・
記事IDの完全移行を保証しません。移行完了の確認前に内蔵データを削除しません。
## 実装済みの読取機能
`/v/feeds` に購読一覧、フォルダ、記事一覧、外部原文へのリンク、Wiki保存を提供します。
FreshRSSの記事・既読・starは取得しますが、状態の変更は送信しません。UIにも読取専用と明示し、
FreshRSS passwordを設定時以外にブラウザへ返さず、login tokenはbackend内でのみ利用します。
資格情報は既存の暗号化機構を使い、Domain・所有者・source UUID・用途に束縛します。
cacheはsource UUID、remote item ID、title、安全化したHTML本文とテキスト本文、記事URL、公開日時、配信元、
フォルダ、read/starを保持します。取得時刻・ETag・Last-Modified・失敗分類はsource側に持ちます。
IDなしRSSは記事URL、URLもなければ題名・日時・本文の組合せから代替キーを作り、題名だけで
重複排除しません。Atomはentry IDを使います。[Atom仕様](https://www.rfc-editor.org/rfc/rfc4287)。
### 高密度ビューア
newsboat/neomuttを参考に、デスクトップは左から購読元・一行記事一覧・本文の3ペインとします。
一覧には未読/star、日付、配信元、件名を並べます。狭幅は一覧と本文を切り替え、スマホでは
行とボタンのタッチ領域を広げます。モバイルの共通ナビはアイコンのみとし、名称はアクセシブル名と
tooltipに残します。タブ名は「RSS」、原文リンクはアイコンです。件数・保持上限・操作の説明は常設せず、
キー案内は`?`で表示します。設定と保存フォームは本文ペイン内に置き、モーダルを増やしません。
`j/k`・上下矢印で移動、`Enter/l`で本文、`Esc/h`で一覧、`/`で件名・配信元検索、`n`で次の未読、
`m`で既読切替、`*`でstar、`r`で背景更新予約、`?`でキー案内です。フォーム入力・IME変換中は
一覧ショートカットを抑止します。FreshRSSでは`m`と`*`も外部変更を行いません。
HTML本文は見出し・表・箇条書き・強調・リンクを保持して描画し、plain textは文字情報として表示します。
server側の許可リストでscript・イベント属性・任意CSS・form・iframe・画像等を除去し、表示時にも再検査します。
Shadow DOMでWiki UIと表示スタイルを分離し、本文リンクは安全なHTTP(S) URLに解決して別タブで開きます。
Wiki macroは展開せず、記事表示のための外部画像や原文サイトのfetchも行いません。
検索とページングは保存済みcacheだけを対象にし、画面表示で
feed取得の完了を待ちません。ダッシュボードには任意追加のRSS widgetを用意します。
### APIと保存層
API prefixは `/_/api/v1/extension/organizer.feeds/`。Domain内の本人専用で、匿名・他人のsourceには
アクセスできません。readonlyアカウントは読取のみです。すべての応答はprivate/no-storeとします。
| endpoint | 操作 |
| --- | --- |
| `GET sources` / `POST sources` | source一覧/追加・設定更新。新規はUUIDで再送を識別、更新はversion CAS |
| `POST sources/{uuid}/refresh` | 次回背景取得を予約。画面から外部通信しない |
| `POST sources/{uuid}/delete` | versionを照合してsource・cache・内蔵read/starを削除 |
| `GET items` | source/unread/starred/件名・配信元で絞り込み、100件単位のkeysetページング |
| `GET catalog?source=…` | 本人のFreshRSS購読・カテゴリの取得済み一覧。外部通信なし |
| `GET item?source=…&id=…` | 本人の記事本文 |
| `POST state` | 内蔵read/starの条件付き変更。FreshRSSは拒否 |
| `POST note` | 公開範囲確認付きのWiki単独保存。request_idと入力hashで再送を識別 |
| `GET opml/export` | 本人の内蔵購読をOPML 2.0としてダウンロード |
| `POST opml/preview` | ファイルを解析し、追加可能・登録済み・重複・未対応等を返す。保存・外部通信なし |
| `POST opml/import` | 選択行を再解析・検査し、確認時の購読設定と一致する場合だけ原子的に追加 |
managed schema `feeds` v1に `feed_sources`、`feed_items`、`feed_states`、`feed_note_receipts`を追加し、
v2で`feed_items.body_html`を追加します。既存のテキスト本文・既読・starは保持し、条件付きGETのvalidatorを
一度クリアして次回背景取得でHTMLを取り直します。migration前のworkerは設定versionで無効化します。
v3で`feed_import_receipts`を追加し、購読の一括追加と再送記録を同時保存します。
v4でsourceに購読一覧、記事にremote feed ID・カテゴリIDを追加します。FreshRSSの旧workerを
versionで無効化し、次の背景取得を予約します。内蔵sourceのversion・取得予約は変更しません。
既存テーブルを破壊・再構成しません。SQLiteのforeign_keys設定に依存せず削除を完遂するtriggerを
持ちます。内蔵read/starを本文cacheから分離し、記事を保持窓から落としても状態は黙って消しません。
DBは内蔵購読・状態・保存receiptの正本であり、全体を捨てられるcacheとは扱いません。
sourceのprovider・URL・資格情報の変更は別sourceを作る契約です。設定versionとworker claimの
両方を照合し、停止/削除/設定更新後に古い取得結果を書き戻しません。完了保存時にも本人の
所属・状態・extension有効状態をwriter transaction内で確認します。
### 背景取得の上限
| 項目 | 初期実装の値・挙動 |
| --- | --- |
| 個人のsource数 | Domain・本人ごとに32 |
| 定期event | `feed.source.sync`、既定60秒周期、低優先度、1回最大4 sourceを直列取得 |
| source更新間隔 | 5〜1440分、既定30分。取得候補になる間隔であり、混雑時の完了時刻保証ではない |
| 通信予算 | 1 source 8秒、batch 35秒、応答/展開後本文4 MiB |
| 外部接続 | 公開HTTPS/443のみ。DNS検査・接続先固定、内部アドレス・redirect・proxyを拒否 |
| 内蔵記事cache | 1 source最大500件、text本文32 KiB・HTML本文128 KiB。HTML上限超過はtextへフォールバックし、text切詰めを明示 |
| 内蔵read/star | 1 source最大10,000件。上限では新規状態保存を拒否し、既存状態を捨てない |
| FreshRSS | reading-list最新200件の窓を取得。更新成功時はその窓で置換し、全履歴同期とはしない |
| FreshRSS購読一覧 | 最大1,000購読、1購読64カテゴリ、保存JSON 1 MiB。記事と同じ取得予算で収集 |
| 再試行 | 次の設定間隔まで待機。手動予約にも最終成功から60秒の制限、取得中の重複claim拒否 |
内蔵は条件付きGET、304ではcacheを保持します。どちらのproviderも通信・認証・構文失敗で
前回cacheを消しません。sourceには安全な失敗分類と最終成功日時を表示し、イベントログには
成功/失敗件数だけを記録します。資格情報・生本文・秘密を含み得るURLをログへ出しません。
extension無効化は画面・API・取得・完了保存に適用します。購読を登録するまで外部通信は発生しません。
### FreshRSSの購読とカテゴリ
背景取得ではlogin後にreading-listと`subscription/list`を読み、両方に成功した場合だけ
記事・購読一覧を同じtransactionで置換します。一方の取得失敗、上限超過、不正なsnapshotでは
前回の両cacheを保持します。記事が取得窓内にない購読も一覧には残します。
左ペインでFreshRSS sourceを選ぶとカテゴリ選択・購読名の検索・購読一覧を表示します。
カテゴリは表示名でなくremote category ID、購読は`origin.streamId`とsubscription IDを対応させます。
同名でも混同せず、複数カテゴリに属する購読も扱います。`GET items`の`feed`/`category`は
source指定と組み合わせ、既存の未読・star・検索・keysetページングと併用できます。
絞り込み対象は最新200記事のcache内に限られ、購読を選んでも履歴全件を外部取得しません。
購読の追加・削除やカテゴリの編集はFreshRSS側で行います。
## 既読・star同期を追加する条件
server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。
FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。
### 書戻しの次段階設計
以下は未実装のRSS-3です。購読navigationの追加だけでは書戻しを有効にしません。
sourceごとに既定OFFの書戻し設定を設け、操作は`read`または`starred`の一項目と希望値に限定します。
cache内の他項目を同時に送らず、全件既読・購読編集も初期対象に含めません。
操作記録は記事cacheから分離し、Domain・本人・request_id、source・記事ID、対象項目、希望値、
source version、状態、claim期限を保持します。同一request_idの同じ入力は同じ記録を返し、
違う入力は拒否します。同じ記事に未解決の操作がある間は次の操作を受け付けません。
受付APIは外部通信せず、低優先度workerが送信します。記録数とworkerの時間予算は必ず有限にします。
| 状態 | 次の処理 |
| --- | --- |
| queued | sourceの有効状態・書戻し設定・version・本人の権限を再検査してclaim。古すぎる未送信操作は中止 |
| preparing | FreshRSSの現在値を取得。すでに希望値なら書き込まず確認済み。異なる場合だけ変更tokenを取得 |
| sending | この状態をDBに確定してから変更を送る。再起動やtimeoutでも自動再送しない |
| confirmed | 送信後の読取で希望値を確認。確認できた値だけcacheへ反映 |
| unknown | 送信済みか適用済みか判断できない。成功扱いにせず、利用者の再確認操作を待つ |
| checking | unknownの再確認。読取のみで、希望値ならconfirmed、異なれば競合として提示 |
| failed / cancelled / conflict | 原因を示して終了。新たに送る場合は利用者の明示操作を必要とする |
通常取得と書戻しはsourceのleaseを共有し、古い取得結果が書戻し後の値を上書きしないようにします。
設定変更・無効化・削除は未送信操作を止めますが、すでに外へ送った要求は取り消せません。
その場合はunknownを保持し、設定変更後のcacheへ旧workerが反映することを拒否します。
外部clientとの同時変更を原子的に防げないAPIでは、確認直後に状態が再変更される可能性もあります。
readbackは観測結果であり、exactly-onceやリモートCASの保証とは区別します。
受入テストは、opt-inなしの拒否、同じ操作の再送、別項目の保持、送信前の権限失効、
送信直後の応答喪失、worker停止・再起動、unknownの読取専用再確認、source削除・設定変更、
通常取得との排他、他clientによる同時変更を含めます。実サービスを使わない合成fixtureで
これらを通した後、指定版FreshRSSでの受入を別途行います。
## 内蔵簡易reader
購読追加/削除、フォルダ、記事一覧、既読/未読、star、更新間隔と保持上限を初期範囲に
します。取得は背景ジョブで行い、更新失敗で購読や状態を消しません。記事本文cacheと
既読・starの保持期間を分離し、古い記事を再取得しただけで未読へ戻る挙動を防ぎます。
高度な自動分類、全文収集、reader向け互換APIはFreshRSSとの機能競争として追加しません。
初期版では全体を直列化し、上記の予算内で取得します。将来の並列化時にhost別同時数・公平性・
指数backoff/Retry-Afterを追加します。RSS 2.0とAtomを対象とし、XML外部entityは展開しません。
外部画像の同意付き表示は未実装で、現在は一律に取得・表示しません。
### OPML入出力
RSSツールバーの`⇄`から、本文ペイン内でファイル選択・確認・追加を行います。書出しは本人の内蔵購読の
名前・URL・フォルダをOPML 2.0に保存し、停止中の購読も含みます。FreshRSS接続・資格情報は含めません。
購読URLのqueryに秘密がある場合はそのURLも書き出されるため、ファイルは本人用として扱います。
既読・star・記事本文・有効状態・更新間隔のバックアップではありません。
取込はUTF-8のOPML 1.0/1.1/2.0を対象とします。OPMLは購読と階層outlineを交換する形式であり、
この実装はfeed購読部分のみ扱います。[OPML公式仕様](https://2005.opml.org/spec2.html)。
ネストしたフォルダは`親 / 子`という一つのフォルダ名へ投影します。名前のmarkupは文字情報にし、
`include`・外部outline・HTMLページの参照は取得しません。コメント扱いのoutline配下も追加対象外です。
確認表では、追加・登録済み・ファイル内重複・未対応URL/形式・名前不正を区別し、追加可能な行を選択します。
HTTPS/443と内部アドレス拒否の既存契約は維持し、ファイル取り込みを検証の迂回経路にはしません。
初期版は**追加のみ**で、置換/既存購読の削除は提供しません。有効状態と更新間隔は追加時に指定します。
保存後のfeed取得は既存の背景eventが行い、previewやimportのHTTP request中には通信しません。
上限はファイル512 KiB、記事購読候補500行、outline 1,000個、XML階層16段です。既存sourceと合わせた
32件上限を確認画面とwriter transactionの両方で検査します。既存・ファイル内重複は、hostの大小文字・
既定443 port・空pathを正規化して判定します。queryの順序、pathの大小文字、redirect先を同一視しません。
previewはsource UUID・設定versionのsnapshotを返し、適用時に一致しなければ412で再確認を求めます。
選択行の再解析、本人・Domain・有効状態の確認、source追加とreceipt保存を一つのtransactionで実行します。
同じrequest_id・同じ入力は保存結果を返し、入力が異なれば拒否します。後でsourceを削除してもreceiptを
保持するため、古い要求を再送して購読が復活することはありません。receiptはDomain・本人ごとに1,000件まで
保持し、上限時は新しいimportを拒否します。既存のWiki/タスク・既読/starは変更しません。
## Wiki保存と権利・公開
既定はURL、出典、短いメモの保存です。全文保存は取得可能性・利用条件・個人用途等を確認する独立操作とし、feedが短いからといって有料記事を自動取得しません。保存先が自動公開範囲なら内容と添付の公開を明示確認します。
Wiki単独は親Path配下の `rss-{request UUID}` に新規作成します。既存Pathを上書きせず、Page・Path・
初回Revision・活動outbox・再送receiptを同じDB transactionで保存します。権限はtransaction内でも
再確認します。初期版の単独保存は通常Wiki空間のみで、独自所有契約を持つ`/u`・`/g`は対象外です。
タスクも作成する場合は既存capture APIの原子的なWiki+タスク保存を使います。この経路のPathは
既存契約の`mail-{request UUID}`です。途中失敗時は部分的なPage/タスクを残さず、同じ要求で再試行できます。
保存先の公開範囲確認を必須にし、取得済み本文のコピーは別チェックとします。
購読削除で明示保存したWikiやタスクは消しません。内蔵cacheを削除しても既存Wikiへの参照と
再送receiptは残します。文書payloadの不変ファイルは既存Document Storeに保存するため、DB失敗時に
未参照payloadが残る可能性は既存GC契約に従い、参照のないPage/Pathとは区別します。
## TODOと受け入れ
- [x] RSS-1:read-only FreshRSS connectorと合成fixture。実接続の受入は別。
- [x] RSS-2:安全な共通一覧、出典付きWiki保存、任意のタスク化、ダッシュボード。
- [ ] RSS-3:FreshRSSへの明示的な既読/star操作と送信状態・競合・再送の契約。
- [x] RSS-4a:内蔵簡易reader、購読設定、既読・star、背景取得。
- [x] RSS-4b:OPML export/importのpreview、選択追加、重複確認、原子的な保存と再送防止。置換・状態移行は範囲外。
- [ ] RSS-5:FreshRSS実環境の接続先・版・API資格情報を指定してread-only受入。
- [ ] RSS-6:大規模利用時の公平性、host別並列上限、Retry-After/backoff、資格情報rotation UI。
- [x] RSS-7:FreshRSSの購読一覧・カテゴリを使うnavigation。同名ID分離、複数カテゴリ、cache内絞り込み、背景での原子的更新、失敗時保持。
隔離試験はRSS/Atom・FreshRSS login/read、欠落ID・巨大/不正feed、条件付きGET、失敗時cache保持、
本人分離・失効・readonly、二重送信・版競合・旧worker拒否、migration再実行/失敗rollback、
Wiki保存失敗の原子性を含みます。Chromiumの1440px/390pxで一覧・本文・検索・キー操作・
Wiki保存を試験します。実FreshRSS、newsboat、実機Safariの受入はこの合成試験に含めません。
## 実施段階
1. **共通契約とfixture**:Domain/本人のsource所有、provider ID、remote ID、cursor、取得予算、
最終成功/失敗と無効化を定義する。FreshRSS読取connectorを合成fixtureで先に検証し、
内蔵providerも同じ表示契約へ接続する。sourceの資格情報をブラウザ・ログへ出さない。
2. **読取UIと背景取得**:購読/フォルダ、記事の一行一覧、本文表示、出典リンクを用意する。
デスクトップでは一覧を見渡せる配置、スマホでは一覧と本文を切り替える。画面表示で外部fetchを
待たず、schedulerで有界に更新し、取得済みcacheと鮮度を表示する。source停止・失効も検証する。
3. **Wiki保存とタスク化**:タイトル・URL・出典・短いメモをpreviewし、保存先Pathを選ぶ。
既存captureと権限確認を再利用し、二重送信・保存先競合・自動公開範囲を検査する。全文保存は
独立した明示操作。Wiki単独保存とWiki+タスクの原子保存を分け、要求内の失敗では部分成功を
残さない。過去に保存済みのWikiは別のタスク作成失敗で削除しない。
4. **ダッシュボードとprovider完成**:読める記事だけのwidget、内蔵簡易readerとOPML、
FreshRSSの明示的な既読/star操作を段階的に追加する。接続先・対象版の指定後に実環境で
read-only→書込の順に受入し、read-only連携を有効化しただけで外部状態を変更しない。
各段階で無効化、件数・時間・容量上限、移行の再実行、ユーザー/Domain間の分離を試験する。
source解除時のcache清掃と、利用者が明示保存したWiki/タスクの保持は別操作とする。