Settings: restart the daemon with POST /v1/restart and simlock daemon restart

オープン
#1,155 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
48/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
node.js, typescript
領域
api, backend, cli

調査の方向性

Start with ADR 0057 and the update flow in src/daemon/update-coordinator.ts, then trace the operation through src/contract/operations.ts, src/daemon/server.ts, and the dispatchers. Run the named coordinator, server, HTTP, updater, launcher, and CLI tests as you work. Done means the CLI and POST /v1/restart launch restart mode once, with the specified update conflicts and failure behavior, and the updater restarts without installing or rolling back.

索引モデルが issue の本文から書いたものです。

説明

task:draft

Part of #1151.

Scope

An admin restarts the daemon without a terminal: POST /v1/restart, the daemon.restart operation, or simlock daemon restart. The daemon hands the restart to the updater process, run in a restart mode that stops the daemon and starts it again, with no install. Leases are kept, as for any restart.

In short

After this PR simlock daemon restart prints Daemon restarting and returns; a few seconds later the same daemon role answers again, having read config.json afresh. POST /v1/restart answers 202 { "restarting": true }. During an update it answers 503 DAEMON_UPDATING. A lease request still waiting in the queue fails with today's restart message (The daemon restarted before this lease request settled; send it again with a new key).

$ simlock daemon restart
{"error":{"code":"USAGE","message":"Unknown daemon command: restart"}}          (today, exit 2)
Daemon restarting                                                               (after)
$ simlock daemon restart --json
{"status":"restarting"}                                                         (after)
sequenceDiagram
  participant C as CLI or HTTP
  participant D as Daemon
  participant U as Updater, restart mode (new)
  C->>D: daemon.restart (new)
  D-->>C: { restarting: true }
  D->>U: launch detached: --restart --pid --gateway?
  U->>D: daemon.stop
  U->>U: wait until the socket is free (10 min, then SIGKILL the pid)
  U->>U: daemon start (2 min)
  alt running
    U-->>U: exit 0
  else not started
    U-->>U: one stderr line in daemon.log, exit 1
  end

If this goes wrong, a daemon stops and does not come back, an update and a restart run at once, or a restart installs or rolls back a version.

Technical spec

Facts

Commit bcedd2fa.

# Fact Source
F1 runUpdater: install, {"stage":"restarting"}, probe.stop(), wait for the pid (SIGKILL when it does not exit), back up the databases, daemon start, rollback on a failed start src/updater/index.ts:96-140
F2 The updater's arguments are --from, --to, --pid and --gateway; anything else throws bad updater arguments src/updater/index.ts:247-272
F3 Limits: daemon start 2 min, each probe call 30 s src/updater/index.ts:40-41
F4 UpdaterLaunch carries entry, from, to, role, pid, simlockHome, logPath; NodeUpdaterLauncher spawns it detached, stdout a pipe, stderr appended to the log src/ports/updater-launcher.ts:9-69
F5 FakeUpdaterLauncher records launches src/ports/updater-launcher.ts:71-80
F6 The update coordinator launches the updater from dist/updater/main.js with the role, pid, home and log path, and keeps the running update in #run src/daemon/update-coordinator.ts:111, :212-223
F7 DAEMON_UPDATING is CLI exit 1, HTTP 503 src/contract/errors.ts:384
F8 daemon.stop is admin, write, { stopping: true } src/contract/operations.ts:634-640
F9 simlock daemon has start, stop, status, logs, install, uninstall; stop connects with launch: false and prints Daemon stopping src/cli/commands/daemon.ts:120-125, :191-201
F10 POST /v1/update is declared with status 202 and served through deps.dispatch src/http/admin-declarations.ts:73-89, src/http/app.ts:655-662
F11 A waiting lease request fails at the next start with the "daemon restarted" message src/leasing/lease-startup.ts:39
F12 The page the restart section lives on today website/src/content/docs/docs/worker/running-the-daemon.mdx:123-130
F13 The updater test table drives runUpdater with fakes and checks stdout and stderr lines src/updater/index.test.ts:500-610
F14 DaemonServer routes each socket request by an explicit case; an operation with none answers UNKNOWN_REQUEST src/daemon/server.ts:1287-1294
F15 The launcher's argv is built in NodeUpdaterLauncher and asserted in its own test; the fake records options only src/ports/updater-launcher.ts:33-44, :81-82, src/ports/updater-launcher.test.ts:16, :46
F16 A second daemon.update during an update answers { started: false, update }; only leasing throws DAEMON_UPDATING src/daemon/update-coordinator.ts:141-147, src/leasing/lease-acquisition-coordinator.ts:99
F17 daemon.update {query} is how the gateway, simlock update and the updater probe read a daemon src/gateway/worker-link.ts:370-381, src/cli/commands/update.ts:85-95, src/updater/probe.ts:55
F18 The coordinator's update state (#run) is what status.get, the gateway's worker view and daemon status show; a failed run emits daemon.update-failed and sets lastUpdateFailure src/daemon/update-coordinator.ts:124-130, :233-268
F19 The updater waits for running at version to, and stops a started daemon before a rollback src/updater/index.ts:111-114, :206-215
F20 Update calls run one at a time through the coordinator's call chain; #run is set only after npm view and checkInstall src/daemon/update-coordinator.ts:133-157, :189-193
Modules touched

Searches: UpdaterLaunch, parseUpdaterArgs, runUpdater, launcher.launch, daemon.stop, "stop" in src/cli/commands/daemon.ts, updateRoute, restart in website/.

  • src/contract/operations.ts, src/contract/protocol.ts: daemon.restart.
  • src/ports/updater-launcher.ts: a restart launch (--restart, no --from, --to).
  • src/updater/index.ts, src/updater/main.ts: parseUpdaterArgs takes --restart --pid [--gateway]; runUpdater in restart mode skips the install, the backup and the rollback.
  • src/daemon/update-coordinator.ts: restart(), on the same call chain as daemon.update (F20): refuses while an update is running, launches once, and keeps its own restarting flag apart from the update state (F18), so status.get, the worker view and daemon status show no update and a failed restart emits no daemon.update-failed. While the flag is set, a daemon.update that would start an update answers DAEMON_STOPPING; query answers as today (F17).
  • src/daemon/server.ts: a case "daemon.restart" in the socket router (F14).
  • src/ports/updater-launcher.test.ts: the restart argv (F15).
  • src/daemon/dispatcher.ts, src/gateway/dispatcher.ts: the daemon.restart handler (the gateway through its update option).
  • src/simlock-client/client.ts, src/simlock-client/types.ts, src/admin/index.ts: restartDaemon().
  • src/cli/commands/daemon.ts: restart.
  • src/http/admin-declarations.ts, src/http/app.ts: POST /v1/restart.
  • website/src/content/docs/docs/reference/cli.mdx, website/src/content/docs/docs/worker/running-the-daemon.mdx.
flowchart LR
  CLI["cli daemon *"] --> CL["client *"]
  H["http app *"] --> DI["dispatchers *"]
  CL --> DI
  DI --> UC["update-coordinator *"]
  UC --> L["ports updater-launcher *"]
  L -.spawns.-> UP["updater *"]
Contract and event changes

This PR bumps the protocol by one.

  • daemon.restart: admin, write; input {}; output { restarting: true }.
  • POST /v1/restart: no body; 202 with the output; 503 DAEMON_UPDATING.
  • daemon.update's shapes do not change; it may answer DAEMON_STOPPING, an error code every route already declares.
  • No new event, so no EVENTS.md entry: the restart shows as today's daemon.stopping and daemon.started entries.
Other code on the same state

Searches: users of the update coordinator's #run and of launcher.launch (1 launch site, src/daemon/update-coordinator.ts:215), writers of update-result.json and update-backup (src/updater/index.ts only), callers of daemon.stop (CLI daemon stop, daemon install, daemon uninstall, the updater).

  • An update waiting or installing: daemon.restart answers DAEMON_UPDATING; the update goes on.
  • A restart running, then a daemon.update that would start an update: DAEMON_STOPPING (the daemon is about to stop); daemon.update {query} answers as today, so the gateway, simlock update and the updater probe keep reading it (F17). An update call already in its version check when the restart arrives finishes first: both run on one call chain (F20). One updater process at a time.
  • A restart running, then a second daemon.restart: { restarting: true }, no second launch.
  • simlock daemon stop during a restart: stops the daemon; the updater's start brings it back. Said in the CLI reference.
  • A service manager (launchd, systemd): the updater's daemon start goes through it as an update's does (launcherFor); nothing new.
  • update-result.json and update-backup: a restart writes neither.
Failure modes
Call Outcome What happens Limit, counted from
launch the updater ok { restarting: true }; the daemon is stopped by it —
launch the updater throws daemon.restart answers INTERNAL with the reason; the daemon keeps running; a later call may try again —
updater daemon.stop no answer counted as stopped after the wait 30 s per call, from the call
updater wait for the pid still running SIGKILL the pid, as an update does 10 min, from daemon.stop
updater daemon start not running in time, at any version one stderr line restart failed: <reason> (lands in daemon.log), exit 1; nothing rolled back, nothing stopped 2 min, from the start
updater process exits non-zero before it stopped the daemon the coordinator clears its restarting flag and logs one warn line; no daemon.update-failed, no lastUpdateFailure; the next daemon.restart launches again —
Rules in play
  • ADR 0057 §5: "launches the updater process in a restart mode ... No install, no database copy, no rollback"; "During an update it answers DAEMON_UPDATING"; "A second call while one runs answers { restarting: true } again and starts nothing".
  • ADR 0042: one detached updater restarts the daemon; daemon.update's shape is frozen, so the restart is a new operation, not an option on daemon.update.
  • src/updater/AGENTS.md: main.ts imports everything statically; the restart mode keeps that.
  • src/contract/AGENTS.md, "Adding an operation": matrices, protocol bump, both dispatchers, client, CLI, HTTP, website.
  • Documentation rule 9: the CLI reference and the restart section of running the daemon change in this PR.
Tests

Seam: startDaemon with FakeUpdaterLauncher through daemon.dispatch (model: src/daemon/main.test.ts), the socket (model: src/daemon/server.test.ts), the route in src/http/app.test.ts, runUpdater (model: src/updater/index.test.ts:500-610), the launcher's argv (model: src/ports/updater-launcher.test.ts) and runCli (model: src/cli/index.test.ts).

  • An admin restarts the daemon with POST /v1/restart and the daemon launches the updater once in restart mode: first call 202 and one launch in restart mode with the pid and the role; a second call 202, no second launch; the same call over the daemon socket; during an update 503 DAEMON_UPDATING; a new daemon.update during a restart DAEMON_STOPPING, while daemon.update {query} answers as today; the launch throws: 500 INTERNAL, the daemon keeps running and a later call launches again; the updater exits non-zero before stopping the daemon: a later call launches again, no daemon.update-failed; an agent 403.
  • The updater in restart mode stops the daemon and starts it again, with no install: the launcher's arguments are --restart --pid <pid> plus --gateway for a gateway; starts (running at any version): exit 0, no npm call, no backup, no result file; does not start in 2 minutes: one stderr line, exit 1, no reinstall, nothing stopped; --gateway starts the gateway.
  • simlock daemon restart asks the running daemon to restart: running: prints Daemon restarting, --json {"status":"restarting"}; none running: fails as daemon stop does.

Done when

  • daemon.restart is in the role and effect matrices, and the protocol range is one higher.
  • parseUpdaterArgs(["--restart", "--pid", "42"]) parses; ["--restart", "--from", "1.0.0", "--to", "1.0.1", "--pid", "42"] throws.
  • A restart-mode run calls no npm.install and writes no update-backup or update-result.json.
  • simlock daemon --help lists restart; the CLI reference and running the daemon describe it.

Out of scope

  • Restarting a worker through the gateway.
  • Waiting for leases to end before a restart (leases survive it).
  • A restart event of its own.

Depends on

  • #1154

Written by an agent.

主要言語
TypeScript
スター
705
フォーク
40
平均マージ
12時間 9分
マージ済み PR(30日)
376

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

callstackincubator/simlock のほかの issue

callstackincubator/simlock の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。