Rust + PostgreSQL で実装している、複数サービス向けの外形監視・通知ハブ。
複数の個人プロジェクトを定期的に監視し、HTTP probe の結果を記録して、異常時に incident を生成し Slack へ通知することを目的としています。
Render / Neon の無料枠を前提に、常駐 scheduler は持たず、外部 scheduler から POST /v1/runs を呼び出して1巡を開始する構成です。
ポートフォリオプロジェクトです。 現在は監視実行の入口・排他制御・取り残し回収・target の HTTP probe と結果記録・CI / Ruleset まで実装済みで、状態遷移・incident・通知は Task 09 以降で実装します。
複数の個人プロジェクトを運用していると、「サービスが落ちていないか」をそれぞれ個別に確認する必要があります。
このプロジェクトでは、単に HTTP を定期実行するだけではなく、特に次の点を自分で設計・実装することを目的としています。
同じ巡回を二重実行させないこと。
GitHub Actions などの外部 scheduler から呼び出す場合、前回の巡回が終わる前に次の実行が始まる可能性があります。PostgreSQL advisory lock を利用し、同時に1巡だけが動くようにしています。
途中でプロセスが死んでも状態を回収できること。
実行途中でプロセスが消えると、DB には running の run が残ります。一方、advisory lock はセッション単位なので、異常なセッションが残れば以降の巡回を塞ぐ可能性があります。この2種類を分け、自動スイーパーと手動の脱出ハッチを用意しています。
無料枠でも運用できること。
常駐 scheduler をアプリ内に持つと、Render のスピンダウンや無料枠の制約と相性がよくありません。定期実行そのものは外部に任せ、アプリは1回分の巡回を開始する API を提供する設計にしています。
| 機能 | エンドポイント / CLI |
|---|---|
| DB を含む health check | GET /health |
| process liveness | GET /livez |
| 監視 run の開始 | POST /v1/runs |
| stale run の自動回収 | run 開始時の sweeper |
有効な target への HTTP probe と checks への記録 |
run のバックグラウンド処理 |
| advisory lock holder の確認 | ops-hub unlock |
| advisory lock holder の手動切断 | ops-hub unlock --force |
POST /v1/runs は advisory lock を取得できた場合に 202 Accepted を返し、バックグラウンドで run を実行します。
すでに別の run が実行中の場合はエラーにはせず、
200 already_running
として扱います。
競合時の run_id はタイミングによって取得できず、null になる場合があります。
run は有効な target を PROBE_CONCURRENCY(既定4)件ずつ並行に probe し、結果を checks に記録します。
| 結果 | 条件 |
|---|---|
success |
expected_status と一致(degraded_threshold_ms 超過なら degraded = true) |
http_error |
応答はあったがステータスが不一致(リダイレクトは追わない) |
timeout |
timeout_ms 以内に応答ヘッダが返らない |
connection_error |
DNS・TCP・TLS など接続段階の失敗 |
対象が落ちていても run 自体は completed になります。error_detail の URL はユーザ情報とクエリ文字列を伏せてから保存します。
状態遷移、incident、Slack 通知は今後の実装範囲です。
GitHub Actions / external scheduler
│
│ POST /v1/runs
▼
Rust + axum API
│
┌───────────┴───────────┐
│ │
▼ ▼
stale run sweeper advisory lock
│ │
└───────────┬───────────┘
│
▼
run_service
│
▼
target / probe / checks
│
│ Task 09以降
▼
target_states / incidents
│
▼
outbox / Slack
│
▼
PostgreSQL 17
(Neon)
現在は run_service の入口、排他制御、run の記録、stale run の回収、target の probe と checks の記録まで実装済みです。
ops-hub/
├── .github/
│ ├── dependabot.yml
│ └── workflows/
│ ├── ci.yml
│ └── security-audit.yml
├── back_cargo/
│ ├── .sqlx/ # SQLx offline query metadata
│ ├── migrations/ # 0001〜0004
│ ├── src/
│ │ ├── main.rs # serve / healthcheck / unlock
│ │ ├── lib.rs # router
│ │ ├── config.rs
│ │ ├── recovery.rs # stale run / advisory lock recovery
│ │ └── service/
│ │ └── run_service.rs
│ ├── tests/
│ │ ├── runs_test.rs
│ │ ├── run_lock_test.rs
│ │ └── recovery_test.rs
│ ├── Cargo.toml
│ └── compose.yaml
├── src/ # React / Vite scaffold
├── scripts/
│ ├── assert_local_database_url.py
│ ├── check_ruleset_contract.py
│ └── github/
│ ├── main-ruleset.json
│ ├── verify_main_ruleset.py
│ └── sync_main_ruleset.py
├── CLAUDE.md # AI エージェント向けの作業ガイド(.cursor/rules/ も同じ内容の要約)
├── Makefile
└── package.json
Render の無料枠ではアクセスがない状態でプロセスが停止するため、アプリ内の timer や常駐 scheduler を実行基盤として信用できません。
そのため、
external scheduler
↓
POST /v1/runs
↓
1回分の巡回
という構成にしています。
定期実行の責務と監視処理そのものを分離することで、アプリが再起動しても次回の外部呼び出しから処理を再開できます。
同じ監視 run が二重に動くと、check・incident・notification が重複する可能性があります。
PostgreSQL の session-level advisory lock を利用し、
lock acquired
↓
run start
↓
background work
↓
run finish
↓
lock release
の間、1つの run だけを許可します。
競合は障害ではなく「すでに実行中」という正常系として扱います。
2つは性質が異なります。
| 対象 | 排他への影響 | 回収 |
|---|---|---|
DB に残った running run |
なし | 自動 |
| 生存セッションが保持する advisory lock | あり | 手動 |
プロセス終了時には advisory lock は通常 PostgreSQL が解放しますが、DB 上の runs.status は自動では更新されません。
そのため stale run は sweeper で自動回収します。
一方、advisory lock holder の強制切断は正常実行中のセッションを殺す危険があるため、
ops-hub unlock
ops-hub unlock --forceという明示的な操作に限定しています。
常駐 scheduler を持たないため、定期的に cleanup を実行できる場所がありません。
そこで POST /v1/runs の開始処理を、
sweep
↓
lock
↓
run
の順にしています。
sweep に失敗しても本来の監視 run は続行します。
stale run の整理は観測情報の修復であり、排他制御そのものではないためです。
通常のアプリケーション query は SQLx macro と .sqlx offline metadata で compile-time validation しています。
一方 pg_locks / pg_stat_activity は PostgreSQL の system catalog であり、server version による列定義の違いをローカル .sqlx metadata に固定したくありません。
そのため recovery 用の system catalog query だけは sqlx::query を利用しています。
SQLx の compile-time validation は DATABASE_URL の database schema を参照します。
ローカル shell に Neon など本番 DB の URL が残っている状態で品質検証を実行しないよう、
localhost
127.0.0.1
db
postgres
以外の host を scripts/assert_local_database_url.py で拒否しています。
| 領域 | 技術 |
|---|---|
| Backend | Rust 1.96 / axum 0.8 / Tokio |
| Database | PostgreSQL 17 |
| DB access | SQLx 0.9 |
| Frontend | React 19 / TypeScript / Vite 8 |
| Local runtime | Docker / Docker Compose |
| CI | GitHub Actions |
| Dependency updates | Dependabot |
| Production target | Render / Neon |
- Rust 1.96 以上
- Node.js 24
- Docker / Docker Compose
sqlx-cli0.9
repository root から起動します。
docker compose -f back_cargo/compose.yaml up --build -d既定の host port:
| 対象 | Host | Container |
|---|---|---|
| API | 8081 |
8080 |
| PostgreSQL | 5433 |
5432 |
疎通確認:
curl -f http://localhost:8081/health
curl -f http://localhost:8081/livezrun の開始:
curl -i -X POST http://localhost:8081/v1/runspackage.json は repository root にあります。
npm ci
npm run dev個別検証:
npm run lint
npm run buildローカル PostgreSQL を起動し、migration を適用します。
cd back_cargo
docker compose up -d
cargo sqlx migrate run
cd ..SQLx offline metadata を更新する場合:
make sqlx-prepare品質ゲート:
DATABASE_URL=postgres://ops_hub:ops_hub@localhost:5433/ops_hub make verifymake verify は以下を実行します。
DATABASE_URL safety guard
↓
Ruleset / CI contract check
↓
cargo fmt --check
↓
cargo clippy -D warnings
↓
cargo sqlx prepare --check
↓
cargo test
Task 08 完了時点の Rust test:
| 分類 | 件数 |
|---|---|
| unit tests | 38 |
| probe tests | 14 |
| recovery integration tests | 11 |
| advisory lock tests | 4 |
| run API tests | 5 |
| 合計 | 72 |
72 passed
0 failed
probe tests では、ローカルの HTTP サーバに対する success / http_error / degraded / timeout / connection_error / HEAD / リダイレクト非追従 / マスキングと、POST /v1/runs から checks への記録を検証しています。
recovery tests では、stale run の回収、閾値判定、複数 run の一括処理、advisory lock holder の取得、session terminate による lock 解放などを実 DB で検証しています。
Pull Request
↓
GitHub Actions
↓
PostgreSQL 17
↓
migration
↓
make verify
↓
required check: verify
↓
main-protection Ruleset
↓
merge
ci.yml は main への push と pull request で実行します。
主な処理:
- PostgreSQL 17 service を起動
npm cisqlx-cliを install- migration を適用
make verify
現在 frontend の、
npm run lint
npm run buildは make verify には含まれておらず、別途実行します。
dependabot.yml で以下を週次監視しています。
| ecosystem | directory |
|---|---|
| npm | / |
| Cargo | /back_cargo |
| GitHub Actions | / |
Dependabot が実際に update PR を生成することまで確認済みです。
TypeScript の semver-major update は、現行 toolchain との互換性のため除外しています。
security-audit.yml では cargo audit を毎週月曜と手動実行で行います。
2026-09-13 時点では workflow は設定済みですが、実行履歴の確認は今後の運用項目です。
main-protection Ruleset は enforcement: active。
| 項目 | 設定 |
|---|---|
| Default branch deletion | 禁止 |
| Non-fast-forward | 禁止 |
| Pull request | 必須 |
| Required status check | verify |
| Strict status checks | 有効 |
| Review thread resolution | 必須 |
| Extra approval for unattributed changes | 必須 |
| Bypass actors | なし |
scripts/github/main-ruleset.json を repository 内の正本とし、GitHub live 設定との一致を確認済みです。
Task 22 では実際の PR で、
verify FAIL
↓
merge BLOCKED
と、
verify PASS
↓
merge ALLOWED
の両方を確認しています。
| Task | 状態 |
|---|---|
| Task 01〜06 | 完了 |
| Task 07: stale run / advisory lock recovery | 完了 |
| Task 08: target取得・probe・check記録 | 完了 |
| Task 09: 状態遷移・incident | 次に実装 |
| Task | 状態 |
|---|---|
| Task 17〜19 | 復旧・repository整理 完了 |
| Task 20 | CI の make verify 実行を実質化 |
| Task 21 | Dependabot 導入 |
| Task 22 | main Ruleset の正本・live 設定を一致 |
現在の run は、
request
↓
sweep
↓
lock
↓
run record
↓
perform()
↓
targets → probe → checks
まで実装されています。
次に監視サービスとして必要なのは以下です。
| 優先度 | 項目 | 完了条件 |
|---|---|---|
| P1 | 状態遷移 | success / failure の変化を判定できる |
| P1 | incident | 障害発生・復旧を記録できる |
| P1 | outbox / Slack | 通知を失わず Slack へ送信できる |
| P1 | target 登録 API | psql を使わずに監視対象を登録できる |
| P2 | 日次集計 | uptime / failure 等を集計できる |
| P2 | status page | 監視状態を UI から確認できる |
| P2 | frontend CI | lint / build を required quality gate に含める |
| P2 | production unlock | Render 上で安全に unlock を実行できる運用経路を確立 |
タスクごとの設計判断・失敗・検証結果は docs/ に記録しています。2026-10-24 以降のタスクは GitHub Issue で管理し、作業メモもその Issue に書いています。
このプロジェクトでは、完成したコードだけでなく、
- CI が green でも実際の品質検証をしていなかった
- SQLx compile-time validation の前に CI DB migration が必要だった
- 古い branch との merge で
back_cargo/が消失した - Ruleset の live 設定の方が repository 内の正本より安全だった
- stale run と stale advisory lock は別の回収方法が必要だった
pg_locksは test DB 単位ではなく PostgreSQL cluster 全体を参照する
といった、実装中に判明した問題も task document に残しています。
過去の task 文書はその時点のスナップショットを含むため、現在の動作を判断する場合は、
実コード
↓
test
↓
CI
を優先してください。