# 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・デプロイは今回含めない。