workflow 5.0.0-beta.30 → 5.0.0-beta.31
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.
|
@@ -47,8 +47,8 @@ Workflow SDK contains the following functions you can use inside your workflow f
|
|
|
47
47
|
<Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
|
|
48
48
|
Access the current workflow run's default stream.
|
|
49
49
|
</Card>
|
|
50
|
-
<Card href="/docs/api-reference/workflow/
|
|
51
|
-
Attach
|
|
50
|
+
<Card href="/docs/api-reference/workflow/set-attributes" title="setAttributes()">
|
|
51
|
+
Attach string metadata to the current workflow run.
|
|
52
52
|
</Card>
|
|
53
53
|
</Cards>
|
|
54
54
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: setAttributes
|
|
3
3
|
description: Attach string metadata to workflow run for observability.
|
|
4
4
|
type: reference
|
|
5
|
-
summary: Use
|
|
5
|
+
summary: Use setAttributes inside a workflow or step function to set run attributes.
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/foundations/workflows-and-steps
|
|
8
8
|
related:
|
|
@@ -12,17 +12,13 @@ related:
|
|
|
12
12
|
|
|
13
13
|
Attaches string metadata to the current workflow run.
|
|
14
14
|
|
|
15
|
-
<Callout>
|
|
16
|
-
This API is experimental and may change before the stable attributes API is released.
|
|
17
|
-
</Callout>
|
|
18
|
-
|
|
19
15
|
```typescript lineNumbers
|
|
20
|
-
import {
|
|
16
|
+
import { setAttributes } from "workflow"
|
|
21
17
|
|
|
22
18
|
export async function orderWorkflow(orderId: string) {
|
|
23
19
|
"use workflow"
|
|
24
20
|
|
|
25
|
-
await
|
|
21
|
+
await setAttributes({
|
|
26
22
|
phase: "received",
|
|
27
23
|
orderId,
|
|
28
24
|
})
|
|
@@ -35,24 +31,24 @@ export async function orderWorkflow(orderId: string) {
|
|
|
35
31
|
|
|
36
32
|
<TSDoc
|
|
37
33
|
definition={`
|
|
38
|
-
import {
|
|
39
|
-
export default
|
|
34
|
+
import { setAttributes } from "workflow";
|
|
35
|
+
export default setAttributes;`}
|
|
40
36
|
showSections={['parameters']}
|
|
41
37
|
/>
|
|
42
38
|
|
|
43
39
|
## Usage
|
|
44
40
|
|
|
45
|
-
Call `
|
|
41
|
+
Call `setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
|
|
46
42
|
|
|
47
43
|
Attribute values must be strings. Pass `undefined` to remove an attribute:
|
|
48
44
|
|
|
49
45
|
```typescript lineNumbers
|
|
50
|
-
import {
|
|
46
|
+
import { setAttributes } from "workflow"
|
|
51
47
|
|
|
52
48
|
export async function cleanupAttributes() {
|
|
53
49
|
"use workflow"
|
|
54
50
|
|
|
55
|
-
await
|
|
51
|
+
await setAttributes({ staleKey: undefined })
|
|
56
52
|
}
|
|
57
53
|
```
|
|
58
54
|
|
|
@@ -62,4 +58,8 @@ Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error)
|
|
|
62
58
|
|
|
63
59
|
Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
|
|
64
60
|
|
|
65
|
-
Native attributes require spec version 4 or later. Step-body storage errors throw from `
|
|
61
|
+
Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.
|
|
62
|
+
|
|
63
|
+
<Callout>
|
|
64
|
+
This function was previously exported as `experimental_setAttributes`. The old name still works as a deprecated alias — update imports to `setAttributes`.
|
|
65
|
+
</Callout>
|
|
@@ -59,7 +59,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
|
|
|
59
59
|
* Each call to `start()` creates a new workflow run. If retried requests must route to one active workflow, have the workflow create a deterministic hook token and use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to reuse an already-registered active hook. The lookup is not atomic with `start()`, so concurrent callers can still create extra runs before the hook is registered; handle that race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can return the active owner to the caller. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Idempotency](/docs/foundations/idempotency#run-idempotency).
|
|
60
60
|
* All arguments must be [serializable](/docs/foundations/serialization).
|
|
61
61
|
* When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
|
|
62
|
-
* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`
|
|
62
|
+
* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`setAttributes`](/docs/api-reference/workflow/set-attributes) option of the same name.
|
|
63
63
|
|
|
64
64
|
<Callout type="info">
|
|
65
65
|
If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
|
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Attributes
|
|
3
|
-
description: Attach
|
|
3
|
+
description: Attach metadata to workflow runs for observability.
|
|
4
4
|
type: reference
|
|
5
5
|
summary: Add string attributes to a workflow run.
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/foundations/workflows-and-steps
|
|
8
8
|
related:
|
|
9
9
|
- /docs/observability
|
|
10
|
-
- /docs/api-reference/workflow/
|
|
10
|
+
- /docs/api-reference/workflow/set-attributes
|
|
11
11
|
- /docs/api-reference/workflow-errors/workflow-world-error
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
This feature is experimental and may change before the stable attributes API is released.
|
|
16
|
-
</Callout>
|
|
17
|
-
|
|
18
|
-
[`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
|
|
14
|
+
[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
|
|
19
15
|
In the future, you'll be able to search and filter runs by attributes.
|
|
20
16
|
|
|
21
17
|
You can also seed any attributes directly when starting a run:
|
|
@@ -28,35 +24,35 @@ const run = await start(orderWorkflow, ["ord_123"], {
|
|
|
28
24
|
```
|
|
29
25
|
|
|
30
26
|
```typescript lineNumbers
|
|
31
|
-
import {
|
|
27
|
+
import { setAttributes } from "workflow"
|
|
32
28
|
|
|
33
29
|
export async function orderWorkflow(orderId: string) {
|
|
34
30
|
"use workflow"
|
|
35
31
|
|
|
36
|
-
await
|
|
32
|
+
await setAttributes({ // [!code highlight]
|
|
37
33
|
phase: "received", // [!code highlight]
|
|
38
34
|
orderId, // [!code highlight]
|
|
39
35
|
}) // [!code highlight]
|
|
40
36
|
|
|
41
37
|
// ...work...
|
|
42
38
|
|
|
43
|
-
await
|
|
39
|
+
await setAttributes({ phase: "complete" }) // [!code highlight]
|
|
44
40
|
}
|
|
45
41
|
```
|
|
46
42
|
|
|
47
43
|
## Usage
|
|
48
44
|
|
|
49
|
-
Call [`
|
|
45
|
+
Call [`setAttributes`](/docs/api-reference/workflow/set-attributes) from a `"use workflow"` function or a `"use step"` function. Plain application code is not supported because there is no active workflow run to attach attributes to.
|
|
50
46
|
|
|
51
47
|
Values must be strings. Pass `undefined` to remove a key:
|
|
52
48
|
|
|
53
49
|
```typescript lineNumbers
|
|
54
|
-
import {
|
|
50
|
+
import { setAttributes } from "workflow"
|
|
55
51
|
|
|
56
52
|
export async function cleanupAttributes() {
|
|
57
53
|
"use workflow"
|
|
58
54
|
|
|
59
|
-
await
|
|
55
|
+
await setAttributes({ staleKey: undefined }) // [!code highlight]
|
|
60
56
|
}
|
|
61
57
|
```
|
|
62
58
|
|
|
@@ -68,7 +64,7 @@ The run details panel in the observability UI shows the run's current attributes
|
|
|
68
64
|
|
|
69
65
|
|
|
70
66
|
|
|
71
|
-
Each `
|
|
67
|
+
Each `setAttributes` call appears on the trace timeline as a diamond marker at the moment the attributes were written:
|
|
72
68
|
|
|
73
69
|
|
|
74
70
|
|
|
@@ -76,12 +72,10 @@ Expanding an `attr_set` event — in the run sidebar or the Events tab — shows
|
|
|
76
72
|
|
|
77
73
|
|
|
78
74
|
|
|
79
|
-
##
|
|
80
|
-
|
|
81
|
-
While attributes are experimental:
|
|
75
|
+
## Behavior
|
|
82
76
|
|
|
83
77
|
- Attributes require a World implementing spec version 4 or later.
|
|
84
78
|
- Writes from workflow and step bodies append native `attr_set` events and immediately materialize `run.attributes`.
|
|
85
79
|
- Storage errors surface rather than being silently ignored: transient errors on workflow-body writes are retried, and a write the World rejects as invalid (for example, exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.
|
|
86
|
-
- Step-body storage errors throw from `
|
|
80
|
+
- Step-body storage errors throw from `setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
|
|
87
81
|
- Reading and querying attributes is not available yet. A query API is planned.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "workflow",
|
|
3
|
-
"version": "5.0.0-beta.
|
|
3
|
+
"version": "5.0.0-beta.31",
|
|
4
4
|
"description": "Workflow SDK - Build durable, resilient, and observable workflows",
|
|
5
5
|
"main": "dist/typescript-plugin.cjs",
|
|
6
6
|
"type": "module",
|
|
@@ -57,18 +57,18 @@
|
|
|
57
57
|
},
|
|
58
58
|
"dependencies": {
|
|
59
59
|
"ms": "2.1.3",
|
|
60
|
-
"@workflow/astro": "5.0.0-beta.
|
|
61
|
-
"@workflow/cli": "5.0.0-beta.
|
|
62
|
-
"@workflow/core": "5.0.0-beta.
|
|
60
|
+
"@workflow/astro": "5.0.0-beta.31",
|
|
61
|
+
"@workflow/cli": "5.0.0-beta.31",
|
|
62
|
+
"@workflow/core": "5.0.0-beta.31",
|
|
63
63
|
"@workflow/errors": "5.0.0-beta.10",
|
|
64
64
|
"@workflow/typescript-plugin": "5.0.0-beta.5",
|
|
65
65
|
"@workflow/utils": "5.0.0-beta.6",
|
|
66
|
-
"@workflow/next": "5.0.0-beta.
|
|
67
|
-
"@workflow/nest": "5.0.0-beta.
|
|
68
|
-
"@workflow/nitro": "5.0.0-beta.
|
|
69
|
-
"@workflow/nuxt": "5.0.0-beta.
|
|
70
|
-
"@workflow/sveltekit": "5.0.0-beta.
|
|
71
|
-
"@workflow/rollup": "5.0.0-beta.
|
|
66
|
+
"@workflow/next": "5.0.0-beta.31",
|
|
67
|
+
"@workflow/nest": "5.0.0-beta.31",
|
|
68
|
+
"@workflow/nitro": "5.0.0-beta.31",
|
|
69
|
+
"@workflow/nuxt": "5.0.0-beta.31",
|
|
70
|
+
"@workflow/sveltekit": "5.0.0-beta.31",
|
|
71
|
+
"@workflow/rollup": "5.0.0-beta.31"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@types/ms": "2.1.0",
|