admin_rb
32 lines
3.7 KiB
Markdown
32 lines
3.7 KiB
Markdown
# WebGUI HTTP APIv2 - Core3.3 / schema5 candidate
|
|
|
|
Core service/wire/event remains1.0 and is reached through fixed aimctl transport. WebGUI HTTPv2 is a separate authenticated API. All existing review, one-run, credential, grant, plan/retry/delete routes remain; unsafe requests require existing CSRF and same-origin policy. No arbitrary core-command/actor/path endpoint.
|
|
|
|
## Existing workflows
|
|
|
|
POST /api/v2/preflight takes customer,playbook,explicit targets,overrides,check,key_mode and returns private expiring review_id and normalized plan. result_contract is now preserved. POST /api/v2/runs takes review_id,confirm plus Idempotency-Key; no saved plan is required. Optional one-shot UTC scheduled_at remains unchanged. POST /api/v2/plans has an optional unique account-local name, never an upsert. POST /api/v2/runs/{id}/retry is a new requester-owned reviewed attempt; running jobs cannot be deleted.
|
|
|
|
Credential POST /api/v2/runs/{id}/credentials and existing jobs alias remain8KiB, requester-only reserved-window input; private FD downstream; no credential response echo. GET credential-status does not extend reservations or prove correctness. Modal and full-page fallback remain unchanged.
|
|
|
|
## New retained-evidence reads
|
|
|
|
All routes use owner-or-admin job authorization. Missing/inaccessible jobs are404, not aggregate leaks.
|
|
|
|
| GET | Meaning |
|
|
|---|---|
|
|
| /api/v2/runs/{id}/progress | Tail snapshot/checkpoint, default200 records. after/before mutually exclusive, nonnegative committed local cursors; limit1..500. |
|
|
| /api/v2/runs/{id}/progress/stream?after=N | Replay then follow committed public metadata through SSE; Last-Event-ID overrides initial after on reconnect. |
|
|
| /api/v2/runs/{id}/console | Compatibility alias to the durable progress SSE, not raw console output. |
|
|
| /jobs/{id}/progress?before=N | Authorized server-rendered pagination/no-JavaScript timeline. |
|
|
| /api/v2/runs/{id}/reports | Report header/availability/retention index; no report bodies. |
|
|
| /api/v2/runs/{id}/report?host=HOST | One retained slot, schema/availability/mode/time/retention and bounded data. Empty host selects global scope where applicable. |
|
|
| /jobs/{id}/reports?host=HOST&field=FIELD&page=N | Schema-aware HTML summary,50-row collection paging and lazy JSON. |
|
|
|
|
A journal response includes job/status/terminal, available,cursor,next_cursor,first_cursor,events,checkpoint,has_more,has_older,omitted_events,dropped_events,capture_state and capture_interrupted. Each event record has local cursor,receipt time,allowlisted Core event and derived display text. Text is rendered on reads, never stored as a console transcript.
|
|
|
|
SSE events: snapshot (committed metadata), line (record and legacy text), gap (retention omission), end (terminal or revoked access). Only durable records carry data cursors. Transport keepalive comments are not task activity. Final event and final response are one run, not duplicate reports. Final authoritative target facts remain in /api/v2/runs/{id}; operation_result there is a compact availability/retention projection, with bodies only in the separate report route.
|
|
|
|
Report states: available,missing,withheld,invalid,not_started,indeterminate. Local retention: retained,metadata_only,unavailable,not_retained_limit. Do not conflate these fields with execution success. Checkmk configuration defaults to metadata_only even with Core status available. Reports are finalization-only.
|
|
|
|
No browser read calls prepare/execute, opens the credential channel, probes hosts or imports terminal Core history. Deletion cascades journal/reports while audit keeps its compact event. Old jobs without evidence show unavailable; cursor replay cannot recover nonretained/uncaptured data. All evidence uses Cache-Control:no-store and is escaped for display.
|