99 lines
2.7 KiB
Markdown
99 lines
2.7 KiB
Markdown
# API: hyper-p2p-cron-gossip
|
|
|
|
**Protocol:** `cron-gossip/v1`
|
|
|
|
**Export:** `{ HyperP2PCronGossip, PROTOCOL }`
|
|
|
|
## Overview
|
|
|
|
`HyperP2PCronGossip` stores jobs in a local `Map` keyed by `jobId`. `schedule(expr, jobId)` registers an expression. `tick(now)` evaluates due jobs, emits `fire`, and gossips `cron-fire` to peers. Remote fires update `lastRun` and emit `remote-fire`. Expressions support `@every Nms|s|m|h` or five-field UTC cron (`minute hour day month weekday`).
|
|
|
|
## Constructor
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `topic` | `string` \| `Buffer` \| `null` | `null` | Hyperswarm topic |
|
|
| `keyPair` | `KeyPair` | `hypercore-crypto.keyPair()` | Swarm identity; `peerHex` derived for gossip |
|
|
|
|
## Methods
|
|
|
|
### `schedule(expr, jobId)`
|
|
|
|
- **Returns:** `{ jobId, expr, lastRun, at }` job record
|
|
- **Throws:** `ValidationError` if `jobId` or `expr` empty
|
|
- **Emits:** `schedule`
|
|
|
|
### `unschedule(jobId)`
|
|
|
|
- **Returns:** `boolean` — whether job existed
|
|
|
|
### `tick(now = Date.now())`
|
|
|
|
Evaluates all jobs; fires due ones.
|
|
|
|
- **Returns:** `string[]` — fired `jobId` list
|
|
- **Emits:** `fire` per local job
|
|
|
|
### `list()` / `get(jobId)`
|
|
|
|
Snapshots of registered jobs.
|
|
|
|
### `async ready()` / `async close()`
|
|
|
|
`close()` clears jobs, destroys swarm, emits `closed`.
|
|
|
|
### `getStats()`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `scheduled` | `number` | `schedule` calls |
|
|
| `fired` | `number` | Local tick fires |
|
|
| `gossipIn` / `gossipOut` | `number` | Wire counters |
|
|
| `jobs` | `number` | Map size |
|
|
| `protocol` | `string` | `cron-gossip/v1` |
|
|
|
|
## Events
|
|
|
|
| Event | Payload | When |
|
|
|-------|---------|------|
|
|
| `schedule` | job object | `schedule()` |
|
|
| `fire` | `{ jobId, at }` | Local `tick` fired job |
|
|
| `remote-fire` | `{ jobId, peer, at }` | Inbound `cron-fire` |
|
|
| `closed` | — | `close()` |
|
|
|
|
## getStats()
|
|
|
|
Shallow copy with live `jobs` count.
|
|
|
|
## Wire
|
|
|
|
| type | fields | direction | behavior |
|
|
|------|--------|-----------|----------|
|
|
| `cron-fire` | `jobId`, `expr`, `peer`, `at` | bidirectional | Update/create job `lastRun`; emit `remote-fire` |
|
|
|
|
Gossip only sends when `_peerMsgs` is populated (after `ready()` + connections).
|
|
|
|
## Cron expression helpers
|
|
|
|
| Form | Example | Semantics |
|
|
|------|---------|-----------|
|
|
| `@every` | `@every 30s` | Interval since `lastRun` |
|
|
| Five-field | `0 * * * *` | UTC minute/hour/day/month/weekday match |
|
|
|
|
## Errors
|
|
|
|
| Message | Source |
|
|
|---------|--------|
|
|
| `jobId is required` / `expr is required` | `schedule` |
|
|
| `topic is required for createSwarm` | swarm |
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
cd modules/scheduling-queues/hyper-p2p-cron-gossip
|
|
npm install && npm test
|
|
bare examples/basic.js
|
|
```
|
|
|
|
Drive `tick` with injected `now` for deterministic tests.
|