Definition

A queue definition is one JSON object, stored at <host>/taskhoster-queues/<name>.json. It has five top-level keys: taskhoster-settings, taskhoster-access, and the three schemas taskhoster-schema-item, taskhoster-schema-progress and taskhoster-schema-result. Only taskhoster-schema-item is meaningful to supply; everything else defaults. The same parser validates it on the local package (before syncing) and on the server (on receipt). User definitions live in the sibling taskhoster-users/ folder.

Full shape

{
  "taskhoster-settings": {
    "taskhoster-leaseSeconds": 60,
    "taskhoster-queueSeconds": 3600,
    "taskhoster-retainSeconds": 3600,
    "taskhoster-retainFrom": "finished",
    "taskhoster-archivePayloads": false
  },
  "taskhoster-access": {
    "taskhoster-post":  { "taskhoster-public": bool, "taskhoster-users": ["<name>", …] },
    "taskhoster-fetch": { "taskhoster-public": bool, "taskhoster-users": [ … ] },
    "taskhoster-work":  { "taskhoster-public": bool, "taskhoster-users": [ … ] }
  },
  "taskhoster-schema-item":     [ { "taskhoster-name": "<name>", "taskhoster-type": …, "taskhoster-required": bool, "taskhoster-max": N }, … ],
  "taskhoster-schema-progress": [ … ],
  "taskhoster-schema-result":   [ … ]
}

`taskhoster-settings`

All keys optional. A value that is missing, negative or non-numeric falls back to the default; taskhoster-retainFrom falls back if it is not one of the two allowed strings.

Key	Type	Default	Meaning
`taskhoster-leaseSeconds`	number ≥ 0	`60`	How long a claim holds an item before the sweep re-queues it.
`taskhoster-queueSeconds`	number ≥ 0	`3600`	Maximum item lifetime from post; on expiry the item fails with `error: "timeout"`.
`taskhoster-retainSeconds`	number ≥ 0	`3600`	How long a done item and its result are kept before deletion.
`taskhoster-retainFrom`	`"finished"` \| `"fetched"`	`"finished"`	When the retain clock starts: at completion, or at the producer's first read of the result.
`taskhoster-archivePayloads`	boolean	`false`	Whether to keep each task's payload bodies in the durable Task Logs history (Store → the payload archive), separate from the queue's own storage. The history records payload sizes either way.

`taskhoster-access`

Each of the three operations is an object, { "taskhoster-public": bool, "taskhoster-users": [ … ] }. An operation is allowed if the presented token belongs to a user in taskhoster-users, OR taskhoster-public is true; both may be on at once. A missing or empty rule grants nothing; the default is fully closed.

Key	Governs
`taskhoster-post`	Posting an item. The authenticated user's name is recorded as the item's `postedBy` (`null` when the post was public/anonymous).
`taskhoster-fetch`	Reading status and the monitor socket.
`taskhoster-work`	Claim, progress, result and the work socket.

Rule key	Type	Default	Meaning
`taskhoster-public`	boolean	`false`	When `true`, the operation needs no credential.
`taskhoster-users`	array of names	`[]`	The users whose token grants the operation.

The schema blocks

Each of taskhoster-schema-item, taskhoster-schema-progress and taskhoster-schema-result is an array of field objects. A field object carries its name in taskhoster-name plus its spec. taskhoster-schema-progress and taskhoster-schema-result default to empty ([]) if omitted. See Types for the spec keys and every field type.

Block	Validated on	Notes
`taskhoster-schema-item`	`POST /<queue>`	The task a producer posts.
`taskhoster-schema-progress`	`…/progress`	Only the last accepted progress record is retained.
`taskhoster-schema-result`	`…/result`	Finishes the item. An `error` field here is the idiom for in-band failures.

Every field object needs a non-empty taskhoster-name, and names must be unique within a schema. A missing or unknown taskhoster-type is rejected on push; an enum without a non-empty taskhoster-values array is rejected too.

Annotated example

{
  "taskhoster-settings": {
    "taskhoster-leaseSeconds": 120,      // a worker holds a claim for 2 minutes
    "taskhoster-queueSeconds": 600,      // a task lives at most 10 minutes, then fails "timeout"
    "taskhoster-retainSeconds": 3600,    // keep the result for an hour...
    "taskhoster-retainFrom": "fetched",  // ...counted from when the producer first reads it
    "taskhoster-archivePayloads": true   // keep task bodies in the durable Task Logs history
  },
  "taskhoster-access": {
    "taskhoster-post":  { "taskhoster-public": true,  "taskhoster-users": [] },          // anyone may submit a job
    "taskhoster-fetch": { "taskhoster-public": false, "taskhoster-users": ["alice"] },   // alice may read status
    "taskhoster-work":  { "taskhoster-public": false, "taskhoster-users": ["worker1"] }  // worker1 may claim and complete
  },
  "taskhoster-schema-item": [
    { "taskhoster-name": "url",    "taskhoster-type": "url",  "taskhoster-required": true },   // required source
    { "taskhoster-name": "format", "taskhoster-type": "enum", "taskhoster-values": ["png","jpg","webp"], "taskhoster-required": true },
    { "taskhoster-name": "width",  "taskhoster-type": "integer" },                             // optional
    { "taskhoster-name": "blob",   "taskhoster-type": "blob", "taskhoster-max": 5000000 }      // optional inline payload
  ],
  "taskhoster-schema-progress": [
    { "taskhoster-name": "percent", "taskhoster-type": "integer" }
  ],
  "taskhoster-schema-result": [
    { "taskhoster-name": "output", "taskhoster-type": "blob" },   // the finished artifact, base64
    { "taskhoster-name": "error",  "taskhoster-type": "text" }    // set instead of output on an app-level failure
  ]
}

User definitions

The users named in an access rule are defined in the domain's sibling taskhoster-users/ folder: one file per user, at <host>/taskhoster-users/<name>.json. A user file is a small JSON object; its taskhoster-name must match the filename, and taskhoster-token is a 32-character hex string you author yourself (mint one with any random source, as Usage → Local shows). The local package validates and syncs these exactly like queue files.

{
  "taskhoster-name": "alice",
  "taskhoster-token": "0123456789abcdef0123456789abcdef"
}

The user Alice, defined in alice.json

Key	Type	Meaning
`taskhoster-name`	string	The user's name; must equal the file's stem (`alice.json` → `"alice"`).
`taskhoster-token`	32 hex chars	The bearer token this user presents. A caller sends it as `Authorization: Bearer <token>` (or `?token=` on a socket).