Improved job and log handling/endpoints in CUBE

[rudolphpienaar]

Proposal: Job Handling Enhancements for CUBE

Context

ChRIS “jobs” are PluginInstances. Today there is no explicit job control surface: clients list/filter plugin instances, poll status, and can cancel via PUT status=cancelled. Logs are embedded/truncated in summary and the full pfcon response is stored zipped in raw; there is no clean log/tail API. The UX would benefit from OS-like affordances (ps/top, tail, /proc).

Proposal (three pillars)

1. Active filter on existing plugin instance endpoint

   • Add active=true|false to PluginInstanceFilter and honor it on /api/v1/plugins/instances/search/ (and optionally /api/v1/plugins/instances/).
   • “Active” = non-terminal statuses (e.g., created, waiting, scheduled, started, registeringFiles), terminal = finishedSuccessfully, finishedWithError, cancelled.
   • Benefit: cheap, server-side “ps-like” view without client-side filtering.

2. Per-instance logs endpoint (chunked, tail-friendly)

   • New endpoint: GET /api/v1/plugins/instances/<id>/logs/
   • Return chunked/paged log data (bounded payloads), e.g., by chunk index with offset/limit or tail helper. Optionally add SSE/WebSocket for live tailing.
   • Keep summary as a lightweight status snapshot; keep raw for archival pfcon payload; stop relying on summary truncation for logs.
   • Benefit: clients can tail/view stdout-like logs cleanly without parsing summary/raw.

3. /proc-style virtual view (active-only)

   • Expose a read-only virtual namespace (e.g., /proc/jobs) that lists active plugin instances with subentries such as status, logs (chunked), output (link), parent/descendants, compute_resource.
   • Scope to active jobs by default; history can live elsewhere (paged API).
   • Benefit: familiar, discoverable, shell-friendly navigation (ps/top analogue).

Optional complementary ideas

• Eventing: SSE/WebSocket for job state changes and log tail to reduce polling and power “tail -f”.
• Queue/compute visibility: Per compute resource/queue counts of queued/running jobs, dispatch/start timestamps, perhaps basic runtime metrics.

Rationale

• Active filter: small, backward-compatible change; enables fast “show me what’s running” views.
• Logs endpoint: avoids truncation; provides proper stdout/stderr access; chunking keeps payloads reasonable.
• /proc view: improves discoverability and UX for shell users; can be layered over existing APIs with lazy, read-only VFS.

Scope/compatibility

• No breaking changes to PluginInstance schema.
• New filter on existing endpoint; new logs endpoint per instance; optional new virtual view.
• Existing clients continue to work; richer clients can opt into the new surfaces.

Open questions for discussion

• Exact “active” set: propose active = non-terminal; terminal = {finishedSuccessfully, finishedWithError, cancelled}.
• Logs chunking shape: chunk size, indexing (offset/limit), tail helper; SSE/WebSocket necessity in first iteration?
• /proc mount location and contents: active-only? Which subentries by default?

[jbernal0019]

@rudolphpienaar Point 2. Per-instance logs endpoint (chunked, tail-friendly) is related to this previous discussion: ChRIS plugin apps' logs streaming and replay architecture.

I guess point 3. /proc-style virtual view (active-only) is just the result of applying the active filter in point 1 to the plugin instances API.