Settings: change a setting through the daemon, live where it can
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 42/100
- Issue 类型
- 功能
- 描述清晰度
- 描述清楚
- 活跃度
- 活跃
- 技术栈
- typescript
调研方向
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.
由索引模型根据 Issue 内容生成。
描述
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 validatorconfig setandconfig.setcall (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.getreads it too.src/daemon/settings.ts:set(key, value, requesterId), one at a time;src/daemon/main.tspasses it the filesystem, the path and the holder.src/daemon/dispatcher.ts,src/gateway/dispatcher.ts: theconfig.sethandler.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'sBAD_REQUESTprinted asUSAGE; theRemovedline fromremoved.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 segmentBAD_REQUESTInvalid config key: <key>, the CLI's words (F2); an unknown key is refused by the validation (F3).value: any JSON, required: a missingvalueisBAD_REQUEST, so no call removes a key. Output{ rows, removed? }: the touched rows (feature Shared values, "Keysconfig.settakes") asconfig.listgives them after the write, at most 500;removedlists retired keys the write dropped (eventLog.rotateBytes), at most 10.PUT /v1/config/{key}: JSON body{ value }, strict; 200 with the output{ rows, removed? }; 400BAD_REQUESTon 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" (livewhen there are touched rows and all are live), requesterId: string }, moduledaemon. Documented indocs/internal/EVENTS.md(System) andwebsite/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.setat 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): writesstate.db, neverconfig.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, throughconfig.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):requesterIdis the session's principal, never from the input. src/cli/AGENTS.mdrules: 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.getshows it); a parent keyidle(both rows answered, both live); a field inside a json rowhttp.proxyAuth.header(thehttp.proxyAuthrow answered); a key a gateway ignores (no rows, saved);eventLog.rotateBytesin the file (dropped, listed inremoved); other keys and a hand edit kept; file mode0600; 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.shutdownAfterMslowered: 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.deleteAfterMslowered;diskPressure.freeBytesThresholdraised 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.defaultTtlMsoverlease.maxTtlMs;mode; a badgateway.tokenrefused with no value in the message; a key with an empty segment (Invalid config key: <key>); a body with novalue; the file is not valid JSON. - A save emits
config.changedwith the key, how it applied and the caller: live key; restart key; no event on a refusal; the payload holds no value. simlock config setgoes 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;--gatewaywith no gateway present: written by the CLI; daemon running and no admin token: refused, file unchanged; a refusal with a daemon running printsUSAGEand the daemon's message, exit 2; the daemon droppedeventLog.rotateBytes: the CLI prints today'sRemovedline; 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.setis in the role and effect matrices, and the protocol range is one higher.config.changedis inEVENT_NAMES,docs/internal/EVENTS.mdand the website's events reference.simlock config setnever writesconfig.jsonwhile a daemon of its role answers.PUT /v1/config/idle.shutdownAfterMschanges the reaper's shutdown time with no restart.- The CLI reference and both configuration pages say which keys apply at once and that
config setgoes through a running daemon.
Out of scope
- Removing a key; more live keys; changing what
config.getredacts (#1097).config.getdoes show a live key's new value. - Joining a fleet from one key at a time:
gateway.urlandgateway.tokenmust 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 insrc/core/create-core.tsand theidleread insrc/core/warm-pool/converger.ts)
Written by an agent.
- 主要语言
- TypeScript
- 星标
- 705
- 派生
- 40
- 平均合并
- 12 小时 9 分钟
- 30 天内合并 PR
- 376
环境准备
这个项目没有提供开发容器、Dockerfile 或贡献指南,环境需要你自己搭建:先看它的 README,通用步骤见我们的新手贡献指南。
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
callstackincubator/simlock 的其他 Issue
-
request:new
难度 2/5 1-3 小时 新手友好度 72/100
callstackincubator/simlock#1806 ·
维护者通常 1 天内回复
-
bug:new
难度 2/5 1-3 小时 新手友好度 78/100
callstackincubator/simlock#1780 · 1 条评论 ·
维护者通常 1 天内回复
-
task:draft
难度 2/5 1-3 小时 新手友好度 72/100
callstackincubator/simlock#1441 ·
维护者通常 1 天内回复
-
bug:new
难度 2/5 1-3 小时 新手友好度 45/100
callstackincubator/simlock#1805 · 1 条评论 ·
维护者通常 1 天内回复
-
bug:new
难度 2/5 1-3 小时 新手友好度 45/100
callstackincubator/simlock#1804 · 1 条评论 ·
维护者通常 1 天内回复
查看 callstackincubator/simlock 的全部 Issue
相似的 Issue
-
难度 1/5 1 小时以内 新手友好度 82/100
维护者通常 1 天内回复
-
Update project links after the repository renames可能已有人在做 @JonathanTSilva 今天认领。 未关闭ai-generated priority: p2 size: xs type: bug
难度 2/5 1-3 小时 新手友好度 85/100
JonathanTSilva/jts-website#119 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 72/100
-
难度 2/5 1-3 小时 新手友好度 74/100
promplate/code-review#158 · 1 条评论 · 1 个 reaction ·
维护者通常 1 天内回复
-
[Docs] CONTRIBUTING points the Backend Remake milestone at a branch that does not exist可能已有人在做 @franpts2 今天认领。 未关闭docs
难度 1/5 1 小时以内 新手友好度 90/100
维护者通常 3 天内回复