@powerhousedao/reactor-workflow 6.2.3-dev.83 → 6.2.3-dev.85
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 +206 -38
- package/dist/index.d.ts +263 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1786 -171
- package/dist/index.js.map +1 -1
- package/dist/{piece-registry-ByALLpvA.d.ts → piece-registry-DNIk31Vv.d.ts} +82 -3
- package/dist/piece-registry-DNIk31Vv.d.ts.map +1 -0
- package/dist/{telemetry-5AAX-Pst.js → telemetry-B5OOpfCS.js} +708 -29
- package/dist/telemetry-B5OOpfCS.js.map +1 -0
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +1 -1
- package/dist/worker-entry.js +161 -16
- package/dist/worker-entry.js.map +1 -1
- package/package.json +7 -7
- package/dist/piece-registry-ByALLpvA.d.ts.map +0 -1
- package/dist/telemetry-5AAX-Pst.js.map +0 -1
package/README.md
CHANGED
|
@@ -55,7 +55,7 @@ rather than restated here.
|
|
|
55
55
|
Its `base64` is computed on first read, as upstream's getter is, so a piece
|
|
56
56
|
that only reads `data` holds one copy of the file. A `streaming: true` FILE
|
|
57
57
|
prop gets upstream's `ApStreamingFile` instead: `{ filename, extension,
|
|
58
|
-
|
|
58
|
+
size, body }`, with `body` read from the staged file or the network.
|
|
59
59
|
- **Prop validation**, from the same place. Before an action's `run()` or any
|
|
60
60
|
trigger hook but `onDisable`, a prop left unset takes its `defaultValue` and
|
|
61
61
|
the coerced values go through the engine's `validateProperty`. A failure is
|
|
@@ -156,7 +156,7 @@ the sweeps and the supervisor are per process.
|
|
|
156
156
|
with nobody running them. This is only for a host that never composed: one
|
|
157
157
|
that lost the lease after composing stays without workflows until restart.
|
|
158
158
|
- **The default owner is stable**: `<hostname>/<fingerprint of the journal's
|
|
159
|
-
|
|
159
|
+
storage location>`. So one deployment slot restarting re-claims its OWN lease
|
|
160
160
|
once the killed process's heartbeat is stale (40s) rather than waiting out
|
|
161
161
|
the whole TTL. A genuine second replica still differs
|
|
162
162
|
by hostname or by the journal it points at. The storage location is hashed,
|
|
@@ -324,7 +324,9 @@ action at another version is the same block.
|
|
|
324
324
|
### The core piece
|
|
325
325
|
|
|
326
326
|
The engine's own blocks are the built-in piece `@powerhousedao/piece-core`, in
|
|
327
|
-
`src/pieces/core/`. Its actions are `branch
|
|
327
|
+
`src/pieces/core/`. Its actions are `branch`, `assert`, `delay`,
|
|
328
|
+
`approval` ("Request approval"), `stop` ("Stop run") and `waitForWebhook`
|
|
329
|
+
("Respond and wait for webhook"); its triggers are
|
|
328
330
|
`manual`, `schedule` and `webhook`. It is written with `createPiece`,
|
|
329
331
|
`createAction` and `createTrigger`, and its version is this package's version.
|
|
330
332
|
|
|
@@ -339,8 +341,51 @@ The engine's own blocks are the built-in piece `@powerhousedao/piece-core`, in
|
|
|
339
341
|
- `branch` and `assert` run through `ActivepiecesBlockExecutor` like any piece
|
|
340
342
|
action, with the same resolution and journaling. `branch` leaves on `true`
|
|
341
343
|
or `false` by its result.
|
|
344
|
+
- `delay` ("Delay for" an amount and unit, or "Delay until" a date) suspends
|
|
345
|
+
the run on a `DELAY` waitpoint and outputs `{ resumedAt }`; a time already
|
|
346
|
+
past does not wait. `approval` suspends it on a WEBHOOK waitpoint of kind
|
|
347
|
+
`approval` (title, Markdown details rendered when the run pauses, labels,
|
|
348
|
+
when a reason is required, approver DIDs, an optional expiry) and outputs
|
|
349
|
+
`{ approved, reason, decidedBy, decidedAt }` from the editor's decision
|
|
350
|
+
(`decidedAt` is when it was decided, not when the run resumed). It
|
|
351
|
+
gets no resume URL: a waiting step stops the leg, so no later step could send
|
|
352
|
+
one. To email a link, use Activepieces' approval pieces (Gmail's "Request
|
|
353
|
+
approval in email", or Create Approval Links then Wait for Approval). Both
|
|
354
|
+
throw in a single-step test, and both leave on `next`.
|
|
355
|
+
- `stop` ends the run `SUCCEEDED` without running the steps after it, through
|
|
356
|
+
the same path as `ctx.run.stop`. Its optional response (`responseType`
|
|
357
|
+
`json`, `raw` or `redirect`; `status`, `headers`, `body`, `text`,
|
|
358
|
+
`redirectUrl`) answers a held request; with none set it answers 200 with
|
|
359
|
+
`{}`, as `run.stop()` does. Its only port is `error`, so the editor offers
|
|
360
|
+
no step after it.
|
|
361
|
+
- `waitForWebhook` is Activepieces' "Respond and Wait for Next Webhook": it
|
|
362
|
+
suspends the run on a WEBHOOK waitpoint of kind `webhook` whose
|
|
363
|
+
`responseToSend` is the configured response (the same props as `stop`)
|
|
364
|
+
with the resume URL in the `x-resume-webhook-url` header and, for a JSON
|
|
365
|
+
object body unless `includeResumeUrl` is off, in a `resumeUrl` field. The
|
|
366
|
+
URL is the plain resume URL; a caller appends `/sync` to hold for the run's
|
|
367
|
+
answer. It outputs `{ resumeUrl }` while waiting and the resuming request's
|
|
368
|
+
`{ body, headers, queryParams }` after. `expiresAfter` and `expiresUnit`
|
|
369
|
+
end the run if nobody calls in time. It needs the host's
|
|
370
|
+
`waitpointBaseUrl`, throws in a single-step test, and leaves on `next`.
|
|
342
371
|
- The triggers are fed by the host: `reactor/schedule.ts`, `reactor/webhook.ts`
|
|
343
372
|
and the `fire` mutation. Their hooks are never called.
|
|
373
|
+
- `manual` takes optional `inputs`, shaped after Activepieces' web form
|
|
374
|
+
fields: per field a payload key (`name`), `displayName`, `type` (`text`,
|
|
375
|
+
`text_area`, `number`, `toggle`, `date`, `dropdown`, `json`), `required`,
|
|
376
|
+
`defaultValue` and `description`. A dropdown's `options` is one per line,
|
|
377
|
+
either a bare value or `Label = value` (split at the first `=` with a space
|
|
378
|
+
on each side); the Run form shows the label and the payload carries the
|
|
379
|
+
value, which is what the fire checks. Its `defaultValue` is a value, or an
|
|
380
|
+
option's label. A caller's
|
|
381
|
+
`fire` checks its payload against the published trigger's inputs
|
|
382
|
+
(`coerceManualPayload` in `@powerhousedao/pieces-framework/workflow`):
|
|
383
|
+
defaults fill missing fields, values are coerced (`"42"` to 42, `"true"` to
|
|
384
|
+
true, a date to ISO 8601), keys no field declares pass through, and a
|
|
385
|
+
missing required field or a bad value refuses the fire with a
|
|
386
|
+
`ManualPayloadError` naming each field, before any run row. Reruns and
|
|
387
|
+
other trigger kinds are not checked. The inputs also type
|
|
388
|
+
`{{trigger.payload.<name>}}` in the expression picker.
|
|
344
389
|
|
|
345
390
|
## Block resolution
|
|
346
391
|
|
|
@@ -414,17 +459,17 @@ at all enforces nothing, but only hand-built definitions lack one: `policy` is
|
|
|
414
459
|
non-null in the workflow model since v1, so every workflow document, old or
|
|
415
460
|
new, carries one.
|
|
416
461
|
|
|
417
|
-
| Field
|
|
418
|
-
|
|
|
419
|
-
| `concurrency`
|
|
420
|
-
| `maxParallelRuns`
|
|
421
|
-
| `runTimeoutSeconds`
|
|
422
|
-
| `defaultRetry`, step `retry`
|
|
423
|
-
| `onFailure`
|
|
424
|
-
| `maxSuspensionDays`
|
|
425
|
-
| `retainRunsDays`
|
|
426
|
-
| `journalAsDocument`
|
|
427
|
-
| step `idempotencyKeyExpression` | —
|
|
462
|
+
| Field | Where | Behaviour |
|
|
463
|
+
| ------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
464
|
+
| `concurrency` | `reactor/run-gate.ts` | SINGLETON drops a firing while a run is active; QUEUE serialises; PARALLEL runs concurrently |
|
|
465
|
+
| `maxParallelRuns` | `reactor/run-gate.ts` | Bounds PARALLEL; null is unbounded. SINGLETON and QUEUE are 1 by definition |
|
|
466
|
+
| `runTimeoutSeconds` | `pieces/engine/coordinator.ts` | A run deadline from FIRING time, checked between steps and bounding every retry wait; expiry ends the run CANCELLED |
|
|
467
|
+
| `defaultRetry`, step `retry` | `pieces/engine/retry.ts` | Attempts, backoff, delays and `retryOn`; attempts land on the step's journal row |
|
|
468
|
+
| `onFailure` | `reactor/service.ts` | On a trigger's failed run: PARK parks the trigger; NOTIFY logs at error level; IGNORE does nothing. A failed manual run or rerun changes nothing |
|
|
469
|
+
| `maxSuspensionDays` | `reactor/waitpoint-poller.ts` | A WEBHOOK waitpoint expires this long after it was created (sooner if its block says so); expiry of the one the run waits on ends the run CANCELLED with `WaitpointExpired`. A `DELAY` longer than this is refused when created |
|
|
470
|
+
| `retainRunsDays` | — | **Not enforced** per workflow; `PH_WORKFLOWS_RUN_RETENTION_DAYS` is the journal-wide control |
|
|
471
|
+
| `journalAsDocument` | — | **Not enforced**: the journal is relational, and there is no run document model |
|
|
472
|
+
| step `idempotencyKeyExpression` | — | **Not enforced**: a fire dedupes on its trigger operation or a trigger item's `_dedupe_key` |
|
|
428
473
|
|
|
429
474
|
**Enforcing the policy changes every deployed workflow.** The model's initial
|
|
430
475
|
values are `concurrency: QUEUE`, `onFailure: PARK` and
|
|
@@ -608,26 +653,26 @@ Everything the engine itself reads from the environment is prefixed
|
|
|
608
653
|
— that manifest is the published surface a host reads, this table is the
|
|
609
654
|
explanation behind it.
|
|
610
655
|
|
|
611
|
-
| Variable | Default
|
|
612
|
-
| ------------------------------------- |
|
|
613
|
-
| `PH_WORKFLOWS_SECRETS_MASTER_KEY` | generated key file
|
|
614
|
-
| `PH_WORKFLOWS_EGRESS_ALLOW_ADDRESSES` | unset
|
|
615
|
-
| `PH_WORKFLOWS_RUN_CONCURRENCY` | from the host
|
|
616
|
-
| `PH_WORKFLOWS_RUN_QUEUE_DEPTH` | `0`
|
|
617
|
-
| `PH_WORKFLOWS_WORKER_MEMORY_MB` | `256`
|
|
618
|
-
| `PH_WORKFLOWS_WORKER_MAX_REQUESTS` | `1000`
|
|
619
|
-
| `PH_WORKFLOWS_WORKER_MIN` | `1`
|
|
620
|
-
| `PH_WORKFLOWS_TRIGGER_SLOTS` | `1`
|
|
621
|
-
| `PH_WORKFLOWS_RUNS_IN_FLIGHT` | 8 × the pool
|
|
622
|
-
| `PH_WORKFLOWS_ADMIT_MAX_ELU` | `0.8`
|
|
623
|
-
| `PH_WORKFLOWS_MAX_QUEUED_FIRINGS` | `100`
|
|
624
|
-
| `PH_WORKFLOWS_POLL_INTERVAL_MS` | `60000`
|
|
625
|
-
| `PH_WORKFLOWS_WEBHOOK_RECONCILE_MS` | `900000`
|
|
626
|
-
| `PH_WORKFLOWS_WEBHOOK_TIMEOUT_MS` | `30000`
|
|
627
|
-
| `PH_WORKFLOWS_PIECE_MAX_FILE_BYTES` | `8388608`
|
|
628
|
-
| `PH_WORKFLOWS_HOST_CALL_TIMEOUT_MS` | `10000`
|
|
629
|
-
| `PH_WORKFLOWS_ATTACHMENT_CACHE_BYTES` | `1073741824`
|
|
630
|
-
| `PH_WORKFLOWS_RUN_RETENTION_DAYS` | `30`
|
|
656
|
+
| Variable | Default | What it sets |
|
|
657
|
+
| ------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
658
|
+
| `PH_WORKFLOWS_SECRETS_MASTER_KEY` | generated key file | 64 hex chars (32 bytes) encrypting connection secrets at rest (`reactor/secret-store.ts`) |
|
|
659
|
+
| `PH_WORKFLOWS_EGRESS_ALLOW_ADDRESSES` | unset | Addresses or CIDRs a piece may reach, widening the default policy (`reactor/lib.ts`) |
|
|
660
|
+
| `PH_WORKFLOWS_RUN_CONCURRENCY` | from the host | Most piece children at once (`worker/pool.ts`); unset, sized from the cores and memory, at most 32 |
|
|
661
|
+
| `PH_WORKFLOWS_RUN_QUEUE_DEPTH` | `0` | Requests that may wait for a child before new ones are refused; `0` waits without limit |
|
|
662
|
+
| `PH_WORKFLOWS_WORKER_MEMORY_MB` | `256` | Each child's V8 heap (`--max-old-space-size`); a child past 80% of it is retired |
|
|
663
|
+
| `PH_WORKFLOWS_WORKER_MAX_REQUESTS` | `1000` | Requests a child serves before it is retired |
|
|
664
|
+
| `PH_WORKFLOWS_WORKER_MIN` | `1` | Idle children kept warm; `0` lets every idle child exit |
|
|
665
|
+
| `PH_WORKFLOWS_TRIGGER_SLOTS` | `1` | Children reserved for trigger hooks |
|
|
666
|
+
| `PH_WORKFLOWS_RUNS_IN_FLIGHT` | 8 × the pool | Runs admitted at once across workflows (`reactor/run-dispatcher.ts`) |
|
|
667
|
+
| `PH_WORKFLOWS_ADMIT_MAX_ELU` | `0.8` | Main-thread event-loop utilization above which no new run is admitted; one always runs |
|
|
668
|
+
| `PH_WORKFLOWS_MAX_QUEUED_FIRINGS` | `100` | Firings of ONE workflow that may wait for its concurrency slot; past it a firing is journaled CANCELLED (`reactor/run-gate.ts`) |
|
|
669
|
+
| `PH_WORKFLOWS_POLL_INTERVAL_MS` | `60000` | Cadence for a polling trigger that names none of its own |
|
|
670
|
+
| `PH_WORKFLOWS_WEBHOOK_RECONCILE_MS` | `900000` | How often a webhook trigger re-registers with its provider |
|
|
671
|
+
| `PH_WORKFLOWS_WEBHOOK_TIMEOUT_MS` | `30000` | How long a sync-mode delivery holds the provider's socket |
|
|
672
|
+
| `PH_WORKFLOWS_PIECE_MAX_FILE_BYTES` | `8388608` | File-size ceiling for FILE-property hydration and `ctx.files.write` |
|
|
673
|
+
| `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`) |
|
|
674
|
+
| `PH_WORKFLOWS_ATTACHMENT_CACHE_BYTES` | `1073741824` | Downloaded attachments kept on disk by content (`engine/attachment-cache.ts`); `0` is off |
|
|
675
|
+
| `PH_WORKFLOWS_RUN_RETENTION_DAYS` | `30` | Deletes finished runs older than this many days; `0`/`off` keeps everything (`reactor/run-retention.ts`) |
|
|
631
676
|
| `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`) |
|
|
632
677
|
|
|
633
678
|
Each numeric one parses as `Number(raw) || default`: a value that is not a
|
|
@@ -728,7 +773,7 @@ more trusted than one that arrived inside a package.
|
|
|
728
773
|
|
|
729
774
|
## OAuth2 connections
|
|
730
775
|
|
|
731
|
-
An OAUTH2 connection brings its own app. `startOAuth` (`reactor/oauth.ts`)
|
|
776
|
+
An OAUTH2 connection brings its own app, or names a publisher's (below). `startOAuth` (`reactor/oauth.ts`)
|
|
732
777
|
builds the provider's authorize URL from the piece's `PieceAuth.OAuth2`
|
|
733
778
|
(`{prop}` placeholders filled from the connection's config, PKCE when the
|
|
734
779
|
piece asks for it) and records a pending attempt in the `oauth` namespace,
|
|
@@ -743,6 +788,62 @@ Token requests leave from the reactor process, so they are held to the egress
|
|
|
743
788
|
policy pieces run under: `https` to a public address, or an address named in
|
|
744
789
|
`PH_WORKFLOWS_EGRESS_ALLOW_ADDRESSES`, over `http` too.
|
|
745
790
|
|
|
791
|
+
### Publisher apps and the relay
|
|
792
|
+
|
|
793
|
+
A connection may instead name a publisher's app (`oauth_app` in its config),
|
|
794
|
+
configured once per host in `workflows.oauthApps`:
|
|
795
|
+
|
|
796
|
+
```json
|
|
797
|
+
{
|
|
798
|
+
"id": "sektar-google",
|
|
799
|
+
"clients": { "desktop": "desktop.json", "web": "web.json" },
|
|
800
|
+
"relay": {
|
|
801
|
+
"clientId": "<the web client's id>",
|
|
802
|
+
"redirectUri": "https://sektar.io/api/oauth/callback",
|
|
803
|
+
"tokenUrl": "https://sektar.io/api/oauth/token"
|
|
804
|
+
}
|
|
805
|
+
}
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
`clients` are the provider's client files (relative to the config file). A
|
|
809
|
+
host may pass the same list programmatically (Switchboard's
|
|
810
|
+
`workflows.oauthApps` option), which wins over the config file. `startOAuth`
|
|
811
|
+
picks, for the redirect it is given (`oauthSignInFor` in
|
|
812
|
+
`reactor/oauth-apps.ts`, also answered by the `oauthSignIn` query as
|
|
813
|
+
`DESKTOP | WEB | RELAY | NONE`):
|
|
814
|
+
|
|
815
|
+
- a loopback callback: the **desktop** client, always with PKCE;
|
|
816
|
+
- any other callback: the **web** client when the host has its file, sending
|
|
817
|
+
the provider the host's own callback, exactly as without a relay;
|
|
818
|
+
- any other callback, no web client file, a `relay`: the **relay**;
|
|
819
|
+
- otherwise none, and `startOAuth` refuses.
|
|
820
|
+
|
|
821
|
+
The relay is a token broker the publisher runs and that alone holds the web
|
|
822
|
+
client's secret. Its one `redirectUri` is registered with the provider, so
|
|
823
|
+
hosts whose own callback is not (a cloud environment per hostname) need no
|
|
824
|
+
provider change. A relayed sign-in:
|
|
825
|
+
|
|
826
|
+
- sends the provider `redirect_uri` = `relay.redirectUri`, `client_id` =
|
|
827
|
+
`relay.clientId`, PKCE whatever the piece says;
|
|
828
|
+
- sets `state` to `<nonce>.<base64url(own callback)>`: the nonce is the usual
|
|
829
|
+
base64url of 32 random bytes (no dots), the callback the redirect the host
|
|
830
|
+
passed, base64url without padding. The relay forwards the provider's
|
|
831
|
+
parameters unchanged to that callback, which runs `completeOAuth` as ever;
|
|
832
|
+
the whole string is the attempt's key;
|
|
833
|
+
- records the attempt with `relay.redirectUri` and `relay.tokenUrl` and no
|
|
834
|
+
client secret ref (`client_secret_ref` null);
|
|
835
|
+
- exchanges the code at `relay.tokenUrl` with `client_id`, `code_verifier`
|
|
836
|
+
and `redirect_uri`, no secret; the broker adds it and answers with the
|
|
837
|
+
provider's token response;
|
|
838
|
+
- stores the token set with `relayed: true`, its `token_url` the relay's: every
|
|
839
|
+
refresh posts `grant_type=refresh_token`, the refresh token and `client_id`
|
|
840
|
+
there, again without a secret, whatever the config says by then.
|
|
841
|
+
|
|
842
|
+
A relay needs a `clientId` and two absolute `https` URLs without credentials;
|
|
843
|
+
otherwise it is dropped with a warning and the app kept without it. The
|
|
844
|
+
relay's token URL is held to the egress policy above, which a public `https`
|
|
845
|
+
host passes.
|
|
846
|
+
|
|
746
847
|
## Files and attachments
|
|
747
848
|
|
|
748
849
|
Bytes never cross the worker's IPC channel; host and worker share
|
|
@@ -760,6 +861,8 @@ step returns. Directories a crashed host left behind are swept at startup.
|
|
|
760
861
|
the step's directory under the ceiling. After the step the host ingests each
|
|
761
862
|
file, hashing and uploading it from disk, and refuses any path the step did
|
|
762
863
|
not write: outside its directory, a symlink or a hard link.
|
|
864
|
+
`ctx.files.upload` stages the same way, but the host ingests the file during
|
|
865
|
+
the call, over the host-call channel, and returns the ref.
|
|
763
866
|
- **Who may read.** A run reads the refs its own steps wrote, and the refs its
|
|
764
867
|
journaled steps already held on a rerun or a step test. Anything else is the
|
|
765
868
|
host's call (`canReadAttachmentRef`), made against the documents the run was
|
|
@@ -856,10 +959,72 @@ releases what an earlier enable registered. The reason reads
|
|
|
856
959
|
action's default retry (3 attempts, exponential from 5s) unless the action
|
|
857
960
|
declares a `defaultRetry`. `continueOnFailure` is ignored.
|
|
858
961
|
- `test` is never called.
|
|
962
|
+
- `run.canPause` is `true` in a run and `false` in a single-step test, where
|
|
963
|
+
`createWaitpoint`, `waitForWaitpoint` and `run.pause` throw.
|
|
964
|
+
- `createWaitpoint`, `waitForWaitpoint` and the deprecated `run.pause` (both
|
|
965
|
+
pause shapes) suspend the run (#3218): the step and run go `WAITING` and
|
|
966
|
+
the run gives up its worker, its admission slot and its `concurrency`
|
|
967
|
+
slot. A resume goes through admission again, re-runs the waiting step as
|
|
968
|
+
`RESUME` with `resumePayload`, and gets a fresh `runTimeoutSeconds`.
|
|
969
|
+
- A step has at most one live waitpoint, as upstream: a second
|
|
970
|
+
`createWaitpoint` in the step, a retry of it, or a retry of a create whose
|
|
971
|
+
answer was lost gets the same waitpoint and resume URL, already resolved if
|
|
972
|
+
its resume came before the step paused. Once the step resumes, it can wait
|
|
973
|
+
again on a new one. Only the hash of a resume URL's token is stored, so the
|
|
974
|
+
URL is re-issued only within the leg that minted it; a step that would get a
|
|
975
|
+
live waitpoint from an earlier leg fails instead (unreachable today).
|
|
976
|
+
- A waiting run resumes on the waitpoint its step waits on, or on a WEBHOOK
|
|
977
|
+
link a step that succeeded created (Create Approval Links, then Wait for
|
|
978
|
+
Approval), as upstream. When the run starts waiting, the waitpoints of
|
|
979
|
+
steps that failed close `CANCELLED`; when it resumes on such a link, the
|
|
980
|
+
waitpoint its step waited on closes. Only the expiry of the waitpoint it
|
|
981
|
+
waits on ends the run; a link that expires just closes. A resume already
|
|
982
|
+
delivered wins over that expiry.
|
|
983
|
+
- Every end of a run (succeeded, failed, cancelled, expired, or failed by the
|
|
984
|
+
orphan sweep) closes its waitpoints and fails its waiting step. A resume
|
|
985
|
+
URL of a closed waitpoint, or of a run that has ended, answers `gone`, and
|
|
986
|
+
the editor refuses to resolve it.
|
|
987
|
+
- One poller on the singleton owner wakes due `DELAY` waitpoints and expires
|
|
988
|
+
overdue ones, in batches, on a single timer armed for the next due time
|
|
989
|
+
(re-checked at least every five minutes). An expiry and the run it ends are
|
|
990
|
+
one transaction. Each pass also ends, `CANCELLED` with `WaitpointNotLive`,
|
|
991
|
+
a WAITING run whose waitpoint closed without ending it.
|
|
992
|
+
- Not yet: a run left `RUNNING` by a crash after it resumed is failed, not
|
|
993
|
+
resumed (#3224).
|
|
994
|
+
- A run resumed on a definition that was re-published meanwhile rebuilds it
|
|
995
|
+
by replaying the workflow's global operations below the revision it pinned,
|
|
996
|
+
from the latest `UPGRADE_DOCUMENT` snapshot, without denied or undone
|
|
997
|
+
operations. This is not the reactor's own rebuild (keyframes, upgrade
|
|
998
|
+
transitions); when the result does not hash to the pin, the leg fails.
|
|
999
|
+
- A WEBHOOK waitpoint needs the host's `waitpointBaseUrl`; without it
|
|
1000
|
+
`createWaitpoint({ type: "WEBHOOK" })` throws.
|
|
1001
|
+
- A resumed run reads steps journaled before it waited from the journal: a
|
|
1002
|
+
truncated or redacted output is unavailable to later steps, and a document
|
|
1003
|
+
output is its reference, not the document.
|
|
859
1004
|
- `requireAuth` defaults to `false` in the descriptor; upstream defaults to
|
|
860
1005
|
`true`.
|
|
861
|
-
- `run.
|
|
862
|
-
|
|
1006
|
+
- `run.respond` and `run.stop` answer the request the run holds: a
|
|
1007
|
+
`responseMode: "sync"` webhook delivery, or a `POST <resumeUrl>/sync` for
|
|
1008
|
+
the leg it resumed. The first answer wins and later ones are ignored; within
|
|
1009
|
+
a step the last of `respond`, `stop` and `waitForWaitpoint` wins, as
|
|
1010
|
+
upstream. The answer goes out when the step returns, with status 200 and
|
|
1011
|
+
body `{}` by default; a string body goes as text, anything else as JSON, and
|
|
1012
|
+
`set-cookie` and framing headers are dropped. The answer is served on the
|
|
1013
|
+
host's origin, so it always carries `x-content-type-options: nosniff` and
|
|
1014
|
+
`content-security-policy: sandbox`, over any the step sets: a step's HTML
|
|
1015
|
+
renders without scripts or the origin's cookies. Unlike upstream, any step may
|
|
1016
|
+
answer, not only one of the trigger's piece. `run.stop` ends the run
|
|
1017
|
+
`SUCCEEDED` and skips the steps after it.
|
|
1018
|
+
- A run that pauses answers the held request with its waitpoint's
|
|
1019
|
+
`responseToSend`; without one, a sync webhook answers 202 with the run's
|
|
1020
|
+
status. A `/sync` resume is held up to `PH_WORKFLOWS_WEBHOOK_TIMEOUT_MS`
|
|
1021
|
+
(504 after), and answered with the run's status when the leg ends or waits
|
|
1022
|
+
without responding. One whose waitpoint closes, or whose run ends, before a
|
|
1023
|
+
leg resumes on it (including a resume that fails to start) answers 409 with
|
|
1024
|
+
the run's status and error.
|
|
1025
|
+
- The deprecated `generateResumeUrl` links to the waitpoint the step's
|
|
1026
|
+
deprecated `run.pause` creates (one link per step). A step that pauses some
|
|
1027
|
+
other way, or that already made a waitpoint, leaves that link dead.
|
|
863
1028
|
- `connections.get`, `tags`, `server`, `agent` and `flows.list` throw.
|
|
864
1029
|
- `ctx.store` checks the key length on `put` only; `get` and `delete` of an
|
|
865
1030
|
over-long key answer as if it were absent.
|
|
@@ -871,6 +1036,9 @@ releases what an earlier enable registered. The reason reads
|
|
|
871
1036
|
|
|
872
1037
|
- Trigger hooks cannot read `attachment://` refs, and a trigger's
|
|
873
1038
|
`ctx.files.write` returns an inline data URI rather than a ref.
|
|
1039
|
+
- `ctx.files.upload` returns the attachment ref as both `id` and `url`; the
|
|
1040
|
+
`url` is not an HTTP URL. In a trigger hook both are the inline data URI.
|
|
1041
|
+
Without an attachment store an action's call throws.
|
|
874
1042
|
- A webhook body that is not JSON or form data is decoded as UTF-8 text, so
|
|
875
1043
|
binary and multipart deliveries are corrupted.
|
|
876
1044
|
- A step cannot read back a file it wrote: its `apfile://` token only becomes
|
|
@@ -917,7 +1085,7 @@ A case this engine is known to fail runs as `it.fails` and names the issue that
|
|
|
917
1085
|
fixes it; never edit those files by hand. To regenerate them:
|
|
918
1086
|
|
|
919
1087
|
```sh
|
|
920
|
-
pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.
|
|
1088
|
+
pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.92.3 --from <activepieces checkout>
|
|
921
1089
|
```
|
|
922
1090
|
|
|
923
1091
|
## Design documents
|