@helipod/fleet 0.1.0 → 0.1.2
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 +37 -0
- package/package.json +13 -13
package/README.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# @helipod/fleet
|
|
2
|
+
|
|
3
|
+
Multi-node fleet mode for Helipod: run several `helipod serve` nodes against one Postgres database, with a lease-elected writer, read/sync nodes serving from embedded replicas, and sharded write scale-out.
|
|
4
|
+
|
|
5
|
+
## License
|
|
6
|
+
|
|
7
|
+
Source-available under the Helipod Commercial License (see the LICENSE file in this package). In the current phase it is free to use in production — no license key is required. It may not be copied, modified, or distributed as part of a product or service that competes with Helipod, and it does not convert to an open-source license.
|
|
8
|
+
|
|
9
|
+
## What it provides
|
|
10
|
+
|
|
11
|
+
- **Lease-based writer election with live failover.** Nodes boot symmetrically; a Postgres lease decides which node is the writer. If the writer dies or wedges, a sync node acquires the expired lease and promotes itself — no manual intervention. The failover clock scales from a single lease-TTL knob (`HELIPOD_FLEET_LEASE_TTL_MS`, default 15000 ms).
|
|
12
|
+
- **Sync/read nodes with embedded replicas.** Non-writer nodes tail the commit log into a local SQLite replica and serve queries and reactive subscriptions from it, forwarding mutations to the current writer with read-your-own-writes catch-up.
|
|
13
|
+
- **Group commit.** Batches concurrent commits into fewer Postgres flushes for higher write throughput (enabled via `HELIPOD_GROUP_COMMIT`).
|
|
14
|
+
- **Sharded write scale-out.** Writes are partitioned across per-shard leases (shard count from `HELIPOD_FLEET_SHARDS`, persisted at first boot and immutable after), with a balancer distributing shard ownership across nodes and an offline reshard path (`reshardFleet`) for changing the count on a stopped deployment.
|
|
15
|
+
- **Fencing.** A node that loses its lease fails closed (`FencedError`) rather than continuing to write.
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
Install alongside `helipod` in the project you deploy:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
bun add helipod @helipod/fleet
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Fleet mode is activated per node by `helipod serve --fleet`. The CLI has no static dependency on this package — when `--fleet` is passed it loads `@helipod/fleet` via dynamic import at runtime and fails fast with an actionable message if the package is not installed.
|
|
26
|
+
|
|
27
|
+
Each fleet node needs a Postgres URL and the URL other nodes can reach it at:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
helipod serve --fleet \
|
|
31
|
+
--database-url postgres://user:pass@db-host:5432/helipod \
|
|
32
|
+
--advertise-url http://this-node:3000
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`HELIPOD_FLEET=1`, `HELIPOD_DATABASE_URL`, and env equivalents of the flags are also honored (flags win). Start additional nodes with the same `--database-url` and their own `--advertise-url`; roles (writer vs sync) are decided at boot and re-decided on failover.
|
|
36
|
+
|
|
37
|
+
Part of [Helipod](https://github.com/helipod-sh/helipod) — docs at https://helipod-six.vercel.app/docs
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@helipod/fleet",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -26,21 +26,21 @@
|
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
28
|
"pg": "^8.13.1",
|
|
29
|
-
"@helipod/errors": "0.1.
|
|
30
|
-
"@helipod/docstore-postgres": "0.1.
|
|
31
|
-
"@helipod/docstore": "0.1.
|
|
32
|
-
"@helipod/docstore-sqlite": "0.1.
|
|
33
|
-
"@helipod/runtime-embedded": "0.1.
|
|
34
|
-
"@helipod/index-key-codec": "0.1.
|
|
35
|
-
"@helipod/id-codec": "0.1.
|
|
36
|
-
"@helipod/values": "0.1.
|
|
29
|
+
"@helipod/errors": "0.1.2",
|
|
30
|
+
"@helipod/docstore-postgres": "0.1.2",
|
|
31
|
+
"@helipod/docstore": "0.1.2",
|
|
32
|
+
"@helipod/docstore-sqlite": "0.1.2",
|
|
33
|
+
"@helipod/runtime-embedded": "0.1.2",
|
|
34
|
+
"@helipod/index-key-codec": "0.1.2",
|
|
35
|
+
"@helipod/id-codec": "0.1.2",
|
|
36
|
+
"@helipod/values": "0.1.2"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
39
|
"@electric-sql/pglite": "^0.2.17",
|
|
40
|
-
"@helipod/executor": "0.1.
|
|
41
|
-
"@helipod/test": "0.1.
|
|
42
|
-
"@helipod/scheduler": "0.1.
|
|
43
|
-
"@helipod/transactor": "0.1.
|
|
40
|
+
"@helipod/executor": "0.1.2",
|
|
41
|
+
"@helipod/test": "0.1.2",
|
|
42
|
+
"@helipod/scheduler": "0.1.2",
|
|
43
|
+
"@helipod/transactor": "0.1.2",
|
|
44
44
|
"@types/pg": "^8.11.10",
|
|
45
45
|
"@types/node": "^22.10.5",
|
|
46
46
|
"@types/ws": "^8.5.13",
|