Runtime warm-pool targets: warm.set and warm.list, kept in state.db

Abierto
#1,143 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript

Línea de trabajo

Start with src/core/warm-pool/converger.ts and src/core/warm-pool/policy.ts, then read src/core/warm-pool/converger.test.ts and the operation patterns in src/contract/operations.ts. The scope also spans state migrations, daemon and gateway dispatch, client, bus events, and doctor. Done means runtime targets persist and affect warm-pool planning and shutdowns, with the specified operations, event, and tests working across those modules.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

task:draft

Part of #1137.

Scope

After this PR an admin client (the typed client's listWarmTargets and setWarmTargets, or any caller of the contract) can change what a worker's warm pool keeps without a restart. Runtime rows sit in the warm pool's own state.db tables and stand in for every configured target of the same key. A count can be 0. learn can be set too. A change that keeps fewer devices shuts them down at once. Each change emits warm-pool.targets-changed. Status, doctor and warm-pool.target-missed see runtime rows. A gateway refuses both operations. The HTTP routes, the CLI and the console come in #1144 to #1146.

It touches more than one module (warm pool, contract, bus, daemon, gateway, client, doctor). They split along no seam a test can drive alone: the operations without the pool's rule have nothing to test, and the pool's rule has no caller without the operations.

In short

An admin client sends the whole runtime list with warm.set, which stores it and answers the effective list at once, without waiting for a pass. warm.list answers it any time. Every pass starts by reading the stored rows and learn. When they differ from those its last plan used, it takes the devices that plan kept, resolves the new list, and takes them again: the devices kept before and not after are the lowered set. In that same pass it shuts each of them down that is still idle and ready, with initiator warm-pool, and boots or creates what a raised count needs. A daemon restart keeps the rows. "Runtime row", "key" and "effective list" are defined in #1137's Words used. For example, configured {ios, "iPhone 17", osVersion "26.0", count 2} with runtime {ios, "iPhone 17", osVersion "26.0", count 0} keeps no iPhone 17 26.0, learned or not.

flowchart LR
  A[warm.set] -->|changed| B[runtime rows in state.db]
  B --> C[effective list]
  K[config.json targets] --> C
  C --> D[pass: resolve, plan, act]
  D --> E[shut down what the change stopped keeping]
  D --> F[boot or create what is short]
  A -->|changed| G[warm-pool.targets-changed]
  style A stroke-width:3px
  style B stroke-width:3px
  style C stroke-width:3px
  style E stroke-width:3px
  style G stroke-width:3px

Inputs (warm.set, the row bounds in #1137's Shared values):

Input Today After
{targets: [{platform: "ios", model: "iPhone 17", osVersion: "26.0", count: 0}]} no such operation stored; the configured target of that key keeps none
{targets: [], learn: false} no such operation stored; learned kinds are not planned
{targets: []} after the two above no such operation stored; configured targets and warmPool.learn apply again
a row with count: 257 no such operation BAD_REQUEST whose message starts targets.0.count:
two rows with key ios iPhone 17 26.0 no such operation BAD_REQUEST targets.1: repeats the platform, model, osVersion and mode of targets.0
any input, agent token no such operation FORBIDDEN
any input, on a gateway no such operation UNSUPPORTED_IN_GATEWAY_MODE "warm.set acts on one machine's devices; run it against a worker"

If this goes wrong, a user sees a device shut down that the pool should still keep, or a count that does not take effect until a restart.

Technical spec

Facts

Commit ce8fea85.

# Fact Source
F1 The pool takes the config's warmPool block once, at construction; the config is frozen at load src/core/create-core.ts:255, src/core/config.ts:626, :1313-1318
F2 The pool reads config.targets in every pass's resolve and config.learn in every read of learned kinds src/core/warm-pool/converger.ts:452-459, :245-246
F3 figures() lists the configured targets from config before the first pass or with the pool off src/core/warm-pool/converger.ts:333-356
F4 Targets of one spec merge, counts summed; a learned kind of a configured spec is that entry with max(configured, learned) src/core/warm-pool/policy.ts:416-439 (plannedKinds), :525-529
F5 targetedDevices keeps, per kind, the ready idle devices, oldest createdAt first, up to its count, plus every ready idle device a waiting request is matched to src/core/warm-pool/policy.ts:517-542, :480-493
F6 A warm-pool shutdown goes through lifecycle.shutdown(device, "warm-pool", "cleanup") after a revalidation; the reason is only in the log line "a warm pool shut a device down" src/core/warm-pool/converger.ts:723-735
F7 device.shutdown's payload is {deviceId, initiator}, no reason src/bus/index.ts:181
F8 WarmProposal.reason for a shutdown is over-budget, disabled, waiting-request, displaced, target or never-leased-idle src/core/warm-pool/policy.ts:23-41
F9 The warm pool's schema owner is warm-pool, version 1, one migration; state.db runs each step from the stored version and refuses a stored version above the code's src/core/warm-pool/learned.ts:6-30, src/state/open.ts:145-161
F10 StateDatabase.transaction(work) runs work in one transaction src/state/open.ts:31, :125
F11 The worker daemon opens state.db with warmPoolOwner among its owners src/daemon/main.ts:345
F12 warm.forget is an admin write operation; the daemon's handler calls warmKinds.forget; the gateway refuses it with unsupportedByDesign src/contract/operations.ts:610-622, src/daemon/dispatcher.ts:788-801, src/gateway/dispatcher.ts:252
F13 unsupportedByDesign throws UNSUPPORTED_IN_GATEWAY_MODE "<operation> acts on one machine's devices; run it against a worker" src/gateway/dispatcher.ts:767-774
F14 A handler gets the parsed input and the session; the principal is session.principal src/daemon/dispatcher.ts:191-194, :461
F15 A bad input is BAD_REQUEST with path: message pairs joined by ; , the path joined by . src/daemon/dispatch.ts:382, src/contract/errors.ts:494-502
F16 A configured target's fields and bounds: platform ios/android, model 1–256 chars, osVersion checked by parseOsConstraint, mode slim/full, count a positive integer, unknown key refused, at most 256 targets src/core/warm-pool/config.ts:55-108, src/contract/schemas.ts:476-477
F17 The status target schema's origin is configured or learned src/contract/schemas.ts:496-507
F18 warm-pool.target-missed is emitted for configured reports only, payload origin: "configured" src/core/warm-pool/converger.ts:537-563, src/bus/index.ts:274-283
F19 Doctor's warm findings read only origin === "configured" figures and sum config.warmPool.targets for its over-limit finding src/core/doctor.ts:603-630
F20 forgetKinds keeps a spec's retry backoff when a configured target resolved to it (#resolved) src/core/warm-pool/converger.ts:190-199
F21 Nuke clears the learned record through warmPool.forget() src/core/nuke-service.ts:48, :89
F22 The protocol range is {min: 66, max: 66} src/contract/protocol.ts:13
F23 Adding an event: EventMap, EVENT_NAMES, an EVENTS.md row and the website reference src/bus/AGENTS.md ("Adding an event"), src/bus/index.test.ts:65
F24 The converger test harness takes targets, learn and an optional state, and owns an EventBus src/core/warm-pool/converger.test.ts:105-140
F25 The typed client declares forgetWarmKind and calls warm.forget src/simlock-client/client.ts:265, :686-687
F26 The console's figures row reads origin as a string ui/src/model/worker-page.ts:551, :581
F27 simlock status prints a target's origin as given src/cli/format.ts:321
F28 config.json may hold two targets of one key: the validator checks the list's length and each row only src/core/warm-pool/config.ts:101-107
F29 Status caps its warm-pool entries at 256 + 2 × 32 = 320, and the daemon parses its own status answer with that schema src/contract/schemas.ts:476-481, :516, src/daemon/dispatcher.ts:857
F30 CORE_ROUTE_SEGMENTS lists the first path segment of every core route src/contract/protocol.ts:82-98
F31 component.removed carries the admin's principal as requesterId src/bus/index.ts:207-233
F32 The socket server sends each operation through an explicit switch (frame.type) (case "warm.forget"), whose default throws UNKNOWN_REQUEST; a test routes warm.forget from the socket src/daemon/server.ts:1163-1166, :1294; src/daemon/server.test.ts:2793
F33 A test pins CORE_ROUTE_SEGMENTS' exact list src/http/core-routes.test.ts:105-123
F34 operations.test.ts lists every operation's role and effect src/contract/operations.test.ts:36, :125
F35 src/admin/index.ts re-exports the client's warm types; the CLI tests' fakeClient implements SimlockAdminClient src/admin/index.ts:67-68, src/cli/index.test.ts:8226
F36 target-missed's memory and a report's coverage are keyed by position in warmPool.targets src/core/warm-pool/converger.ts:141-150, :537-572
F37 A pass that starts while one runs joins it; a pass under nuke returns early; a pass that throws is caught and logged src/core/warm-pool/converger.ts:270-280, :406-430
Modules touched

Searches: config.targets, config.learn, warmPool.targets, origin === "configured", "configured", warmPoolOwner, warm.forget, WarmKindForgetter, target-missed, PROTOCOL_VERSION_RANGE over src/ and ui/src/.

  • src/core/warm-pool/runtime-targets.ts (new): RuntimeTargets, the store of the runtime list and learn, and effectiveTargets(configured, runtime) (a runtime row replaces every configured target of its key, once, at the first one's place).
  • src/core/warm-pool/learned.ts: warmPoolOwner version 2, a second migration adding warm_runtime_targets and warm_runtime_settings.
  • src/core/warm-pool/converger.ts: setTargets, listTargets, the effective list in resolve, figures(), targeted() and learn; at the start of each pass, the comparison with the rows of the last plan and the lowered set's shutdowns ("before" is computed from the resolved targets and learn the last plan used, kept apart from #resolved and the live setting, so a pass that resolved and then threw, or a learn-only change, still compares against the last plan); the event; target-missed for runtime rows, its memory keyed by row key in place of position (F36).
  • src/core/warm-pool/policy.ts: origin runtime; an exact count that drops the spec's learned count; shutdown reason target-lowered.
  • src/core/warm-pool/figures.ts, index.ts, AGENTS.md.
  • src/core/core-ports.ts, src/core/create-core.ts: a WarmTargetsControl port beside WarmKindForgetter.
  • src/core/doctor.ts: warm-pool-target-unreachable reads figures() filtered origin !== "learned" in place of === "configured"; the over-limit sum reads the effective list's counts through the pool (listTargets) in place of config.warmPool.targets; its remedy names both places a count lives.
  • src/contract/operations.ts, src/contract/schemas.ts (the runtime row, origin, WARM_POOL_ENTRIES_MAX), src/contract/protocol.ts, src/contract/operations.test.ts (F34).
  • src/daemon/server.ts (two case lines, F32), src/admin/index.ts (F35), src/cli/index.test.ts's fakeClient (F35), src/http/core-routes.test.ts (F33).
  • src/bus/index.ts, src/bus/index.test.ts.
  • src/daemon/dispatcher.ts, src/daemon/main.ts.
  • src/gateway/dispatcher.ts.
  • src/simlock-client/client.ts, src/simlock-client/types.ts.
  • docs/internal/EVENTS.md, website/src/content/docs/docs/reference/events.mdx, website/src/content/docs/docs/using-devices/programmatic-client.mdx (listWarmTargets, setWarmTargets beside forgetWarmKind, documentation rule 9).
flowchart LR
  CL[simlock-client *] --> DI[daemon dispatcher *]
  GW[gateway dispatcher *] -.refuses.-> DI
  DI --> CP[core ports *]
  CP --> WP[warm-pool converger *]
  WP --> RT[runtime-targets *]
  WP --> PO[policy *]
  RT --> ST[(state.db)]
  WP --> BUS[bus *]
  DR[doctor *] --> WP
  WP --> LC[ManagedDeviceLifecycle]
sequenceDiagram
  participant C as Admin client
  participant D as Daemon dispatcher
  participant W as WarmPool
  participant S as state.db
  C->>D: warm.set {targets, learn}
  alt bad input or agent token
    D-->>C: BAD_REQUEST or FORBIDDEN
  else valid
    D->>W: setTargets(input, principal)
    W->>S: replace rows (one transaction)
    alt transaction throws
      W-->>D: throws
      D-->>C: INTERNAL, rows as before
    else stored and changed
      W->>W: emit warm-pool.targets-changed, ask for a pass
      W-->>D: effective list
      D-->>C: effective list
      W->>W: next pass: rows or learn differ from its last plan, so before = kept by that plan, resolve, after = kept now, shut down before − after still idle and ready
    end
  end
Surface and extension points
  • WarmPool gains setTargets(input: WarmSetInput, principal: string): Promise<WarmListAnswer> (it stores and answers at once; the answer's resolved and learnedCount are those of the last resolve, absent and 0 for a row it has not resolved) and listTargets(): Promise<WarmListAnswer> (it resolves the rows first when no pass has, as targeted() does).
  • createCore returns warmTargets: WarmTargetsControl (list(): Promise, set(input, principal): Promise), beside warmKinds. The daemon hands it to the dispatcher as warmTargets.
  • RuntimeTargets (new RuntimeTargets(state)): read(): {targets, learn?}, replace(next): boolean (true when it changed anything).

No second implementation of anything.

Contract and event changes

This PR bumps the protocol by one.

  • warm.list: role admin, effect read, input {}, output the warm.list answer in #1137's Shared values.
  • warm.set: role admin, effect write, input {targets: runtimeRow[] (max 256), learn?: boolean}, output the warm.list answer. runtimeRow is strict: platform ios|android; model string 1–256; osVersion optional string 1–256 that parseOsConstraint accepts; mode optional slim|full; count integer 0–256. A repeated key is refused by a refine on the list naming the later row. A bad value gets BAD_REQUEST (F15). The effective list may hold 512 rows (256 configured keys, 256 runtime ones), so WARM_POOL_ENTRIES_MAX rises from 256 + 2 × 32 to 2 × 256 + 2 × 32 = 576 (F29); configured targets of one key make one row, counts summed.
  • warm.list answer rows: targets (the effective list, at most 512) each {platform, model, osVersion?, mode?, count, origin, configuredCount?, learnedCount, resolved?: {osVersion, mode}}; runtime: {targets: runtimeRow[], learn?: boolean} as stored; learnedCount is an integer 0 or more: the learned peak the pool plans for the spec the row resolves to; 0 on a runtime row (its count is exact), and when none, unresolved, or learning is off. learn is {value, origin, configured}, configured being warmPool.learn (true when unset). resolved is the OS version and mode (full or slim) of the spec the row resolved to in the last pass, absent when it did not; before the first pass warm.list resolves the rows first, as targeted() does (converger.ts:309-311).
  • warm.list's learned rows: platform, model, osVersion, mode (full when unset), imageTag?, count (the 24-hour peak), at most 64 (2 × WARM_POOL_LEARNED_KINDS_MAX).
  • Status target origin gains runtime (F17); a report that merges rows of one spec is runtime when any of them is.
  • New event warm-pool.targets-changed, payload {targets: runtimeRow[], learn?: boolean, requesterId: string} (the caller's principal, F31), module warm-pool; an EVENTS.md row and a row in website/src/content/docs/docs/reference/events.mdx.
  • CORE_ROUTE_SEGMENTS gains warm-pool (F30), for #1144's routes.
  • warm-pool.target-missed's origin becomes "configured" | "runtime"; its EVENTS.md and website rows change their "always configured".
  • The typed client gains listWarmTargets() and setWarmTargets(input).
Other code on the same state

Searches over src/ outside tests: config.warmPool (4 hits, 2 files), figures() (9 hits, 6 files), targeted() (3 hits, 2 files), warm_kinds (10 hits, 1 file), warmPool.targets (5 hits, 4 files); the one writer of config.json is simlock config set (src/cli/commands/config.ts:60-62).

Component Both act Wins
A pass running when setTargets is called setTargets stores and answers without waiting; the running pass plans with the rows it read at its start, and the next pass sees the new rows and compares the change, from the next pass
Two warm.set between passes the next pass compares the rows of its last plan with the latest rows the later list; the union of what both lowered is shut down
targeted() read by the reaper reads the effective list from the next resolve on; before that, the last pass's the effective list, from the next pass
idle-shutdown, idle-destroy a device the change stopped keeping may be proposed by both; each revalidates ready and unclaimed under the lock the first to claim; the other skips
A lease granted between the change and the pass the shutdown revalidates no lease (F6) the lease
A waiting request its matched device is in targeted() before and after, so never in the difference (F5) the request
forgetKinds keeps the backoff of a spec any effective-list row resolved to the effective list
Nuke forget() clears learned kinds only; runtime rows stay —
simlock config set warmPool.targets writes the file; after a restart a runtime row still replaces a configured target of its key the runtime row
config.get still answers the file's warmPool; runtime rows are only in warm.list —
Doctor reads the effective list for both warm findings —
config.json with two targets of one key one runtime row of that key replaces both, once (F28) the runtime row
Failure modes
Call Outcome What happens Limit, counted from
RuntimeTargets.replace ok, changed rows stored, event, pass asked for, answer the effective list —
RuntimeTargets.replace ok, unchanged answer the effective list, no event, no pass —
RuntimeTargets.replace throws warm.set answers INTERNAL; the transaction rolls back; no event —
RuntimeTargets.read in a pass throws the pass plans from the configured targets and config learn, logs a warning once per pass (as learned kinds do, converger.ts:245-257) —
lifecycle.shutdown for a target-lowered device answers undefined (leased, gone or moved) nothing; no log line —
lifecycle.shutdown throws logged as any warm shutdown; held back one tick (converger.ts:676-677) 30 s, from the failure
resolve of a runtime row refused a report short with the refusal, as for a configured target —

Restart in the middle: the rows are written in one transaction, so a restart sees the old list or the new one. The rows and learn count as used only once a pass has planned with them: a pass that does not plan (under nuke, while stopping) or that throws leaves the comparison to the next pass that plans. After a restart there is no last plan, so the devices of rows lowered just before it are left to the idle rules.

The read failure has no Tests line: the planning fallback is the learned kinds' (as today, converger.test.ts), and no caller sees it.

Rules in play
  • ADR 0056 §1–6: the whole task; the key, the effective list, the exact count, the target-lowered rule, the operations and the event as written there.
  • ADR 0051 §1–2, "Every configured count fills before any learned count": runtime rows are configured counts in effective-list order.
  • ADR 0036, "Each owner creates its own tables and keeps its own schema version": warmPoolOwner version 2, one migration step.
  • ADR 0014, an event "minted where the fact happened": the pool emits warm-pool.targets-changed after the commit.
  • ADR 0003, one typed contract: both operations are in OPERATIONS, so every transport reaches them.
  • Safety rule 2 (revalidate before acting): every target-lowered shutdown revalidates under the lock (F6).
  • src/core/warm-pool/AGENTS.md Rules, "Only displacement shuts a device down for a target": this task adds the target-lowered case, and the manual says so.
Tests

Seam: the WarmPool harness in src/core/warm-pool/converger.test.ts with a memory state.db (openMemoryState), the dispatcher in src/daemon/dispatcher.test.ts (model: its warm.forget block), and the gateway's in src/gateway/dispatcher.test.ts.

  • An admin client sets the runtime list and gets the effective list back, which a later list answers: replace a configured target by key; two configured targets of one key make one row, and one runtime row replaces it; a new kind; count 0; a list without a row brings the configured target back; learn set, then absent; a key that differs only by mode as written keeps both; learnedCount of a configured row's learned spec, 0 on a runtime row; resolved of a row with no mode; learn.configured; runtime in stored order.
  • An admin sends an invalid warm.set, or an agent sends either operation, and nothing is stored; a valid one reaches the pool with the caller's principal: count −1, 257, 1.5; a repeated key; an unknown key class; 257 rows; osVersion twenty; platform windows; an agent on warm.set and warm.list FORBIDDEN; an admin's principal passed; both operations from the socket (model: src/daemon/server.test.ts:2793).
  • The pool keeps what the effective list says, from the pass a change asks for: a raised count boots a shut-down device or creates one; count 0 on a configured kind keeps none; count 0 on a learned kind keeps none; count 1 under a learned peak of 2 keeps 1; runtime learn: false over a configured true; a runtime row fills before a learned kind and displaces it.
  • A change that keeps fewer devices shuts down the idle ones no longer kept at once, initiator warm-pool, log reason target-lowered: count 2 → 1 shuts the newest ready one; count → 0 shuts every idle one; a leased device stays; a device a waiting request is matched to stays; runtime learn: false shuts learned-only devices; a raised count shuts nothing; a set during a running pass answers at once and the next pass shuts down; two sets between passes shut down the union; a pass under nuke leaves the comparison to the next pass that plans; a pass that starts right after the store plans with the new rows.
  • A change emits warm-pool.targets-changed with the runtime list, learn and the caller's principal as requesterId; a set that changes nothing emits nothing: a change; the same input again; a learn-only change; a reordered list.
  • A daemon restart keeps the runtime rows and learn, and nuke leaves them: reopen the same state.db; after the pool's forget(); a database at warm-pool version 1 migrates with no rows (model: learned.test.ts:209).
  • Status shows a runtime row with origin runtime, and a short runtime row fires warm-pool.target-missed with origin runtime: a runtime row met; a runtime row short for running-limit; a configured row as today; a configured 26.0 row and a runtime 26 row resolving to one spec report runtime; a list change between two short passes emits once for a row still short; 512 rows and 64 learned kinds pass the status schema.
  • Doctor counts runtime rows in its warm findings: a runtime row whose runtime is missing is warm-pool-target-unreachable; a runtime row that replaced a configured one is summed once in the over-limit check, whose remedy says to lower the warm targets' counts in config.json or the runtime list; a count-0 row adds 0 and no finding (src/core/doctor.test.ts).
  • A store write that fails answers an error, keeps the old rows and emits nothing: the transaction throws.
  • A gateway refuses warm.list and warm.set with UNSUPPORTED_IN_GATEWAY_MODE: warm.list; warm.set (extend the warm.forget case at src/gateway/dispatcher.test.ts:1573).

Done when

  • pnpm vitest run src/core/warm-pool src/daemon/dispatcher.test.ts src/daemon/server.test.ts src/gateway/dispatcher.test.ts src/core/doctor.test.ts src/bus src/contract src/http/core-routes.test.ts src/cli/index.test.ts passes, each Tests line a test there.
  • src/contract/protocol.ts is one higher than the base branch's, and .agents/scripts/protocol-bump-check.mjs passes.
  • docs/internal/EVENTS.md and website/src/content/docs/docs/reference/events.mdx list warm-pool.targets-changed and say warm-pool.target-missed's origin may be runtime.
  • src/core/warm-pool/AGENTS.md describes runtime rows, the effective list and the target-lowered shutdown.

Out of scope

  • HTTP routes, the CLI and their website pages (#1144); the console (#1145, #1146).
  • Changing config.json, or any setting other than targets and learn.
  • A revision check on warm.set.
  • An MCP tool.

Depends on

Written by an agent.

Lenguaje dominante
TypeScript
Estrellas
705
Forks
40
Merge medio
12 h 9 min
PR fusionados (30 d)
376

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de callstackincubator/simlock

Todos los issues de callstackincubator/simlock

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.