Skip to main content

pi-orch HTTP Route Restoration — RCA & Runbook (MC #100591)

pi-orch HTTP Route Restoration — RCA & Runbook (MC #100591, parent #100588)

Servis: orchestrator-http-server.js (port 3052, registrovan u ~/system/config/known-api-endpoints.json), pokreće ga LaunchAgent com.john.pi-orchestrator preko kernel/pi-orchestrator.js start.

Simptom (2026-05-14, MC #100588)

Root-level /health i /stats su vraćali 404 na portu 3052 dok je proces bio živ. Verifikatori i autonomni Pi agenti koji provjeravaju liveness na root-level putanjama (/health, /stats) su bili slijepi za servis koji je zapravo radio.

Root cause

tools/orchestrator-http-server.js je od početka imao samo namespaced health endpoint:

GET /api/v1/health   — Health check (jedini deklarisani u header-komentaru, linija 20)

Nije postojao root-level /health ni /stats. Vanjski verifikatori/agenti (mišljeni za generičku "je li servis živ" provjeru) hardkodirano gađaju root /health i /stats, ne namespaced /api/v1/... putanju — otud 404 uprkos procesu koji je bio up.

Fix (live-verifikovano 2026-07-28)

U tools/orchestrator-http-server.js (linije 96-136) sada postoje tri route-a, sva tri backed istim healthPayload() funkcijom:

Linija Route Napomena
96 GET /api/v1/health namespaced, izvorni endpoint, ostaje za API klijente
101 GET /health root-level alias — fix
107 GET /stats root-level, DAG/task brojevi iz runner.dagList() — fix

healthPayload() vraća {status, service, version, backend, timestamp, uptime} — identičan payload na oba health route-a, tako da namespaced i root klijenti vide isti kontrakt.

Git napomena: git blame pokazuje da su root-level /health//stats uvedeni commit-om c8c0dcb2d4f ("[BACKUP] catchup 2026-05-22 — restoring 8-day hourly-backup gap, MC #101729") — to je auto-backup catchup commit, ne namjenski feature commit. Zaključak: fix je vjerovatno napravljen ranije u radnom stablu (isti dan/nedjelju kao #100588, 2026-05-14) ali nije bio zakomitovan sve do backup-catchup-a osam dana kasnije. Nema namjenskog "fix #100588" commita u istoriji — restauracija je zabilježena tek retroaktivno kroz backup mehanizam.

Verifikacija (2026-07-28, live, port 3052 na 127.0.0.1)

$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3052/health          # 200
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3052/stats          # 200
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3052/api/v1/health  # 200
$ ps aux | grep orchestrator-http-server   # proces živ (KeepAlive daemon)

Sva tri endpointa vraćaju 200 uživo. Fix je i danas na mjestu — nije regresovao. Endpoint kontrakt dodan u ~/system/config/known-api-endpoints.json (ključ za port 3052) da spriječi buduće halucinacije putanja za ovaj servis.

Operativna lekcija

Kad se servis dizajnira sa namespaced API prefiksom (/api/v1/...), uvijek dodaj i root-level alias za /health i /stats ako bilo koji eksterni verifikator, monitoring probe ili autonomni agent može hardkodirano gađati root putanju bez znanja o prefiksu. Ne pretpostavljaj da će svi klijenti čitati OpenAPI/header-komentar prije nego što probaju najočigledniju putanju.

Reference

  • Kod: ~/system/tools/orchestrator-http-server.js (linije 96-107)
  • Endpoint registry: ~/system/config/known-api-endpoints.json (ključ za port 3052)
  • Parent: MC #100588 (pi-orch HTTP route restoration, status: paused — root cause je nezavisno potvrđen i zatvoren ovim RCA-om)
  • Ovaj task: MC #100591 (Skillforge RCA + runbook)
  • Srodan runbook: pi-orchestrator-fixes-105648.md (kasniji, nepovezan set discipline fixova u pi-orchestrator.js klasifikatoru/lease sistemu — različit fajl, ne miješati)

No comments to display

Back to top