Persisted state
The small JSON value Blaise keeps for a plug, per session, and the rules around it.
Most plugs need no stored state: they work out what they need again from their inputs and the session id. Persisted state is for what cannot be derived, typically an id that a provider assigned.
The record
One record per session and plug id:
| Field | Description |
|---|---|
id | The id of the entry in setup. A plug that declares persisted must have one. |
plug | The plug's name. A record is never handed to a plug with a different name. |
value | Any JSON value, validated against the plug's persisted schema when it is loaded. |
A plug reads ctx.persisted.value and writes with ctx.persisted.set(value) and
ctx.persisted.clear(). A write resolves when Blaise has stored it.
Limits and protection
- A value is at most 16 KB as JSON. Keep ids, paths and snapshot references, not data.
- Values are encrypted at rest. They are readable only with the token of one of that session's runs, and are never shown in the dashboard.
- A record that cannot be decrypted (the server's key changed, or the record was altered) fails the run. It is never skipped: a plug that found no state would create its resources again while the first ones still exist.
- A write is accepted only while the run that makes it is still active. One that arrives after the run finished is rejected, so it cannot bring back a record that teardown deleted.
- Do not store credentials. Work them out again on every run.
- A record is deleted when the session's teardown succeeds. Nothing else deletes it.
Loading
The runner fetches all records of the session in one call before it loads the plugs. For each plug
with a persisted schema:
- A record whose
plugdiffers from the plug now at thatidis not handed over, and is reported as one that nothing owns (replaced). - A stored value that validates is the plug's
persisted.value. - One that does not is given to
onMigrate(ctx, stored). If that returns a value, it is validated and written back. If it returnsundefined, the value is dropped and the plug starts empty. - Throwing, returning an invalid value, or having no
onMigratefails the run.
onLoad runs after this, so it sees the migrated state.
Records that nothing owns
A record whose id is no longer in blaise.yml, or whose plug was replaced, cannot be torn down by
the plug that wrote it. The runner reports it at the start of every run, and the session view lists
it with the plug name and the reason. It is never deleted automatically, so that what it points at
can be cleaned up by hand. See
handle an orphaned environment.
Procedures
The runner stores state through sessions.plugState.list, set, clear and reportOrphans of the
SDK. They are available only to a run's own token, for its own session.