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.
8.2 KiB
Ordoschnellic の通知配送契約
2026-11-01、既存のWeb Push配送を internal/ordoschnellic に初期分離した。
通知の作成・Inboxへの登録と、登録済み通知の配送を区別する。
今回の対象は配送ループ、再試行方針、購読データ検証、暗号化したWeb Pushの送信。
メール等の新チャネル追加、通知UI変更、独立サービス化は含めない。
コンポーネント命名 と アクティブ通知 を併読する。
責務と依存方向
| 部品 | 所有する処理 |
|---|---|
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試験も維持する。
検証結果は コンポーネント検証記録 に記載する。 ソース変更とテスト、本番反映は別段階。commit・push・デプロイは今回含めない。