Files
pages/docs/design/ja/active-notifications.md
T
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

6.7 KiB
Raw Blame History

アクティブ通知とWeb Push

更新:2026-09-25。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。反映記録。実機Push受信確認は未実施。

2026-11-01追記:配送処理を Ordoschnellic へ初期分離。 以下のUI・API・DB・購読を維持するソース変更であり、この分離自体は未デプロイ。 claim世代と購読更新競合を含む配送保証・残件は同契約に記録する。

UIと設定

通知ベルを開いたInboxの「⚙ 通知設定」に集約する。アカウント・ドメイン・ブラウザごとにlocalStorageへ保存し、他ユーザの設定を継承しない。通知本文はlocalStorageに保存しない。

状態 動作
フォーカス中 右下に8秒で消えるトースト。最大3個。入力フォーカスを奪わない。既定ON
別タブ・別ウィンドウ/タブ終了 明示的に許可した端末へWeb Push。OSの通知UIを使用
再訪 前回訪問以降の未読がある場合、設定ONならInboxを自動表示。既定OFF
ダイアログ・入力を操作中 自動Inboxは保留し、次の確認時まで待つ

新着は30件ずつ取得し、Inboxは「さらに表示」でページングする。訪問watermarkはサーバー時刻を使う。Web Locksと通知UUIDの短い履歴(最大200個)で複数タブのトーストを抑制する。Web Locks非対応時はbest effort。

音は「なし/ソフト/チャイム/ベル」と音量・試聴。Web Audioはブラウザの自動再生制限に従い、利用者の操作後に有効になる。カスタム音はフォーカス中のページ通知用。背景/タブ終了時の音はOS設定で決まり、サイト側から任意の音に置き換えることは保証しない。

ブラウザの通知許可は設定操作時のみ要求する。HTTPSと対応ブラウザが必要。iOS等はホーム画面への追加など端末側の条件もある。サービス・省電力・通信・キュー待ちに依存するため、定刻到達を保証するアラーム用途ではない。

配信経路と安全性

notification_inbox挿入のDB triggerでnotification_push_queueへ原子的に追加する。Inboxの全種類(タスク期限・計画日、Pomodoro、アナウンス等)で同じ経路を使う。購読開始前の通知を一斉再送しない。

/_/api/v1/notifications/push:

  • GET: VAPID公開鍵のみ。秘密鍵はDB内部に保存。
  • POST: PushSubscription、focused、seen(最大30通知ID)。購読更新/閲覧中のack。
  • DELETE: 現在の利用者が所有する購読を削除。

購読はDomain・Principal・元の認証セッションのハッシュに束縛する。Bearer tokenは保存しない。claim時にセッション期限/失効、Principal、membership、Domain配置を再確認する。この時点でログアウト済み・無効化済みなら送信しない。claim後の失効と送信の競合は残る。最大8購読/利用者・Domain、30日lease(閲覧時に更新)。

VAPID秘密鍵はnotification_push_keysに保存するため、DBバックアップを秘密情報として扱う。鍵を失った復旧では再購読が必要。端末の購読URL・鍵・通知本文をログへ出さない。

送信先はChrome/Chromium FCM、Mozilla Push、Apple Web Pushに限定。HTTPS/443のみ、資格情報・fragmentを拒否し、公開IPをDNS解決後に固定する。proxy環境変数とredirectは使用しない。プライベートIPへの接続は禁止する。Push本文は暗号化された通知UUID/受取人UUID/Domain UUIDのみ。件名・本文をPushサービスへ送らない。OSに表示するのも一般的な「新着通知」のみ。クリック後に通常の認可されたInboxで詳細を表示する。

Service Workerは/static/js/notifications-worker.js、scopeは/static/js/。fetch handlerやページキャッシュを持たず、既存のWikiページ/エディタに古い内容を返さない。notificationclickは同一originの/v/notificationだけを開く。

スケジューラと上限

イベントnotification.push.deliver、定義builtin.notification.push。既定30秒、priority -3。設定画面のイベント設定から停止・間隔変更・手動実行でき、再起動で既存設定を上書きしない。

  • 最大20件/run、全体25秒、送信要求5秒。DB transaction内でネットワーク通信しない。
  • 60秒のclaim lease。期限切れを再取得できる。クラッシュ時はat-least-onceだが、ブラウザ通知tagを固定し積み上げない。
  • 429/5xx/通信失敗は指数backoff、最大5試行。404/410は購読を削除。
  • キューの有効期間24時間、Push側TTL300秒。期限切れキュー削除は最大500件/run、期限切れ購読削除は100件/run。
  • フォーカスlease90秒。閲覧中は送信を延期し、ブラウザが一覧を受け取った通知のackでキューを消す。表示できなかったままタブが閉じればlease終了後に再評価する。
  • 前面pollは30秒。Pushが有効な背景タブは定期pollを停止し、Pushと復帰を契機に更新する。
  • sent/failed集計をイベントログへ記録。再送でもInbox本体は複製しない。

フォーカスを失う瞬間やネットワーク遅延にはraceがあり、OS通知を完全に抑制する保証はしない。常に通知権限とOSの設定が優先する。

検証・残TODO

  • Go: 原子rollback、claim重複防止、focus延期とack、他人のack拒否、失効後の配信遮断、backoff、購読API認証、公開鍵のみ、送信先とP-256鍵検証、イベント設定保持。
  • Chromiumの合成fixture: 前面トースト、再訪Inbox、設定モーダルの横幅、既存Inbox既読/バッジ。実通知サービスへは送っていない。
  • TODO: 実機Chrome/Firefox/Safari/iOSでの購読・閉タブ配信・復帰・logoutを確認。Pushサービス障害テストの拡充、端末一覧/VAPID rotation UI、quiet hours/digest、種類別設定、OS通知の詳細表示opt-in、端末間の個人設定同期。
  • TODO: expired/revoked購読の清掃メトリクス、Push queue深さ/遅延/失敗コードの管理UI。旧worker購読の移行手順。

参考:MDN Push API、MDN Notifications API、webpush-go。