Settings: read every setting through GET /v1/config

Đang mở
#1,153 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
52/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
api, backend, documentation

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
TypeScript
Star
705
Fork
40
Merge trung bình
12 giờ 9 phút
Pull request đã merge (30 ngày)
376

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstackincubator/simlock

Tất cả issue của callstackincubator/simlock

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.