Files
pages/docs/design/ja/dregarnuhr.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

109 lines
8.0 KiB
Markdown

# Dregarnuhr:イベント実行基盤
2026-11-01。初期分離を実装。公開API・永続データ形式は変更しない。
名称と全体の移行順序は [コンポーネント命名と責務](component-names.md)、
イベント仕様は [Event Scheduler](../event-scheduler.md) を参照。
## 目的と今回の境界
Dregarnuhr は「いつ、何件を実行し、失敗後にいつ再試行するか」を担当する。
カレンダー同期、通知配送、City再構成、プレビュー生成の内容は担当しない。
神名の導入に合わせ、従来の `server` にあった実行ループと制御を
`internal/dregarnuhr` に分離した。別サービスや別コンテナにはしない。
| 層 | 責務 | 主な実装 |
| --- | --- | --- |
| 汎用実行基盤 | 時刻、定期フック、実行枠、ハンドラー呼出し、完了判定、再試行計算 | `internal/dregarnuhr` |
| アプリケーション | 14種類の既存イベント登録、業務payload、監視・設定との接続 | `internal/server/event_handlers.go`、`dregarnuhr_queue.go` |
| 永続化 | 優先順位付きatomic claim、実行状態、イベント定義、ログ・保持設定 | `internal/store/event_jobs.go` |
依存方向は server/store → dregarnuhr。Dregarnuhr は server、store、DB、
ネットワーク、ファイルI/Oを直接参照しない。パッケージ境界をテストで固定する。
SQLのスケジュール定義評価や投入時の重複排除は、今回の分離ではstoreに残す。
## 契約
- `Clock` / `Timer`:現在時刻とタイマーを注入する。テストは仮想時間を進め、実時間の待機に依存しない。
- `Loop`:定期dispatch、初回のみの処理、繰り返し処理、外部wakeをまとめる。
遅延したtickはまとめて処理し、取り戻すために何千回も連続実行しない。
- `Registry`:イベント型から `Handler(context.Context, *Job)` を引く。
空名、nilハンドラー、重複登録は拒否。未登録型は既存同様エラーになる。
- `Queue`:設定読込、atomic claim、キャンセル状態確認、開始ログ、完了保存のアダプター契約。
`ErrNoJob` は正常な空キューを表す。既存storeの `sql.ErrNoRows` はアダプターで変換する。
- `Runner`:実行枠の確認からclaimまでを同一runner内で直列化し、ハンドラーをgoroutineで実行する。
1回のdispatchは最大32件。完了で枠を解放し、次のdispatchをwakeする。
- `Complete` / `RetryDelay`:DBを触らず完了状態と再試行時刻を算出する。
`store.EventJob` / `QueueSettings` / `ErrEventSkipped` は互換aliasを維持する。
既存のHTTPエンドポイント、JSONフィールド、イベント型・ID・キー、consumerのcheckpoint、
DBスキーマ、UI表示名は変更しない。実行ログには `component=dregarnuhr` を付ける。
payloadを新たにログへ出力しない。業務エラー本文の安全性は引き続き各ハンドラーで担保する。
## 維持する実行規則
優先順位は `priority DESC, run_at_ms, created_at_ms, uuid`。
SQLiteの単一 `UPDATE ... RETURNING` で選択とclaimを行い、同じジョブの二重claimを防ぐ。
同一プロセスの実行上限はキュー設定に従う。foregroundリクエストがある間は、
既存ジョブを強制終了せず、実行中が0件の場合に限り1件を開始できる。
これにより長時間の編集接続があってもバックグラウンドを完全停止させない。
| フック | 間隔 |
| --- | --- |
| 定義評価・dispatch | 1秒、またはwake時 |
| 初回プレビュー走査 | 起動後5秒 |
| 定期プレビュー走査 | 15分 |
| 履歴整理 | 1時間 |
| 承認期限・City変更の走査 | 10秒、またはwake時 |
遅延後の定期フックは実行時刻から次の間隔を数える。厳密な壁時計への位相固定や
取り逃した回数分のcatch-upは行わない。業務イベント定義のスケジュール方式は変更しない。
成功は `succeeded`、適用対象外は `skipped`、キャンセル要求を伴う失敗は `cancelled`。
その他の失敗は上限前なら `queued`、上限到達なら `failed`。
再試行は基準秒数 × 2^(試行回数−1)、上限24時間。
例えば基準30秒なら最初の失敗後30秒、次は60秒となる。
## 同時に是正した点
1. 複数呼出しが同時に空き枠を確認して上限を超える競合を、runnerのadmissionロックで防ぐ。
2. 再試行秒数・試行回数が極端に大きくても、durationのオーバーフロー前に24時間へ飽和させる。
従来の通常設定での待ち時間は同じだが、初回から24時間を超える基準値も上限対象となる。
3. 業務ハンドラーのpanicを失敗として記録・再試行対象にする。panicの内容自体は記録しない。
4. キャンセル状態のDB読込失敗を「キャンセルなし」と扱わない。業務処理を止め、失敗経路へ送る。
5. worker contextが取り消されても、独立した5秒contextで完了保存を試みる。
保存失敗はログへ出す。旧式の設定・ログ用DB呼出しにはcontext未対応部分が残るため、
保存処理全体の厳密な5秒上限を保証するものではない。
## 未実装:リース・HA・終了処理
**atomic claimは期限付きリースではない。現時点は単一writerプロセスの運用を前提とする。**
別プロセス同士の同時実行数は共有されず、定期定義の投入もHA対応ではない。
完了UPDATEはUUIDで対象を指定しており、旧workerの遅延完了を防ぐfencingはない。
既存の起動時復旧は `running` を再投入するため、他のwriterが生きている状態では実行してはならない。
exactly-onceの配送・実行は保証しない。外部副作用の冪等性は業務ハンドラー側の責務となる。
- [ ] owner、attempt/claim token、lease expiry、heartbeatを永続化する。
- [ ] 完了・キャンセル更新で所有権とattemptを比較するfencingを導入する。
- [ ] 期限切れ回収と定期投入を複数プロセスから安全に実行し、全体の実行上限を定義する。
- [ ] 成功後・完了保存前の障害、lease更新停止、旧workerの遅延完了を障害注入試験する。
- [ ] アプリケーションの停止contextをschedulerに接続し、受付停止・実行中処理のdrain・期限付き終了を実装する。
- [ ] 各業務ハンドラーへcontextを伝播する。現状は独自のBackground/timeoutを使う処理も残る。
- [ ] 古い設定・ログDB呼出しをcontext対応にする。完了保存失敗の回収方針も定義する。
コアのLoop/Runnerはキャンセルを受け付けるが、現行アプリケーションは従来どおり
Background contextで起動する。これをgraceful shutdown対応済みとは扱わない。
これらはDB migrationとDR/authority設計を伴う後続作業であり、命名・初期分離に混在させない。
## 検証方針
本番DB、外部カレンダーの内容、実際の通知配送先には触れず、一時DB・合成ハンドラーで検証する。
- fake clock:初回・定期・wake、長時間遅延、閉じたwake channel、キャンセルとtimer解放。
- race detector:並行dispatch、foreground制限、registryの排他、実行カウンター。
- 一時DB:優先順・独立DB接続でのclaim、時刻境界、試行回数、30秒/60秒retry、各終了状態。
- server接続:14ハンドラーの登録、実行間隔、永続状態と監視counter、read-only/ジョブ無効化の抑止。
- 全Go回帰テスト・静的検査。既存API・業務イベントのテストも併用する。
実行結果は [命名文書の検証記録](component-names.md#検証記録) に追記する。
ソース変更・テスト・commit・CI・本番展開は別段階として記録する。