anbaric 1.58.3 → 1.60.0

package/docs/api/cli.md

@@ -23,11 +23,19 @@ project — they walk up to the nearest `package.json`.
 | --- | --- |
 | `anbaric apps` | List deployed apps (name, status, port). |
 | `anbaric app configure` | Create or update `.anbaric/app-config.json` (`name`, `internalPort`). |
-| `anbaric app deploy` | Deploy the app and wait until it is live (prompts before replacing a running one). |
+| `anbaric app deploy` | Deploy the app and wait until it is live (prompts before replacing a running one). A running version is drained first — see below. |
 | `anbaric app update` | Deploy, replacing a running app **without** prompting. |
-| `anbaric app status [name]` | Show deploy state, liveness, and recent logs. |
+| `anbaric app status [name]` | Show deploy state (`building`, `draining`, `running`, `failed`, `stopped`), liveness, and recent logs. |
 | `anbaric app tail [name]` | Stream the app's runtime logs. |
-| `anbaric app tear-down [name]` | Stop and remove the app (prompts unless `--yes`). |
+| `anbaric app tear-down [name]` | Stop and remove the app (prompts unless `--yes`). A running app is drained first. |
+
+**Draining.** Replacing or removing an app never cuts a job off mid-step. The
+running version is told to stop taking on new work — messages the platform
+offers it are refused and wait for the new version — and given up to **five
+minutes** to finish the steps it has in hand; `app deploy`, `app update` and
+`app tear-down` show `draining (finishing n steps in flight)` while it does.
+Only then is it stopped. A step still running at the deadline is stopped
+regardless: once an app has taken a job on, what becomes of it is the app's.
 
 The name is optional, because an `app` command is normally about the app you
 are standing in: the CLI walks up from the working directory to the nearest
@@ -67,7 +75,7 @@ ask for, so the CLI runs unattended in scripts and CI.
 | `--name <name>` | `app configure`/`deploy`/`update` | App name; prompts if omitted (suggested from `package.json`). |
 | `--port <port>` | `app configure`/`deploy`/`update` | Internal port (1–65535); prompts if omitted. |
 | `--yes` | `app deploy`, `app tear-down`, `jobs kill-old` | Skip confirmation. (`app update` implies it.) |
-| `--state <state>`, `--status <status>`, `--app <app>` | `jobs list` | Only jobs in that state / with that status (`active`, `Awaiting input`, `Failed`) / belonging to that app. |
+| `--state <state>`, `--status <status>`, `--app <app>` | `jobs list` | Only jobs in that state / with that status (`active`, `Awaiting input`, `Failed`, `Stalled`) / belonging to that app. |
 | `--page <n>`, `--page-size <n>` | `jobs list` | Which page (from 0) and how many per page (default 100). |
 | `--oldest` | `jobs list` | Oldest first instead of newest. |
 | `--help`, `-h` | all | Print usage. |

package/docs/api/state-machine.md

@@ -156,6 +156,7 @@ readonly id : string
 name : string
 description : string
 actor : Actor
+longRunning : boolean = false
 
 constructor(name : string, actor : Actor, description : string = "", id? : string)
 
@@ -177,6 +178,10 @@ sendWelcome.run = async (job) => new Map([["welcomeSent", true]]);
 - **`run`** — return a `Map` of the properties to change. Only properties in the
   machine's schema are applied; others are ignored with a warning. Only the
   properties that actually changed are written back.
+- **`longRunning`** — set it on a step that takes minutes rather than seconds.
+  Nothing constrains how long a step may take either way; what this changes is
+  that the job is [heartbeated](#stalled-jobs) while the step runs, so a step
+  that dies is visible rather than silent.
 
 See [Actions and actors](../features/actions-and-actors.md).
 
@@ -269,22 +274,24 @@ One instance moving through a machine. You mostly **read** jobs (returned by
 ```ts
 readonly id : string
 readonly state : string
-readonly properties : Map<string, any>
+readonly properties : JobProperties   // read on demand; see below
 readonly workflowId? : string     // the machine's id …
 readonly appId? : string          // … and the app it runs in (its composite identity)
 readonly startedAt : Date
 readonly startedBy : string
 readonly lastUpdated : Date
 readonly killed : boolean
-status : string                  // "active", "Awaiting input" or "Failed"
+status : string                  // "active", "Awaiting input", "Failed" or "Stalled"
 waitingFor? : string
 awaitMetadata? : WaitForInput     // present while parked on an Await
+heartbeatAt? : Date               // when a long-running step last said it was going
 
 namespace Job {
     const Status = {
         ACTIVE: "active",
         AWAITING_INPUT: "Awaiting input",
         FAILED: "Failed",
+        STALLED: "Stalled",
     } as const
 }
 ```
@@ -296,6 +303,23 @@ A job whose action threw is `FAILED`, with the reason in its audit trail. It
 stays in its state rather than transitioning, and an update that moves it on
 returns it to `ACTIVE` — so a failure is recoverable, not terminal.
 
+### Stalled jobs
+
+While an action marked [`longRunning`](#action) runs, the machine heartbeats
+its job once a minute. If those heartbeats stop for five minutes — the process
+running the step died, in a crash or a restart — the job is marked `STALLED`.
+
+That is all that happens. The platform does not re-run the step and does not
+requeue the job: only the app knows what a half-finished long step already did,
+so replaying it is not the platform's call. A stalled job is a job somebody
+should look at — list them with `anbaric jobs list --status Stalled` — and
+resume, by updating it or setting its state, if that is the right thing to do.
+A heartbeat arriving from a job already marked stalled returns it to `ACTIVE`,
+so a step that was merely slower than the sweep corrects itself.
+
+Ordinary actions are not heartbeated: they are expected to be short, and the
+[drain](cli.md#apps) on deploy is what protects them.
+
 ### `JobProperties`
 
 `job.properties` is not a `Map`: it reads on demand, so a job may hold a great
@@ -339,7 +363,7 @@ type JobPersistence.Query = {
     workflowId? : string,
     appId? : string,
     state? : string,
-    status? : string,            // "active", "Awaiting input", "Failed"
+    status? : string,            // "active", "Awaiting input", "Failed", "Stalled"
     killed? : boolean,
     order? : "oldest" | "newest" // by when the job was started; oldest by default
 }

package/docs/api/web.md

@@ -109,7 +109,7 @@ job was started: `oldest` (the default, for compatibility) or `newest`.
 The other parameters are filters, applied on the platform **before** paging, so
 a filter sees every job and page numbers count matching jobs only. All are
 optional and combine with AND: `workflowId` (the state machine), `appId`,
-`state`, `status` (`active`, `Awaiting input`, `Failed`) and `killed`
+`state`, `status` (`active`, `Awaiting input`, `Failed`, `Stalled`) and `killed`
 (`true`/`false`).
 
 In code the same listing is `JobPersistenceFactory.instance().list(actor,

package/docs/features/actions-and-actors.md

@@ -41,6 +41,28 @@ the example above, and why a transition's guard may be too. Afterwards the
 machine writes back only the properties that changed — never the ones the pass
 read, let alone the ones it never loaded.
 
+### Say when a step is long-running
+
+Nothing limits how long an action may take — a mailbox import that runs for
+twenty minutes is a perfectly ordinary action. But a step that long is worth
+declaring:
+
+```ts
+importMailbox.longRunning = true;
+```
+
+While it runs, the machine tells the platform once a minute that the job is
+still going. If that stops for five minutes — the process died, in a crash or
+a restart — the job is marked **`Stalled`**. Nothing else happens: the platform
+never re-runs a long step on its own, because only your app knows what a
+half-finished one already did. A stalled job is one for a person to look at
+(`anbaric jobs list --status Stalled`) and resume if it should be. A heartbeat
+from a stalled job puts it back to `active`, so a step slower than the check
+corrects itself.
+
+Leave it off for ordinary steps: they are short, and a
+[drain](../api/cli.md#apps) on deploy is what keeps those from being cut off.
+
 ### Prewarm what a state needs
 
 Each property read that wasn't already held is a fetch. A state can name what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.58.3",
+  "version": "1.60.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.58.3",
-    "anbaric-data-store": "^1.58.3",
-    "anbaric-state-machine": "^1.58.3",
-    "anbaric-tsapi": "^1.58.3"
+    "anbaric-impl-cloud": "^1.60.0",
+    "anbaric-data-store": "^1.60.0",
+    "anbaric-state-machine": "^1.60.0",
+    "anbaric-tsapi": "^1.60.0"
   }
 }