Skip to content

operator-clients Specification

Purpose

What every operator client (the TUI, the web app) does alike: contexts, backend access through the gateway, pushed data, error reporting, worker operations, tables and navigation. Each client binds it in its own spec (terminal-ui, web-app); shared conformance vectors keep them alike.

Requirements

Requirement: Clients and Bindings

An operator client (the TUI, terminal-ui; the web app, web-app) SHALL implement the requirements of this spec and of value-presentation, so both clients show the same data the same way and decide alike. A client's binding spec SHALL say only how it does so: its controls, layout, storage locations and transport. Where a binding and this spec disagree, this spec SHALL win.

Scenario: One behaviour, two clients

  • WHEN the same workers are listed in the TUI and in the web app against the same context with the same filter expression
  • THEN both SHALL show the same workers in the same sort order, with the same statuses

Requirement: Contexts

A client SHALL work against one of several API endpoints, its contexts. Each context SHALL have a name and an endpoint, and MAY have a description, an API key, event topics and protected. The catalog of contexts SHALL be configuration; the active context SHALL be state, kept apart from the catalog, so choosing one never rewrites the catalog. An entry that is incomplete, or a catalog that does not parse, SHALL NOT stop the client: the entry SHALL be left out and the problem shown.

The client SHALL show the active context's name and its health on every view, and each context's health in the list of contexts. An API key SHALL travel only between the client's trusted side and the API; it SHALL NOT be shown.

Scenario: Switch context

  • WHEN the user picks another context
  • THEN the client SHALL first check that the new context answers, then stop every subscription and stream of the old one, read and subscribe against the new one, and drop what it showed for the old one
  • AND a context that does not answer SHALL be reported, and the old one SHALL stay active

Scenario: Health

  • WHEN contexts are configured
  • THEN each context's reachability SHALL come from a health stream or the transport's own liveness, not from a periodic probe
  • AND each time a context comes up, one keyed call SHALL check its API key

Scenario: A protected context

  • WHEN the active context is protected
  • THEN the client SHALL mark it in red on every view and say so
  • AND every write it sends to it (worker create/delete/start/stop/tags/load code, worker commands other than status, state saves and deletes, trigger schedule/delete) SHALL wait for the user's yes in a dialog naming the context; a no SHALL send nothing
  • AND after a yes, the writes of the next 5 s SHALL go through without asking, so one action of several calls asks once

Scenario: No active context

  • WHEN no context resolves
  • THEN the client SHALL show the contexts, every one not connected, and SHALL watch no endpoint; every view that needs a context SHALL say so instead of opening

Requirement: Backend Access through the Gateway

A client SHALL reach the backend services (WorkManager, the registries, triggers, worker commands) through the API gateway, without vendored backend stubs. Messages SHALL be resolved through the gateway's reflection, in one of two ways: - the client loads the service's descriptors from the gateway's reflection and calls Gateway.Invoke with protobuf bytes, keeping one descriptor pool per backend service (backend protos all declare package virtufin and MAY declare identically-named messages); - the client calls Gateway.InvokeJson with the proto3 JSON mapping, and the gateway resolves the descriptors and converts.

The API's own services (Gateway, Pubsub, State, Config) MAY use generated stubs.

Scenario: List workers

  • WHEN a client reads the worker list
  • THEN it SHALL call WorkManager.ListWorkers through the gateway by one of the two ways, and an RPC added to a backend SHALL be callable without rebuilding the client

Requirement: Pushed Data, Not Polling

A client SHALL keep its lists and statuses current from events (Pubsub.Subscribe, gRPC server streaming), not by calling the backend on a timer. Each list SHALL be read once when its subscription is live, then again only when an event says it changed, with a burst of changes read once. While a subscription is down the client SHALL fall back to reading the lists it shows every 2 seconds, so no view freezes. Topic and state-key names SHALL come from the naming library and the owning devkits' fragments, never from literals.

Scenario: Workers

  • WHEN the worker lifecycle subscription is live
  • THEN ListWorkers SHALL be read once, and again only after a listing change (registered, deleted, updated, loaded, load-failed, online, stopped, failed)

Scenario: Subscription down

  • WHEN the event subscription drops
  • THEN the shown lists SHALL be read every 2 seconds until it is live again, then once more, and the timer SHALL stop

Requirement: Error Reporting

A client SHALL report a failed action one way: one error notice naming the action and a readable reason (a gRPC status in words, a refused call as STATUS: message), with the details in its log. When reading data a view shows fails, the view SHALL keep what it shows and say that it is stale, since when and why, until a read succeeds; it SHALL NOT act on the failed read as if there were no data.

Scenario: Failed action

  • WHEN an action (create, delete, tag, publish, ...) fails
  • THEN the client SHALL show <Action> failed: <reason> once

Scenario: Failed read

  • WHEN reading a view's data fails
  • THEN the view SHALL keep its rows and show stale since <time>: <reason> until the next good read
  • AND a failed read SHALL NOT prune saved state

Requirement: Worker Operations

A client SHALL list the workers of the active context with their name, id, status, type, code source, topics and tags, and SHALL offer their detail, creation, tagging and lifecycle, backed by the WorkManager RPCs (ListWorkers, GetTags, GetWorkerHistory, CreateWorker, SetTag, StartWorker, StopWorker, DeleteWorker, LoadCode). The list SHALL take the value-presentation Worker Filter.

Scenario: Worker detail

  • WHEN the user opens a worker's detail
  • THEN the client SHALL show its tags (GetTags), its history (GetWorkerHistory) and its creation-time config from the latest ListWorkers (config is immutable after creation)
  • AND the worker's lifecycle events received since the client connected (newest first, a bounded number per worker, repeats counted) and its last load-failed or failed with error_type and error_message, since the WorkManager keeps no history of them

Scenario: Delete with confirmation

  • WHEN the user deletes a worker
  • THEN the client SHALL ask first; on yes it SHALL call DeleteWorker, on no nothing SHALL be sent

Scenario: Set a tag with undo

  • WHEN the user sets a tag on a worker
  • THEN the client SHALL call SetTag and offer an undo for 10 s; undoing SHALL restore the prior value via SetTag, or, for a tag that was new, the prior tags via SetTags (which replaces the whole map)

Scenario: Create a worker

  • WHEN the user creates a worker with MIME type, topics, code source and tags
  • THEN the client SHALL call CreateWorker, and the worker SHALL appear in the list when its registered lifecycle event arrives

Scenario: Many workers at once

  • WHEN the user starts, stops or deletes with workers marked, or with none marked
  • THEN the action SHALL apply to the marked workers, or with none marked to every worker the filter shows; the client SHALL list them before acting, ask once more before deleting, run a bounded number at a time, carry on past a worker that fails, and report each worker's result, the failed ones first
  • AND on a protected context that one choice SHALL be the confirmation for every write of the run

Scenario: Upgrade in place

  • WHEN a worker runs a version of a worker-registry package and the user upgrades it
  • THEN the client SHALL find the registry entry and version from the worker's code URL (the entry's templated source_url), offer the entry's versions newest first, and call LoadCode with the picked one; the worker SHALL keep its id, topics, config, secrets and tags
  • AND a worker whose code is no registry package SHALL say there is nothing to load

Requirement: Tables

A client's lists SHALL be tables that behave alike: - Bounded cells: a cell SHALL be bounded in width and height, and its full value SHALL be available on demand. - Resizable columns: the user SHALL be able to set any column's width; a width the user set SHALL replace the automatic one and SHALL be remembered per table and column header. - Sorting: by any column, again reversed; numbers as numbers, text without case, empty cells last; the selected row SHALL stay selected. - Filtering: by the value-presentation Filter Expressions (a word in any cell, column:value in that column's cell, the column's header lower-cased with other characters as _), the expression and the shown and total counts shown; a bad expression SHALL be marked, say why and filter nothing. - Selection and marks: one selected row, and any number of marked rows for bulk actions. - Live rows: rows updated by events SHALL keep the selection, the marks and the scroll position, and SHALL be re-sorted and re-filtered as they change.

Scenario: Sort keeps the selection

  • WHEN the user sorts a table by a column while a row is selected
  • THEN the rows SHALL be in the column's order and the same row SHALL stay selected

Scenario: A row changes under the filter

  • WHEN a row no longer passes the filter after an update
  • THEN it SHALL leave the table, and a row that now passes SHALL join it at its sorted place

Requirement: Navigation

A client SHALL offer the same views, grouped by the navigation structure in use (navigation-specs), whose built-in default is: Home; Trading (World, Instruments, Order Book, Indicators, Portfolio, P&L, Risk, Strategy, Scenario); Infra (Workers, Connections, Triggers, States, EventStores, Alerts, Changes, Events, Services); Config (Pages, Navigation). How a client draws the structure SHALL be its representation (navigation-specs, Representation Profiles: tabs and keys in the terminal, tabs, a sidebar and routes in the browser). A view SHALL keep its filter, selection and scroll position while another view is shown, and a context switch SHALL drop the views of the previous context.

Scenario: Back to a view

  • WHEN the user leaves the Workers view with a filter set and comes back
  • THEN the filter, the selection and the scroll position SHALL be as they were