Files
pages/docs/design/ja/dregarnuhr.md
T

149 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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秒上限を保証するものではない。
## v0.2.0後の優先修正:ログ保存競合
2026-11-01、ソース実装・合成データ検証。基点は `0f686aa`。
同日20:00 JST、[v0.2.1として本番反映](../../operations/deployments/2026-11-01-v0.2.1.md)した。
v0.2.0本番観察で開始ログ保存のSQLITE_BUSY_SNAPSHOT(517)が発生したため、
読取transactionをwriterへ昇格させる `AddEventLog` を修正した。
- `AddEventLogContext` は専用接続の `BEGIN IMMEDIATE` で書込権を先に取得し、
イベント型/保持policyの読取、rawログ、集約bucketを同じtransaction内で扱う。
DBスキーマ・公開API・ジョブの実行規則は変更しない。
- 予算は最大2秒、呼出し元に短い期限があればそちらを優先する。
接続取得後のSQLite busy待機を50msに限定し、BEGINのBUSYだけを10〜80ms間隔で再試行する。
書込開始後やCOMMIT応答不明時の再送はしない。これにより内部retryの二重集計を避ける。
OS/接続初期化/ドライバの停止までを含む厳密な実時間保証ではない。
- 取消時も独立した最大1秒のcleanupでROLLBACKと接続のbusy_timeout復元を試みる。
transaction状態や待機設定を確定できない接続はpoolへ戻さない。
- 通常のイベント型取得はJob UUIDの主キー検索。履歴全走査やOR条件のsortを
writer lock内で行わない。Job不在かつEvent UUID指定時のみ従来のfallbackを使う。
空のEvent UUIDで無関係なジョブを拾わない。DB読取エラーを既定policyで隠さない。
- rawログとbucketの途中失敗は両方rollback。ログ保存が成功した場合のみ両方を確定する。
これはログ呼出し間のexactly-once保証ではなく、単一呼出し内の原子性である。
- 完了状態を保存後にログだけ失敗した場合は `ErrEventCompletionLog` を返す。
server adapterは `finish-log failed` として報告し、完了状態を失敗へ変えたり
成功した業務処理を再実行したりしない。開始/進捗の失敗も別stageで報告する。
- ログ保存失敗の診断はcomponent、Job UUID、イベント型、エラー分類/SQLite codeだけ。
ドライバの生メッセージ、SQL、進捗本文、payload、認証情報はcomposeログへ転載しない。
受入試験は独立8接続の320件ログと別writer、原子rollback、取消後の再利用・待機設定復元、
readonly、空ID誤分類、policy読取失敗、主キー利用、完了/retry状態の維持、
開始・進捗・完了の失敗診断と秘密の非露出を対象とする。
全Goテスト(`go test ./... -count=1`)、全Go vet、関連store/server試験のrace検査
(3回)が成功。通常の関連store試験は20回反復して確認した。
テストは一時DBと合成ジョブのみ。本番DB・外部カレンダー・実通知先は使用しない。
長時間ロックで保存できなかったログの自動回収、完了状態とログ自体の一体commit、
event-only fallback検索や保持処理の最適化は後続。v0.2.0タグは変更せず、
新しいPATCH版v0.2.1として別途検証・公開した。
## 未実装:リース・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を使う処理も残る。
- [x] 開始/進捗/完了ログのcontext伝播、有界writer取得、ログ保存失敗の診断(v0.2.1で本番反映)。
- [ ] 古い設定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・本番展開は別段階として記録する。