Warm-pool targets over HTTP and the CLI

Ouverte
#1,144 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
38/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
node.js, typescript
Domaine
api, cli, documentation

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

task:draft

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: first Learning: <on|off> (<configured|runtime>); then one line per row of the answer's targets (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 (no warm.set is sent).
  • warm learn: Learning: <on|off> (runtime). for on and off; Learning follows config.json again: <on|off>. for config.
  • warm forget's last line ends unless a target keeps them (see simlock warm list). in place of unless a configured warmPool.targets entry keeps them.
  • --json on any of them prints the daemon's answer; on warm unset with no runtime row, the warm.list answer it read.
  • --count takes 0 or 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, tag Devices), 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 beside warmPool.targets; line 15 says which settings need a restart), worker/configuration.mdx and reference/configuration.mdx (a config.json edit still needs a restart; simlock warm changes targets and learn without one), gateway/index.mdx:37 (the four subcommands fail on a gateway too).
  • docs/internal/IDEAS.md.
  • src/http/AGENTS.md, src/cli/AGENTS.md where 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, the warm.set input as is (the contract validates it).
  • DELETE /v1/warm-pool/learned: query platform, model (each one value), optional osVersion, mode, imageTag, read with firstValue and passed to warm.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: GET 200; PUT 200 with the body passed through; DELETE with the query passed to warm.forget; an agent token 403; a bad body 400; a gateway's 501.
  • A user runs simlock warm list and reads the effective list: configured, runtime and replaced rows; learned kinds; --json; nothing set.
  • A user runs simlock warm set and the one row changes, the rest of the runtime list and the runtime learn kept: a new row, at the end; an existing row; --count 0; a runtime learn: false kept; --json; --count missing, 257, 1.5, "", 02 or many is the count usage error; platform windows and --mode tiny are usage errors.
  • A user runs simlock warm unset or simlock warm learn: unset a runtime row; unset a key with no runtime row, sending nothing; learn on, off, config; --json on each; learn maybe is a usage error.

Done when

  • pnpm vitest run src/http src/cli passes, each Tests line a test there.
  • simlock --help lists warm list, warm set, warm unset and warm learn.
  • The website pages in Modules touched describe runtime rows and the four subcommands, say that simlock warm changes need no restart and that a config.json edit still does, and gateway/index.mdx names the four subcommands among those that fail on a gateway; docs/internal/IDEAS.md no longer lists "changing targets without a restart".

Out of scope

  • The console (#1145, #1146).
  • A warm command that edits config.json.

Depends on

  • #1143

Written by an agent.

Langage dominant
TypeScript
Étoiles
705
Forks
40
Merge moyen
12 h 9 min
PR mergées (30 j)
376

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de callstackincubator/simlock

Toutes les issues de callstackincubator/simlock

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.