feat(feeds): queue explicit FreshRSS state changes with uncertain-outcome recovery
Build and publish container images / images (push) Failing after 12m40s

This commit is contained in:
Anya Tokugawa committed 2026-11-08 05:51:47 +09:00
1 parent 16e572397b
commit 131a7ca01f
12 files changed
+973 -58

No files matched your search

+29 -10
View File
@@ -1,7 +1,7 @@
# 15. RSSビューア・FreshRSS・newsboat
状態:内蔵簡易reader、FreshRSS読取connector、共通viewer、Wiki保存・タスク化、ダッシュボードを実装。
OPMLの確認付き追加取り込み・書出し、FreshRSS購読・カテゴリのnavigationも実装済み。FreshRSSへの書戻しは残件。本番反映と実FreshRSSへの接続は未実施。
OPMLの確認付き追加取り込み・書出し、FreshRSS購読・カテゴリのnavigation、opt-inの既読・star書戻しを実装済み。本番反映と実FreshRSSへの接続は未実施。
既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。
2026-11-08:利用者指定のサブプロジェクト順で最初に実施する。内蔵readerは簡易利用の
@@ -33,7 +33,7 @@ FreshRSS停止時は取得済みcacheと鮮度・接続状態を示し、内蔵
## 実装済みの読取機能
`/v/feeds` に購読一覧、フォルダ、記事一覧、外部原文へのリンク、Wiki保存を提供します。
FreshRSSの記事・既読・starは取得しますが、状態の変更は送信しません。UIにも読取専用と明示し、
FreshRSSの記事・既読・starを取得します。既定は読取専用で、source設定で明示的に許可した場合だけ状態の変更を送信します。
FreshRSS passwordを設定時以外にブラウザへ返さず、login tokenはbackend内でのみ利用します。
資格情報は既存の暗号化機構を使い、Domain・所有者・source UUID・用途に束縛します。
@@ -52,7 +52,7 @@ tooltipに残します。タブ名は「RSS」、原文リンクはアイコン
`j/k`・上下矢印で移動、`Enter/l`で本文、`Esc/h`で一覧、`/`で件名・配信元検索、`n`で次の未読、
`m`で既読切替、`*`でstar、`r`で背景更新予約、`?`でキー案内です。フォーム入力・IME変換中は
一覧ショートカットを抑止します。FreshRSSでは`m`と`*`も外部変更を行いません。
一覧ショートカットを抑止します。FreshRSSでは書戻し許可時だけ`m`と`*`で操作を予約します。
HTML本文は見出し・表・箇条書き・強調・リンクを保持して描画し、plain textは文字情報として表示します。
server側の許可リストでscript・イベント属性・任意CSS・form・iframe・画像等を除去し、表示時にも再検査します。
@@ -75,6 +75,9 @@ API prefixは `/_/api/v1/extension/organizer.feeds/`。Domain内の本人専用
| `GET catalog?source=…` | 本人のFreshRSS購読・カテゴリの取得済み一覧。外部通信なし |
| `GET item?source=…&id=…` | 本人の記事本文 |
| `POST state` | 内蔵read/starの条件付き変更。FreshRSSは拒否 |
| `POST remote-state` | FreshRSSの一記事・一項目の変更を予約。request_id、source、id、field、desired、source_versionを指定 |
| `GET action?source=…&id=…` | 本人の記事の最新操作記録。外部通信なし |
| `POST action/check` | request_idで結果不明操作の読取専用再確認を予約 |
| `POST note` | 公開範囲確認付きのWiki単独保存。request_idと入力hashで再送を識別 |
| `GET opml/export` | 本人の内蔵購読をOPML 2.0としてダウンロード |
| `POST opml/preview` | ファイルを解析し、追加可能・登録済み・重複・未対応等を返す。保存・外部通信なし |
@@ -86,6 +89,9 @@ v2で`feed_items.body_html`を追加します。既存のテキスト本文・
v3で`feed_import_receipts`を追加し、購読の一括追加と再送記録を同時保存します。
v4でsourceに購読一覧、記事にremote feed ID・カテゴリIDを追加します。FreshRSSの旧workerを
versionで無効化し、次の背景取得を予約します。内蔵sourceのversion・取得予約は変更しません。
v5でsourceの`write_enabled`(既定OFF)と`feed_actions`を追加します。操作記録はsourceを削除しても保持し、
送信済みの可能性があるものはunknown、未送信はcancelledにします。DB更新前にバックアップを取得し、
旧バイナリへの切戻しだけで追加schemaが巻き戻るとは扱いません。
既存テーブルを破壊・再構成しません。SQLiteのforeign_keys設定に依存せず削除を完遂するtriggerを
持ちます。内蔵read/starを本文cacheから分離し、記事を保持窓から落としても状態は黙って消しません。
DBは内蔵購読・状態・保存receiptの正本であり、全体を捨てられるcacheとは扱いません。
@@ -100,6 +106,7 @@ sourceのprovider・URL・資格情報の変更は別sourceを作る契約です
| --- | --- |
| 個人のsource数 | Domain・本人ごとに32 |
| 定期event | `feed.source.sync`、既定60秒周期、低優先度、1回最大4 sourceを直列取得 |
| 書戻しworker | 同じevent内で最大2操作を先に処理。各8秒、取得と合計35秒の予算を共有し、残り9秒未満なら次の操作・取得を開始しない |
| source更新間隔 | 5〜1440分、既定30分。取得候補になる間隔であり、混雑時の完了時刻保証ではない |
| 通信予算 | 1 source 8秒、batch 35秒、応答/展開後本文4 MiB |
| 外部接続 | 公開HTTPS/443のみ。DNS検査・接続先固定、内部アドレス・redirect・proxyを拒否 |
@@ -127,22 +134,24 @@ source指定と組み合わせ、既存の未読・star・検索・keysetペー
絞り込み対象は最新200記事のcache内に限られ、購読を選んでも履歴全件を外部取得しません。
購読の追加・削除やカテゴリの編集はFreshRSS側で行います。
## 既読・star同期を追加する条件
## 既読とstarの書戻し
server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。
FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。
FreshRSSへの変更は一項目のtag追加・削除です。更新直前の状態と不可分に照合するCASではないため、
他clientとの同時操作を完全に直列化する双方向同期ではありません。
### 書戻しの次段階設計
### 操作記録と送信状態
以下は未実装のRSS-3です。購読navigationの追加だけでは書戻しを有効にしません。
sourceごとに既定OFFの書戻し設定を設け、操作は`read`または`starred`の一項目と希望値に限定します。
RSS-3は合成環境で実装・検証済みです。sourceごとに既定OFFの「FreshRSSの既読・star変更を許可」を設け、操作は`read`または`starred`の一項目と希望値に限定します。
cache内の他項目を同時に送らず、全件既読・購読編集も初期対象に含めません。
操作記録は記事cacheから分離し、Domain・本人・request_id、source・記事ID、対象項目、希望値、
source version、状態、claim期限を保持します。同一request_idの同じ入力は同じ記録を返し、
違う入力は拒否します。同じ記事に未解決の操作がある間は次の操作を受け付けません。
受付APIは外部通信せず、低優先度workerが送信します。記録数とworkerの時間予算は必ず有限にします。
受付APIは外部通信せず、低優先度workerが送信します。Domain・本人ごとに未解決20件、全記録10,000件を上限とし、
上限で新規受付を拒否します。receiptを自動削除して古い要求を再送可能にすることはしません。
queuedは受付から5分で失効します。claimは60秒で、期限切れsending/checkingはunknownにし、変更を再送しません。
| 状態 | 次の処理 |
| --- | --- |
@@ -160,6 +169,15 @@ source version、状態、claim期限を保持します。同一request_idの同
外部clientとの同時変更を原子的に防げないAPIでは、確認直後に状態が再変更される可能性もあります。
readbackは観測結果であり、exactly-onceやリモートCASの保証とは区別します。
結果不明時は操作欄の`↻`からclaim期限後に再確認できます。書戻し設定をOFFにしても、sourceが有効なら
この読取専用再確認は可能です。画面は未解決操作の間だけ2秒間隔で自サーバーの記録を確認し、
背景タブでは停止します。記事の既読・star表示は遠隔の状態を確認するまで切り替えません。
再確認で希望値と異なる場合はconflictを表示し、新しい変更は利用者が明示的に操作します。
外部APIはlogin、記事参照、変更token、edit-tag、記事再参照の順です。記事の個別参照は
`POST stream/items/contents`(読取操作)、変更は`POST edit-tag`に`i`・`T`・`a`または`r`一項目を送ります。
URLや本文、資格情報を操作記録・ログへ保存しません。[FreshRSS API実装](https://github.com/FreshRSS/FreshRSS/blob/edge/p/api/greader.php)。
受入テストは、opt-inなしの拒否、同じ操作の再送、別項目の保持、送信前の権限失効、
送信直後の応答喪失、worker停止・再起動、unknownの読取専用再確認、source削除・設定変更、
通常取得との排他、他clientによる同時変更を含めます。実サービスを使わない合成fixtureで
@@ -222,7 +240,8 @@ Wiki単独は親Path配下の `rss-{request UUID}` に新規作成します。
- [x] RSS-1:read-only FreshRSS connectorと合成fixture。実接続の受入は別。
- [x] RSS-2:安全な共通一覧、出典付きWiki保存、任意のタスク化、ダッシュボード。
- [ ] RSS-3:FreshRSSへの明示的な既読/star操作と送信状態・競合・再送の契約。
- [x] RSS-3:opt-inの既読/star書戻し、操作receipt、背景処理、readback、結果不明の再確認、失効・競合・排他の合成試験。
- [ ] RSS-3b:未解決操作の総覧、cache窓から落ちた記事や削除sourceの操作記録確認、保全付きreceiptの整理。既存のGET action/action/checkは記事IDで利用できる。
- [x] RSS-4a:内蔵簡易reader、購読設定、既読・star、背景取得。
- [x] RSS-4b:OPML export/importのpreview、選択追加、重複確認、原子的な保存と再送防止。置換・状態移行は範囲外。
- [ ] RSS-5:FreshRSS実環境の接続先・版・API資格情報を指定してread-only受入。