Emulate platform migrations: migrate endpoint, console Migrate button, reboot, migration events

Emulates the Apify platform's Actor run migration so developers can test
their Actor's migration handling locally, with the same end-user experience
as the platform (reference: apify-core and apify-sdk-js):

- POST /actor-runtime/migrate/:runId (plus the /v2 alias): publishes a
  {"name":"migrating","data":{}} frame on the run's events websocket, stops
  the container 5s later, then restarts the same run - same run id,
  byte-identical env, same default storages, status RUNNING throughout,
  cumulative log, remaining (not full) timeout budget. Responds with the run
  object; a second call joins an open window. Finished run: 403 job-finished;
  READY/ABORTING: 400 invalid-request.
- Console run detail view: migrationCount/rebootCount fields and a Migrate
  button for RUNNING runs (console-local form POST into the same service
  path, cross-site-guarded like the console's other writes).
- POST /v2/actor-runs/:runId/reboot: the real platform endpoint the SDKs
  call on `migrating`; stops and restarts the container immediately, cancels
  an open migration window, increments stats.rebootCount.
- Run records carry the platform's restart-bookkeeping stats
  (migrationCount/rebootCount/restartCount/resurrectCount) and expose them
  on the run DTO.
- Graceful abort now sends the platform's frame pair: aborting plus
  persistState {isMigrating:false}; the periodic persistState stays
  SDK-generated and `migrating` is never paired with a server-sent one.
- An abort landing during a migration window or an in-flight restart wins:
  the migration stands down and the run ends ABORTED.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CzpRaq1BVPX272KpQmVwCT

Author: claude

CLAUDE.MD

@@ -30,6 +30,11 @@ Local Actor runtime is an Actor development tool for developing, running, and de
   hardcodes a `/v2`-suffixed base URL). From then on, edit locally, recompile locally (`tsc` or the
   language-appropriate equivalent), and `apify call` again - no `apify push`/build in between. Submitting
   `--body '""'` clears the registration. Dependency changes still need a real rebuild.
+- To test how an Actor handles platform migrations: while a run is `RUNNING`, call
+  `apify api POST /actor-runtime/migrate/<runId>`, or press the Migrate button on the run's console
+  detail page. The run gets the platform migration experience: a `migrating` event, its container
+  stopped a few seconds later, and a fresh container for the same run (same run id, env vars, and
+  storages, in-memory state gone). `POST /v2/actor-runs/<runId>/reboot` is also implemented.
 - If a call fails because this runtime doesn't have the Actor/run/build/storage id you're after, or
   doesn't implement that endpoint at all, you can opt in to having such calls transparently relayed to
   the real Apify platform instead of failing:

requirements/api.md

@@ -65,6 +65,7 @@
         - v2/actor-runs
         - v2/actor-runs/:runId
         - v2/actor-runs/:runId/abort
+        - v2/actor-runs/:runId/reboot
         - v2/actor-runs/:runId/log
     - Datasets
         - v2/datasets
@@ -145,7 +146,8 @@
   reject exactly the same inputs with the same outcomes.
 - **`GET /actor-runtime/events/:runId`** - a websocket upgrade, reachable at exactly this one path on
   the fixed API port (`system.md`). It carries the run's platform events: `systemInfo` once a second
-  (`actor-driver.md`), plus a one-off `aborting` frame under `?gracefully=` (below). Each frame is a
+  (`actor-driver.md`), a one-off `aborting`-plus-`persistState` pair under `?gracefully=` (below), and a
+  one-off `migrating` frame when a migration is triggered ("Migration emulation" below). Each frame is a
   single text message, `{"name": "...", "data": {...}}`.
     - The endpoint has no authentication. The run id in the path is the only thing it scopes on, and a
       connection only ever receives that run's own frames; one run never sees another's.
@@ -154,20 +156,53 @@
       as fatal to the Actor.
     - A connection to a live run stays open until the run ends, when the server closes it with `1000`. It
       is never dropped while healthy, except that a graceful runtime shutdown terminates every open
-      connection along with the rest of the server.
-    - `persistState` is never sent over this channel; both SDKs generate it themselves.
+      connection along with the rest of the server. A migration/reboot restart is not the run ending: the
+      restarted container reconnects to the same path.
+    - The _periodic_ `persistState` is never sent over this channel; both SDKs generate it themselves.
+      The server sends `persistState` exactly once per graceful abort, alongside `aborting` (matching the
+      platform), and never alongside `migrating` (the SDKs synthesize that one).
 
 ## Graceful abort (`?gracefully=`)
 
 - `POST /v2/actor-runs/:runId/abort` accepts an optional `?gracefully=` boolean.
 - Omitted or `false`: the run aborts immediately.
-- `true` on a running run: the record moves to `ABORTING` at once, an `aborting` frame with an empty
-  payload is published on the run's events channel, and the container is stopped 30 seconds later. The
-  request stays open until then.
+- `true` on a running run: the record moves to `ABORTING` at once, an `aborting` frame plus a
+  `persistState {"isMigrating": false}` frame (in that order, matching the platform) are published on
+  the run's events channel, and the container is stopped 30 seconds later. The request stays open until
+  then.
 - `true` on a run with no container (still `READY`, or already terminal): behaves as if omitted.
 - A second abort arriving during an open window: another `?gracefully=true` joins that window and neither
   restarts it nor stops the container early; a non-graceful one escalates and stops the container at once.
 
+## Migration emulation (`POST /actor-runtime/migrate/:runId`) and reboot
+
+A platform migration is not a run status: the run stays `RUNNING` while its container is killed and a
+new one starts for the same run - same run id, env vars, and default storages, in-memory state gone.
+This runtime emulates that observable experience on demand:
+
+- **`POST /actor-runtime/migrate/:runId`** (also at `/v2/actor-runtime/migrate/:runId`) - authenticated
+  like the rest of this namespace, scoped to the caller's own runs. The console's run detail view
+  exposes the same trigger as a Migrate button (`console.md`).
+    - Publishes a `migrating` frame (empty payload) on the run's events channel immediately, stops the
+      container 5 seconds later (the platform promises only "a few seconds"), then restarts the same
+      run. Status stays `RUNNING`; `startedAt`, `finishedAt`, `exitCode`, the default storage ids, and
+      the container env are unchanged. `stats.migrationCount` increments once per performed stop.
+    - Responds immediately with the run object (same shape as `abort`/`reboot`). A second call during
+      the open window joins it: same response, no second frame or window.
+    - Errors: unknown/foreign run `404` `record-not-found`; finished run `403` `job-finished`;
+      `READY`/`ABORTING` `400` `invalid-request`.
+    - The timeout budget is per run, not per container: a restarted container gets only the remaining
+      `timeoutSecs`.
+    - An abort (graceful or hard) landing during the window or restart wins: the run ends `ABORTED`,
+      never restarted.
+- **`POST /v2/actor-runs/:runId/reboot`** - the real platform endpoint the SDKs call from their default
+  `migrating` handler. Stops and restarts the run's container immediately (no warning frame), cancels an
+  open migration window, and increments `stats.rebootCount`. A finished run is `403` `job-finished`; a
+  non-terminal run with no container (`READY`, `ABORTING`) gets the count bump but no restart.
+- The run object's `stats` carries `migrationCount`, `rebootCount`, `restartCount`, and `resurrectCount`
+  (the latter two always `0` here), initialized to `0` at run creation like the platform.
+- The run's log is cumulative across restarts, with a one-line marker between the incarnations' output.
+
 ## Upstream fallback (opt-in, off by default, all HTTP methods)
 
 - Two independent booleans, `fallbackUnimplementedEnabled` and `fallbackNotFoundEnabled`, gate whether

requirements/console.md

@@ -6,9 +6,9 @@
 - The console has no login of its own, so with multiple users it lists and shows every user's objects
   rather than scoping to one - the API's own endpoints stay strictly scoped to the calling token's user
   (`storage.md`'s "Users" section).
-- The console is unauthenticated. Every route is a read except the console's only two writes: the
-  dev-folder form and the Settings form (both below).
-- Both of those writes reject a submission that identifies itself as cross-site (via the
+- The console is unauthenticated. Every route is a read except the console's only three writes: the
+  dev-folder form, the run detail view's Migrate button, and the Settings form (all below).
+- All three of those writes reject a submission that identifies itself as cross-site (via the
   `Sec-Fetch-Site` header) with a plain `403`; a submission that does not is unaffected.
 - There are three types of objects: key-value store, dataset, request queue.
     - For each object type there must be exactly one widget for inspection.
@@ -50,6 +50,16 @@
 - A submission that fails validation redirects back to the same detail page with the classified error
   message shown inline, never swallowed by the redirect.
 
+## Migrate button (run detail view)
+
+- The run detail view shows the run's `migrationCount` and `rebootCount`, and a "Migration" section:
+  for a `RUNNING` run, a Migrate button that triggers the same emulated migration as
+  `POST /actor-runtime/migrate/:runId` (`api.md`); for any other status, a note that only a `RUNNING`
+  run can be migrated, with no button.
+- Pressing the button returns to the same detail page while the migration proceeds in the background.
+  A press that raced the run ending shows the reason inline, never swallowed by the redirect.
+- Like the dev-folder form, the button writes cross-user - the console's usual unauthenticated model.
+
 ## Settings page
 
 - Every page's header navigation includes a link to `/settings`, the one page for the upstream API

src/api/dto/actors.ts

@@ -77,7 +77,13 @@ export function runDto(run: RunRecord) {
 		},
 		generalAccess: run.generalAccess ?? 'FOLLOW_USER_SETTING',
 		meta: run.meta,
-		stats: {},
+		// The platform's restart-bookkeeping stats (see `RunRecord.stats`); zeros backfill old fixtures.
+		stats: {
+			migrationCount: run.stats?.migrationCount ?? 0,
+			rebootCount: run.stats?.rebootCount ?? 0,
+			restartCount: run.stats?.restartCount ?? 0,
+			resurrectCount: run.stats?.resurrectCount ?? 0,
+		},
 		statusMessage: run.statusMessage,
 		containerUrl: undefined,
 	};

src/api/errors.ts

@@ -35,6 +35,12 @@ export function cannotRemoveRunningRun(): ApiError {
 	);
 }
 
+/** Matches the real platform's rejection of reboot/migrate on a finished run (`apify-core`'s
+ * `errors.actor.jobAlreadyFinished()`). */
+export function jobAlreadyFinished(): ApiError {
+	return new ApiError(403, 'job-finished', 'Actor job is already finished.');
+}
+
 /**
  * Matches the real Apify platform exactly: `DELETE /v2/actor-builds/:buildId` on a non-terminal build
  * is rejected rather than aborted-then-deleted (`apify-core`'s `errors.api.deletingUnfinishedBuild()`,

src/api/routes/migrate.ts

@@ -0,0 +1,41 @@
+/**
+ * `POST /actor-runtime/migrate/:runId` - triggers an emulated migration of one run
+ * (`requirements/api.md`, "Migration emulation"). Lives in the local-runtime-only namespace because the
+ * real platform has no migrate API. Ownership-scoped; responds with the run object (still `RUNNING`)
+ * while the migration proceeds in the background. Only a `RUNNING` run can migrate: finished is `403`
+ * `job-finished`, `READY`/`ABORTING` is `400` `invalid-request`.
+ */
+import type { Router } from 'express';
+
+import { requireUser } from '../auth.js';
+import { sendData } from '../envelope.js';
+import { invalidRequest, jobAlreadyFinished, recordNotFound } from '../errors.js';
+import { h } from '../handler.js';
+import { isTerminalJobStatus } from '../../services/job-status.js';
+import { getOwnedRun } from '../../services/runs.js';
+import { migrateRun } from '../../services/migrations.js';
+import { runDto } from '../dto/actors.js';
+import type { ApiServerDeps } from '../server.js';
+
+/** Mounts the `/migrate/:runId` route, matching `mountDevFolder`'s convention. */
+export function mountMigrate(router: Router, deps: ApiServerDeps): void {
+	router.post(
+		'/migrate/:runId',
+		h(async (req, res) => {
+			const user = requireUser(req);
+			const run = await getOwnedRun(user.id, req.params.runId as string);
+			if (!run) throw recordNotFound();
+			if (isTerminalJobStatus(run.status)) throw jobAlreadyFinished();
+
+			const result = await migrateRun(deps.driver, run);
+			if (result === 'not-running') {
+				// Non-terminal but without a container to migrate (READY, ABORTING).
+				throw invalidRequest(`Only a RUNNING run can be migrated (current status: ${run.status})`);
+			}
+
+			// Read back after the migration started, like abort/reboot return the post-write record.
+			const current = await getOwnedRun(user.id, run.id);
+			sendData(res, runDto(current ?? run));
+		}),
+	);
+}

src/api/routes/runs.ts

@@ -3,9 +3,10 @@ import type { Router } from 'express';
 import { requireUser } from '../auth.js';
 
 import { paginate, sendData, sortByTimestamp } from '../envelope.js';
-import { cannotRemoveRunningRun, recordNotFound } from '../errors.js';
+import { cannotRemoveRunningRun, jobAlreadyFinished, recordNotFound } from '../errors.js';
 import { h, paginationParams, queryBoolean } from '../handler.js';
 import { abortRun, deleteRun, getOwnedRun, listOwnedRuns } from '../../services/runs.js';
+import { rebootRun } from '../../services/migrations.js';
 import { isTerminalJobStatus } from '../../services/job-status.js';
 import { runDto } from '../dto/actors.js';
 import type { ApiServerDeps } from '../server.js';
@@ -61,6 +62,19 @@ export function mountRuns(router: Router, deps: ApiServerDeps): void {
 		}),
 	);
 
+	router.post(
+		'/actor-runs/:runId/reboot',
+		h(async (req, res) => {
+			const run = await getOwnedRun(requireUser(req).id, req.params.runId as string);
+			if (!run) throw recordNotFound();
+			// Mirrors `apify-core`'s reboot route: a finished run is rejected 403 job-finished; anything
+			// non-terminal is accepted. The SDKs call this endpoint from their default `migrating` handler.
+			if (isTerminalJobStatus(run.status)) throw jobAlreadyFinished();
+			const updated = await rebootRun(deps.driver, run);
+			sendData(res, runDto(updated ?? run));
+		}),
+	);
+
 	router.get(
 		'/actor-runs/:runId/log',
 		h(async (req, res) => serveLog(req, res, req.params.runId as string)),

src/api/server.ts

@@ -14,6 +14,7 @@ import { mountRuns } from './routes/runs.js';
 import { mountLogs } from './routes/logs.js';
 import { mountRunStorageAliases } from './routes/run-storage-aliases.js';
 import { mountDevFolder } from './routes/dev-folder.js';
+import { mountMigrate } from './routes/migrate.js';
 import { mountApiFallback } from './routes/api-fallback.js';
 import { attemptFallback, type LocalError } from '../services/api-fallback.js';
 import type { Driver } from '../driver/types.js';
@@ -42,12 +43,13 @@ export function createApiServer(deps: ApiServerDeps): Express {
 	// `/actor-runtime/*` - a deliberately non-Apify, local-runtime-only namespace (`api.md`), registered
 	// before the `v2` router (and its own `auth()`) below entirely, so it gets its own sub-router with its
 	// own `auth()` rather than inheriting `v2.use(auth())`. Registered once here, shared by every route
-	// module mounted on this router (`mountDevFolder`, `mountApiFallback`) rather than each registering
+	// module mounted on this router (`mountDevFolder`, `mountMigrate`, `mountApiFallback`) rather than each registering
 	// its own - they are the same router instance, so a second registration would just run `auth()`
 	// twice per request for no benefit.
 	const actorRuntime = express.Router();
 	actorRuntime.use(auth());
 	mountDevFolder(actorRuntime, deps);
+	mountMigrate(actorRuntime, deps);
 	mountApiFallback(actorRuntime);
 	app.use('/actor-runtime', actorRuntime);
 	// Also served at `/v2/actor-runtime/*` - the *same* router instance, no duplicated route logic - solely

src/api/spec-table.ts

@@ -91,6 +91,7 @@ export const SPEC_TABLE: SpecTableEntry[] = [
 	pathTemplate('GET', 'v2/actor-runs/:runId', true),
 	pathTemplate('DELETE', 'v2/actor-runs/:runId', true),
 	pathTemplate('POST', 'v2/actor-runs/:runId/abort', true),
+	pathTemplate('POST', 'v2/actor-runs/:runId/reboot', true),
 	pathTemplate('GET', 'v2/actor-runs/:runId/log', true),
 
 	// --- Datasets ---