Skip to content

Contexts and the write gate

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 contexts file and its fields: The contexts file. Switching: Switch context.

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.

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.

  1. Admins only. A non-admin's write is refused at once (only admins may write); the app server refuses it too.
  2. Protected context: asks first. On a context with protected = true a dialog asks Write to the protected context <name>?, naming the action. Yes, send it sends it; No (or Escape) sends nothing and the action is recorded as declined in Changes.
  3. 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.
  4. Recorded. Every write is recorded in your change log: done, failed with the reason, or declined (Find what you changed).

Reads never ask. The protected flag also colours the context button red, with protected: writes ask first, on every view.