Warm-pool targets over HTTP and the CLI
Maintainer antworten meist innerhalb von 1 Tag
Dieses Issue hat noch niemand übernommen.
Bewertung
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Anfängerfreundlichkeit
- 38/100
- Issue-Typ
- Feature
- Klarheit
- Klar beschrieben
- Aktivitätsstatus
- Aktiv
- Tech-Stack
- node.js, typescript
- Bereich
- api, cli, documentation
Rechercherichtung
Start with #1143's warm-operation contract, then read src/cli/commands/warm.ts and the route declarations in src/http/admin-declarations.ts; the issue names the related CLI, HTTP, and documentation files. Run the CLI and HTTP tests in src/cli/index.test.ts, src/http/app.test.ts, and src/http/openapi.test.ts, plus the website OpenAPI check. Done means the specified commands and routes behave as described, gateway requests return 501, and the affected documentation reflects runtime changes.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
Part of #1137.
Scope
After this PR a user on a worker changes what the warm pool keeps from the CLI: simlock warm list, warm set, warm unset and warm learn. An HTTP caller uses GET /v1/warm-pool, PUT /v1/warm-pool/targets and DELETE /v1/warm-pool/learned. All of them go through #1143's warm.list, warm.set and warm.forget. The website's warm-pool, CLI, configuration and gateway pages say that a runtime change needs no restart, while a config.json edit still does.
In short
simlock warm set reads warm.list, changes one row of its runtime list (the stored list, in stored order) and sends that list back with runtime.learn. The other runtime rows and the runtime learn stay as they were. It sets the count given; it does not raise from a learned peak. A new key goes at the end of the runtime list. warm unset drops one runtime row, so the configured target of that key applies again. warm learn on|off|config sets or drops the runtime learn. The three routes reach the same operations, and a gateway answers 501. The kind is spelled as in #1137's Shared values ("Kind spelling").
flowchart LR
A[simlock warm set] --> B[warm.list]
B --> C[change one row]
C --> D[warm.set whole runtime list]
H[PUT /v1/warm-pool/targets] --> D
G[GET /v1/warm-pool] --> B
X[DELETE /v1/warm-pool/learned] --> F[warm.forget]
style A stroke-width:3px
style C stroke-width:3px
style G stroke-width:3px
style H stroke-width:3px
style X stroke-width:3px
Before:
$ simlock warm list
{"error":{"code":"USAGE","message":"Unknown warm command: list (run `simlock --help` for usage)"}}
After (configured: ios iPhone 17 26.0 count 2 and ios iPhone 17 26.0 (slim) count 2; learned: ios iPhone 16 18.5 (full) peak 1):
$ simlock warm set android "Pixel 8" --count 1
Keeping 1 android Pixel 8 warm (runtime). The pool acts on its next pass.
$ simlock warm set ios "iPhone 17" 26.0 --count 0
Keeping no ios iPhone 17 26.0 warm (runtime). Its idle devices shut down now.
$ simlock warm list
Learning: on (configured)
ios iPhone 17 26.0: 0 (runtime; config says 2)
ios iPhone 17 26.0 (slim): 2 (configured)
android Pixel 8: 1 (runtime)
Learned: ios iPhone 16 18.5 (full), peak 1
$ simlock warm unset ios "iPhone 17" 26.0
ios iPhone 17 26.0 follows config.json again.
$ simlock warm unset ios "iPhone 17" 26.0
No runtime row for ios iPhone 17 26.0; nothing changed.
$ simlock warm learn off
Learning: off (runtime).
$ simlock warm learn config
Learning follows config.json again: on.
$ simlock warm set ios "iPhone 17" --count many
{"error":{"code":"USAGE","message":"warm set needs --count <n>, a whole number from 0 to 256 (run `simlock --help` for usage)"}}
Printed lines, word for word, with <kind> as the Kind spelling:
warm list: firstLearning: <on|off> (<configured|runtime>); then one line per row of the answer'stargets(the effective list) in its order,<kind>: <count> (<configured|runtime>), with; config says <configuredCount>before the)on a runtime row that replaced one;No targets.when there are none; then one line per learned kind,Learned: <kind>, peak <count>, its mode always in the brackets and its image tag after it;Learned: none.when there are none.warm set:Keeping <n> <kind> warm (runtime). The pool acts on its next pass.when n ≥ 1;Keeping no <kind> warm (runtime). Its idle devices shut down now.when n is 0.warm unset:<kind> follows config.json again.;No runtime row for <kind>; nothing changed.when the key has no runtime row (nowarm.setis sent).warm learn:Learning: <on|off> (runtime).foronandoff;Learning follows config.json again: <on|off>.forconfig.warm forget's last line endsunless a target keeps them (see simlock warm list).in place ofunless a configured warmPool.targets entry keeps them.--jsonon any of them prints the daemon's answer; onwarm unsetwith no runtime row, thewarm.listanswer it read.--counttakes0or a whole number without a leading zero or sign, at most 256 (^(0|[1-9][0-9]{0,2})$, then ≤ 256).
| Input | Today | After |
|---|---|---|
warm set ios "iPhone 17" --count 2 |
USAGE unknown warm command |
a runtime row set, line printed |
warm set ios "iPhone 17" --count 0 |
USAGE |
a runtime row of 0 |
warm set ios "iPhone 17" (no --count) |
USAGE |
USAGE warm set needs --count <n>, a whole number from 0 to 256 |
warm set ios "iPhone 17" --count 257, 1.5, many, "", 02, +1, 1e2, --count=-1 |
USAGE |
the same USAGE |
warm set ios "iPhone 17" --count -1 |
USAGE |
USAGE with the argument parser's own message (Option '--count' argument is ambiguous…), as for any option value that starts with - |
warm set windows X --count 1 |
USAGE |
USAGE warm set needs a platform first: ios or android |
warm set ios "iPhone 17" --mode tiny --count 1 |
USAGE |
USAGE --mode is slim or full |
warm unset ios "iPhone 17" with no such row |
USAGE |
No runtime row for ios iPhone 17; nothing changed., exit 0 |
warm learn maybe |
USAGE |
USAGE warm learn takes on, off or config |
GET /v1/warm-pool on a worker |
404 | 200, the warm.list answer |
PUT /v1/warm-pool/targets with an agent token |
404 | 403 FORBIDDEN |
PUT /v1/warm-pool/targets with {"targets":[{"count":1}]} |
404 | 400 BAD_REQUEST |
| any of the three, on a gateway | 404 | 501 UNSUPPORTED_IN_GATEWAY_MODE |
If this goes wrong, a user sees warm set drop another runtime row, or a route that does not reach its operation.
Technical spec
Facts
Commit ce8fea85.
| # | Fact | Source |
|---|---|---|
| F1 | A route is declared once with declareRoute (method, path, tag, summary, role, request, reply, errors) and wired in createHttpApp with app.openapi, dispatching its operation with buildHttpSession |
src/http/route-declarations.ts:87-100, src/http/app.ts:304-313 |
| F2 | A route's method is "get" | "post" | "delete" |
src/http/routes.ts:98 |
| F3 | Admin routes sit in ADMIN_ROUTES in admin-declarations.ts; a DELETE with a query schema exists (componentRemoveRoute) |
src/http/admin-declarations.ts:131-145 |
| F4 | RouteTag is a closed list including Devices |
src/http/routes.ts:8-16 |
| F5 | CORE_ROUTE_SEGMENTS lists the first segment of every core route; a test checks every registered route's segment is in it (#1143 adds warm-pool) |
src/contract/protocol.ts:82-98, src/http/core-routes.test.ts:48-59 |
| F6 | UNSUPPORTED_IN_GATEWAY_MODE maps to HTTP 501, FORBIDDEN to 403, BAD_REQUEST to 400 |
src/contract/errors.ts:236, :250, :423 |
| F7 | The website builds an HTTP reference from the OpenAPI document and checks it after a build | website/scripts/check-openapi.mjs:1-8 |
| F8 | The OpenAPI test reads the admin routes with their codes and the side that answers 501 | src/http/openapi.test.ts:211 |
| F9 | Route behaviour is tested with a fake dispatch in app.test.ts, e.g. POST /v1/devices and DELETE /v1/devices/{id} |
src/http/app.test.ts:439 |
| F10 | simlock warm has only forget; any other subcommand is USAGE Unknown warm command: <name> |
src/cli/commands/warm.ts:9-15 |
| F11 | A UsageError message gets (run \simlock --help` for usage)and prints as{"error":{"code":"USAGE","message":…}}`, exit 2 |
src/cli/usage-error.ts:8-9, src/cli/errors.ts:42, :57 |
| F12 | warm forget's platform and mode messages are warm forget needs a platform first: ios or android and --mode is slim or full; its last line names warmPool.targets |
src/cli/commands/warm.ts:27-35, :70 |
| F13 | named() spells a kind as its words, then mode and image tag in brackets |
src/cli/commands/warm.ts:73-78 |
| F14 | The command tree lists warm with child forget; the help text has one warm forget line |
src/cli/tree.ts:70, src/cli/index.ts:25-26 |
| F15 | CLI behaviour is tested through the CLI entry in src/cli/index.test.ts |
src/cli/index.test.ts:2849 |
| F16 | The capacity page says every setting on it takes effect on the next restart, and describes targets, learn and warm forget |
website/src/content/docs/docs/worker/capacity.mdx:15, :162-199 |
| F17 | The configuration pages say a change needs a restart | website/src/content/docs/docs/worker/configuration.mdx:102, :108; website/src/content/docs/docs/reference/configuration.mdx:32, :120 |
| F18 | The CLI reference documents warm forget and says a configured target is not changed by it |
website/src/content/docs/docs/reference/cli.mdx:484-507 |
| F20 | IDEAS.md defers "changing targets without a restart" | docs/internal/IDEAS.md:7-8 |
| F21 | The gateway page lists the commands that fail on a gateway, warm forget among them |
website/src/content/docs/docs/gateway/index.mdx:37 |
| F22 | commandArgs runs Node's parseArgs strict and turns its error into a UsageError with its message |
src/cli/args.ts:14-21 |
Modules touched
Searches: warm forget, forgetWarmKind, warmPool.targets, restart in website/src/content/docs/, "get" | "post" | "delete", ADMIN_ROUTES, CORE_ROUTE_SEGMENTS.
src/http/routes.ts(method gains"put"),src/http/admin-declarations.ts(three routes, tagDevices),src/http/app.ts.src/cli/commands/warm.ts,src/cli/tree.ts,src/cli/index.ts(help lines).website/src/content/docs/docs/reference/cli.mdx(the four subcommands,warm forget's line),worker/capacity.mdx(runtime rows besidewarmPool.targets; line 15 says which settings need a restart),worker/configuration.mdxandreference/configuration.mdx(aconfig.jsonedit still needs a restart;simlock warmchanges targets andlearnwithout one),gateway/index.mdx:37(the four subcommands fail on a gateway too).docs/internal/IDEAS.md.src/http/AGENTS.md,src/cli/AGENTS.mdwhere they list routes or commands.
flowchart LR
CLI[cli warm *] --> CL[simlock-client]
HTTP[http app *] --> DI[daemon dispatcher]
CL --> DI
DI --> WP[warm pool]
GW[gateway dispatcher] -.501.-> HTTP
sequenceDiagram
participant U as simlock warm set
participant D as Daemon
U->>D: warm.list
D-->>U: effective list
U->>D: warm.set {runtime rows with one changed, learn as it was}
alt refused
D-->>U: BAD_REQUEST / FORBIDDEN / UNSUPPORTED_IN_GATEWAY_MODE
U-->>U: prints the error, exit code from the error table
else ok
D-->>U: effective list
U-->>U: prints Keeping … line
end
Contract and event changes
none: the operations, their shapes and CORE_ROUTE_SEGMENTS' warm-pool are #1143's. The routes' bodies and queries:
PUT /v1/warm-pool/targets: JSON body, thewarm.setinput as is (the contract validates it).DELETE /v1/warm-pool/learned: queryplatform,model(each one value), optionalosVersion,mode,imageTag, read withfirstValueand passed towarm.forget, which validates them; an unknown query key is ignored, as on other routes.
Other code on the same state
Searches: callers of setWarmTargets and listWarmTargets (none before this task), writers of the runtime list (warm.set only).
| Component | Both act | Wins |
|---|---|---|
Another warm set or a console change between this command's warm.list and its warm.set |
this command sends the list it read with its one change | the later warm.set; the earlier change is lost (#1137's Assumption on two writers) |
warm unset or warm learn |
read warm.list and send the stored runtime list with one change, the same way |
the later warm.set |
simlock config set warmPool.targets |
writes the file; a runtime row still replaces its key after a restart | the runtime row; warm list shows runtime |
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
CLI warm.list or warm.set |
error reply | prints {"error":…}, exit code from the error table |
the client's call limit, as other commands |
| CLI to daemon | no daemon | the connect error every command prints | as other commands |
| HTTP route → dispatch | error | the error's HTTP status and {error: {code, message}} |
— |
No state is written by this task.
Rules in play
- ADR 0056 §6: the three routes, the four subcommands, a gateway's 501.
- ADR 0040, "every HTTP route is declared once": the three routes are declarations in
ADMIN_ROUTES, so the OpenAPI document and the website reference list them. - ADR 0003, one contract behind every frontend: the CLI and the routes call #1143's operations only.
- Documentation rule 9 (
docs/internal/agent-rules/documentation.md), a public surface change updates its pages in the same change: the website pages in Modules touched.
Tests
Seam: createHttpApp with a fake dispatch (src/http/app.test.ts, model: POST /v1/devices and DELETE /v1/devices/{id}) and the OpenAPI test (src/http/openapi.test.ts:211); the CLI entry with a fake client (src/cli/index.test.ts).
- An HTTP caller reaches the three warm-pool routes and the OpenAPI document lists them:
GET200;PUT200 with the body passed through;DELETEwith the query passed towarm.forget; an agent token 403; a bad body 400; a gateway's 501. - A user runs
simlock warm listand reads the effective list: configured, runtime and replaced rows; learned kinds;--json; nothing set. - A user runs
simlock warm setand the one row changes, the rest of the runtime list and the runtimelearnkept: a new row, at the end; an existing row;--count 0; a runtimelearn: falsekept;--json;--countmissing,257,1.5,"",02ormanyis the count usage error; platformwindowsand--mode tinyare usage errors. - A user runs
simlock warm unsetorsimlock warm learn: unset a runtime row; unset a key with no runtime row, sending nothing;learn on,off,config;--jsonon each;learn maybeis a usage error.
Done when
pnpm vitest run src/http src/clipasses, each Tests line a test there.simlock --helplistswarm list,warm set,warm unsetandwarm learn.- The website pages in Modules touched describe runtime rows and the four subcommands, say that
simlock warmchanges need no restart and that aconfig.jsonedit still does, andgateway/index.mdxnames the four subcommands among those that fail on a gateway;docs/internal/IDEAS.mdno longer lists "changing targets without a restart".
Out of scope
- The console (#1145, #1146).
- A
warmcommand that editsconfig.json.
Depends on
- #1143
Written by an agent.
- Vorherrschende Sprache
- TypeScript
- Sterne
- 705
- Forks
- 40
- Ø Merge
- 12 Std. 9 Min.
- Gemergte PRs (30 T.)
- 376
Entwicklungsumgebung
Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus callstackincubator/simlock
-
request:new
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
callstackincubator/simlock#1806 ·
Maintainer antworten meist innerhalb von 1 Tag
-
bug:new
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 78/100
callstackincubator/simlock#1780 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
task:draft
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
callstackincubator/simlock#1441 ·
Maintainer antworten meist innerhalb von 1 Tag
-
bug:new
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 45/100
callstackincubator/simlock#1805 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
bug:new
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 45/100
callstackincubator/simlock#1804 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
Alle Issues in callstackincubator/simlock
Ähnliche Issues
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 82/100
Maintainer antworten meist innerhalb von 1 Tag
-
Update project links after the repository renamesEvtl. vergeben @JonathanTSilva hat das heute übernommen. Offenai-generated priority: p2 size: xs type: bug
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 85/100
JonathanTSilva/jts-website#119 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 74/100
promplate/code-review#158 · 1 Kommentar · 1 Reaktion ·
Maintainer antworten meist innerhalb von 1 Tag
-
[Docs] CONTRIBUTING points the Backend Remake milestone at a branch that does not existEvtl. vergeben @franpts2 hat das heute übernommen. Offendocs
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 90/100
Maintainer antworten meist innerhalb von 3 Tagen