ablative docs

Go to

↑↓ move↵ openesc close
 Stack Notebook ablative.com.au

Worker deployment HTTP API

Create, read, replace and remove durable builtin worker deployments.

Open .md

Routes and fields

GET /worker-deployments
List durable deployment records and undecodable rows separately. Requires enabled deployment and the deploy grant.
GET /worker-deployments/{name}
Read one durable worker record; absent names return not-found.
PUT /worker-deployments/{name}
Create or replace. Required body fields: artifact, namespaces, task_queue, desired. Optional node. Returns outcome and deployment. The node acts on the new desired state before answering.
POST /worker-deployments/{name}/desired-state
Body: {"desired":"running"} or {"desired":"stopped"}. Persists desired state and asks this node’s supervisor to apply it.
DELETE /worker-deployments/{name}
Delete the record and ask supervision to stop and forget the process. Returns existed plus the removed deployment; a missing name returns not-found. Read logs if stopping fails.
Artifact
Only type builtin is accepted. verb is the argument list after this server’s executable path. The server captures its binary identity. Names beginning auto/ are reserved.

Put a record

Save this worker document at the named path on the server host. Replace that path and the gRPC endpoint in the deployment request for your installation. The queue and launch arguments must agree with the document.

//! Serve a prompt by returning its text.
worker reviewers
  action review(prompt: String) -> String
    run text "printf %s {{prompt}}"

Start with desired stopped so you can inspect the record before launching it.

curl --fail-with-body -sS -X PUT "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers" \
  -H "authorization: Bearer $AION_TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"artifact":{"type":"builtin","verb":["worker","awl","/srv/aion/reviewers.awl","--endpoint","http://127.0.0.1:50051","--namespace","default","--concurrency","2","--reconnect-initial-backoff","0.1","--reconnect-max-backoff","5","--reconnect-max-attempts","100"]},"namespaces":["default"],"task_queue":"reviewers","node":null,"desired":"stopped"}'

The builtin artifact launches the server executable with the declared worker command. The supervisor supplies its deployment identity. This request includes concurrency and reconnect settings; add the worker authentication settings required by your server.

Read and start

curl --fail-with-body -sS -X GET "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers" \
  -H "authorization: Bearer $AION_TOKEN"
curl --fail-with-body -sS -X GET "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/workers/managed" \
  -H "authorization: Bearer $AION_TOKEN"

After reviewing the launch and supervision policy, request running state.

curl --fail-with-body -sS -X POST "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers/desired-state" \
  -H "authorization: Bearer $AION_TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"desired":"running"}'

Replacement updates the stored launch and replaces a supervised instance using the old launch. Read the managed status and logs to confirm the new process registered successfully.

The implementation is in the HTTP router’s worker deployment family and the worker deployment handlers. Deletion logs a stopping failure even after deleting its record; retain the process identity before deleting a running deployment.