localhost:8780 with no auth, as in the
Quickstart. With auth enabled, add
-H "Authorization: Bearer $TOKEN" to every call.
The Node runtime
Node runs
handler.ts directly with its built-in type stripping, so there is
no compile step. Write TypeScript whose types can simply be erased, and import
local files with their .ts extension. The runtime’s package.json sets
"type": "module", so the handler is an ES module.
Nothing is installed at build time. A function built from source can import
Node’s modules, apache-arrow and its own files under /app. A function that
needs other packages ships as an image.
ListRuntimes returns the exact runtime image for your server:
The protocol
For each invocation the supervisor startsnode /app/handler.ts as a new
process, writes the input to stdin and closes it, takes stdout as the output
and streams stderr to the invocation’s log. A non-zero exit is a crash, with
the exit status and the last 4 KiB of stderr as the error message. An
uncaught exception exits non-zero, so it is reported the same way.
A JSON Schema contract passes one JSON value each way. An Arrow contract
passes one Arrow IPC stream with exactly one record batch each way. See
Contracts.
Write diagnostics with console.error. console.log writes to stdout, which
is the output.
Write a JSON handler
The runtime’s JSON Schema starter reads one value and returns it:handler.ts
readFileSync(0) reads stdin to the end and writeSync(1, ...) writes stdout
before the process exits.
Write an Arrow handler
An Arrow function receives a batch of rows and returns a batch with the same number of rows in the same order. The runtime’s Arrow starter:handler.ts
examples/embed/typescript/handler.ts
is a complete one. It reads id and text columns and returns per row the
cleaned text, its token count and a 64-dimension embedding.
The contract carries both schemas as serialized Arrow IPC. Build them for the
embed example with apache-arrow, in a directory where it is installed
(npm install apache-arrow@21.0.0):
schemas.ts
contract.ts
Deploy from source
A function built from source names the runtime image and carries its files. The server keeps them in its artifacts bucket and hosts extract them over the image at/app, at most 64 files and 1 MiB in total. The runtime runs
handler.ts. Do not send a package.json: it would replace the runtime’s,
and nothing is installed.
1
Create the function
protocol is required and INVOCATION_PROTOCOL_EXEC is the only one
implemented. Leave timeoutMs, maxConcurrency, retries and
resources out to take the defaults: a 30 s timeout, no concurrency
limit, 2 retries, 1 vCPU and 128 MiB.2
Wait for the build
The version starts in
BUILDING and turns READY once a host has built
and snapshotted it. Only a ready version can be invoked.Source builds need the server’s
ARTIFACTS_BUCKET. Without it,
CreateFunction refuses a spec with source.Deploy as an image
Ship an image when the function needs packages beyondapache-arrow. Build
on the runtime so the entrypoint stays node /app/handler.ts. The embed
example’s Dockerfile:
Dockerfile
package.json over the runtime’s, keep
apache-arrow in it if you use Arrow, and run npm install in the
Dockerfile. Then build for the hosts’ architecture and push:
source:
Invoke it
POST the input to/functions/<function-id>/invoke with the contract’s
content type.
Alchemy-Invocation-Id and Alchemy-Version. A handler
that throws answers 500 with the error as JSON, and one past its timeout
answers 504. The function’s Invocations tab shows each call with its
stderr, and the Workbench tab invokes it from the browser. See
HTTP invoke for versions, retries and async calls.
Next steps
Troubleshooting
Read contract violations, crashes, timeouts and build failures.
Runtimes and builds
How a spec becomes a root filesystem and a snapshot.