@powerhousedao/reactor-workflow 6.2.3-dev.50 → 6.2.3-dev.51
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -1
- package/dist/index.d.ts +185 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +878 -217
- package/dist/index.js.map +1 -1
- package/dist/{piece-registry-Ds8WkewF.d.ts → piece-registry-BdkdVugw.d.ts} +2 -1
- package/dist/{piece-registry-Ds8WkewF.d.ts.map → piece-registry-BdkdVugw.d.ts.map} +1 -1
- package/dist/{piece-registry-BKRLK7Kv.js → piece-registry-D0pa4v0T.js} +37 -15
- package/dist/piece-registry-D0pa4v0T.js.map +1 -0
- package/dist/testing.d.ts +1 -1
- package/dist/testing.d.ts.map +1 -1
- package/dist/testing.js +1 -1
- package/package.json +6 -6
- package/dist/piece-registry-BKRLK7Kv.js.map +0 -1
package/README.md
CHANGED
|
@@ -82,6 +82,93 @@ rather than restated here.
|
|
|
82
82
|
the text of an HTML error page reach the run journal. Redaction runs last,
|
|
83
83
|
over the formatter's output as well.
|
|
84
84
|
|
|
85
|
+
## Placement: one reactor runs workflows
|
|
86
|
+
|
|
87
|
+
**Workflow execution is a singleton pinned to one reactor.** The engine forks
|
|
88
|
+
child processes, so no browser reactor can compose it; the hazard a guard is
|
|
89
|
+
needed for is two Node replicas over one run journal. It is not theoretical:
|
|
90
|
+
opening the journal runs `recoverOrphanedRuns` and `recoverAbandonedRuns`,
|
|
91
|
+
which close out every RUNNING and PENDING run that is not in **this** process's
|
|
92
|
+
in-flight set — so a second replica booting marks the first one's live runs
|
|
93
|
+
FAILED, and then both arm every trigger and both poll it.
|
|
94
|
+
|
|
95
|
+
The guard is a durable claim on the journal's own database
|
|
96
|
+
(`reactor/singleton-lease.ts`, one row in `workflow_singleton`), taken by the host
|
|
97
|
+
**before** the runtime is built, and refused by name when another live process
|
|
98
|
+
holds it (`WorkflowSingletonConflictError`). The
|
|
99
|
+
`trigger_state.lease_owner` / `lease_expires_at` columns stay in the schema,
|
|
100
|
+
always null and unread: they were per trigger, the wrong granularity, since
|
|
101
|
+
the sweeps and the supervisor are per process.
|
|
102
|
+
|
|
103
|
+
- The lease is valid for 60s and renewed every 20s from the moment it is
|
|
104
|
+
claimed, so a slow compose cannot outlast it. A compose that fails after the
|
|
105
|
+
claim releases it, and so does `stop()`, so the next boot owns workflows
|
|
106
|
+
immediately instead of waiting out the TTL.
|
|
107
|
+
- An **expired** lease is taken over: a killed process does not lock workflows
|
|
108
|
+
out until a human intervenes. A claim under the holder's own owner name may
|
|
109
|
+
take it over earlier, once the holder's heartbeat has been silent for two
|
|
110
|
+
renewal periods (40s), but never from a holder that is still renewing: the
|
|
111
|
+
new process opening the journal would fail the old one's live runs.
|
|
112
|
+
- Each claim records a random **instance** token, never configured. Heartbeat
|
|
113
|
+
and release match on owner and instance, so during a rolling deploy under
|
|
114
|
+
one stable owner name the old process can neither renew nor delete the new
|
|
115
|
+
process's lease.
|
|
116
|
+
- A heartbeat that finds the lease held by another claim logs an **error**
|
|
117
|
+
naming the holder, stops renewing and calls `onLost`. The host shuts the
|
|
118
|
+
runtime down: no trigger, webhook or manual run starts after that, and the
|
|
119
|
+
host reports its triggers unavailable. It does not re-claim; workflows come
|
|
120
|
+
back on the next boot, since re-arming needs a fresh compose.
|
|
121
|
+
- A firing the shutdown refuses, whether queued for its concurrency slot or
|
|
122
|
+
still on its way in, is recorded once. Every trigger firing (an operation, a
|
|
123
|
+
piece trigger's items, a schedule slot, a webhook delivery) is journaled as a
|
|
124
|
+
PENDING run with its payload before it fires. If its source will not deliver
|
|
125
|
+
it again, the refusal fails that run, so it can be rerun. If it will (a sync
|
|
126
|
+
webhook answered 503 for the sender to retry, or piece items whose cursor the
|
|
127
|
+
stopped trigger put back), the run is cancelled as redelivered. A firing
|
|
128
|
+
refused before its run was written is left to its source: the operation is
|
|
129
|
+
replayed, the sender retries, the schedule slot stays due, the trigger's
|
|
130
|
+
cursor is put back or never moved. A close-out write that fails leaves the
|
|
131
|
+
run PENDING, and the next owner fails it when it opens the journal. Without a
|
|
132
|
+
working journal a firing that still runs is unrecorded, and its refusal is
|
|
133
|
+
logged as an error.
|
|
134
|
+
- A renewal that fails or hangs is retried every 5s. A holder that has gone
|
|
135
|
+
30s without a renewal it knows landed reports itself lost
|
|
136
|
+
(`reason: "unrenewable"`), before a stale same-owner claim (40s) or expiry
|
|
137
|
+
(60s) could take the lease: journal writes are best-effort, so it would
|
|
138
|
+
otherwise keep running workflows beside the next owner. Switchboard then
|
|
139
|
+
goes down through its fatal shutdown, since nobody else runs workflows,
|
|
140
|
+
and the restarted process re-claims; an embedded host without one stays
|
|
141
|
+
without workflows and logs that a restart is needed.
|
|
142
|
+
- Over a journal no other process can open (embedded PGlite) nothing can take
|
|
143
|
+
the lease, so the holder never fences itself; a stalled renewal is logged.
|
|
144
|
+
- Nothing fences the journal itself: writes do not check the lease, so a
|
|
145
|
+
process keeps writing until it notices the loss.
|
|
146
|
+
- **A refused claim does not take the API down.** The host boots WITHOUT the
|
|
147
|
+
workflow runtime and warns, naming the current owner: no trigger fires here
|
|
148
|
+
and the workflow GraphQL face is absent, while inspection, GraphQL, sync, MCP
|
|
149
|
+
and every drive serve normally. The one thing this process must not do is run
|
|
150
|
+
workflows against a journal a live process owns; aborting the whole boot over
|
|
151
|
+
it turned "not allowed to run one component" into an outage — and, with a
|
|
152
|
+
random owner name, into a crash loop for the TTL after every unclean kill.
|
|
153
|
+
The host retries the claim every 20s and starts workflows once it succeeds,
|
|
154
|
+
so a rolling deploy whose slots have different owner names does not end
|
|
155
|
+
with nobody running them. This is only for a host that never composed: one
|
|
156
|
+
that lost the lease after composing stays without workflows until restart.
|
|
157
|
+
- **The default owner is stable**: `<hostname>/<fingerprint of the journal's
|
|
158
|
+
storage location>`. So one deployment slot restarting re-claims its OWN lease
|
|
159
|
+
once the killed process's heartbeat is stale (40s) rather than waiting out
|
|
160
|
+
the whole TTL. A genuine second replica still differs
|
|
161
|
+
by hostname or by the journal it points at. The storage location is hashed,
|
|
162
|
+
never printed: it can be a Postgres URL with credentials, and the owner name
|
|
163
|
+
goes into a database row and every log line about the lease. The case a stable
|
|
164
|
+
name cannot separate is two processes on ONE host over ONE journal, which is a
|
|
165
|
+
misconfiguration those two already share — and it is not silent: the loser's
|
|
166
|
+
heartbeat finds the lease taken and says so by name.
|
|
167
|
+
- `PH_WORKFLOWS_SINGLETON_OWNER` is still the operator's contract and overrides
|
|
168
|
+
the derived name. Set it per deployment slot when the hostname is not stable
|
|
169
|
+
(a fresh container id each deploy) or when two slots share a journal on
|
|
170
|
+
purpose.
|
|
171
|
+
|
|
85
172
|
## How the host composes it
|
|
86
173
|
|
|
87
174
|
The engine names no host type. `WorkflowRuntimeHostDeps` (`src/reactor/host.ts`)
|
|
@@ -327,7 +414,7 @@ That is what the fields have said since the first schema; what changed is that
|
|
|
327
414
|
they are true.
|
|
328
415
|
|
|
329
416
|
- **Concurrency is process-local**, which is exactly right: workflow execution
|
|
330
|
-
is a singleton pinned to one reactor, so this
|
|
417
|
+
is a singleton pinned to one reactor (see **Placement** above), so this
|
|
331
418
|
process is the deployment's whole run set. A firing SINGLETON drops is
|
|
332
419
|
journaled as a CANCELLED run rather than discarded — a firing that vanished
|
|
333
420
|
is indistinguishable from a trigger that never fired.
|
|
@@ -486,6 +573,7 @@ explanation behind it.
|
|
|
486
573
|
| `PH_WORKFLOWS_HOST_CALL_TIMEOUT_MS` | `10000` | Cap on one call a piece makes of its host; raised to the step's own timeout when that is longer, clipped to the step deadline (`activepieces/context/limits.ts`) |
|
|
487
574
|
| `PH_WORKFLOWS_ATTACHMENT_CACHE_BYTES` | `1073741824` | Downloaded attachments kept on disk by content (`engine/attachment-cache.ts`); `0` is off |
|
|
488
575
|
| `PH_WORKFLOWS_RUN_RETENTION_DAYS` | `30` | Deletes finished runs older than this many days; `0`/`off` keeps everything (`reactor/run-retention.ts`) |
|
|
576
|
+
| `PH_WORKFLOWS_SINGLETON_OWNER` | `<host>/<journal hash>` | Names this process as the workflow singleton's owner; the default is stable per slot, so a restart re-claims once the old heartbeat is stale (`reactor/singleton-lease.ts`) |
|
|
489
577
|
|
|
490
578
|
Each numeric one parses as `Number(raw) || default`: a value that is not a
|
|
491
579
|
positive number falls back silently rather than failing at boot.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { C as StepExecutionRecord, F as BlockResolution, I as PieceOrigin, O as PieceResolver, P as BlockMatch, S as PropertySettingDef, T as ReactorTap, _ as PieceWorkerResult, b as WorkflowTelemetryOptions, f as SecretStore, g as PieceWorker, h as ModelManifestSource, i as ReplayedStep, j as EgressPolicy, l as ConnectionRequest, n as packagePieces, r as CORE_PIECE_NAME, s as AttachmentPort, t as PieceRegistry, v as TELEMETRY_SCOPE, w as WorkflowRunResult, y as WorkflowTelemetry } from "./piece-registry-
|
|
1
|
+
import { C as StepExecutionRecord, F as BlockResolution, I as PieceOrigin, O as PieceResolver, P as BlockMatch, S as PropertySettingDef, T as ReactorTap, _ as PieceWorkerResult, b as WorkflowTelemetryOptions, f as SecretStore, g as PieceWorker, h as ModelManifestSource, i as ReplayedStep, j as EgressPolicy, l as ConnectionRequest, n as packagePieces, r as CORE_PIECE_NAME, s as AttachmentPort, t as PieceRegistry, v as TELEMETRY_SCOPE, w as WorkflowRunResult, y as WorkflowTelemetry } from "./piece-registry-BdkdVugw.js";
|
|
2
2
|
import { ActionBase, TriggerBase } from "@powerhousedao/pieces-framework";
|
|
3
3
|
import { ILogger, OperationWithContext } from "document-model";
|
|
4
4
|
import "@powerhousedao/pieces-framework/workflow";
|
|
@@ -146,6 +146,7 @@ interface OutputTree {
|
|
|
146
146
|
}
|
|
147
147
|
//#endregion
|
|
148
148
|
//#region src/reactor/piece-catalog.d.ts
|
|
149
|
+
type PieceSource = "local" | "registry" | "activepieces";
|
|
149
150
|
interface PieceSummary {
|
|
150
151
|
name: string;
|
|
151
152
|
displayName: string;
|
|
@@ -155,6 +156,7 @@ interface PieceSummary {
|
|
|
155
156
|
actionCount: number;
|
|
156
157
|
triggerCount: number;
|
|
157
158
|
categories: string[];
|
|
159
|
+
source: PieceSource;
|
|
158
160
|
auth: unknown;
|
|
159
161
|
unsupported?: string;
|
|
160
162
|
deprecated?: boolean;
|
|
@@ -203,13 +205,34 @@ interface BlockSearchHit {
|
|
|
203
205
|
strategy: string | null;
|
|
204
206
|
unsupported?: string;
|
|
205
207
|
}
|
|
208
|
+
interface SearchPieceMeta {
|
|
209
|
+
pieceName: string;
|
|
210
|
+
pieceVersion: string;
|
|
211
|
+
displayName: string;
|
|
212
|
+
description: string;
|
|
213
|
+
logoUrl: string;
|
|
214
|
+
categories: string[];
|
|
215
|
+
source: PieceSource;
|
|
216
|
+
deprecated?: boolean;
|
|
217
|
+
unsupported?: string;
|
|
218
|
+
}
|
|
219
|
+
interface PieceSearchMatch extends SearchPieceMeta {
|
|
220
|
+
namedPiece: boolean;
|
|
221
|
+
blocks: BlockSearchHit[];
|
|
222
|
+
}
|
|
206
223
|
type BlockSearchStatus = "ready" | "indexing" | "error";
|
|
207
|
-
interface
|
|
224
|
+
interface PieceSearchResult {
|
|
208
225
|
status: BlockSearchStatus;
|
|
209
|
-
|
|
226
|
+
pieces: PieceSearchMatch[];
|
|
210
227
|
indexedPieces: number;
|
|
211
228
|
error: string | null;
|
|
212
229
|
}
|
|
230
|
+
interface PieceSearchFilter {
|
|
231
|
+
kind: BlockSearchKind;
|
|
232
|
+
sources?: readonly PieceSource[];
|
|
233
|
+
categories?: readonly string[];
|
|
234
|
+
limit?: number;
|
|
235
|
+
}
|
|
213
236
|
//#endregion
|
|
214
237
|
//#region src/reactor/sync-wait.d.ts
|
|
215
238
|
export declare const WORKFLOW_SYNCING_MESSAGE = "Workflow is still syncing; try again in a moment";
|
|
@@ -428,6 +451,20 @@ declare class WorkflowRunStore {
|
|
|
428
451
|
* reach its limit — the boot loop it exists to bound.
|
|
429
452
|
*/
|
|
430
453
|
claimAndEnqueueRun(dedupeKey: string, ttlMs: number, nowIso: string, options: EnqueueRunOptions): Promise<FireClaim>;
|
|
454
|
+
journalTriggerItems(items: {
|
|
455
|
+
dedupeKey?: string;
|
|
456
|
+
options: EnqueueRunOptions;
|
|
457
|
+
}[], ttlMs: number, nowIso: string): Promise<(string | undefined)[]>;
|
|
458
|
+
recordScheduleFire(nowIso: string, nextPollAtIso: string, options: EnqueueRunOptions): Promise<string>;
|
|
459
|
+
/**
|
|
460
|
+
* Puts a piece_store partition back to `entries` and, in the same write,
|
|
461
|
+
* cancels the runs the restored cursor delivers again and releases their
|
|
462
|
+
* claims, so no reader sees the old cursor while the claims still hold.
|
|
463
|
+
*/
|
|
464
|
+
rewindPieceStore(scope: string, scopeKey: string, entries: Record<string, unknown>, redelivered?: {
|
|
465
|
+
runIds: string[];
|
|
466
|
+
reason: string;
|
|
467
|
+
}): Promise<void>;
|
|
431
468
|
/**
|
|
432
469
|
* Counts one delivery of an operation, and reports whether a run was ever
|
|
433
470
|
* journaled for it.
|
|
@@ -549,7 +586,7 @@ interface TriggerSupervisorOptions {
|
|
|
549
586
|
store: () => Promise<WorkflowRunStore | undefined>;
|
|
550
587
|
parks?: ParkState;
|
|
551
588
|
resolveAuth: (connectionId: string | null | undefined, request?: ConnectionRequest) => Promise<unknown>;
|
|
552
|
-
fire: (workflowId: string, payload: unknown, kind: string) => void;
|
|
589
|
+
fire: (workflowId: string, payload: unknown, kind: string, runId: string) => void;
|
|
553
590
|
cacheDir: string;
|
|
554
591
|
resolver?: PieceResolver;
|
|
555
592
|
worker?: PieceWorker;
|
|
@@ -578,10 +615,14 @@ declare class TriggerSupervisor {
|
|
|
578
615
|
private ops;
|
|
579
616
|
private ticking;
|
|
580
617
|
private warnedMissingJournal;
|
|
618
|
+
private stopped;
|
|
581
619
|
constructor(options: TriggerSupervisorOptions);
|
|
582
620
|
start(): void;
|
|
583
621
|
stop(): void;
|
|
584
622
|
private enqueue;
|
|
623
|
+
private throwIfStopped;
|
|
624
|
+
private store;
|
|
625
|
+
private fire;
|
|
585
626
|
private readonly enabledOk;
|
|
586
627
|
private readonly descriptors;
|
|
587
628
|
private own;
|
|
@@ -659,7 +700,9 @@ declare class TriggerSupervisor {
|
|
|
659
700
|
private renew;
|
|
660
701
|
private fireSchedule;
|
|
661
702
|
private poll;
|
|
662
|
-
private
|
|
703
|
+
private fireItems;
|
|
704
|
+
private redeliver;
|
|
705
|
+
private failRefused;
|
|
663
706
|
}
|
|
664
707
|
//#endregion
|
|
665
708
|
//#region src/reactor/service.d.ts
|
|
@@ -811,6 +854,8 @@ export declare class WorkflowRuntimeService {
|
|
|
811
854
|
private fireUnjournaled;
|
|
812
855
|
private enqueueFire;
|
|
813
856
|
private fireFromTrigger;
|
|
857
|
+
private journalFiring;
|
|
858
|
+
private startFiring;
|
|
814
859
|
private readonly firedLifecycle;
|
|
815
860
|
private readonly firedLifecycleQueue;
|
|
816
861
|
private lifecycleAlreadyFired;
|
|
@@ -829,8 +874,11 @@ export declare class WorkflowRuntimeService {
|
|
|
829
874
|
private triggerSupervisor?;
|
|
830
875
|
private readonly parks;
|
|
831
876
|
supervisor(): TriggerSupervisor;
|
|
877
|
+
private laneFailed;
|
|
832
878
|
startTriggerSupervisor(): void;
|
|
833
879
|
stopTriggerSupervisor(): void;
|
|
880
|
+
private closed;
|
|
881
|
+
private throwIfClosed;
|
|
834
882
|
shutdown(): void;
|
|
835
883
|
triggerStates(ctx?: WorkflowCaller): Promise<TriggerStateRow[]>;
|
|
836
884
|
private webhookEndpoints?;
|
|
@@ -901,7 +949,8 @@ export declare class WorkflowRuntimeService {
|
|
|
901
949
|
pieceCatalog(): Promise<PieceSummary[]>;
|
|
902
950
|
pieceActions(packageName: string, version?: string): Promise<PieceActionsResult>;
|
|
903
951
|
pieceTriggers(packageName: string, version?: string): Promise<PieceTriggersResult>;
|
|
904
|
-
|
|
952
|
+
warmPieceSearch(): void;
|
|
953
|
+
searchPieces(query: string, filter: PieceSearchFilter): Promise<PieceSearchResult>;
|
|
905
954
|
pieceDetail(packageName: string, version?: string): Promise<unknown>;
|
|
906
955
|
private localPieceAt;
|
|
907
956
|
blockDescriptor(block: BlockRef): Promise<unknown>;
|
|
@@ -932,6 +981,7 @@ export declare class WorkflowRuntimeService {
|
|
|
932
981
|
fire(workflowId: string, triggerPayload?: unknown, triggerKind?: string, resume?: RunResume, ctx?: WorkflowCaller, enqueuedRunId?: string): Promise<PersistedRunResult>;
|
|
933
982
|
private runFired;
|
|
934
983
|
private readonly runGate;
|
|
984
|
+
private readonly heldReplies;
|
|
935
985
|
/** Why a trigger's firing of a PARKED workflow is refused; undefined when
|
|
936
986
|
* it is not parked, or when an operator started the run. */
|
|
937
987
|
private parkedFiring;
|
|
@@ -950,6 +1000,7 @@ export declare class WorkflowRuntimeService {
|
|
|
950
1000
|
* of bug this work package exists to stamp out. An already-enqueued row is
|
|
951
1001
|
* closed out in place, so nothing is left PENDING for a sweep to find.
|
|
952
1002
|
*/
|
|
1003
|
+
private refuseClosed;
|
|
953
1004
|
private skipFiring;
|
|
954
1005
|
/**
|
|
955
1006
|
* `policy.onFailure` for a run that failed terminally.
|
|
@@ -983,6 +1034,133 @@ export declare class InvalidRunCursorError extends Error {
|
|
|
983
1034
|
constructor();
|
|
984
1035
|
}
|
|
985
1036
|
//#endregion
|
|
1037
|
+
//#region src/reactor/singleton-lease.d.ts
|
|
1038
|
+
/**
|
|
1039
|
+
* Names this process as the workflow singleton's owner.
|
|
1040
|
+
*
|
|
1041
|
+
* Set it to a STABLE name per deployment slot (`switchboard-0`, the
|
|
1042
|
+
* StatefulSet pod name, the Render service id). The owner name is the
|
|
1043
|
+
* operator's contract: a restart under the same name re-claims its own lease
|
|
1044
|
+
* once the old heartbeat is stale instead of waiting out
|
|
1045
|
+
* {@link SINGLETON_LEASE_TTL_MS}.
|
|
1046
|
+
*
|
|
1047
|
+
* Unset, the owner is derived from a STABLE identity — the hostname and a
|
|
1048
|
+
* fingerprint of the journal's own storage location ({@link
|
|
1049
|
+
* AcquireSingletonOptions.storageId}) — not from the pid and a random suffix.
|
|
1050
|
+
* A random per-process owner meant every unclean kill locked the next boot out
|
|
1051
|
+
* for the whole {@link SINGLETON_LEASE_TTL_MS}: the dead process's lease was
|
|
1052
|
+
* nobody's to re-claim, and `release()` never ran. One deployment slot
|
|
1053
|
+
* restarting is the common case and it has to be quick; a genuine second
|
|
1054
|
+
* replica still differs, by hostname or by the journal it points at.
|
|
1055
|
+
*/
|
|
1056
|
+
export declare const WORKFLOW_SINGLETON_OWNER_ENV = "PH_WORKFLOWS_SINGLETON_OWNER";
|
|
1057
|
+
/** How long a claim stays valid without a heartbeat. */
|
|
1058
|
+
export declare const SINGLETON_LEASE_TTL_MS = 60000;
|
|
1059
|
+
/** How often the holder renews it; a third of the TTL, so two renewals may be
|
|
1060
|
+
* lost (a GC pause, a slow database) before anyone may take over. */
|
|
1061
|
+
export declare const SINGLETON_HEARTBEAT_MS: number;
|
|
1062
|
+
/**
|
|
1063
|
+
* How long the holder's heartbeat must have been silent before a claim under
|
|
1064
|
+
* the SAME owner name takes the lease over, short of its expiry. Two renewal
|
|
1065
|
+
* periods: a live holder renews well inside it, and its self-fence fires
|
|
1066
|
+
* before it passes.
|
|
1067
|
+
*/
|
|
1068
|
+
export declare const SINGLETON_STALE_HEARTBEATS = 2;
|
|
1069
|
+
/** Another live process holds the singleton. The refusal is the point: a host
|
|
1070
|
+
* that cannot own workflow execution must not compose the engine. */
|
|
1071
|
+
export declare class WorkflowSingletonConflictError extends Error {
|
|
1072
|
+
readonly owner: string;
|
|
1073
|
+
readonly expiresAt: string;
|
|
1074
|
+
readonly wouldBe: string;
|
|
1075
|
+
constructor(owner: string, expiresAt: string, wouldBe: string);
|
|
1076
|
+
}
|
|
1077
|
+
/**
|
|
1078
|
+
* Why a holder stopped owning workflow execution.
|
|
1079
|
+
*
|
|
1080
|
+
* - `taken`: a renewal matched no row, so another claim holds the lease
|
|
1081
|
+
* (`heldBy` names it when the row still exists).
|
|
1082
|
+
* - `unrenewable`: no renewal landed for long enough that another claim could
|
|
1083
|
+
* take it over; none was seen to.
|
|
1084
|
+
*/
|
|
1085
|
+
type WorkflowSingletonLoss = {
|
|
1086
|
+
reason: "taken";
|
|
1087
|
+
heldBy: string | undefined;
|
|
1088
|
+
} | {
|
|
1089
|
+
reason: "unrenewable";
|
|
1090
|
+
silentMs: number;
|
|
1091
|
+
};
|
|
1092
|
+
/** A held claim, renewed from the moment it is taken. The host releases it on
|
|
1093
|
+
* shutdown, so the next boot does not wait out the TTL. */
|
|
1094
|
+
interface WorkflowSingletonLease {
|
|
1095
|
+
readonly owner: string;
|
|
1096
|
+
/** Renews once; false when the lease is no longer ours. */
|
|
1097
|
+
heartbeat(): Promise<boolean>;
|
|
1098
|
+
/** Stops renewing and drops the row if it is still ours. */
|
|
1099
|
+
release(): Promise<void>;
|
|
1100
|
+
}
|
|
1101
|
+
interface AcquireSingletonOptions {
|
|
1102
|
+
relationalDb: IRelationalDb;
|
|
1103
|
+
logger?: ILogger;
|
|
1104
|
+
/** Defaults to {@link WORKFLOW_SINGLETON_OWNER_ENV}, then
|
|
1105
|
+
* `<hostname>/<storageId fingerprint>`. */
|
|
1106
|
+
owner?: string;
|
|
1107
|
+
/**
|
|
1108
|
+
* Where this host's journal lives — a Postgres URL, an absolute PGlite
|
|
1109
|
+
* directory — as the stable half of the default owner name. Hashed, so a
|
|
1110
|
+
* connection string's credentials never reach the lease row or a log line.
|
|
1111
|
+
*
|
|
1112
|
+
* It is what separates two hosts that share a hostname but not a journal,
|
|
1113
|
+
* and it is stable across restarts, which is the whole point.
|
|
1114
|
+
*/
|
|
1115
|
+
storageId?: string;
|
|
1116
|
+
ttlMs?: number;
|
|
1117
|
+
heartbeatMs?: number;
|
|
1118
|
+
/** Called once, when this process stops owning workflow execution. */
|
|
1119
|
+
onLost?: (loss: WorkflowSingletonLoss) => void;
|
|
1120
|
+
/**
|
|
1121
|
+
* Whether a holder that cannot renew reports itself lost before anyone
|
|
1122
|
+
* could take over. On by default. Off for a journal no other process can
|
|
1123
|
+
* open (embedded PGlite): nothing can take the lease, so a stalled renewal
|
|
1124
|
+
* is only logged.
|
|
1125
|
+
*/
|
|
1126
|
+
selfFence?: boolean;
|
|
1127
|
+
env?: Record<string, string | undefined>;
|
|
1128
|
+
}
|
|
1129
|
+
/**
|
|
1130
|
+
* The owner name this process claims under.
|
|
1131
|
+
*
|
|
1132
|
+
* `<hostname>/<storage fingerprint>`, so it is the same name on every boot of
|
|
1133
|
+
* one deployment slot — a restart re-claims its OWN lease once the dead
|
|
1134
|
+
* process's heartbeat is stale, rather than waiting out the TTL — and a different
|
|
1135
|
+
* name on any host or journal that is genuinely somebody else.
|
|
1136
|
+
*
|
|
1137
|
+
* The storage location is hashed, never printed: it can be a Postgres URL with
|
|
1138
|
+
* credentials in it, and the owner name goes into a database row an operator
|
|
1139
|
+
* reads and into every log line about the lease.
|
|
1140
|
+
*
|
|
1141
|
+
* The residual case a stable name cannot tell apart is two processes on ONE
|
|
1142
|
+
* host over ONE journal, which is a misconfiguration those two already share
|
|
1143
|
+
* (one read-model directory, one run journal). It is not silent: the loser's
|
|
1144
|
+
* heartbeat finds the lease taken and says so by name.
|
|
1145
|
+
*/
|
|
1146
|
+
export declare function singletonOwnerName(env?: Record<string, string | undefined>, storageId?: string): string;
|
|
1147
|
+
/**
|
|
1148
|
+
* Claims the workflow singleton, or refuses.
|
|
1149
|
+
*
|
|
1150
|
+
* Three steps, each one a single statement whose own outcome is the claim — a
|
|
1151
|
+
* prior `SELECT` would be a race:
|
|
1152
|
+
*
|
|
1153
|
+
* 1. `INSERT … ON CONFLICT DO NOTHING RETURNING` — the first ever boot.
|
|
1154
|
+
* 2. `UPDATE … WHERE expires_at <= now OR (owner = me AND heartbeat stale)
|
|
1155
|
+
* RETURNING` — a dead lease taken over once it has expired, or our own
|
|
1156
|
+
* slot's lease once its holder stopped renewing (a restart under a stable
|
|
1157
|
+
* owner name), never a live holder's. Either way the row gets this claim's
|
|
1158
|
+
* instance, so the previous holder's heartbeat and release no longer
|
|
1159
|
+
* match.
|
|
1160
|
+
* 3. Neither matched: someone live holds it, and we refuse by name.
|
|
1161
|
+
*/
|
|
1162
|
+
export declare function acquireWorkflowSingletonLease(options: AcquireSingletonOptions): Promise<WorkflowSingletonLease>;
|
|
1163
|
+
//#endregion
|
|
986
1164
|
//#region src/reactor/run-user.d.ts
|
|
987
1165
|
export declare function publishRunUser(client: Pick<IReactorClient, "getOperations">, workflowId: string, hostIdentity?: HostIdentity, signal?: AbortSignal): Promise<RunUser | null>;
|
|
988
1166
|
//#endregion
|
|
@@ -19581,6 +19759,6 @@ interface WebhookPayload {
|
|
|
19581
19759
|
body: unknown;
|
|
19582
19760
|
}
|
|
19583
19761
|
//#endregion
|
|
19584
|
-
export { type AttachmentClientLike, type AttachmentReadRequest, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, TELEMETRY_SCOPE, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, type WorkflowTelemetryOptions, packagePieces };
|
|
19762
|
+
export { type AcquireSingletonOptions, type AttachmentClientLike, type AttachmentReadRequest, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, TELEMETRY_SCOPE, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, type WorkflowSingletonLease, type WorkflowSingletonLoss, type WorkflowTelemetryOptions, packagePieces };
|
|
19585
19763
|
export {};
|
|
19586
19764
|
//# sourceMappingURL=index.d.ts.map
|