brama maintain¶
Ask the serving gateway for one more maintenance pass through POST /v1/admin/maintain. The serving process runs its own passes and needs no schedule: one when it starts, then one at the next moment its usage ledger states something becomes due (a grant's stated expiry, a plan window's stated reset, a rate block's stated end), and one right after it refuses a request subscription_reauthorization_required. Each pass renews due grants and signs members in through Weles by itself; the log records maintenance_pass_finished with next_due_ms, and maintenance_woken_by_refusal. The pass runs inside the serving process because that process holds the usage ledger, the journal and the credentials; this command is for an operator who wants a pass now.
Invocation¶
brama maintain (--gateway <URL> | --gateway-consumer <CONSUMER>) [--bearer-role <ROLE>] [--json] [< bearer]| Input | Required/default | Meaning |
|---|---|---|
--gateway <URL> | one of the two | The gateway's origin. |
--gateway-consumer <CONSUMER> | one of the two | Resolve the gateway through stado service directory connect brama --consumer <CONSUMER>. |
--bearer-role <ROLE> | optional | Read the console bearer at the moment of the pass from the token field of the vault item that plays this role, through stado credentials get --role <ROLE> --field token. No item is named, so replacing the item changes nothing here. Without it the bearer is read from standard input. |
--json | optional; off | Print the gateway's report as JSON instead of lines. |
The command can still be run on a schedule, for example stado schedule create --pinned-host <gateway host> --cron '* * * * *' 'brama maintain --gateway-consumer <consumer> --bearer-role brama-desktop-model-router', but nothing depends on one.
Output and state¶
The pass reads every plan usage report that is due (no reading, a reset window, a reading naming no reset, or a failed last read), records for every renewable provider the account each member's own grant states (the same work as brama subscription attribute, so a member imported without its account can be signed in through Weles), renews every grant whose stated expiry has passed and schedules a Weles sign-in for each member that needs one, decides whether a spent pool needs a new account (see brama subscription acquire; when it does, the purchase starts and the pass does not wait for it), and takes a fresh readiness reading for /readyz. Lines read:
plan usage: <N> subscription(s), <N> read
failed <subscription> (<provider>): <error envelope>
account attribution failed for <provider>: <error>
credentials: <N> subscription(s), <N> refreshed, <N> refused, <N> sign-in check(s) scheduled
acquisition: "<provider>" "refused"|"started" ("<code>"): "<sentence>"
readiness: ready=<bool> <reason>An acquisition refusal (for example pool_not_spent naming the account with plan left, or account_cap_reached naming the cap and the accounts) is a decision and does not make the pass fail; a purchase the pass started reports its verdict in the gateway's log (subscription_acquisition_finished) and the journal.
When renewal could not list the credentials, the credentials line is credentials: <inventory error>. It exits 0 only when the gateway's report says ok: true.
Refusals¶
| Sentence | Exit | Meaning |
|---|---|---|
the parser's refusal for neither or both of --gateway and --gateway-consumer | 2 | The pass has to run in one serving gateway; nothing was contacted. |
reading the console bearer from stdin: <error> | 1 | Standard input could not be read. |
a gateway needs the console's bearer: --bearer-role, or the token on stdin | 1 | No bearer was given either way. |
--bearer-role names the role the console's bearer item plays, and `<value>` is not one | 1 | The value is empty or is an item#field coordinate. |
the item playing role <role> holds no value in its token field | 1 | The vault answered with an empty field. |
`<stado> <arguments>` refused: <stado's own sentence>, or `<stado>` could not be run: <error> | 1 | The vault read or directory lookup failed in Stado; BRAMA_STADO_BIN names another Stado binary. |
Stado's service directory answered `<answer>` for consumer `<consumer>`, which names no gateway origin | 1 | The directory has no Brama origin for that consumer. |
the gateway <origin> did not answer: <error> | 1 | Transport failure; nothing ran. |
the gateway refused the maintenance pass: HTTP <status>: <reason> | 1 | The gateway refused the request, for example a wrong bearer. |