The source contract

A source answers three calls under its destination’s address. Each call carries Authorization: Bearer <token>, and every body is JSON. A source that works is examples/notes: the three calls, in one file that uses only Go’s standard library.

With an address of https://notes.example.com/api/worker, the first call is GET https://notes.example.com/api/worker/ping.

Ping

check calls it to prove the address and the token, and shows waiting, how many jobs wait. It claims nothing.

Claim

• capabilities lists what the source may hand out now: those the operator allowed for it, minus any that is resting. Hand out no job for another.
• limit is how many jobs to hand out at most; sandcastle asks for 1.
• jobs may be empty.
• A job has three fields, and sandcastle reads no other. Any other field, such as a destination or a url, has no effect.
  • id: a number or a text, without slashes, backslashes, dots or spaces. A job without an id makes the whole answer unreadable.
  • capability: claude or ocr.
  • input: what the capability takes.
• A claimed job is held for this worker for as long as the source decides. sandcastle sends a result for every job it claimed, unless it stops in the middle.

Result

• released means “not now, and not the job’s fault”: the capability could not be used. Offer the job again without counting an attempt.
• Answer 409 when the source no longer holds the job for this worker. sandcastle keeps the result in its record and does not send it again.
• An output is untrusted. Check its shape before you use it.

Answers

• 401 or 403 to any call means the token is wrong. check says so, and names the secret to set.
• Any other answer outside 2xx fails the call; sandcastle shows the first line of its body.
• A redirect is never followed, and fails the call.
• Each call has 30 seconds. An answer may be up to 32 MiB.