Quickstarts
Your first serverless endpoint
Write a Python handler with the worker runtime, build it into an image, create an endpoint that scales from zero, run a job and read its streamed output.
A serverless endpoint runs your worker image on demand. Jobs wait in the endpoint's queue; workers start when there is work and stop after they have been idle, so an endpoint with no jobs costs nothing.
Write the handler
A handler takes one job and returns a JSON value. A generator handler streams every value it yields to the caller while it runs, and its return value becomes the job's output.
import time
import serverless_worker as sw
def handler(job: sw.Job):
"""Streams each word of the input text back, then returns a summary."""
words = str(job.input.get("text", "")).split()
for i, word in enumerate(words):
job.check_cancelled() # stop early when the job is canceled
yield {"index": i, "word": word.upper()}
time.sleep(0.1)
return {"words": len(words)}
if __name__ == "__main__":
sw.serve(handler)The worker runtime, serverless_worker (package hayonix-serverless-worker), has no third-party dependencies. Run the same file on your machine, without the platform, by passing a test input:
python handler.py --test-input '{"text": "hello from a worker"}'Build and push the image
Start from the worker base image: Python with the runtime installed, running as an unprivileged user. Any Python image works too, after pip install hayonix-serverless-worker.
# The worker base image: Python with the worker runtime, running as an unprivileged user.
ARG BASE=registry.example.com/team/serverless-worker:0.1.0
FROM ${BASE}
COPY handler.py /app/handler.py
CMD ["python", "/app/handler.py"]IMAGE=registry.example.com/team/word-streamer:1.0.0
docker build -t "$IMAGE" .
docker push "$IMAGE"Push to a registry your endpoint can pull from. For a private registry, add a registry credential to the project and pass its ID as registry_credential_id.
Create the endpoint
The samples read the image reference from IMAGE. skus lists acceptable hardware in order of preference: each new worker takes the first SKU with capacity.
ENDPOINT_ID=$(
jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{
name: "word-streamer", image: $image, skus: [$sku], region: $region, max_workers: 1
}' |
curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints" \
-H "$AUTH" -H "Content-Type: application/json" -d @- |
jq -r .id
)
echo "endpoint $ENDPOINT_ID"The response also holds webhook_secret, which signs completion webhooks. It is returned only here; see Webhooks.
Run a job and follow its output
Submitting a job returns at once with the job queued. The first job on an idle endpoint waits for a worker to start and pull the image (a cold start). The stream long-polls, so chunks arrive as the handler yields them.
JOB_ID=$(
curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID/jobs" \
-H "$AUTH" -H "Content-Type: application/json" \
-d '{"input": {"text": "hello from a worker"}}' |
jq -r .id
)
# Long-poll the stream: each page has the chunks after `next_after`, until `done`.
AFTER=0
while :; do
PAGE=$(curl -sS --fail-with-body \
"$API_BASE_URL/serverless/jobs/$JOB_ID/stream?after=$AFTER&wait=20" -H "$AUTH")
echo "$PAGE" | jq -c '.chunks[] | "chunk: \(.data | tojson)"' -r
AFTER=$(echo "$PAGE" | jq .next_after)
[ "$(echo "$PAGE" | jq .done)" = true ] && break
done
curl -sS --fail-with-body "$API_BASE_URL/serverless/jobs/$JOB_ID?wait=60" -H "$AUTH" |
jq -r '"state: \(.state) output: \(.output | tojson)"'To wait for a short job in the same call, submit it with wait (up to 60 seconds): the response is the finished job, or the job still running when the wait runs out.
Delete the endpoint
Deleting cancels the endpoint's open jobs and removes its workers.
delete_endpoint() {
curl -sS --fail-with-body -X DELETE "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID" \
-H "$AUTH" >/dev/null
echo "deleted $ENDPOINT_ID"
}
trap delete_endpoint EXITNext
- Webhooks: get a signed callback when a job finishes.
- Idempotency: submit jobs safely from a retrying client.