@astrale-os/sdk 0.6.0-beta.54 → 0.6.0-beta.56
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/dist/application/action/authoring.d.ts +2 -0
- package/dist/application/action/authoring.js +1 -0
- package/dist/application/action/context.d.ts +6 -1
- package/dist/application/action/index.d.ts +2 -0
- package/dist/application/action/index.js +1 -0
- package/dist/application/file/binary.d.ts +11 -0
- package/dist/application/file/binary.js +45 -0
- package/dist/application/file/file.d.ts +72 -0
- package/dist/application/file/file.js +111 -0
- package/dist/application/file/index.d.ts +4 -0
- package/dist/application/file/index.js +2 -0
- package/dist/application/file/input.d.ts +13 -0
- package/dist/application/file/input.js +57 -0
- package/dist/application/mutation/authoring/properties.d.ts +12 -1
- package/dist/application/mutation/authoring/properties.js +6 -3
- package/dist/application/runtime/runtime.js +12 -0
- package/dist/execution/invocation/dispatch/context.d.ts +2 -2
- package/dist/execution/invocation/dispatch/context.js +22 -2
- package/dist/execution/invocation/invocation.js +1 -1
- package/dist/execution/invocation/result/errors.js +8 -0
- package/dist/index.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/dist/testing/file.d.ts +20 -0
- package/dist/testing/file.js +49 -0
- package/dist/testing/index.d.ts +4 -2
- package/dist/testing/index.js +3 -2
- package/docs/durable-workflows.md +55 -0
- package/docs/handler-dependencies.md +160 -68
- package/package.json +8 -8
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { ReceivedFile } from '../application/file/index.js';
|
|
2
|
+
/** What a test file declares besides its bytes. */
|
|
3
|
+
export interface TestFileOptions {
|
|
4
|
+
/** The file's media type. Default: `text/plain` for a string, else the Blob's type, else `application/octet-stream`. */
|
|
5
|
+
readonly type?: string;
|
|
6
|
+
/** The receipt the file object carries. Default: a new `test-receipt-<n>`. */
|
|
7
|
+
readonly receipt?: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* A file object as a handler receives it at a `file()` field, over bytes held in memory: a handler
|
|
11
|
+
* unit test passes it in its input without a Kernel. Each read yields the same bytes, under the same
|
|
12
|
+
* limits as a received file; a Mutation attaches it as its `receipt`.
|
|
13
|
+
*
|
|
14
|
+
* ```ts
|
|
15
|
+
* import * as testing from '@astrale-os/sdk/testing'
|
|
16
|
+
*
|
|
17
|
+
* const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export declare function file(content: string | Uint8Array | Blob, options?: TestFileOptions): ReceivedFile;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { receivedFile } from '../application/file/index.js';
|
|
2
|
+
let receipts = 0;
|
|
3
|
+
/**
|
|
4
|
+
* A file object as a handler receives it at a `file()` field, over bytes held in memory: a handler
|
|
5
|
+
* unit test passes it in its input without a Kernel. Each read yields the same bytes, under the same
|
|
6
|
+
* limits as a received file; a Mutation attaches it as its `receipt`.
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* import * as testing from '@astrale-os/sdk/testing'
|
|
10
|
+
*
|
|
11
|
+
* const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
export function file(content, options = {}) {
|
|
15
|
+
if (options === null || typeof options !== 'object') {
|
|
16
|
+
throw new TypeError('Test file options must be an object.');
|
|
17
|
+
}
|
|
18
|
+
const mediaType = options.type ??
|
|
19
|
+
(typeof content === 'string'
|
|
20
|
+
? 'text/plain'
|
|
21
|
+
: content instanceof Blob && content.type !== ''
|
|
22
|
+
? content.type
|
|
23
|
+
: 'application/octet-stream');
|
|
24
|
+
// The bytes as they are now: a later change to `content` never reaches the file.
|
|
25
|
+
const held = typeof content === 'string'
|
|
26
|
+
? new TextEncoder().encode(content)
|
|
27
|
+
: content instanceof Uint8Array
|
|
28
|
+
? content.slice()
|
|
29
|
+
: content instanceof Blob
|
|
30
|
+
? content
|
|
31
|
+
: invalidContent();
|
|
32
|
+
const read = async () => held instanceof Blob ? new Uint8Array(await held.arrayBuffer()) : held.slice();
|
|
33
|
+
receipts += 1;
|
|
34
|
+
const receipt = (options.receipt ?? `test-receipt-${receipts}`);
|
|
35
|
+
return receivedFile(receipt, async () => {
|
|
36
|
+
const bytes = await read();
|
|
37
|
+
return {
|
|
38
|
+
body: (async function* () {
|
|
39
|
+
if (bytes.byteLength > 0)
|
|
40
|
+
yield bytes;
|
|
41
|
+
})(),
|
|
42
|
+
length: bytes.byteLength,
|
|
43
|
+
mediaType,
|
|
44
|
+
};
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
function invalidContent() {
|
|
48
|
+
throw new TypeError('Test file content must be a string, a Uint8Array, or a Blob.');
|
|
49
|
+
}
|
package/dist/testing/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Development and test resources: schema-admitted demo Datasets, their lazy project references,
|
|
3
|
-
*
|
|
2
|
+
* Development and test resources: schema-admitted demo Datasets, their lazy project references, an
|
|
3
|
+
* in-memory engine that runs durable Workflows, and file objects for handler unit tests.
|
|
4
4
|
*/
|
|
5
5
|
export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
|
|
6
6
|
export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetReferences, DatasetReferenceInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
|
|
@@ -12,5 +12,7 @@ export { isTests, tests } from './tests.js';
|
|
|
12
12
|
export type { Tests, TestsInput } from './tests.js';
|
|
13
13
|
export { createTestWorkflowEngine } from './durable/index.js';
|
|
14
14
|
export type { TestExecution, TestJournalEntry, TestStartOptions, TestStepCapabilities, TestWorkflowEngine, TestWorkflowEngineOptions, } from './durable/index.js';
|
|
15
|
+
export { file } from './file.js';
|
|
16
|
+
export type { TestFileOptions } from './file.js';
|
|
15
17
|
export { checkQuery } from './query.js';
|
|
16
18
|
export type { CheckQueryOptions } from './query.js';
|
package/dist/testing/index.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Development and test resources: schema-admitted demo Datasets, their lazy project references,
|
|
3
|
-
*
|
|
2
|
+
* Development and test resources: schema-admitted demo Datasets, their lazy project references, an
|
|
3
|
+
* in-memory engine that runs durable Workflows, and file objects for handler unit tests.
|
|
4
4
|
*/
|
|
5
5
|
export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
|
|
6
6
|
export { loadDataset, loadDatasets } from './load.js';
|
|
7
7
|
export { dataset, isDatasetReference } from './reference.js';
|
|
8
8
|
export { isTests, tests } from './tests.js';
|
|
9
9
|
export { createTestWorkflowEngine } from './durable/index.js';
|
|
10
|
+
export { file } from './file.js';
|
|
10
11
|
export { checkQuery } from './query.js';
|
|
@@ -18,6 +18,13 @@ remind: method({
|
|
|
18
18
|
A durable callable needs `authenticated` or `authorized` auth, a value input and output, and a
|
|
19
19
|
remote binding. Implement it with `defineWorkflow`; `defineAction` refuses a durable callable.
|
|
20
20
|
|
|
21
|
+
A durable Workflow receives each `file()` input field as a file reference, a string, not a file
|
|
22
|
+
object. A receipt is bound to the user who uploaded it and lives 15 minutes, while the Steps act as
|
|
23
|
+
the Domain and the run may last longer. At the durable start the Kernel therefore checks each
|
|
24
|
+
receipt for the caller and against the field's `maxBytes` and `mediaTypes`, and replaces it by a
|
|
25
|
+
reference bound to this Execution and to the Domain; neither the Execution record nor the engine
|
|
26
|
+
journal holds the receipt. See [Files in a durable Workflow](#files-in-a-durable-workflow).
|
|
27
|
+
|
|
21
28
|
```ts
|
|
22
29
|
export const remind = defineWorkflow<typeof schema>()(
|
|
23
30
|
'Invoice.remind',
|
|
@@ -202,6 +209,54 @@ a result the Workflow handles, such as a declared error; unmapped, the engine re
|
|
|
202
209
|
Step spends its budget. A retried Step whose Mutation already committed still receives that commit's
|
|
203
210
|
receipt, even though its precondition no longer holds.
|
|
204
211
|
|
|
212
|
+
## Files in a durable Workflow
|
|
213
|
+
|
|
214
|
+
A `file()` field of a durable callable reaches the Workflow as a file reference: the Kernel
|
|
215
|
+
exchanged the caller's receipt for it when it started the Execution, after checking the receipt for
|
|
216
|
+
the caller and the file against the field's `maxBytes` and `mediaTypes`. A refused receipt refuses
|
|
217
|
+
the call with `FUNCTION_INPUT_INVALID`, the refusal's code as its reason and the field's JSON
|
|
218
|
+
Pointer as `path`, and no Execution is recorded. A replay of the same idempotency key compares each
|
|
219
|
+
file field by its content, so the same file under a fresh receipt is the same call; a replay still
|
|
220
|
+
needs a valid receipt.
|
|
221
|
+
|
|
222
|
+
A Step uses the reference wherever a receipt goes, through its own `kernel` and `mutate`, which act
|
|
223
|
+
as the Domain for this Execution:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
export const importBalance = defineWorkflow<typeof schema>()(
|
|
227
|
+
'importBalance',
|
|
228
|
+
async ({ input, step }) => {
|
|
229
|
+
const lines = await step.run('count-lines', async ({ kernel }) => {
|
|
230
|
+
const { body } = await kernel.content.download({ receipt: input.balance })
|
|
231
|
+
// A Uint8Array, or chunks as they arrive.
|
|
232
|
+
const chunks = body instanceof Uint8Array ? [body] : await Array.fromAsync(body)
|
|
233
|
+
return new TextDecoder().decode(await new Blob(chunks).bytes()).split('\n').length
|
|
234
|
+
})
|
|
235
|
+
await step.mutate(
|
|
236
|
+
'attach',
|
|
237
|
+
recordBalance, // writes input.balance as the TrialBalance `source` blob Property
|
|
238
|
+
{ fiscalYear: input.fiscalYear, balance: input.balance },
|
|
239
|
+
{ as: 'executor' },
|
|
240
|
+
)
|
|
241
|
+
return { lines }
|
|
242
|
+
},
|
|
243
|
+
)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
- **Bound to its run.** The reference is accepted only from a Step of the Execution it names, as
|
|
247
|
+
the Domain, while the engine holds that run unfinished and for at most 7 days. The caller cannot
|
|
248
|
+
use it, nor another Execution of the same Domain, nor anyone once the run ended. It never expires
|
|
249
|
+
within the run: a Step may read or attach it long after the original receipt expired.
|
|
250
|
+
- **Attach to keep the file.** While the run lasts its Execution keeps the content. Afterwards only
|
|
251
|
+
the Nodes a Step attached it to keep it: attach the file in a Step, and keep the Node.
|
|
252
|
+
- **Not passed on.** A Step cannot hand its reference to a child durable call, which accepts only a
|
|
253
|
+
receipt of its caller: attach the file, then pass the Node.
|
|
254
|
+
- **No file object yet.** The Workflow receives the reference string, not the file object an Action
|
|
255
|
+
receives (`stream()`, `text()`, `bytes()`), so the field's `maxBytes` and `mediaTypes` are checked
|
|
256
|
+
by the Kernel at the start and by the Property when a Step attaches the file, not on each read.
|
|
257
|
+
- **The envelope.** The run's engine input names each reference in `files`, its JSON Pointer and
|
|
258
|
+
`Ref`; the SDK does not need it to run the Workflow.
|
|
259
|
+
|
|
205
260
|
## Testing
|
|
206
261
|
|
|
207
262
|
`createTestWorkflowEngine` from `@astrale-os/sdk/testing` runs a durable Workflow in memory with
|
|
@@ -102,98 +102,190 @@ refuses it for any other. Cancellation and the parent deadline are inherited. A
|
|
|
102
102
|
the deadline; a child does not inherit the parent's idempotency key. Detached
|
|
103
103
|
`const { invoke } = dependencies.directory.caller` keeps its types and authority binding.
|
|
104
104
|
|
|
105
|
+
## Receiving a file
|
|
106
|
+
|
|
107
|
+
A file never travels inside a call. The client uploads its bytes to the Kernel first, and the call
|
|
108
|
+
carries the receipt the upload returned: a signed string, bound to the user who uploaded the file,
|
|
109
|
+
valid for 15 minutes. A callable declares where it takes a file with a `file()` input field. Its
|
|
110
|
+
handler receives a file object there, reads the file with the caller's authority if it needs to,
|
|
111
|
+
and attaches it to a blob Property, also as the caller.
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { defineAction, type ReceivedFile } from '@astrale-os/sdk/action'
|
|
115
|
+
import { defineMutation } from '@astrale-os/sdk/mutation'
|
|
116
|
+
import { classIcon, defineSchema, file, func, nodeClass, property, schema } from '@astrale-os/sdk/schema'
|
|
117
|
+
import { z } from 'zod'
|
|
118
|
+
|
|
119
|
+
const source = property(schema.values.blob({ maxBytes: 20_000_000, mediaTypes: ['text/csv'] }))
|
|
120
|
+
const TrialBalance = nodeClass({
|
|
121
|
+
icon: classIcon.neutral,
|
|
122
|
+
properties: { fiscalYear: z.string(), source },
|
|
123
|
+
policies: { read: true },
|
|
124
|
+
})
|
|
125
|
+
const Schema = defineSchema('ledger.example', {
|
|
126
|
+
name: 'Ledger',
|
|
127
|
+
classes: { TrialBalance },
|
|
128
|
+
functions: {
|
|
129
|
+
importBalance: func({
|
|
130
|
+
auth: 'authenticated',
|
|
131
|
+
input: z.strictObject({
|
|
132
|
+
fiscalYear: z.string(),
|
|
133
|
+
balance: file(source), // the field states the Property's constraints
|
|
134
|
+
attachments: z.array(file({ maxBytes: 5_000_000 })).max(10),
|
|
135
|
+
}),
|
|
136
|
+
output: z.string(),
|
|
137
|
+
}),
|
|
138
|
+
},
|
|
139
|
+
})
|
|
140
|
+
|
|
141
|
+
const recordBalance = defineMutation<typeof Schema>()('trialBalance.record', {
|
|
142
|
+
build(input: { fiscalYear: string; balance: ReceivedFile }, { TrialBalance }, mutation) {
|
|
143
|
+
mutation.createNode({
|
|
144
|
+
as: 'balance',
|
|
145
|
+
class: TrialBalance,
|
|
146
|
+
props: { fiscalYear: input.fiscalYear, source: input.balance }, // attached as it is
|
|
147
|
+
})
|
|
148
|
+
},
|
|
149
|
+
})
|
|
150
|
+
|
|
151
|
+
export const importBalance = defineAction<typeof Schema>()(
|
|
152
|
+
'importBalance',
|
|
153
|
+
async ({ input, mutate }) => {
|
|
154
|
+
const csv = await input.balance.text() // whole file, in memory: 10 MiB at most
|
|
155
|
+
if (!csv.startsWith('account,')) throw new Error('Not a trial balance.')
|
|
156
|
+
await mutate(recordBalance, input, { as: 'caller' })
|
|
157
|
+
return csv.split('\n').length.toString()
|
|
158
|
+
},
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`ReceivedFile` is exported by `@astrale-os/sdk/action`. A client sends the file in two steps,
|
|
163
|
+
upload then call, or lets the typed `invoke` of a Client Session upload a `Blob` or `File` found at
|
|
164
|
+
a `file()` field before it calls:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const { receipt } = await session.content.upload(csv, { mediaType: 'text/csv' })
|
|
168
|
+
await session.invoke(reference(ledger, ledger.functions.importBalance), {
|
|
169
|
+
fiscalYear: '2026',
|
|
170
|
+
balance: receipt,
|
|
171
|
+
attachments: [],
|
|
172
|
+
})
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Reading the file
|
|
176
|
+
|
|
177
|
+
| Member | Returns |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| `receipt` | The receipt the caller sent. |
|
|
180
|
+
| `stream()` | A `ReadableStream<Uint8Array>` of the file, for a file of any size. |
|
|
181
|
+
| `text()` | The whole file decoded as UTF-8. |
|
|
182
|
+
| `bytes()` | The whole file as a `Uint8Array`. |
|
|
183
|
+
|
|
184
|
+
- **As the caller.** Each read downloads the file again with `kernel.caller.content.download({
|
|
185
|
+
receipt })`. The receipt is the caller's: the Kernel refuses it to this Domain's own authority,
|
|
186
|
+
and to any other user, with `BLOB_RECEIPT_INVALID`. Nothing is kept between reads; a file read
|
|
187
|
+
twice is downloaded twice.
|
|
188
|
+
- **In memory up to `FILE_MEMORY_LIMIT`.** `text()` and `bytes()` hold the whole file, so they
|
|
189
|
+
refuse a file larger than `FILE_MEMORY_LIMIT` (10 MiB, exported by `@astrale-os/sdk/action`) with
|
|
190
|
+
`FileReadError` `FILE_MEMORY_LIMIT`, before reading it when its size is known. Read a larger file
|
|
191
|
+
with `stream()`.
|
|
192
|
+
- **Complete or failed.** `text()` and `bytes()` resolve only once the whole file arrived with the
|
|
193
|
+
size the Kernel declared and passed its integrity check. `stream()` hands chunks over as they
|
|
194
|
+
arrive and fails at its end if the file does not: write nothing derived from it anywhere lasting
|
|
195
|
+
before the stream ends. Cancelling the stream cancels the download.
|
|
196
|
+
- **The field's constraints.** The SDK checks a field's `maxBytes` and `mediaTypes` on each read
|
|
197
|
+
and refuses a file outside them with `FileReadError` (`FILE_TOO_LARGE`, `FILE_MEDIA_TYPE`). The
|
|
198
|
+
Kernel never checks them against a receipt; clients check them before they upload. A file
|
|
199
|
+
attached without being read is checked by the Kernel against the Property's own constraints only,
|
|
200
|
+
so a field that feeds a Property should state them: `file(source)` copies them, and
|
|
201
|
+
`file(source, { maxBytes })` may narrow them.
|
|
202
|
+
- **Refusals reach the caller.** A `FileReadError` the handler does not catch reaches the caller as
|
|
203
|
+
`LIMIT_EXCEEDED` (size) or `VALIDATION_ERROR` (media type) with its code as the reason, and the
|
|
204
|
+
Kernel's refusal of a receipt reaches it as the Kernel sent it.
|
|
205
|
+
|
|
206
|
+
### Attaching the file
|
|
207
|
+
|
|
208
|
+
A blob Property value takes the file object as it is in every Mutation the SDK authors (`mutate`,
|
|
209
|
+
`graph.mutate`, a defined Mutation's `build`, `createNode`, `updateNode`) and writes its receipt.
|
|
210
|
+
Attach as the caller, `mutate(definition, input, { as: 'caller' })` or `graph.caller.mutate`, since
|
|
211
|
+
only the user who uploaded the file can attach its receipt; the Kernel then applies the caller's
|
|
212
|
+
permissions to the write and the Property's constraints to the file. The raw Kernel builder of
|
|
213
|
+
`kernel.caller.mutate((m) => ...)` takes `file.receipt`. Attaching never reads the file.
|
|
214
|
+
|
|
215
|
+
- **Within 15 minutes.** A receipt expires 15 minutes after its upload. Read and attach the file in
|
|
216
|
+
the invocation that received it; keep the attached Node, never the receipt.
|
|
217
|
+
- **Authenticated callables only.** A file is read and attached as the caller, and a call to an
|
|
218
|
+
`anonymous` callable may carry no caller. The runtime refuses a `file()` field in the input of an
|
|
219
|
+
`anonymous` callable when it is built or served.
|
|
220
|
+
- **Passing it on.** To hand the file to a dependency that takes it in a `file()` field, send its
|
|
221
|
+
receipt as the caller: `dependencies.files.caller.invoke(d => d.functions.scan, { file:
|
|
222
|
+
input.balance.receipt })`.
|
|
223
|
+
- **Durable Workflows.** A durable Workflow's input holds a file reference at each `file()`
|
|
224
|
+
field, not a file object: at the durable start the Kernel exchanges the caller's receipt for a
|
|
225
|
+
reference bound to the Execution, which its Steps use as the Domain wherever a receipt goes
|
|
226
|
+
(`kernel.content.download({ receipt })`, a blob Property value) while the run lasts. See
|
|
227
|
+
[Files in a durable Workflow](durable-workflows.md#files-in-a-durable-workflow).
|
|
228
|
+
|
|
229
|
+
### Testing a handler
|
|
230
|
+
|
|
231
|
+
`testing.file(content, { type })` from `@astrale-os/sdk/testing` makes a file object over bytes
|
|
232
|
+
held in memory: a handler unit test passes it in its input without a Kernel. It reads the same bytes
|
|
233
|
+
on every read, under the same limits, and a Mutation attaches it as its `receipt`.
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
import * as testing from '@astrale-os/sdk/testing'
|
|
237
|
+
|
|
238
|
+
const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
|
|
239
|
+
await expect(balance.text()).resolves.toBe('account,amount\n512,10')
|
|
240
|
+
```
|
|
241
|
+
|
|
105
242
|
## Binary Function input
|
|
106
243
|
|
|
244
|
+
A binary input carries a stream the Function processes as it arrives and does not store, such as a
|
|
245
|
+
payload it forwards, transforms, or measures. To receive a file the Domain stores, use a `file()`
|
|
246
|
+
field (see [Receiving a file](#receiving-a-file)).
|
|
247
|
+
|
|
107
248
|
A Function can declare `input.binary(metadataSchema, { maximumBytes })`. The handler receives
|
|
108
249
|
validated JSON metadata in `ctx.input` and a single-consumer `ReadableStream<Uint8Array>` plus its
|
|
109
250
|
declared byte `length` in `ctx.body`. Consume the stream through EOF before returning a successful
|
|
110
251
|
result. The bytes stay outside `Call.input` and are sent as the HTTP request body.
|
|
111
252
|
|
|
112
253
|
```ts
|
|
113
|
-
const
|
|
114
|
-
d => d.functions.
|
|
254
|
+
const digest = await dependencies.hasher.caller.invoke(
|
|
255
|
+
d => d.functions.digest,
|
|
115
256
|
{ mediaType: file.type },
|
|
116
257
|
{ body: file },
|
|
117
258
|
)
|
|
118
|
-
await kernel.invoke(
|
|
119
|
-
await kernel.call({ target:
|
|
259
|
+
await kernel.invoke(digestReference, { mediaType: file.type }, { body: file })
|
|
260
|
+
await kernel.call({ target: digestReference.target, input: { mediaType: file.type } }, { body: file })
|
|
120
261
|
```
|
|
121
262
|
|
|
122
263
|
The typed `invoke` overload requires `body` for a binary Function and forbids it for a value-input
|
|
123
264
|
Function. Raw `call` and `dispatch` also accept `{ body }`; the Server checks the resolved Function
|
|
124
265
|
contract. A binary input cannot use `idempotencyKey`.
|
|
125
266
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
memory. Decoding Base64 from a JSON input and uploading the resulting `Uint8Array` holds the whole
|
|
132
|
-
file, several times over, in memory.
|
|
133
|
-
|
|
134
|
-
```ts
|
|
135
|
-
const schema = defineSchema('files.example', {
|
|
136
|
-
name: 'Files',
|
|
137
|
-
functions: {
|
|
138
|
-
attach: func({
|
|
139
|
-
auth: 'authenticated',
|
|
140
|
-
// Methods cannot take a binary input: the target Node travels in the metadata.
|
|
141
|
-
input: input.binary(z.strictObject({ document: z.string(), mediaType: z.string() }), {
|
|
142
|
-
maximumBytes: 100 * 1024 * 1024,
|
|
143
|
-
}),
|
|
144
|
-
output: z.null(),
|
|
145
|
-
}),
|
|
146
|
-
},
|
|
147
|
-
})
|
|
148
|
-
|
|
149
|
-
export const attach = defineWorkflow<typeof schema>()(
|
|
150
|
-
'attach',
|
|
151
|
-
async ({ body, graph, input, kernel, step }) => {
|
|
152
|
-
const receipt = await step.run('store-file', async () => {
|
|
153
|
-
const uploaded = await kernel.caller.content.upload(body, { mediaType: input.mediaType })
|
|
154
|
-
return uploaded.receipt
|
|
155
|
-
})
|
|
156
|
-
await step.run('record-file', () =>
|
|
157
|
-
graph.caller.mutate(recordFile, { document: NodeId(input.document), receipt }),
|
|
158
|
-
)
|
|
159
|
-
return null
|
|
160
|
-
},
|
|
161
|
-
)
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
`recordFile` stands for the Domain's own Mutation that sets the blob Property from the receipt. The
|
|
165
|
-
rules:
|
|
166
|
-
|
|
167
|
-
- **One attempt.** A stream is read once, so its upload is never retried, follows no Redirect, and
|
|
168
|
-
is cancelled when it fails before reading through its end. A failed upload rejects, and only the
|
|
169
|
-
caller can send the file again. Do not wrap the upload in a retry, do not read or `tee()` the body
|
|
170
|
-
first, and do not upload it from a durable Workflow, whose Steps are retried: store it in an Action
|
|
171
|
-
or in a Step of an inline Workflow, as above.
|
|
267
|
+
- **One reader.** `ctx.body` is the Kernel's own binary request body, `{ body:
|
|
268
|
+
ReadableStream<Uint8Array>, length }`. It is read once: do not `tee()` it or read it from a
|
|
269
|
+
durable Workflow, whose Steps are retried. `kernel.content.upload` still accepts it unread, and
|
|
270
|
+
streams it to the Kernel as it arrives in one attempt that is never retried, but a file the Domain
|
|
271
|
+
stores belongs in a `file()` field.
|
|
172
272
|
- **The declared length is exact.** The Server admits the body against the length its caller
|
|
173
|
-
declared
|
|
273
|
+
declared; a body that ends early or runs over fails.
|
|
174
274
|
- **Declare `maximumBytes` on each binary Function.** It bounds what that Function accepts, and is
|
|
175
|
-
checked against the declared length before the handler runs.
|
|
176
|
-
the blob Property the file is stored in, and within the Kernel's 100 MiB blob limit when the
|
|
177
|
-
file goes to the Kernel: the Kernel refuses an upload past either, but only once the request has
|
|
178
|
-
reached the handler.
|
|
275
|
+
checked against the declared length before the handler runs.
|
|
179
276
|
- **The deployment follows the Domain.** The Server also caps every streamed request, before any
|
|
180
277
|
Function is chosen, with its `maximumBinaryRequestBytes`. A Worker built by the Cloudflare
|
|
181
278
|
adapter sets it to the largest `maximumBytes` among its Domain's binary Functions, so its
|
|
182
279
|
`maximumRequestBytes` (1 MiB by default, 16 MiB at most) bounds only the bodies it buffers. A
|
|
183
280
|
larger body is refused with `413` and `LIMIT_EXCEEDED` before the handler runs. A binary request
|
|
184
281
|
lives up to 30 minutes, or the deployment's `invocationTimeoutMs` when that is longer, and is
|
|
185
|
-
cancelled after 60 seconds without a new chunk while the handler reads it
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
and Pro, 200 MB on Business, more on Enterprise. 100 MiB is 104,857,600 bytes, slightly above
|
|
191
|
-
100 MB, so on Free and Pro declare at most `100_000_000`.
|
|
282
|
+
cancelled after 60 seconds without a new chunk while the handler reads it. A Domain without a
|
|
283
|
+
binary Function keeps the Server defaults. A host that composes `serve()` itself states these in
|
|
284
|
+
its `server.limits` (`maximumBinaryRequestBytes`, `binaryRequestTimeoutMs`,
|
|
285
|
+
`binaryRequestIdleTimeoutMs`). Cloudflare refuses a request body past its plan's limit before the
|
|
286
|
+
Worker runs: 100 MB on Free and Pro, 200 MB on Business, more on Enterprise.
|
|
192
287
|
- **Methods cannot take a binary input.** Declare a Function that names its target Node in the
|
|
193
|
-
metadata
|
|
194
|
-
`graph.caller`, so the Kernel applies the caller's permissions to both.
|
|
195
|
-
- **Receipts expire.** Record the receipt (`expiresAt`) right after the upload, in the same
|
|
196
|
-
invocation.
|
|
288
|
+
metadata.
|
|
197
289
|
|
|
198
290
|
`domain.dependencies` remains immutable loaded Schema metadata. `dependencies` is a separate frozen
|
|
199
291
|
map containing only direct non-Kernel aliases. Each alias exposes exactly `.caller` and `.self`,
|
|
@@ -247,8 +339,8 @@ const shipment = await step.run('ship', ({ dependencies }) =>
|
|
|
247
339
|
)
|
|
248
340
|
```
|
|
249
341
|
|
|
250
|
-
Inline Steps do not imply a distributed transaction, durable replay, or remote deduplication. Stream
|
|
251
|
-
binary objects cannot become portable step results; a native streaming response belongs in an
|
|
342
|
+
Inline Steps do not imply a distributed transaction, durable replay, or remote deduplication. Stream,
|
|
343
|
+
binary, and received file objects cannot become portable step results; a native streaming response belongs in an
|
|
252
344
|
Action. Invocation sessions remain open until a returned stream or binary body settles.
|
|
253
345
|
|
|
254
346
|
Integrations remain useful for consumer-owned substitution, replay metadata, or failure translation.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astrale-os/sdk",
|
|
3
|
-
"version": "0.6.0-beta.
|
|
3
|
+
"version": "0.6.0-beta.56",
|
|
4
4
|
"description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"astrale",
|
|
@@ -258,15 +258,15 @@
|
|
|
258
258
|
"registry": "https://registry.npmjs.org/"
|
|
259
259
|
},
|
|
260
260
|
"dependencies": {
|
|
261
|
-
"@astrale-os/kernel-client": "1.0.0-beta.
|
|
262
|
-
"@astrale-os/kernel-core": "1.0.0-beta.
|
|
263
|
-
"@astrale-os/kernel-dsl": "1.0.0-beta.
|
|
264
|
-
"@astrale-os/kernel-protocol": "1.0.0-beta.
|
|
265
|
-
"@astrale-os/kernel-server": "1.0.0-beta.
|
|
261
|
+
"@astrale-os/kernel-client": "1.0.0-beta.38",
|
|
262
|
+
"@astrale-os/kernel-core": "1.0.0-beta.35",
|
|
263
|
+
"@astrale-os/kernel-dsl": "1.0.0-beta.23",
|
|
264
|
+
"@astrale-os/kernel-protocol": "1.0.0-beta.35",
|
|
265
|
+
"@astrale-os/kernel-server": "1.0.0-beta.35",
|
|
266
266
|
"@lucide/icons": "1.34.0",
|
|
267
267
|
"@typescript/native-preview": "7.0.0-dev.20260707.2",
|
|
268
268
|
"cross-spawn": "7.0.6",
|
|
269
|
-
"hono": "^4.13.
|
|
269
|
+
"hono": "^4.13.11",
|
|
270
270
|
"jose": "^6.2.9",
|
|
271
271
|
"semver": "7.8.5",
|
|
272
272
|
"typescript": "~6.0.3"
|
|
@@ -278,7 +278,7 @@
|
|
|
278
278
|
"@cloudflare/workers-types": "^5.20261023.1",
|
|
279
279
|
"@commitlint/cli": "~21.2.2",
|
|
280
280
|
"@commitlint/config-conventional": "~21.2.2",
|
|
281
|
-
"@hono/node-server": "^2.1.
|
|
281
|
+
"@hono/node-server": "^2.1.3",
|
|
282
282
|
"@hono/node-server-v1": "npm:@hono/node-server@1.19.10",
|
|
283
283
|
"@restatedev/restate-sdk": "1.17.0",
|
|
284
284
|
"@restatedev/restate-sdk-cloudflare-workers": "1.17.0",
|