Settings: change a setting through the daemon, live where it can

Aperta
#1,154 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
42/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
api, backend, cli

Direzione di ricerca

Start with the ConfigSettings and config validation work in src/core/config.ts, then trace the daemon entry point in src/daemon/settings.ts and the config.set contract in src/contract/operations.ts and src/contract/schemas.ts. Check the listed config readers and writers, including the reaper, warm pool, dispatchers, CLI, and HTTP route; run the relevant tests, including src/bus/index.test.ts. Done means daemon-mediated saves validate and write safely, live keys update their readers, restart keys remain pending, and config.changed is emitted without exposing secrets.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

task:draft

Part of #1151.

Scope

An admin changes any setting through the running daemon, with PUT /v1/config/{key} or the config.set operation, and simlock config set goes through the daemon when one runs. The daemon becomes the one writer of its config.json while it runs. Three keys apply at once; every other key is saved and waits for a restart. Each save emits config.changed.

In short

After this PR PUT /v1/config/idle.shutdownAfterMs with { "value": 300000 } writes config.json and the cleanup reaper uses 5 minutes on its next run, with no restart. A restart key, e.g. http.port, is written and its row reads pending: true until the next start. simlock config set with a daemon running asks the daemon to write; with none running it writes the file itself, as today.

$ simlock config set idle.shutdownAfterMs 300000      # daemon running
Updated idle.shutdownAfterMs in /Users/me/.simlock/config.json; applied now.
$ simlock config set http.port 4800                   # daemon running, or not
Updated http.port in /Users/me/.simlock/config.json; takes effect on daemon restart.
$ simlock config set lease.defaultTtlMs 999999999999  # over lease.maxTtlMs
{"error":{"code":"USAGE","message":"Invalid config after setting lease.defaultTtlMs: Invalid config value for \"lease.defaultTtlMs\": expected at most lease.maxTtlMs"}}

The refusal reads the same with and without a daemon, exit 2. Through HTTP it is 400 BAD_REQUEST with the same message.

Input Today After
config set idle.shutdownAfterMs 300000, daemon running file written by the CLI, applies on restart written by the daemon, applied now
config set http.port 4800, daemon running file written by the CLI written by the daemon; row pending
config set http.port 4800, no daemon file written by the CLI the same
config set http.port 4800, daemon running, no admin token file written by the CLI refused FORBIDDEN, file unchanged
PUT /v1/config/foo..bar no route 400 Invalid config key: foo..bar, from the daemon
flowchart LR
  CLI[simlock config set] -->|daemon running: config.set *| D[daemon]
  CLI -.->|none running| F[config.json]
  H["PUT /v1/config/key *"] --> D
  D -->|"read, change, validate, write *"| F
  D -->|"live key: swap the running value *"| R[reaper, warm pool]
  D -->|"config.changed *"| E[event bus]

If this goes wrong, a save is lost, a live key still waits for a restart, the CLI writes behind a running daemon, or a secret lands in the log or an event.

Technical spec

Facts

Commit bcedd2fa.

# Fact Source
F1 config set reads the file, drops eventLog.rotateBytes (and says so on stderr), sets the key from JSON.parse of the value (else the raw string), validates, writes, then prints the restart line src/cli/commands/config.ts:41-63, :103-109
F2 A key with an empty segment is a usage error Invalid config key: <key> src/cli/commands/config.ts:90-93
F3 Validation: loadConfig over a memory file with the whole file as overrides, the role and the modules; any Unknown config key: warning refuses src/cli/environment.ts:419-434
F4 The file is written atomically, mode 0600, after mkdirp of the data directory 0700 src/cli/environment.ts:410-417
F5 The CLI can tell whether a daemon's endpoint is present without starting one src/cli/environment.ts:381-392
F6 connectDaemonClient with launch: false connects to a running daemon only; with no admin credential it falls back to an agent session and writes a notice src/cli/connect.ts:39-78
F7 config set works with --gateway and no gateway present, without connecting src/cli/index.ts:178
F8 Loader messages name the path and the expectation, never the value: Invalid config value for "<path>": expected <...> src/core/validation.ts:17-19
F9 gateway.url and gateway.token must be set together, and a joined worker needs http.enabled false src/core/config.ts:803-835
F10 The reaper reads idle.shutdownAfterMs, idle.deleteAfterMs from its view's config on every rule run, and diskPressure.freeBytesThreshold on every pressure check src/core/cleanup/idle-shutdown.ts:16, src/core/cleanup/idle-destroy.ts:16-17, src/core/reaper.ts:219-236
F11 The warm pool gets idle as a copy at build and reads shutdownAfterMs from it each pass src/core/create-core.ts:265, src/core/warm-pool/converger.ts:617
F12 The loaded config is deep-frozen src/core/config.ts:626
F13 runDispatch logs a failure's message once the input is valid, and from the input only leaseId and requesterId src/daemon/dispatch.ts:253-271
F14 An admin event's caller is requesterId, the admin session's principal docs/internal/EVENTS.md:137, src/bus/index.ts:227-234
F15 BAD_REQUEST is CLI exit 2 and HTTP 400 src/contract/errors.ts:236
F16 Today's CLI refusal is USAGE, exit 2, file untouched src/cli/index.test.ts:3321-3343
F17 config.get answers the dispatcher's options.config; worker.list builds its config from it src/daemon/dispatcher.ts:835, :854
F18 config set takes any non-empty dotted path, a parent or a field inside a json row included; a gateway only warns on a worker-only key src/cli/commands/config.ts:89-100, src/core/config.ts:714
F19 The loader warns Unknown config key on eventLog.rotateBytes; the CLI turns that warning into a refusal, which is why it drops the key first src/core/config.ts:1048, src/cli/environment.ts:428-433
F20 daemon stop's helper connects with launch: false and treats any error that is not a daemon's refusal as no daemon running; config set does not copy that rule (F21) src/cli/daemon-service.ts:16-22
F21 isEndpointAbsent is true only for connection-refused and endpoint-not-found; a connect times out after 10 s src/ports/ipc.ts:22-27, :50-52, src/cli/environment.ts:222-226
Modules touched

Searches: writeConfigFile, validateConfig, readConfigFile, configPath, config.idle, options.config.idle, freeBytesThreshold, options.config in src/core/reaper.ts, EventMap, "config set" in website/.

  • src/contract/operations.ts, src/contract/schemas.ts, src/contract/protocol.ts: config.set.
  • src/core/config.ts: checkConfigFile(file, { role, modules, systemStats }), the one validator config set and config.set call (moved from F3); setConfigKey(file, key, value) (from F1, F2).
  • src/core/reaper.ts, src/core/create-core.ts, src/core/warm-pool/converger.ts: read the live keys from a holder the daemon can change; the dispatchers' config.get reads it too.
  • src/daemon/settings.ts: set(key, value, requesterId), one at a time; src/daemon/main.ts passes it the filesystem, the path and the holder.
  • src/daemon/dispatcher.ts, src/gateway/dispatcher.ts: the config.set handler.
  • src/bus/index.ts, src/bus/index.test.ts: config.changed.
  • src/simlock-client/client.ts, src/simlock-client/types.ts, src/admin/index.ts: setConfig(key, value).
  • src/cli/commands/config.ts, src/cli/environment.ts, src/cli/types.ts: through the daemon when one answers (F5); the file itself only when the connect fails as endpoint absent (F21); a daemon's BAD_REQUEST printed as USAGE; the Removed line from removed.
  • src/http/admin-declarations.ts, src/http/app.ts: PUT /v1/config/{key}.
  • docs/internal/EVENTS.md, website/src/content/docs/docs/reference/events.mdx, website/src/content/docs/docs/reference/cli.mdx, website/src/content/docs/docs/reference/configuration.mdx, website/src/content/docs/docs/worker/configuration.mdx.
sequenceDiagram
  participant C as CLI or HTTP
  participant D as Daemon (settings)
  participant F as config.json
  C->>D: config.set { key, value }
  D->>F: read
  D->>D: set the key, checkConfigFile
  alt refused
    D-->>C: BAD_REQUEST "Invalid config after setting <key>: ..."
  else ok
    D->>F: write atomic 0600
    D->>D: live key: swap the running value
    D->>D: emit config.changed
    D-->>C: { rows, removed? }
  end
Surface and extension points

ConfigSettings (from #1153) gains set(key, value, requesterId): Promise<ConfigSetOutput>. It takes every key config set takes (feature Shared values, "Keys config.set takes"), drops the retired key first ("Retired key"), swaps the live rows it touched in every reader of the running config: the reaper's view, the warm pool's idle copy (F11) and the dispatchers' config.get answer (F17). The live keys are the list #1153 adds; nothing registers a key at run time.

Contract and event changes

This PR bumps the protocol by one.

  • config.set: admin, write; input { key, value }. key: 1 to 200 characters in the contract, any characters (the route adds no check of its own); the handler refuses a key with an empty segment BAD_REQUEST Invalid config key: <key>, the CLI's words (F2); an unknown key is refused by the validation (F3). value: any JSON, required: a missing value is BAD_REQUEST, so no call removes a key. Output { rows, removed? }: the touched rows (feature Shared values, "Keys config.set takes") as config.list gives them after the write, at most 500; removed lists retired keys the write dropped (eventLog.rotateBytes), at most 10.
  • PUT /v1/config/{key}: JSON body { value }, strict; 200 with the output { rows, removed? }; 400 BAD_REQUEST on a refusal or a bad key.
  • Event config.changed { keys: string[] (the touched rows' keys, or the given key when none; 1 to 500), applied: "live" | "restart" (live when there are touched rows and all are live), requesterId: string }, module daemon. Documented in docs/internal/EVENTS.md (System) and website/src/content/docs/docs/reference/events.mdx.
Other code on the same state

Searches: writers of config.json (writeConfigFile: 1 hit, src/cli/commands/config.ts:54); readers of config.json (readConfigFile, configPath: 3 hits); readers of idle.* and freeBytesThreshold (5 hits, F10, F11); readers of the running config (options.config).

  • The CLI with no daemon running: writes the file itself (F4). A daemon starting during that write reads the old or the new file, both whole.
  • The CLI with a daemon running: sends config.set; never writes. The daemon wins.
  • Two config.set at once (two consoles, or the console and the CLI): run one at a time; each reads the file the last one wrote, so both keys are kept. Same key: the later call wins, and each emits its own event.
  • A hand edit: read by the next config.set, which keeps it. One made between a call's read and its write is lost (ADR 0057, Consequences).
  • config.list (#1153): reads the file the daemon just wrote and the running values just swapped.
  • config.get: answers the running values, the live keys' new ones included.
  • warm.set (#1143): writes state.db, never config.json; no overlap.
Failure modes
Call Outcome What happens Limit, counted from
config.set reads config.json absent starts from {}, as config set does —
config.set reads config.json invalid JSON BAD_REQUEST Invalid config after setting <key>: Invalid JSON in config file: <path>; nothing written. The CLI with no daemon now prints the same, through the same checkConfigFile (today it prints JSON.parse's error) —
checkConfigFile refused BAD_REQUEST with the loader's message; nothing written, no event —
write config.json throws (disk full, permission) the error answers (INTERNAL, logged); the old file stays; no swap, no event —
CLI config.set to the daemon no admin credential the daemon answers FORBIDDEN; the CLI prints it, exit as FORBIDDEN; file unchanged —
CLI config.set to the daemon DAEMON_STOPPING printed as is; the file unchanged; run it again once the daemon is gone —
CLI endpoint check absent the CLI writes the file itself (F4) —
CLI connect connection-refused or endpoint-not-found (no daemon, or a socket file a crashed daemon left, F21) the CLI writes the file itself —
CLI connect times out, or any other error the connect's error is printed, exit 1; nothing written: a daemon may be there 10 s, from the connect (F21)
CLI config.set to the daemon BAD_REQUEST printed as USAGE with the daemon's message, exit 2, as with no daemon (F16) —

A stop in the middle: the write is atomic, so the file is the old or the new one; a stop after the write and before the event leaves the file changed and no event.

Rules in play
  • ADR 0057 §1: "only that daemon writes its config.json, through config.set, one call at a time": the settings handle serialises; the CLI sends instead of writing.
  • ADR 0057 §3: the three live keys; "Adding a key to the live list is a code change with its own test".
  • ADR 0057 §4: "its answer and every error message carry no value": the refusal test for gateway.token.
  • ADR 0057 §8: config.changed "Never a value"; "A file written by the CLI with no daemon running emits nothing".
  • Events rules 1 and 8 (docs/internal/agent-rules/events.md): a past-tense fact, documented in both catalogues in this PR.
  • Safety rule 6 (via EVENTS.md:137): requesterId is the session's principal, never from the input.
  • src/cli/AGENTS.md rules: the CLI keeps no decision logic: validation moves to core, called by both.
Tests

Seam: startDaemon through daemon.dispatch with a memory filesystem and a fake clock (model: src/daemon/main.test.ts:526-557), the route in src/http/app.test.ts, and runCli (model: src/cli/index.test.ts:3321-3452).

  • An admin saves a setting with PUT /v1/config/{key} and the daemon writes the file and answers the rows it touched: a restart key (file changed, running unchanged, pending); a live key (running changed, config.get shows it); a parent key idle (both rows answered, both live); a field inside a json row http.proxyAuth.header (the http.proxyAuth row answered); a key a gateway ignores (no rows, saved); eventLog.rotateBytes in the file (dropped, listed in removed); other keys and a hand edit kept; file mode 0600; two saves at once both kept.
  • A saved live key is used by the cleanup reaper and the warm pool on their next run: idle.shutdownAfterMs lowered: a device idle since its lease ended shuts down at the new time with no restart (the reaper); a never-leased ready device no target keeps shuts down at the new time (the warm pool); idle.deleteAfterMs lowered; diskPressure.freeBytesThreshold raised over free disk: pressure is reported.
  • A bad value is refused with the CLI's message and the file is unchanged: a wrong type; an unknown key; lease.defaultTtlMs over lease.maxTtlMs; mode; a bad gateway.token refused with no value in the message; a key with an empty segment (Invalid config key: <key>); a body with no value; the file is not valid JSON.
  • A save emits config.changed with the key, how it applied and the caller: live key; restart key; no event on a refusal; the payload holds no value.
  • simlock config set goes through a running daemon and writes the file itself when none runs: daemon running: written by the daemon, applied now. for a live key; none running: written by the CLI, no daemon started; --gateway with no gateway present: written by the CLI; daemon running and no admin token: refused, file unchanged; a refusal with a daemon running prints USAGE and the daemon's message, exit 2; the daemon dropped eventLog.rotateBytes: the CLI prints today's Removed line; a socket left by a crashed daemon (connection refused): written by the CLI; a daemon that does not answer the connect in time: the connect's error, exit 1, file unchanged.

Done when

  • config.set is in the role and effect matrices, and the protocol range is one higher.
  • config.changed is in EVENT_NAMES, docs/internal/EVENTS.md and the website's events reference.
  • simlock config set never writes config.json while a daemon of its role answers.
  • PUT /v1/config/idle.shutdownAfterMs changes the reaper's shutdown time with no restart.
  • The CLI reference and both configuration pages say which keys apply at once and that config set goes through a running daemon.

Out of scope

  • Removing a key; more live keys; changing what config.get redacts (#1097). config.get does show a live key's new value.
  • Joining a fleet from one key at a time: gateway.url and gateway.token must change together (F9); simlock config set gateway '{"url":…,"token":…}' does it.
  • The console (#1156) and restarting (#1155).

Depends on

  • #1153
  • #1143 (the same new WarmPool({...}) call in src/core/create-core.ts and the idle read in src/core/warm-pool/converger.ts)

Written by an agent.

Lingua principale
TypeScript
Stelle
705
Fork
40
Merge medio
12h 9m
PR unite (30g)
376

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di callstackincubator/simlock

Tutte le issue di callstackincubator/simlock

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.