anbaric 1.59.0 → 1.61.0

package/docs/api/cli.md

@@ -75,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/docs/features/serving-a-web-ui.md

@@ -46,12 +46,12 @@ unrouted absolute path that arrives with a `Referer` from your app is redirected
 back to `/app/<name>/…` (a `307`, so form POSTs keep their body). So ordinary
 absolute links followed from a page of your app just work.
 
-## Your app's own hostname
+## Your app's own address
 
-Every app also answers on a hostname of its own:
+Every app answers on an address of its own:
 
 ```
-https://<app>--<tenant>.<platform domain>
+https://<address>.<platform domain>
 ```
 
 There your app is at the root, exactly where it was when you ran it locally, so
@@ -59,10 +59,29 @@ absolute paths, `fetch("/api/…")` and anything else that assumes the root work
 without being rewritten. This is the address to share and the one to prefer; the
 `/app/<name>` form below stays available and unchanged.
 
-The tenant is part of the name because two tenants may each have a `hello-world`.
-A double hyphen separates the two, so an app name may not contain one, and the
-app and tenant together must fit the 63 characters a hostname label allows. A
-deploy that would break either rule is refused with the reason.
+`anbaric app deploy` prints the address, and the console shows it next to the app
+on the **Manage apps** page.
+
+### How an address is chosen
+
+An address is one label under the platform's domain, so it has to be unique
+across every customer, not just yours. When an app is first deployed it is given
+its own name if that name is free. If it is not, a word is added — `invoices`
+becomes something like `invoices-walnut` — and if even that is crowded, a short
+number. A handful of names are reserved and never handed out.
+
+Your app's name is unaffected by any of this. The name is what you deploy,
+reference and tear down by; the address is only where it answers.
+
+### Changing an address
+
+A builder can set an app's address on the **Manage apps** page in the console. An
+address someone else already holds is refused, and the old address stops working
+as soon as the new one is saved — so change it before you share it, not after.
+
+An address lasts as long as the app. Tearing an app down frees its address for
+anyone to take, including another customer, so a torn-down app's links should be
+treated as gone for good.
 
 ## Under /app/&lt;name&gt;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.59.0",
+  "version": "1.61.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.59.0",
-    "anbaric-data-store": "^1.59.0",
-    "anbaric-state-machine": "^1.59.0",
-    "anbaric-tsapi": "^1.59.0"
+    "anbaric-impl-cloud": "^1.61.0",
+    "anbaric-data-store": "^1.61.0",
+    "anbaric-state-machine": "^1.61.0",
+    "anbaric-tsapi": "^1.61.0"
   }
 }