Files
pages/docs/design/ja/feeds.md
T
Anya Tokugawa 38daea737d
Build and publish container images / images (push) Successful in 12m32s
feat: render RSS HTML bodies and simplify reader navigation
2026-11-08 04:00:27 +09:00

15 KiB
Raw Blame History

15. RSSビューア・FreshRSS・newsboat

状態:内蔵簡易reader、FreshRSS読取connector、共通viewer、Wiki保存・タスク化、ダッシュボードを実装。 FreshRSSへの書戻し・OPMLは残件。本番反映と実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、newsboat公式マニュアル。

本格運用は 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仕様。

高密度ビューア

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 item?source=…&id=… 本人の記事本文
POST state 内蔵read/starの条件付き変更。FreshRSSは拒否
POST note 公開範囲確認付きのWiki単独保存。request_idと入力hashで再送を識別

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で無効化します。 既存テーブルを破壊・再構成しません。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件の窓を取得。更新成功時はその窓で置換し、全履歴同期とはしない
再試行 次の設定間隔まで待機。手動予約にも最終成功から60秒の制限、取得中の重複claim拒否

内蔵は条件付きGET、304ではcacheを保持します。どちらのproviderも通信・認証・構文失敗で 前回cacheを消しません。sourceには安全な失敗分類と最終成功日時を表示し、イベントログには 成功/失敗件数だけを記録します。資格情報・生本文・秘密を含み得るURLをログへ出しません。 extension無効化は画面・API・取得・完了保存に適用します。購読を登録するまで外部通信は発生しません。

既読・star同期を追加する条件

server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。

FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。

内蔵簡易reader

購読追加/削除、フォルダ、記事一覧、既読/未読、star、更新間隔と保持上限を初期範囲に します。取得は背景ジョブで行い、更新失敗で購読や状態を消しません。記事本文cacheと 既読・starの保持期間を分離し、古い記事を再取得しただけで未読へ戻る挙動を防ぎます。 高度な自動分類、全文収集、reader向け互換APIはFreshRSSとの機能競争として追加しません。

初期版では全体を直列化し、上記の予算内で取得します。将来の並列化時にhost別同時数・公平性・ 指数backoff/Retry-Afterを追加します。RSS 2.0とAtomを対象とし、XML外部entityは展開しません。 外部画像の同意付き表示は未実装で、現在は一律に取得・表示しません。

OPMLは購読の入出力として扱い、既読・star・全本文のバックアップと同一視しません。importはpreview・追加/置換選択・重複確認を行い、既存購読を黙って削除しません。

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と受け入れ

  • RSS-1:read-only FreshRSS connectorと合成fixture。実接続の受入は別。
  • RSS-2:安全な共通一覧、出典付きWiki保存、任意のタスク化、ダッシュボード。
  • RSS-3:FreshRSSへの明示的な既読/star操作と送信状態・競合・再送の契約。
  • RSS-4a:内蔵簡易reader、購読設定、既読・star、背景取得。
  • RSS-4b:OPML export/importのpreview、重複確認、明示移行。
  • RSS-5:FreshRSS実環境の接続先・版・API資格情報を指定してread-only受入。
  • RSS-6:大規模利用時の公平性、host別並列上限、Retry-After/backoff、資格情報rotation UI。
  • RSS-7:FreshRSSの購読一覧・カテゴリを使うnavigation。現在の左ペインはPagesWikiに登録したsourceとそのフォルダで、FreshRSSの全購読一覧ではない。

隔離試験は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/タスクの保持は別操作とする。