41 lines
3.3 KiB
Markdown
41 lines
3.3 KiB
Markdown
# Job Catalogue
|
||
|
||
Papercrate stores asynchronous work in the shared `jobs` table. Each job carries a
|
||
`tenant_id`, a small JSON payload, and one of the statuses defined in
|
||
`backend/src/jobs.rs` (`queued`, `processing`, `succeeded`, `failed`). Workers
|
||
continuously reserve jobs by type and execute the appropriate handler. This
|
||
document lists every job type that is currently recognized by the backend and
|
||
briefly describes what it does.
|
||
|
||
| Job type | Payload shape | When it is enqueued | Work performed |
|
||
| --- | --- | --- | --- |
|
||
| `analyze-document` | `{ "document_id": Uuid, "document_version_id": Uuid, "force": bool }` | Uploading a document, calling the re-analyze bulk action, or after a metadata edit (e.g. title change) | Runs the taskflow pipeline (`GenerateThumbnailsTask`, `GenerateOcrTask`, `DetermineIssuedAtTask`, `IndexDocumentTask`) for the specified document version. The handler refuses to run if the tenant is not `Active`. |
|
||
| `purge-document` | `{ "document_id": Uuid }` | `DELETE /api/documents/{id}` after the document has been trashed | Removes every version and asset object from tenant storage, deletes database rows (`documents`, `document_versions`, associated assets/tags/correspondents), and leaves the system ready for GC. |
|
||
| `provision-tenant` | `{ "members": [Uuid, ...] }` | When a tenant is created with status `creating` | Creates/ensures the tenant’s Quickwit index, materializes the system capability sets (`owner`, `user`, `readonly`, `webdav`), attaches the initial member list, and flips the tenant status to `active`. |
|
||
| `delete-tenant` | `{ "remove_tenant": bool, "tenant_name": string, "action": "delete"\|"reset", "nonce": string, "issued_at": RFC3339 datetime, "signature": hex(HMAC-SHA256), "final_status"?: "active"\|"suspended" }` | Administrative action after a tenant has been marked `deleting` | Deletes all tenant-scoped storage objects, wipes the tenant’s Quickwit index (and optionally deletes it entirely), truncates the tenant schemas/tables, removes queued jobs for that tenant, and either deletes the tenant row or leaves it in the requested final status (defaults to `suspended`) while recreating an empty Quickwit index. |
|
||
|
||
## Retired job types
|
||
|
||
`generate-thumbnails` and `generate-ocr-text` once existed as standalone jobs.
|
||
Those behaviors now run as tasks inside `analyze-document`. No worker is
|
||
registered for the legacy types; keep them out of new payloads.
|
||
|
||
### Tenant delete/reset safety checks
|
||
|
||
The `delete-tenant` job refuses to run without a signed payload. The admin CLI
|
||
derives a message of the form `v1|tenant_id|tenant_name|action|nonce|issued_at|final_status`
|
||
and signs it with an HMAC-SHA256 key based on the server’s JWT secret.
|
||
Workers verify the signature, ensure the payload matches the job flags, and
|
||
require the `issued_at` timestamp to be no more than five minutes old. This
|
||
protects against accidental wipes triggered by stale requests or insufficiently
|
||
scoped API calls.
|
||
|
||
## Operational notes
|
||
|
||
* Every job handler calls `ensure_active_tenant` (or an equivalent guard) before
|
||
touching tenant data. If a tenant is suspended or deleting, the job will fail
|
||
immediately.
|
||
* Jobs are only enqueued for the tenant they operate on. Consequently, wiping a
|
||
tenant with `delete-tenant` also removes any remaining queued jobs for that
|
||
tenant so workers do not waste effort on work that can no longer succeed.
|