Settings: read every setting through GET /v1/config

Abierto
#1,153 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
52/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript

Línea de trabajo

Start with the operation and row contracts in src/contract/operations.ts and src/contract/schemas.ts, then trace the admin route through src/http/admin-declarations.ts and src/http/app.ts. Use the listed seams in src/daemon/main.test.ts, src/daemon/server.test.ts, and src/http/app.test.ts to guide implementation and testing. Done means GET /v1/config returns the specified rows, hides secret values, rejects agent tokens, and the configuration pages describe the endpoint.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

task:draft

Part of #1151.

Scope

An admin reads every setting of a worker or a gateway, with GET /v1/config or the config.list operation: one row per setting, with its running value, saved value, default, kind, and whether a change applies live or on restart. Secret settings say only whether they are set. Nothing changes a setting yet (#1154 does).

In short

After this PR an admin asks GET /v1/config and gets one row per setting, e.g. { "key": "idle.shutdownAfterMs", "kind": "number", "running": 600000, "saved": 600000, "default": 600000, "apply": "live", "secret": false, "pending": false }. A secret row reads { "key": "gateway.token", "kind": "string", "apply": "restart", "secret": true, "set": true, "pending": false } and carries no value. A row is pending when the file now says something other than what the daemon runs with (a hand edit after the start, e.g. http.port 4800 in the file while the daemon listens on 4701).

flowchart LR
  A[GET /v1/config] --> B["config.list (new)"]
  B --> C[running config]
  B --> D["config.json read again (new)"]
  B --> E["defaults (new)"]
  C & D & E --> F["rows, secrets hidden (new)"]

If this goes wrong, an admin sees a secret in the answer, a setting missing from the list, or a key marked live that only applies on restart.

Technical spec

Facts

Commit bcedd2fa.

# Fact Source
F1 config.get is admin, a read, with output configSchema src/contract/operations.ts:626-631
F2 The worker answers config.get with the running config, unredacted; the gateway the same src/daemon/dispatcher.ts:835, src/gateway/dispatcher.ts:375
F3 The gateway's config type is config.get's output src/gateway/dispatcher.ts:86
F4 configSchema lists every section; gateway.url, token, label and http.proxyAuth are optional; drivers is not in it; mode is src/contract/schemas.ts:930-1055
F5 redactConfig masks gateway.token and each alert destination's url and secret as [redacted] src/core/config.ts:478-500
F6 The daemon loads the config once, from <data dir>/config.json, with role, modules and systemStats src/daemon/main.ts:281, :286-298
F7 loadConfigWithDefaults reads the file through an injected filesystem and configPath; role defaults to worker src/core/config.ts:543-555
F8 Invalid JSON in the file is ConfigError("Invalid JSON in config file: <path>") src/core/config.ts:1018-1031
F9 The keys a gateway reads: GATEWAY_CONFIG_KEYS; a gateway ignores gateway.url, token, label src/core/config.ts:679-694
F10 A mode key is refused src/core/config.ts:564-566
F11 The cleanup reaper reads idle.* and diskPressure.freeBytesThreshold from its config on every run src/core/cleanup/idle-shutdown.ts:16, src/core/cleanup/idle-destroy.ts:16-17, src/core/reaper.ts:236
F12 runDispatch logs only leaseId and requesterId from an input, and nothing from an output src/daemon/dispatch.ts:253-271
F13 An admin route: declared with declareRoute and listed in ADMIN_ROUTES; served in app.ts through deps.dispatch src/http/admin-declarations.ts:73-89, :234, src/http/app.ts:655-662
F14 The protocol range is { min: 66, max: 66 } src/contract/protocol.ts:13
F15 The existing test that drives a daemon's config.get with a gateway token src/daemon/main.test.ts:526-557
F16 The client's getConfig calls config.get src/simlock-client/client.ts:690-691
F17 DaemonServer routes each socket request by an explicit case; any other operation answers UNKNOWN_REQUEST src/daemon/server.ts:1216, :1293-1294
F18 startDaemon also takes configOverrides, which only tests pass; the default config depends on the capacity strategy in the file and on gateway.url src/daemon/main.ts:294, src/core/config.ts:576-600
Modules touched

Searches: config.get, configGet, redactConfig, REDACTED_VALUE, GATEWAY_CONFIG_KEYS, ADMIN_ROUTES, getConfig over src/ and website/.

  • src/contract/operations.ts, src/contract/schemas.ts, src/contract/protocol.ts: config.list and its row shape.
  • src/core/config.ts: one exported list of secret keys that redactConfig and the rows both read (F5; #1097 edits the same function, and whichever lands second takes the other's list); the live-key list; the gateway's keys (F9) exported for the rows.
  • src/core/config-rows.ts (new): settingsRows({ running, saved, defaults, role }), pure.
  • src/daemon/settings.ts (new): createConfigSettings({ configPath, filesystem, modules, role, systemStats, running }) with list(), built in src/daemon/main.ts and passed to both dispatchers.
  • src/daemon/dispatcher.ts, src/gateway/dispatcher.ts: the config.list handler.
  • src/daemon/server.ts: a case "config.list" in the socket router (F17).
  • src/simlock-client/client.ts, src/simlock-client/types.ts, src/admin/index.ts: listConfig().
  • src/http/admin-declarations.ts, src/http/app.ts: GET /v1/config.
  • website/src/content/docs/docs/reference/configuration.mdx, website/src/content/docs/docs/worker/configuration.mdx: reading settings over HTTP.
flowchart LR
  H["http app *"] --> D["dispatchers *"]
  D --> S["daemon/settings *"]
  S --> R["core/config-rows *"]
  S --> L["core loadConfig"]
  R --> C["contract configSchema"]
Surface and extension points

src/daemon/settings.ts: createConfigSettings(options) returns ConfigSettings { list(): Promise<ConfigListOutput> }. The gateway dispatcher declares the interface it takes (as it does for GatewayUpdate), so src/gateway imports nothing from src/daemon. #1154 adds set to the same handle.

Contract and event changes

This PR bumps the protocol by one.

  • config.list: admin, read; input {}; output { rows, fileProblem? }.
  • The rows: walk configSchema; every object field recurses at any depth, optional objects included; every other field is one row (json for an array, a record or a union); http.proxyAuth one json row; a drivers json row; no mode row (feature Shared values, "The rows of a role").
  • A row: key (1 to 200 characters), kind (boolean, number, string, enum, json), values (the enum's strings, on enum only), running, saved, default (any JSON; absent when the key has no value there, and always absent on a secret row), apply (live or restart), secret (boolean), set (boolean, on a secret row only: from the saved value, or the running one when the file does not load; gateway.alerts.destinations is set when it holds at least one destination), pending (boolean: saved differs from running, secret rows included). At most 500 rows.
  • fileProblem: a string of at most 2000 characters, cut with … when longer.
  • default: what loadConfigWithDefaults gives over no file, with the daemon's role and modules (F18).

No event.

Other code on the same state

Searches: readers of config.json (configPath, readConfigFile: 3 hits, src/daemon/main.ts, src/cli/environment.ts, src/core/config.ts), readers of the running config object (options.config: the dispatchers, src/core/create-core.ts, src/core/reaper.ts).

  • simlock config set writes the file while the daemon runs (until #1154): config.list reads the file on each call, so it shows that write as saved at once; nothing is cached.
  • A hand edit half-written when config.list reads: the CLI and the daemon write atomically (src/cli/environment.ts:410-417); a hand editor may not, and an unparsable file gives fileProblem (F8), not a failure.
  • config.get: unchanged; it still returns secrets (#1097).
Failure modes
Call Outcome What happens Limit, counted from
config.list reads config.json ok rows with saved none: a local file read
config.list reads config.json absent saved is each key's default; no fileProblem —
config.list reads config.json invalid JSON or refused by loadConfig rows with no saved, pending false, fileProblem the loader's message —
config.list reads config.json throws (permission) fileProblem is the error's message; rows as above —

State written: none.

Rules in play
  • ADR 0057 §2: "config.list (admin, read) answers one row per setting": the operation and row shape above.
  • ADR 0057 §4: "config.list says only whether each is set": secret rows carry set only, from the list redactConfig reads.
  • ADR 0057 §7: "A gateway answers config.list ... with the keys it reads": F9.
  • ADR 0003, one contract behind every frontend: the route dispatches config.list; no second reader in src/http.
  • src/contract/AGENTS.md, "Adding an operation": role and effect matrix rows, protocol bump, both dispatchers, client, HTTP, website.
  • Documentation rule 9: the HTTP read is described in the configuration pages in this PR.
Tests

Seam: startDaemon through daemon.dispatch (model: src/daemon/main.test.ts:526-557; tests write config.json, not configOverrides, F18), the socket (model: src/daemon/server.test.ts), and the route in src/http/app.test.ts.

  • An admin reads GET /v1/config on a worker and gets one row per setting with its kind, running, saved and default values and how it applies: a number key; an enum key with its values; a json key (warmPool.targets); drivers; http.proxyAuth as one row; an optional key unset (gateway.url); no mode row; a live key; a restart key.
  • A secret row says only whether it is set: gateway.token set and unset; gateway.token changed in the file after start (set, pending); two alert destinations with url and secret; the answer's text holds none of the three values.
  • A row says pending when the file differs from what runs: a restart key changed in the file after start (pending); a live key changed by hand in the file (pending too: only config.set applies it live); the file no longer loads (fileProblem, no saved); no file (saved is each default); the file unreadable (fileProblem the error's message); a fileProblem over 2000 characters (cut with …).
  • A gateway lists only its own settings, and an agent is refused: gateway: http.port and gateway.disconnectedRetentionMs listed, idle.shutdownAfterMs and gateway.token not; an agent token gets 403; the call over the daemon socket (listConfig()).

Done when

  • config.list is in the role and effect matrices of src/contract/operations.test.ts, and the protocol range is one higher.
  • GET /v1/config with an operator token answers the rows; with an agent token 403.
  • No row of the answer carries the value of gateway.token or of an alert destination's url or secret.
  • pnpm openapi lists GET /v1/config.
  • The configuration pages describe GET /v1/config.

Out of scope

  • Changing a setting (#1154) and restarting (#1155).
  • The console page (#1156).
  • Redacting config.get and simlock config (#1097).
  • A simlock config list command.

Depends on

Written by an agent.

Lenguaje dominante
TypeScript
Estrellas
705
Forks
40
Merge medio
12 h 9 min
PR fusionados (30 d)
376

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de callstackincubator/simlock

Todos los issues de callstackincubator/simlock

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.