@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 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
- size, body }`, with `body` read from the staged file or the network.
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
- storage location>`. So one deployment slot restarting re-claims its OWN lease
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` and `assert`; its triggers are
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 | Where | Behaviour |
418
- | -------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
419
- | `concurrency` | `reactor/run-gate.ts` | SINGLETON drops a firing while a run is active; QUEUE serialises; PARALLEL runs concurrently |
420
- | `maxParallelRuns` | `reactor/run-gate.ts` | Bounds PARALLEL; null is unbounded. SINGLETON and QUEUE are 1 by definition |
421
- | `runTimeoutSeconds` | `pieces/engine/coordinator.ts` | A run deadline from FIRING time, checked between steps and bounding every retry wait; expiry ends the run CANCELLED |
422
- | `defaultRetry`, step `retry` | `pieces/engine/retry.ts` | Attempts, backoff, delays and `retryOn`; attempts land on the step's journal row |
423
- | `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 |
424
- | `maxSuspensionDays` | — | **Not enforced**: nothing suspends. Waitpoints, `run.pause` and `generateResumeUrl` all throw |
425
- | `retainRunsDays` | — | **Not enforced** per workflow; `PH_WORKFLOWS_RUN_RETENTION_DAYS` is the journal-wide control |
426
- | `journalAsDocument` | — | **Not enforced**: the journal is relational, and there is no run document model |
427
- | step `idempotencyKeyExpression` | — | **Not enforced**: a fire dedupes on its trigger operation or a trigger item's `_dedupe_key` |
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 | What it sets |
612
- | ------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------- |
613
- | `PH_WORKFLOWS_SECRETS_MASTER_KEY` | generated key file | 64 hex chars (32 bytes) encrypting connection secrets at rest (`reactor/secret-store.ts`) |
614
- | `PH_WORKFLOWS_EGRESS_ALLOW_ADDRESSES` | unset | Addresses or CIDRs a piece may reach, widening the default policy (`reactor/lib.ts`) |
615
- | `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 |
616
- | `PH_WORKFLOWS_RUN_QUEUE_DEPTH` | `0` | Requests that may wait for a child before new ones are refused; `0` waits without limit |
617
- | `PH_WORKFLOWS_WORKER_MEMORY_MB` | `256` | Each child's V8 heap (`--max-old-space-size`); a child past 80% of it is retired |
618
- | `PH_WORKFLOWS_WORKER_MAX_REQUESTS` | `1000` | Requests a child serves before it is retired |
619
- | `PH_WORKFLOWS_WORKER_MIN` | `1` | Idle children kept warm; `0` lets every idle child exit |
620
- | `PH_WORKFLOWS_TRIGGER_SLOTS` | `1` | Children reserved for trigger hooks |
621
- | `PH_WORKFLOWS_RUNS_IN_FLIGHT` | 8 × the pool | Runs admitted at once across workflows (`reactor/run-dispatcher.ts`) |
622
- | `PH_WORKFLOWS_ADMIT_MAX_ELU` | `0.8` | Main-thread event-loop utilization above which no new run is admitted; one always runs |
623
- | `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`) |
624
- | `PH_WORKFLOWS_POLL_INTERVAL_MS` | `60000` | Cadence for a polling trigger that names none of its own |
625
- | `PH_WORKFLOWS_WEBHOOK_RECONCILE_MS` | `900000` | How often a webhook trigger re-registers with its provider |
626
- | `PH_WORKFLOWS_WEBHOOK_TIMEOUT_MS` | `30000` | How long a sync-mode delivery holds the provider's socket |
627
- | `PH_WORKFLOWS_PIECE_MAX_FILE_BYTES` | `8388608` | File-size ceiling for FILE-property hydration and `ctx.files.write` |
628
- | `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`) |
629
- | `PH_WORKFLOWS_ATTACHMENT_CACHE_BYTES` | `1073741824` | Downloaded attachments kept on disk by content (`engine/attachment-cache.ts`); `0` is off |
630
- | `PH_WORKFLOWS_RUN_RETENTION_DAYS` | `30` | Deletes finished runs older than this many days; `0`/`off` keeps everything (`reactor/run-retention.ts`) |
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.stop`, `run.respond`, `run.pause`, waitpoints and `generateResumeUrl`
862
- throw.
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.91.0 --from <activepieces checkout>
1088
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.92.3 --from <activepieces checkout>
921
1089
  ```
922
1090
 
923
1091
  ## Design documents