98 lines
2.2 KiB
Markdown
98 lines
2.2 KiB
Markdown
# API: hyper-p2p-bucket-rate-limit
|
|
|
|
**Protocol:** `bucket-rate-limit/v1`
|
|
|
|
**Export:** `HyperP2PBucketRateLimit`
|
|
|
|
## Overview
|
|
|
|
Production measurement & rate control module: Hyperswarm discovery + Protomux when `topic` is set.
|
|
|
|
## Constructor
|
|
|
|
```js
|
|
const mod = new HyperP2PBucketRateLimit(opts)
|
|
```
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `topic` | varies | null | topic |
|
|
| `keyPair` | KeyPair | random Ed25519 | keyPair |
|
|
| `rate` | number | 10 | rate |
|
|
| `burst` | number | 20 | burst |
|
|
| `syncIntervalMs` | number | 10000 (ms) | Background sync interval |
|
|
| `enableBackgroundTimers` | boolean | `false` | Periodic timers (off in tests) |
|
|
|
|
## Methods
|
|
|
|
### `configure({ rate, burst })`
|
|
|
|
- **Returns:** `value`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `snapshot(—)`
|
|
|
|
- **Returns:** `value`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `getBucket(peerId)`
|
|
|
|
- **Returns:** `value`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `tryConsume(peerId, cost = 1)`
|
|
|
|
- **Returns:** `value`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `sync(—)`
|
|
|
|
- **Returns:** `value`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `ready(—)`
|
|
|
|
- **Returns:** `Promise`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `getStats(—)`
|
|
|
|
- **Returns:** `object`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
### `close(—)`
|
|
|
|
- **Returns:** `Promise<void>`
|
|
- **Throws:** — (none documented in method body)
|
|
|
|
## Events
|
|
|
|
| Event | Payload |
|
|
|-------|---------|
|
|
| `closed` | no payload |
|
|
| `configure` | snap |
|
|
| `consume` | tokens |
|
|
| `reject` | payload object |
|
|
| `remote-configure` | rate, burst |
|
|
| `sync` | snap |
|
|
|
|
## getStats()
|
|
|
|
Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
|
|
Library-only modules may include `mode: 'local'`.
|
|
|
|
## Errors
|
|
|
|
Stable message substrings: see [`../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
|
|
|
|
## P2P
|
|
|
|
When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `bucket-rate-limit/v1`.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
npm install && npm test
|
|
```
|
|
|
|
Integration: [`../../real_tests/integration/bucket-rate-limit-two-node.js`](../../../real_tests/integration/bucket-rate-limit-two-node.js) |