@electron-stagewright/host-supervisor 0.1.0 → 0.2.0

package/README.md

@@ -88,6 +88,18 @@ serveHost<DbOps, { key: string }>({
 })
 ```
 
+In a main process bundled as CommonJS (Vite, webpack, esbuild), hand the transport Electron's
+`fork` instead of letting it load Electron itself:
+
+```ts
+import { utilityProcess } from 'electron'
+
+utilityProcessTransport({ entry, serviceName: 'Database', fork: utilityProcess.fork })
+```
+
+The package has no dependency on Electron, not even a peer, so it adds nothing Electron-related to
+a production dependency or license report.
+
 `serveHost` finds its port: Electron's `process.parentPort` in a utility process, the
 `worker_threads` parent port in a worker. The entry never imports Electron.
 
@@ -100,18 +112,47 @@ serveHost<DbOps, { key: string }>({
   timeout or an abort rejects the call and aborts `context.signal` in the handler, which receives
   it after the caller's arguments. Past `maxPending` calls and open streams, a call fails with
   `HOST_QUEUE_FULL`.
+- **Abort and settle.** By default an abort rejects with `HOST_CALL_ABORTED` at once, and the
+  host's late answer is dropped, so the caller cannot tell whether the work stopped. Set
+  `limits.abortGraceMs` (or `abortGraceMs` per call) to forward the abort and wait: the call then
+  settles with the host's own answer (the handler's abort error, or its value if it finished
+  anyway), or fails with `HOST_ABORT_UNSETTLED` once the grace passes, which means the work may
+  still be running and the host is a candidate for `kill()`. The call stays counted against
+  `maxPending` until it settles. A call the host never received still fails at once, and streams
+  always close at once.
 - **Streams.** One item per pull; nothing is produced ahead. Leaving a `for await` early closes the
   producer in the host.
 - **Exits.** A call in flight when the host exits fails with `HOST_EXITED`; its `cause` is the
   host's uncaught error when the host could report it. It is never resent. `onExit` then returns
   `fatal` (the default), `on-demand` or `restart`. `restartPolicy()` restarts up to 3 times in 10
   minutes with 0.5, 2 and 8 s of backoff, and a restart whose start fails counts.
+  Calls made while a restart is pending (during its backoff or its start) wait for the new host,
+  within their timeout.
+- **Started.** `onStarted` runs after every successful start with `{ info, launches, restart }`;
+  `restart` is `{ exit, attempt }` when the host replaces one that exited on its own (`attempt`
+  is 1 for the first try after that exit and grows with each failed one), null otherwise.
 - **Stop.** `stop()` refuses new calls, lets accepted ones answer, runs the host's `stop`, and
   terminates the host after `graceMs`. It rejects with `HOST_STOP_TIMEOUT` or
   `HOST_STOP_INCOMPLETE` when the host did not close cleanly, so code that is about to touch its
   files can stop. `kill()` terminates without draining. `close()` stops and refuses every later
   call. After `stop()` or `kill()` the next call starts a new host, once the old one has exited or
   `retireWaitMs` has passed.
+- **Pause.** A handle captured anywhere in the app starts a host on its next call. When the host's
+  files must stay closed (a backup, a restore, a key rotation), `await host.pause()` stops the host
+  like `stop()` and starts none until `host.resume()`. Calls made meanwhile wait (within their
+  timeout and `maxPending`), or fail with `HOST_PAUSED` under `pause({ calls: 'reject' })`. A pause
+  whose stop fails rejects like `stop()` but stays paused, so the caller can decide before touching
+  the files:
+
+  ```ts
+  await host.pause()
+  try {
+    await swapDatabaseFiles()
+  } finally {
+    host.resume()
+  }
+  ```
+
 - **Memory.** Worker `resourceLimits` usually end only the worker, reported as `out-of-memory`;
   one allocation far past the cap can still abort the whole process, so use `utilityProcess` when
   the app must survive its host. A `utilityProcess` that runs out of heap is reported as a
@@ -121,11 +162,80 @@ serveHost<DbOps, { key: string }>({
   the young generation to `maxOldGenerationSizeMb`. An `onStats` that throws or rejects becomes a
   process warning.
 
-Errors keep their message and a code matching `^[A-Z][A-Z0-9_]{1,80}$`; stacks and object graphs
-never cross. The supervisor's own failures are `HostError` with a code from `HOST_ERROR_CODES`.
+## Errors
+
+An error crosses as its name, its message and a code matching `^[A-Z][A-Z0-9_]{1,80}$`; stacks and
+object graphs cross only as the detail a host picks with `errors.data`. The supervisor's own failures are `HostError` with a code from
+`HOST_ERROR_CODES`, and a host can never make an application error pass for one.
+
+When failures carry structured detail, say so on both sides instead of wrapping every answer:
+
+```ts
+// db-host.js
+serveHost<DbOps>({
+  // ...
+  errors: {
+    codePattern: /^[a-z][a-z-]{1,40}$/, // also the app's own codes, such as `engine-gone`
+    data: (error) =>
+      error instanceof EditError ? { step: error.step, fix: error.fix } : undefined,
+  },
+})
+
+// main process
+createHost<DbOps>({
+  // ...
+  errors: {
+    revive: (e) => (e.name === 'EditError' ? new EditError(e.message, e.code, e.data) : undefined),
+  },
+})
+```
+
+`data` must survive structured clone; when it does not, the error still crosses without it.
+Without `revive`, the rebuilt `Error` carries `name`, `message`, `code` and `data`.
+
+## Start info
+
+A host can hand back what it learned while starting, such as the port its server bound:
+
+```ts
+serveHost<ServerOps, Config, { url: string }>({
+  operations: ['ping'],
+  start: async (config, { setInfo }) => {
+    const server = await listen(config)
+    setInfo({ url: server.url })
+    return { ping: () => 'pong' }
+  },
+})
+
+const host = createHost<ServerOps, Config, { url: string }>({/* ... */})
+const { url } = (await host.start())!
+host.info // the running host's info, or undefined while none runs
+```
+
+Call `setInfo` before `start` resolves; later calls throw. Info that cannot be cloned fails the start.
+
+## Exits
+
+`onExit` and `restartPolicy({ isFatal })` receive a `HostExit`, not an `Error`:
+
+| Field          | Meaning                                                                |
+| -------------- | ---------------------------------------------------------------------- |
+| `kind`         | `crash`, `out-of-memory` or `start-failed`                             |
+| `reason`       | `uncaught`, `out-of-memory`, `runtime-fatal`, `exit` or `start-failed` |
+| `error`        | Always an `Error`: the host's uncaught error when it reported one      |
+| `code`         | The exit code, or null                                                 |
+| `uptimeMs`     | Time since `started`, or null when the host never started              |
+| `pendingCalls` | Calls the exit rejected with `HOST_EXITED`                             |
+| `lastStats`    | The last `HostStats` the host sent, or null                            |
+
+`uncaught` means the host reported an uncaught exception (or a worker thread threw one).
+`runtime-fatal` is Electron's utility process `error` event. `exit` is an end with no reported
+cause: `process.exit`, a native crash, or a kill from outside.
 
 ## Platform notes
 
+- The utility process transport needs Electron 42 or later. The package declares no Electron
+  dependency; it uses the app's own.
 - `terminate()` cannot interrupt a synchronous native call: the grace period is honoured between
   calls, not inside one.
 - Large results should stream. `postMessage` copies by structured clone, and Electron's V8 memory

package/dist/contract.d.ts

@@ -32,6 +32,8 @@ export interface ChannelExit {
     readonly error?: Error;
     /** The runtime ended the host for exceeding its memory limit. */
     readonly outOfMemory?: boolean;
+    /** The runtime hit an error it cannot continue from (Electron's utility process `error` event). */
+    readonly runtimeFatal?: boolean;
 }
 /** One running host, as seen from the supervisor. */
 export interface HostChannel {

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEtD,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,KAAK,UAAU,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,IAAI,MAAM,SAAS,CAAC,CAAC,QAAQ,CAAC,GACtE,KAAK,GACL,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GACnB,IAAI,GACJ,KAAK,CAAA;AAEX;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,GAAG,IAAI;KACzB,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GAC1D,UAAU,CAAC,CAAC,CAAC,SAAS,IAAI,GACxB,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,GACjD,GAAG,CAAC,CAAC,CAAC,GACN,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,GACjE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,gDAAgD,GACxE,KAAK;CACV,CAAA;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAA;AAE3E,mCAAmC;AACnC,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI;KAC9B,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CACpF,CAAC,MAAM,GAAG,CAAC,GACV,MAAM,CAAA;AAER,uEAAuE;AACvE,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI;KAChC,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CAC1F,CAAC,MAAM,GAAG,CAAC,GACV,MAAM,CAAA;AAER,yFAAyF;AACzF,MAAM,MAAM,QAAQ,CAAC,GAAG,IAAI;KACzB,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GACnE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChD,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAChE,KAAK;CACZ,CAAA;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACtC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IACrD,0DAA0D;IAC1D,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAA;IACnD,kEAAkE;IAClE,IAAI,IAAI,IAAI,CAAA;CACb;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,MAAM,IAAI,WAAW,CAAA;CACtB"}

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** The supervisor's own failures. Application errors keep their own code when it is well formed. */
-export declare const HOST_ERROR_CODES: readonly ["HOST_STOPPED", "HOST_EXITED", "HOST_START_FAILED", "HOST_FATAL", "HOST_CALL_TIMEOUT", "HOST_CALL_ABORTED", "HOST_QUEUE_FULL", "HOST_OPERATION_REJECTED", "HOST_STOP_TIMEOUT", "HOST_STOP_INCOMPLETE"];
+export declare const HOST_ERROR_CODES: readonly ["HOST_STOPPED", "HOST_EXITED", "HOST_START_FAILED", "HOST_FATAL", "HOST_CALL_TIMEOUT", "HOST_CALL_ABORTED", "HOST_ABORT_UNSETTLED", "HOST_PAUSED", "HOST_QUEUE_FULL", "HOST_OPERATION_REJECTED", "HOST_STOP_TIMEOUT", "HOST_STOP_INCOMPLETE"];
 export type HostErrorCode = (typeof HOST_ERROR_CODES)[number];
 export declare class HostError extends Error {
     readonly code: HostErrorCode;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,kNAmBnB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;gBAEhB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,KAAK,IAAI,SAAS,CAEpF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,yPAwBnB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;gBAEhB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,KAAK,IAAI,SAAS,CAEpF"}

package/dist/errors.js

@@ -9,7 +9,12 @@ export const HOST_ERROR_CODES = [
     /** `onExit` chose `fatal`; the host never starts again. */
     'HOST_FATAL',
     'HOST_CALL_TIMEOUT',
+    /** The call was aborted before the host settled it; the host may still be working on it. */
     'HOST_CALL_ABORTED',
+    /** With `abortGraceMs`: the host did not settle an aborted call within the grace period. */
+    'HOST_ABORT_UNSETTLED',
+    /** `pause({ calls: 'reject' })` is in effect. */
+    'HOST_PAUSED',
     /** More than `maxPending` calls were waiting. */
     'HOST_QUEUE_FULL',
     /** The host refused an operation outside its closed list. */

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,iFAAiF;IACjF,cAAc;IACd,4EAA4E;IAC5E,aAAa;IACb,oEAAoE;IACpE,mBAAmB;IACnB,2DAA2D;IAC3D,YAAY;IACZ,mBAAmB;IACnB,mBAAmB;IACnB,iDAAiD;IACjD,iBAAiB;IACjB,6DAA6D;IAC7D,yBAAyB;IACzB,kFAAkF;IAClF,mBAAmB;IACnB,kFAAkF;IAClF,sBAAsB;CACd,CAAA;AAIV,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAe;IAE5B,YAAY,IAAmB,EAAE,OAAe,EAAE,OAA6B;QAC7E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAAoB;IAC9D,OAAO,KAAK,YAAY,SAAS,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAClF,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,iFAAiF;IACjF,cAAc;IACd,4EAA4E;IAC5E,aAAa;IACb,oEAAoE;IACpE,mBAAmB;IACnB,2DAA2D;IAC3D,YAAY;IACZ,mBAAmB;IACnB,4FAA4F;IAC5F,mBAAmB;IACnB,4FAA4F;IAC5F,sBAAsB;IACtB,iDAAiD;IACjD,aAAa;IACb,iDAAiD;IACjD,iBAAiB;IACjB,6DAA6D;IAC7D,yBAAyB;IACzB,kFAAkF;IAClF,mBAAmB;IACnB,kFAAkF;IAClF,sBAAsB;CACd,CAAA;AAIV,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAe;IAE5B,YAAY,IAAmB,EAAE,OAAe,EAAE,OAA6B;QAC7E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAAoB;IAC9D,OAAO,KAAK,YAAY,SAAS,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAClF,CAAC"}

package/dist/host.d.ts

@@ -3,14 +3,25 @@
  * when the host exits on its own.
  */
 import type { ArgsOf, CallOperation, Contract, HostTransport, StreamOperation } from './contract.js';
-import { type HostStats } from './protocol.js';
+import { type HostStats, type SerializedError } from './protocol.js';
 export declare const DEFAULT_STOP_GRACE_MS = 10000;
 export declare const DEFAULT_RETIRE_WAIT_MS = 5000;
-export type HostState = 'idle' | 'starting' | 'running' | 'restarting' | 'stopping' | 'fatal' | 'closed';
+export type HostState = 'idle' | 'starting' | 'running' | 'restarting' | 'stopping' | 'paused' | 'fatal' | 'closed';
+/**
+ * Why a host ended:
+ * - `out-of-memory`: the runtime ended it at its heap limit (worker threads only).
+ * - `uncaught`: the host reported an uncaught exception, which is `error`.
+ * - `runtime-fatal`: the runtime hit an error it cannot continue from (utility process).
+ * - `exit`: it ended without reporting a cause: `process.exit`, a native crash, a signal.
+ * - `start-failed`: a restart whose start failed.
+ */
+export type HostExitReason = 'out-of-memory' | 'uncaught' | 'runtime-fatal' | 'exit' | 'start-failed';
 /** What the supervisor knows about a host that exited without being asked to. */
 export interface HostExit {
     /** `start-failed` is a restart whose start failed; the first start rejects its callers instead. */
     readonly kind: 'crash' | 'out-of-memory' | 'start-failed';
+    readonly reason: HostExitReason;
+    /** Always an `Error`: the host's own when it reported one, else one describing the exit. */
     readonly error: Error;
     readonly code: number | null;
     /** Milliseconds between `started` and the exit; null when the host never started. */
@@ -32,8 +43,27 @@ export interface CallOptions {
     readonly signal?: AbortSignal;
     /** Overrides `limits.callTimeoutMs`; for a stream it bounds each item. */
     readonly timeoutMs?: number;
+    /** Overrides `limits.abortGraceMs`. */
+    readonly abortGraceMs?: number;
+}
+export interface PauseOptions {
+    /** What a call does while paused: wait for `resume()` (default) or fail with `HOST_PAUSED`. */
+    readonly calls?: 'wait' | 'reject';
 }
-export interface HostOptions<Ops extends Contract<Ops>, Payload = undefined> {
+/** A host answered `start`. */
+export interface HostStartedEvent<Info = undefined> {
+    readonly info: Info | undefined;
+    /** Hosts started so far by this supervisor, this one included. */
+    readonly launches: number;
+    /** Set when this host replaces one that exited on its own. */
+    readonly restart: {
+        /** The exit that started the recovery. */
+        readonly exit: HostExit;
+        /** 1 for the first try after that exit, 2 after one failed restart, and so on. */
+        readonly attempt: number;
+    } | null;
+}
+export interface HostOptions<Ops extends Contract<Ops>, Payload = undefined, Info = undefined> {
     /** The closed list of operations that answer once. */
     readonly operations: readonly CallOperation<Ops>[];
     /** The closed list of operations that answer with a stream. */
@@ -54,26 +84,46 @@ export interface HostOptions<Ops extends Contract<Ops>, Payload = undefined> {
         /** Calls and open streams allowed at once; one more fails with `HOST_QUEUE_FULL`. */
         readonly maxPending?: number;
         readonly callTimeoutMs?: number;
+        /**
+         * After an abort, wait this long for the host to settle the call: it settles with the host's
+         * own answer, or fails with `HOST_ABORT_UNSETTLED`. Unset, an abort fails the call at once.
+         */
+        readonly abortGraceMs?: number;
     };
     /** Decides what follows an exit nobody asked for. Defaults to `fatal`. */
     readonly onExit?: (exit: HostExit) => ExitDecision | Promise<ExitDecision>;
     readonly onStats?: (stats: HostStats) => void;
+    /** Every successful start, restarts included. A throw or rejection becomes a process warning. */
+    readonly onStarted?: (event: HostStartedEvent<Info>) => void | Promise<void>;
+    readonly errors?: {
+        /** Rebuilds an application error, such as the app's own class; `undefined` keeps the default. */
+        readonly revive?: (serialized: SerializedError) => Error | undefined;
+    };
     readonly now?: () => number;
 }
-export interface Host<Ops extends Contract<Ops>> {
+export interface Host<Ops extends Contract<Ops>, Info = undefined> {
     /** One method per operation, with the contract's own signature. */
     readonly ops: Ops;
     call<K extends CallOperation<Ops>>(op: K, args: ArgsOf<Ops[K]>, options?: CallOptions): ReturnType<Ops[K]>;
     stream<K extends StreamOperation<Ops>>(op: K, args: ArgsOf<Ops[K]>, options?: CallOptions): ReturnType<Ops[K]>;
-    /** Starts the host now instead of on the first call. */
-    start(): Promise<void>;
+    /** Starts the host now instead of on the first call, and resolves with its `info`. */
+    start(): Promise<Info | undefined>;
     /** Drains and stops the host. The next call starts a new one. */
     stop(): Promise<void>;
     /** Terminates the host without draining, and waits (bounded) for it to exit. Never throws. */
     kill(): Promise<void>;
     /** Stops the host and refuses every later call. */
     close(): Promise<void>;
+    /**
+     * Stops the host like `stop()` and starts none until `resume()`, so its files can be swapped.
+     * Rejects as `stop()` does, but stays paused either way.
+     */
+    pause(options?: PauseOptions): Promise<void>;
+    /** Lets hosts start again; calls that waited start one. */
+    resume(): void;
     readonly state: HostState;
+    /** What the running host passed to `setInfo`; `undefined` while no host is running. */
+    readonly info: Info | undefined;
 }
-export declare function createHost<Ops extends Contract<Ops>, Payload = undefined>(options: HostOptions<Ops, Payload>): Host<Ops>;
+export declare function createHost<Ops extends Contract<Ops>, Payload = undefined, Info = undefined>(options: HostOptions<Ops, Payload, Info>): Host<Ops, Info>;
 //# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EAEb,QAAQ,EAER,aAAa,EACb,eAAe,EAChB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,eAAe,EACrB,MAAM,eAAe,CAAA;AAEtB,eAAO,MAAM,qBAAqB,QAAS,CAAA;AAC3C,eAAO,MAAM,sBAAsB,OAAQ,CAAA;AAE3C,MAAM,MAAM,SAAS,GACnB,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE7F;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GACxB,eAAe,GAAG,UAAU,GAAG,eAAe,GAAG,MAAM,GAAG,cAAc,CAAA;AAE1E,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,cAAc,CAAA;IACzD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACtB,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CACnC;AAED,+BAA+B;AAC/B,MAAM,WAAW,gBAAgB,CAAC,IAAI,GAAG,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE;QAChB,0CAA0C;QAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;QACvB,kFAAkF;QAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,GAAG,IAAI,CAAA;CACT;AAED,MAAM,WAAW,WAAW,CAAC,GAAG,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,IAAI,GAAG,SAAS;IAC3F,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;IAClD,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,CAAC,GAAG,CAAC,EAAE,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,4EAA4E;QAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;QACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,6EAA6E;QAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;QACzB,qFAAqF;QACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,qFAAqF;QACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;QAC/B;;;WAGG;QACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAA;IAC7C,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,iGAAiG;QACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,KAAK,GAAG,SAAS,CAAA;KACrE,CAAA;IACD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,IAAI,CAAC,GAAG,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS;IAC/D,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,IAAI,CAAC,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,EAC/B,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACrB,MAAM,CAAC,CAAC,SAAS,eAAe,CAAC,GAAG,CAAC,EACnC,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACrB,sFAAsF;IACtF,KAAK,IAAI,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAA;IAClC,iEAAiE;IACjE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,8FAA8F;IAC9F,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,2DAA2D;IAC3D,MAAM,IAAI,IAAI,CAAA;IACd,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;CAChC;AAqGD,wBAAgB,UAAU,CAAC,GAAG,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,IAAI,GAAG,SAAS,EACzF,OAAO,EAAE,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,GACvC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAu1BjB"}