Settings: read every setting through GET /v1/config

未关闭
#1,153 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
52/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
活跃
技术栈
typescript

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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.

主要语言
TypeScript
星标
705
派生
40
平均合并
12 小时 9 分钟
30 天内合并 PR
376

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南,环境需要你自己搭建:先看它的 README,通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

callstackincubator/simlock 的其他 Issue

查看 callstackincubator/simlock 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。