Contexts¶
A context is one virtufin-api endpoint the app works against (for example demo,
or a production cluster). The app shows and changes one context at a time: the
active context, named in the context menu at the top right of every view.
The catalog¶
The contexts are a catalog kept on the app server, never in the browser:
| Where the app runs | The catalog |
|---|---|
Deployed (app.virtufin.com) |
The server's contexts.toml, provisioned by the deployment (k3s-common role virtufin_app). Users cannot add contexts from the browser: an empty menu says No contexts: add them to contexts.toml on the app server. |
Development (npm run dev) |
~/.config/virtufin/api/contexts.toml, the same file the TUI and the notebooks read; VIRTUFIN_CONTEXTS_FILE names another. |
The file is read on every request, so an edit takes effect without a restart. Each
[[contexts]] table has:
| Field | Meaning |
|---|---|
name |
The context's name (required). |
api_host, api_port |
The api's address (required). The port may be the api's gRPC port: the server forwards over HTTP/2. |
tls |
true: https:// (h2 over TLS); otherwise h2c in plain text. |
api_key |
Sent to the api as x-api-key. Without one, the server's VIRTUFIN_API_KEY is used. |
description |
Shown under the name in the context menu. |
protected |
true for a context where a mistake costs: every write asks first (see below). |
An entry without name, api_host or api_port is left out; the context menu lists the
problem (e.g. context foo: no api_port; left out), as it does for an unreadable file.
The proxy keeps keys server-side¶
The browser never sees a context's endpoint or key. It gets the catalog from
GET /contexts (name, description, protected) and reaches a context through
/ctx/<name>/…, which the app server forwards to that context's api, adding the key as
x-api-key. Streams (subscriptions, health) pass through unbuffered. See
The app's API and Architecture.
Which context is active¶
The browser remembers the active context (in localStorage, key virtufin.context). On
the first visit it takes the server's default (VIRTUFIN_CONTEXT), else the first context
of the catalog. Each browser (and each user on it) chooses independently.
Switching¶
- Click the context button (top right): the menu lists every context with its health
dot, its state (
up,connecting,down,key refused), protected when it is, and its description. - Click a context. The app first checks that it answers (one keyed call, at most 10 s); only then does it switch. A context that does not answer is reported as a notice (Switch to … failed: …) and the current one stays active.
- On a switch every view drops what it showed (its filter, selection and scroll too) and reads again from the new context.
Health¶
Each context in the catalog has one health stream (grpc.health.v1.Health/Watch) for as
long as the app is open, plus one keyed call when the context comes up, which tells a
refused key apart:
| Dot / state | Meaning |
|---|---|
green, up |
The api serves and accepts the key. |
yellow, connecting |
Not answered yet. |
red, down |
The api does not serve, or the stream broke; the reason is in the dot's tooltip. The stream is opened again after 5 s. |
red, key refused |
The api answers but refuses the key (UNAUTHENTICATED / PERMISSION_DENIED). |
Home shows the active context's state too. A context that goes down after it answered, and comes back, is also an alert.
Protected contexts and the write gate¶
Every write the app sends passes one write gate (src/stores/writeGate.ts), whatever
sends it: a view's button, a dialog, a script or the
AI assistant.
- Admins only. A non-admin's write is refused at once (only admins may write); the app server refuses it too.
- Protected context: asks first. On a context with
protected = truea dialog asks Write to the protected context<name>?, naming the action. Yes, send it sends it; No (orEscape) sends nothing and the action is recorded asdeclinedin Changes. - One question per action. After a yes, further writes of the next 5 s go through without asking (one action is often several calls). A bulk action (e.g. stopping 12 workers) and a run of several calls ask once for all of them.
- Recorded. Every write is recorded in your change log:
done,failedwith the reason, ordeclined(Find what you changed).
Reads never ask. The protected flag also colours the context button red, with protected: writes ask first, on every view.