Queues

A queue is a single JSON file. Its folder decides its address; its contents decide the shape of the tasks it accepts and how they behave over time. Sync the file with the local package and the queue is live.

{
  "taskhoster-settings": {
    "taskhoster-leaseSeconds": 120,
    "taskhoster-queueSeconds": 600,
    "taskhoster-retainSeconds": 3600,
    "taskhoster-retainFrom": "fetched",
    "taskhoster-archivePayloads": true
  },
  "taskhoster-access": {
    "taskhoster-post":  { "taskhoster-public": true,  "taskhoster-users": [] },
    "taskhoster-fetch": { "taskhoster-public": false, "taskhoster-users": ["alice"] },
    "taskhoster-work":  { "taskhoster-public": false, "taskhoster-users": ["worker1"] }
  },
  "taskhoster-schema-item": [
    { "taskhoster-name": "url",    "taskhoster-type": "url",  "taskhoster-required": true },
    { "taskhoster-name": "format", "taskhoster-type": "enum", "taskhoster-values": ["png", "jpg", "webp"], "taskhoster-required": true },
    { "taskhoster-name": "width",  "taskhoster-type": "integer" },
    { "taskhoster-name": "blob",   "taskhoster-type": "blob", "taskhoster-max": 5000000 }
  ],
  "taskhoster-schema-progress": [
    { "taskhoster-name": "percent", "taskhoster-type": "integer" }
  ],
  "taskhoster-schema-result": [
    { "taskhoster-name": "output", "taskhoster-type": "blob" },
    { "taskhoster-name": "error",  "taskhoster-type": "text" }
  ]
}

A queue definition, taskhoster-queues/resize.json: anyone posts, alice reads status, worker1 works it.

Shape

A definition has five parts, all optional except taskhoster-schema-item: taskhoster-settings, taskhoster-access, and the three schemas below. Anything you omit takes its default.

Settings

taskhoster-settings holds the lifecycle timings. Each is optional and falls back to its default (a missing, negative or non-numeric value is ignored).

Field	Type	Default	Meaning
`taskhoster-leaseSeconds`	integer	`60`	How long a worker may hold a claimed item before its lease lapses and the item is re-queued.
`taskhoster-queueSeconds`	integer	`3600`	Maximum item lifetime from posting; once past it the item terminally fails with `error: "timeout"`.
`taskhoster-retainSeconds`	integer	`3600`	How long a finished or failed item (and its result) is kept before deletion.
`taskhoster-retainFrom`	`"finished"` \| `"fetched"`	`"finished"`	When the retain clock starts: when the result is posted, or when a producer first reads it.
`taskhoster-archivePayloads`	boolean	`false`	Whether to keep each task's payload bodies (item, progress, result, error) in the durable Task Logs history, separate from the queue's own storage. Off by default; the history always records payload sizes regardless.

taskhoster-queueSeconds bounds the whole life of a task, not one attempt. Keep it well above taskhoster-leaseSeconds or items time out mid-flight.

Access

taskhoster-access gives one rule for each operation: taskhoster-post, taskhoster-fetch and taskhoster-work. A rule is an object of:

Field	Type	Meaning
`taskhoster-public`	boolean	Whether anyone may perform the operation without a token. Default `false`.
`taskhoster-users`	array of names	Which users' tokens grant it. Default `[]`.

The operation is allowed if a listed user's token is presented, OR taskhoster-public is true. Both may be on at once; a missing block grants nothing. The three cover posting (taskhoster-post), reading status and the monitor socket (taskhoster-fetch), and claiming, progress, result and the work socket (taskhoster-work).

Schemas

Each of taskhoster-schema-item, taskhoster-schema-progress and taskhoster-schema-result is an array of field objects, and every field object carries:

Field	Type	Meaning
`taskhoster-name`	text	The field's name: its key in a submission. Required.
`taskhoster-type`	field type	One of `text`, `email`, `url`, `integer`, `number`, `boolean`, `blob`, `enum`. Default `text`.
`taskhoster-required`	boolean	Whether a submission must include it. Default `false`.
`taskhoster-max`	integer	Maximum string length before coercion. Default `8000`; for a `blob`, `8388608` (8 MiB of base64).
`taskhoster-values`	array	For an `enum`, the allowed values.

Unknown fields in a submission are dropped, not rejected; the only per-field failures are a missing taskhoster-required field or a value that doesn't match its type.

Item schema

The task a producer posts, validated on POST. The only required schema.

Progress schema

An optional progress record a worker posts while working; only the last one is kept and shown in status.

Result schema

What finishes a task, validated when a worker posts a result. An error field here lets a worker report an application failure in-band, distinct from the terminal "timeout".

The folder layout

One folder per queue host (named exactly for the domain) with two fixed directories: taskhoster-queues/ holding one .json file per queue, and taskhoster-users/ holding one file per user. A queue file's name (without the extension) is the queue's name and its endpoint path.

task.example.com/            queue host  →  https://task.example.com
  taskhoster-queues/
    resize.json               queue "resize"    →  /resize
    thumbnail.json            queue "thumbnail" →  /thumbnail
  taskhoster-users/
    alice.json                user "alice"      (a name + token)
    worker1.json              user "worker1"

So the resize.json above answers at https://task.example.com/resize (post), /resize/items/<id> (status), /resize/claim (claim), and the /resize/monitor and /resize/work sockets. Both folders are mirrored to the server by the local package.