Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
108 lines
8.2 KiB
Markdown
108 lines
8.2 KiB
Markdown
# Ordoschnellic の通知配送契約
|
|
|
|
2026-11-01、既存のWeb Push配送を `internal/ordoschnellic` に初期分離した。
|
|
通知の作成・Inboxへの登録と、登録済み通知の配送を区別する。
|
|
今回の対象は配送ループ、再試行方針、購読データ検証、暗号化したWeb Pushの送信。
|
|
メール等の新チャネル追加、通知UI変更、独立サービス化は含めない。
|
|
[コンポーネント命名](component-names.md) と [アクティブ通知](active-notifications.md) を併読する。
|
|
|
|
## 責務と依存方向
|
|
|
|
| 部品 | 所有する処理 |
|
|
| --- | --- |
|
|
| `ordoschnellic.Dispatcher` | 有界バッチ、閲覧中の延期、配送結果の集計、終了処理、キャンセルの伝播 |
|
|
| `ordoschnellic.WebPush` | 保存済み購読の検証、通知識別子の暗号化、HTTP結果の分類 |
|
|
| `ordoschnellic.Queue` | 清掃・取得・延期・完了を要求する契約。永続化の実装は所有しない |
|
|
| store | Inboxとキューの原子的登録、購読とセッションの束縛、claim時の適格性確認、lease、結果保存 |
|
|
| server | 認証済み購読API、VAPID鍵の取得、接続先制限付きHTTP client、キューadapter、イベント登録・集計ログ |
|
|
| Dregarnuhr | 既存の `notification.push.deliver` を定期実行。通知本文や受取人は決めない |
|
|
|
|
依存方向は server/store → ordoschnellic → Web Pushライブラリ。
|
|
Ordoschnellicからserver/store/DB/ファイルへ戻る依存を持たない。
|
|
接続先の公開IP検証・DNS固定・TLS・redirect禁止はserverが提供するHTTP clientで行う。
|
|
鍵providerやHTTP clientがない場合、既定clientで送信せず再試行扱いにする。
|
|
|
|
`Notification` と `PushDelivery` は共通型として分離し、既存store型はaliasで維持する。
|
|
通知APIのJSON、エラー同一性、UUID、DBテーブルとtrigger、購読ID・session hash、イベント型、
|
|
`builtin.notification.push` の定義IDは変えない。新規migrationや再購読は不要。
|
|
|
|
## 通知の生成と購読位置
|
|
|
|
業務処理が `CreateNotificationTx` を呼び、Inbox INSERT triggerが該当購読のキューを作る。
|
|
業務側のrollbackはInboxと配送キューの両方を取り消す。ネットワーク送信をこのtransactionへ入れない。
|
|
Inboxの重複キー `(domain_uuid, recipient_uuid, event_uuid, kind)` と、
|
|
キューの `(subscription_id, notification_uuid)` を維持し、同じ通知を新UUIDで作り直さない。
|
|
|
|
Activity Subscriptionのconsumer ID・watermark、Task Activityのjournal→outbox橋渡しは
|
|
別契約としてそのまま残す。Ordoschnellicという名前への置換やcheckpointの初期化は行わない。
|
|
新規Push購読への過去Inboxの一斉再送もしない。
|
|
|
|
## 認可と送信情報
|
|
|
|
claimのDB transactionで、Domain・受取人・Inbox・購読・元セッションの対応を確認する。
|
|
セッション期限/失効、Principalのactive/readonly、membershipのactive、Domainの有効性と
|
|
local配置、未読状態、24時間以内の通知であることを検査する。
|
|
条件を満たさないclaimは購読本文を渡さず、送信せずにキューを終了する。
|
|
これはclaim時点の検証であり、検証直後からHTTP送信までの失効との競合を完全には排除しない。
|
|
|
|
送信先は従来のFCM・Mozilla・Appleの許可ホストのみ。
|
|
HTTPS、userinfo/fragment/明示portの禁止、P-256鍵とauth鍵の形式検証を維持する。
|
|
任意URLへの通知チャネルではない。HTTP clientは公開IPへのDNS固定とredirect禁止を維持し、
|
|
サーバーの既存接続防御を迂回しない。
|
|
|
|
暗号化前のwake payloadは `uuid`・`owner`・`domain` の3項目のみ。
|
|
件名・本文・Bearer tokenをPushへ入れない。OS側は一般的な新着表示、詳細は認可済みInboxで読む。
|
|
VAPID秘密鍵は既存DB内にあり、今回の分離で格納場所・rotation方針は変えない。
|
|
ログは `component=ordoschnellic` とsent/failedの件数のみ。購読URL・鍵・本文は記録しない。
|
|
sentはPushサービスの2xx受付であり、端末への到達や利用者の閲覧を意味しない。
|
|
|
|
## 配送予算と終了規則
|
|
|
|
| 項目 | 維持する動作 |
|
|
| --- | --- |
|
|
| 実行間隔 | 既定30秒、priority -3。既存管理者設定を上書きしない |
|
|
| バッチ | 最大20 claim・25秒。focusedや失効済みも件数予算に含む |
|
|
| HTTP | 1要求5秒、redirectを追わない |
|
|
| claim lease | 60秒。ネットワーク処理はclaim transactionの外で実行 |
|
|
| 前面表示 | foreground lease 90秒。延期は1分、配送試行数を消費しない |
|
|
| 成功 | 2xxで現在のキュー項目を完了 |
|
|
| 再試行 | 通信/鍵取得失敗・429・5xx。試行1~4の後に2/4/8/16分、5試行目で終了 |
|
|
| 購読失効 | 404・410、または不正な保存購読データで購読を削除 |
|
|
| その他HTTP結果 | 現行仕様どおり当該通知の配送を終了。401/403も自動再試行しない |
|
|
| 保持 | キュー24時間、Push TTL 300秒。清掃は購読100件・キュー500件/run、Inboxは消さない |
|
|
| 終了保存 | 送信側contextが取り消されても独立した最大3秒で結果保存を試す |
|
|
|
|
`Queue`操作には時刻を渡し、テストでlease境界とbackoffを待ち時間なしで検証できる。
|
|
旧store入口は現在時刻を渡して委譲する。タイムアウトには実時間contextを使う。
|
|
新たにDregarnuhrから配送へcontextを伝播し、開始前キャンセルではDBにも接続しない。
|
|
不正な試行数でshiftを行わず、終端扱いにする防御も追加した。
|
|
|
|
DB失敗は呼出し元へ返し、後続claimへ進まない。バッチ時間を使い切った残件は次回実行へ回す。
|
|
親contextのキャンセルはエラーとして返す。Dregarnuhrの汎用ジョブに期限付きleaseが未実装でも、
|
|
Pushキューには既存の60秒leaseがある。この二つを混同しない。
|
|
|
|
## 配送保証と残件
|
|
|
|
初期分離はexactly-onceを導入しない。HTTP成功直後にプロセスが停止したり結果保存に失敗すると、
|
|
lease後に再送され得る。ブラウザ側のtagによる集約は端末表示の対策であり、配送の一回性ではない。
|
|
通常の完了更新はattempt一致を検査するが、これを完全なfencingと呼ばない。
|
|
|
|
- [ ] claim世代をattemptと分離する。focused延期によるattempt減算では世代が再利用されるため、古いworkerの結果との競合が残る。
|
|
- [ ] 404/410による購読削除を購読version/claim世代で条件付けする。現在はIDだけで削除するため、送信中に更新された同一購読を削除し得る。
|
|
- [ ] claim後の失効と送信の競合を整理する。送信直前の再検証も完全な原子性を保証しないことを明記する。
|
|
- [ ] Retry-After、失敗理由別のメトリクス、キュー深さ・最古待機時間、枯渇/失効/廃棄件数を追加する。本文・endpointは観測属性にしない。
|
|
- [ ] lease超過や多重workerの障害試験、HTTP成功後のDB失敗を含む復旧手順を整備する。
|
|
- [ ] quiet hours、digest、チャネル別設定、メール等の配送はrecipient/channel/versionの冪等キーと受入条件を決めてから追加する。
|
|
- [ ] 実機のPush受信・再訪・ログアウト、VAPID rotation、端末一覧UIは既存の残件として継続する。
|
|
|
|
## 検証と反映
|
|
|
|
合成データ・一時DB・偽HTTP clientのみで検証する。実通知サービスへの送信、
|
|
本番DBや外部から取り込んだカレンダー内容へのアクセスは行わない。
|
|
境界・型/JSON/イベントID互換、バッチ上限、キャンセル後の終了保存、HTTP分類、暗号化、
|
|
認可失効、並行claim、lease回収、旧attempt完了の拒否、focus延期、Inbox保全を対象とする。
|
|
既存のtransaction rollback・重複抑止・Activity Subscriptionのcheckpoint試験も維持する。
|
|
|
|
検証結果は [コンポーネント検証記録](component-names.md#検証記録) に記載する。
|
|
ソース変更とテスト、本番反映は別段階。commit・push・デプロイは今回含めない。
|