@haneinfo/background-jobs 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -26
- package/agent-guide.md +72 -56
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,26 +1,42 @@
|
|
|
1
|
-
# @haneinfo/background-jobs
|
|
2
|
-
|
|
3
|
-
Database-backed jobs for internal Haneinfo Apps. No external queue is required.
|
|
4
|
-
|
|
5
|
-
Install the plugin, copy `prisma/background-jobs.prisma` into the App's Prisma schema and create
|
|
6
|
-
a migration. Register handlers during module initialization on every worker replica:
|
|
7
|
-
|
|
8
|
-
```ts
|
|
9
|
-
jobs.register('example.batch', async (params, context) => {
|
|
10
|
-
await context.checkpoint();
|
|
11
|
-
// Use context.tx for database writes; check context.signal/checkpoint between batches.
|
|
12
|
-
await context.progress(50);
|
|
13
|
-
return { processed: 10 };
|
|
14
|
-
});
|
|
15
|
-
const job = await jobs.enqueue({ type: 'example.batch', params: {}, createdBy: userId });
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
`BackgroundJobsModule.register(config)` exports the service, worker and MCP tools. The plugin
|
|
19
|
-
factory is `backgroundJobs()` from `@haneinfo/background-jobs/plugin`. Apps register MCP tools
|
|
20
|
-
explicitly with `BackgroundJobsMcpTools.registerInto(registry, { scopeNamespace })`.
|
|
21
|
-
|
|
22
|
-
`GET /background-jobs/:id` uses interactive authentication. `get_job_status` requires
|
|
23
|
-
`<namespace>:jobs:read` and a bound user. Both return 404 for another creator's job, including
|
|
24
|
-
administrators. MCP parameters, result and error text are wrapped in `$userContent`.
|
|
25
|
-
|
|
26
|
-
See [agent-guide.md](agent-guide.md) for transaction, retry and cancellation contracts.
|
|
1
|
+
# @haneinfo/background-jobs
|
|
2
|
+
|
|
3
|
+
Database-backed jobs for internal Haneinfo Apps. No external queue is required.
|
|
4
|
+
|
|
5
|
+
Install the plugin, copy `prisma/background-jobs.prisma` into the App's Prisma schema and create
|
|
6
|
+
a migration. Register handlers during module initialization on every worker replica:
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
jobs.register('example.batch', async (params, context) => {
|
|
10
|
+
await context.checkpoint();
|
|
11
|
+
// Use context.tx for database writes; check context.signal/checkpoint between batches.
|
|
12
|
+
await context.progress(50);
|
|
13
|
+
return { processed: 10 };
|
|
14
|
+
});
|
|
15
|
+
const job = await jobs.enqueue({ type: 'example.batch', params: {}, createdBy: userId });
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`BackgroundJobsModule.register(config)` exports the service, worker and MCP tools. The plugin
|
|
19
|
+
factory is `backgroundJobs()` from `@haneinfo/background-jobs/plugin`. Apps register MCP tools
|
|
20
|
+
explicitly with `BackgroundJobsMcpTools.registerInto(registry, { scopeNamespace })`.
|
|
21
|
+
|
|
22
|
+
`GET /background-jobs/:id` uses interactive authentication. `get_job_status` requires
|
|
23
|
+
`<namespace>:jobs:read` and a bound user. Both return 404 for another creator's job, including
|
|
24
|
+
administrators. MCP parameters, result and error text are wrapped in `$userContent`.
|
|
25
|
+
|
|
26
|
+
See [agent-guide.md](agent-guide.md) for transaction, retry and cancellation contracts.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Instance lifecycle (draft 202610-f1a8)
|
|
30
|
+
|
|
31
|
+
Implemented from draft decision 202610-f1a8; the decision remains draft. Upgrade state-machine,
|
|
32
|
+
list-view, collaboration, attachments, import-export, assignment and timer together. No frontend,
|
|
33
|
+
automatic archive or bulk lifecycle operations are included. Permanently purged data cannot be
|
|
34
|
+
restored by this API: database and private file backups must cover the entire deletion retention
|
|
35
|
+
period and be restored consistently.
|
|
36
|
+
|
|
37
|
+
State-machine optionally registers state-machine.instances.purge. Its producer follows the same
|
|
38
|
+
bootstrap/interval/disable/shutdown pattern as attachment cleanup. The job handler uses context.tx
|
|
39
|
+
for events, garbage markers, cascade and success status; failures/cancellation roll back the entire
|
|
40
|
+
batch before normal retry. The state-machine package owns retention, batch bounds and producer
|
|
41
|
+
settings. Core worker enablement and runDue behavior are unchanged. Attachments.cleanup separately
|
|
42
|
+
recycles the committed garbage markers. No change to the core job table or retry policy is needed.
|
package/agent-guide.md
CHANGED
|
@@ -1,56 +1,72 @@
|
|
|
1
|
-
# Background jobs — Agent Guide
|
|
2
|
-
|
|
3
|
-
Use this package for long-running, database-backed work. Import/export producers are separate
|
|
4
|
-
packages; this package provides no file generation, import confirmation or download endpoint.
|
|
5
|
-
|
|
6
|
-
## Runtime contract
|
|
7
|
-
|
|
8
|
-
Provides capability `haneinfo.background-jobs` and plugin-api token `BACKGROUND_JOBS` /
|
|
9
|
-
`BackgroundJobsPort`. A producer plugin declares that capability in `requires`, injects the token
|
|
10
|
-
and registers its handler at module initialization. The host imports the existing provider module
|
|
11
|
-
along that dependency edge. Do not import/register a second BackgroundJobsModule from a producer.
|
|
12
|
-
|
|
13
|
-
- Register a stable lowercase dotted/dashed type with `BackgroundJobsService.register(type, handler)`
|
|
14
|
-
at module initialization. Duplicate types fail. All worker replicas must register the same handlers.
|
|
15
|
-
- `enqueue({ type, params, createdBy, maxRetries? })` is an internal API. The producing package
|
|
16
|
-
authenticates and authorizes the request and supplies the authenticated creator, never a client id.
|
|
17
|
-
- A short committed transaction claims `(id, PENDING, attempt, cancelRequested=false)` by compare-and-set.
|
|
18
|
-
Each attempt then runs in its own business transaction. Use `context.tx` for all database effects.
|
|
19
|
-
Success/result and business writes commit together. Failed/cancelled attempts roll back their effects;
|
|
20
|
-
their control-state update is committed separately. One handler failure does not block later jobs.
|
|
21
|
-
- `maxRetries` is the number of additional attempts, not total attempts. `attempt` counts claims;
|
|
22
|
-
`retryCount` counts failed attempts, including terminal failure. Cancellation does not consume retries.
|
|
23
|
-
Retries are eligible after `retryDelayMs` and are not retried again in the same `runDue()` snapshot.
|
|
24
|
-
- `cancelFor(creatorId, id)` cancels PENDING immediately and flags RUNNING cooperatively. Check
|
|
25
|
-
`checkpoint()` between batches or use the AbortSignal. The cancellation poller aborts that signal;
|
|
26
|
-
a final checkpoint and conditional success update also prevent a cancelled attempt from committing.
|
|
27
|
-
Cancellation racing an already committed success leaves SUCCEEDED. Non-cooperating external calls
|
|
28
|
-
cannot be forcefully interrupted; handlers must make external effects idempotent across retries.
|
|
29
|
-
- `progress(0..100)` persists outside the business transaction; it can be observed while work runs.
|
|
30
|
-
Progress describes attempted work, and may remain on failed/cancelled rows. Retrying resets it to zero.
|
|
31
|
-
- The worker polls one batch at a time per process, waits for its current tick on graceful shutdown,
|
|
32
|
-
and does not poll when disabled. `runDue()` is an explicit operator/test API even when disabled.
|
|
33
|
-
- Claims are durable. A process crash can leave RUNNING work stranded. There is deliberately no
|
|
34
|
-
automatic stale-claim stealing: restarting work without an idempotency/recovery policy could repeat
|
|
35
|
-
external effects. Operators must investigate before a controlled repair; a lease/recovery API is
|
|
36
|
-
a future decision. Pool capacity must allow the business transaction plus control reads/writes.
|
|
37
|
-
|
|
38
|
-
## Configuration
|
|
39
|
-
|
|
40
|
-
The plugin configRef is `backgroundJobs`. Defaults: workerEnabled `true`, pollIntervalMs `1000`,
|
|
41
|
-
batchSize `20`, maxRetries `3`, retryDelayMs `1000`, cancellationPollIntervalMs `250`, and
|
|
42
|
-
transactionTimeoutMs `300000`. Polling starts after the first interval. The plugin validates all
|
|
43
|
-
numeric options; direct module registration uses the same parser. Use `workerEnabled: false` for
|
|
44
|
-
test Apps or replicas without a worker.
|
|
45
|
-
|
|
46
|
-
## Persistence and access
|
|
47
|
-
|
|
48
|
-
`BackgroundJob`: id, type, params, status, progress, result, lastError, attempt, retryCount,
|
|
49
|
-
maxRetries, createdBy, cancelRequested, availableAt, createdAt, startedAt, finishedAt, updatedAt.
|
|
50
|
-
Statuses: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED. Indices cover due polling and creator reads.
|
|
51
|
-
Parameters/results are JSON; future import/export packages can own their payload formats and expiry.
|
|
52
|
-
|
|
53
|
-
Only the creator can read or cancel through the service. There is no administrator override.
|
|
54
|
-
HTTP exposes only status, on the existing interactive auth boundary. MCP exposes only
|
|
55
|
-
`get_job_status`, scope `<namespace>:jobs:read`, with a bound acting user and `$userContent` wrappers.
|
|
56
|
-
No public MCP endpoint is created. Register tools in the App's existing internal registry.
|
|
1
|
+
# Background jobs — Agent Guide
|
|
2
|
+
|
|
3
|
+
Use this package for long-running, database-backed work. Import/export producers are separate
|
|
4
|
+
packages; this package provides no file generation, import confirmation or download endpoint.
|
|
5
|
+
|
|
6
|
+
## Runtime contract
|
|
7
|
+
|
|
8
|
+
Provides capability `haneinfo.background-jobs` and plugin-api token `BACKGROUND_JOBS` /
|
|
9
|
+
`BackgroundJobsPort`. A producer plugin declares that capability in `requires`, injects the token
|
|
10
|
+
and registers its handler at module initialization. The host imports the existing provider module
|
|
11
|
+
along that dependency edge. Do not import/register a second BackgroundJobsModule from a producer.
|
|
12
|
+
|
|
13
|
+
- Register a stable lowercase dotted/dashed type with `BackgroundJobsService.register(type, handler)`
|
|
14
|
+
at module initialization. Duplicate types fail. All worker replicas must register the same handlers.
|
|
15
|
+
- `enqueue({ type, params, createdBy, maxRetries? })` is an internal API. The producing package
|
|
16
|
+
authenticates and authorizes the request and supplies the authenticated creator, never a client id.
|
|
17
|
+
- A short committed transaction claims `(id, PENDING, attempt, cancelRequested=false)` by compare-and-set.
|
|
18
|
+
Each attempt then runs in its own business transaction. Use `context.tx` for all database effects.
|
|
19
|
+
Success/result and business writes commit together. Failed/cancelled attempts roll back their effects;
|
|
20
|
+
their control-state update is committed separately. One handler failure does not block later jobs.
|
|
21
|
+
- `maxRetries` is the number of additional attempts, not total attempts. `attempt` counts claims;
|
|
22
|
+
`retryCount` counts failed attempts, including terminal failure. Cancellation does not consume retries.
|
|
23
|
+
Retries are eligible after `retryDelayMs` and are not retried again in the same `runDue()` snapshot.
|
|
24
|
+
- `cancelFor(creatorId, id)` cancels PENDING immediately and flags RUNNING cooperatively. Check
|
|
25
|
+
`checkpoint()` between batches or use the AbortSignal. The cancellation poller aborts that signal;
|
|
26
|
+
a final checkpoint and conditional success update also prevent a cancelled attempt from committing.
|
|
27
|
+
Cancellation racing an already committed success leaves SUCCEEDED. Non-cooperating external calls
|
|
28
|
+
cannot be forcefully interrupted; handlers must make external effects idempotent across retries.
|
|
29
|
+
- `progress(0..100)` persists outside the business transaction; it can be observed while work runs.
|
|
30
|
+
Progress describes attempted work, and may remain on failed/cancelled rows. Retrying resets it to zero.
|
|
31
|
+
- The worker polls one batch at a time per process, waits for its current tick on graceful shutdown,
|
|
32
|
+
and does not poll when disabled. `runDue()` is an explicit operator/test API even when disabled.
|
|
33
|
+
- Claims are durable. A process crash can leave RUNNING work stranded. There is deliberately no
|
|
34
|
+
automatic stale-claim stealing: restarting work without an idempotency/recovery policy could repeat
|
|
35
|
+
external effects. Operators must investigate before a controlled repair; a lease/recovery API is
|
|
36
|
+
a future decision. Pool capacity must allow the business transaction plus control reads/writes.
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
The plugin configRef is `backgroundJobs`. Defaults: workerEnabled `true`, pollIntervalMs `1000`,
|
|
41
|
+
batchSize `20`, maxRetries `3`, retryDelayMs `1000`, cancellationPollIntervalMs `250`, and
|
|
42
|
+
transactionTimeoutMs `300000`. Polling starts after the first interval. The plugin validates all
|
|
43
|
+
numeric options; direct module registration uses the same parser. Use `workerEnabled: false` for
|
|
44
|
+
test Apps or replicas without a worker.
|
|
45
|
+
|
|
46
|
+
## Persistence and access
|
|
47
|
+
|
|
48
|
+
`BackgroundJob`: id, type, params, status, progress, result, lastError, attempt, retryCount,
|
|
49
|
+
maxRetries, createdBy, cancelRequested, availableAt, createdAt, startedAt, finishedAt, updatedAt.
|
|
50
|
+
Statuses: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED. Indices cover due polling and creator reads.
|
|
51
|
+
Parameters/results are JSON; future import/export packages can own their payload formats and expiry.
|
|
52
|
+
|
|
53
|
+
Only the creator can read or cancel through the service. There is no administrator override.
|
|
54
|
+
HTTP exposes only status, on the existing interactive auth boundary. MCP exposes only
|
|
55
|
+
`get_job_status`, scope `<namespace>:jobs:read`, with a bound acting user and `$userContent` wrappers.
|
|
56
|
+
No public MCP endpoint is created. Register tools in the App's existing internal registry.
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
## Instance lifecycle (draft 202610-f1a8)
|
|
60
|
+
|
|
61
|
+
Implemented from draft decision 202610-f1a8; the decision remains draft. Upgrade state-machine,
|
|
62
|
+
list-view, collaboration, attachments, import-export, assignment and timer together. No frontend,
|
|
63
|
+
automatic archive or bulk lifecycle operations are included. Permanently purged data cannot be
|
|
64
|
+
restored by this API: database and private file backups must cover the entire deletion retention
|
|
65
|
+
period and be restored consistently.
|
|
66
|
+
|
|
67
|
+
State-machine optionally registers state-machine.instances.purge. Its producer follows the same
|
|
68
|
+
bootstrap/interval/disable/shutdown pattern as attachment cleanup. The job handler uses context.tx
|
|
69
|
+
for events, garbage markers, cascade and success status; failures/cancellation roll back the entire
|
|
70
|
+
batch before normal retry. The state-machine package owns retention, batch bounds and producer
|
|
71
|
+
settings. Core worker enablement and runDue behavior are unchanged. Attachments.cleanup separately
|
|
72
|
+
recycles the committed garbage markers. No change to the core job table or retry policy is needed.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@haneinfo/background-jobs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Database-backed background jobs with transactional handlers, retry and cooperative cancellation.",
|
|
6
6
|
"files": [
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"./prisma/background-jobs.prisma": "./prisma/background-jobs.prisma"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
|
-
"@haneinfo/plugin-api": "1.
|
|
32
|
+
"@haneinfo/plugin-api": "1.16.0"
|
|
33
33
|
},
|
|
34
34
|
"peerDependencies": {
|
|
35
35
|
"@haneinfo/common": "^0.3.4 || ^0.4.0",
|
|
@@ -48,9 +48,9 @@
|
|
|
48
48
|
"typescript": "^5.9.3",
|
|
49
49
|
"vitest": "^4.1.11",
|
|
50
50
|
"zod": "^4.4.0",
|
|
51
|
-
"@haneinfo/plugin-host-nest": "2.1.0",
|
|
52
51
|
"@haneinfo/common": "0.4.0",
|
|
53
|
-
"@haneinfo/plugin-testkit": "2.3.0"
|
|
52
|
+
"@haneinfo/plugin-testkit": "2.3.0",
|
|
53
|
+
"@haneinfo/plugin-host-nest": "2.1.0"
|
|
54
54
|
},
|
|
55
55
|
"license": "UNLICENSED",
|
|
56
56
|
"publishConfig": {
|