Skip to content
Hayonix

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.

handler.py
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:

Run the handler locally
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.

Dockerfile
# 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"]
Build and push
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 EXIT

Next

  • Webhooks: get a signed callback when a job finishes.
  • Idempotency: submit jobs safely from a retrying client.