Files
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

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