@helipod/objectstore-substrate 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 +12 -12
package/README.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# @helipod/objectstore-substrate
|
|
2
|
+
|
|
3
|
+
Object-storage substrate for Helipod: the durable commit log and manifests live in an object store (S3-compatible or filesystem), while each node keeps a local SQLite database as a queryable cache — storage/compute separation with no standalone database server.
|
|
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
|
+
- **Durable log + manifests in object storage.** Commits are encoded as immutable segments; a manifest object is the source of truth for the log's tip. Local SQLite holds the same data in queryable form and is rebuildable from the bucket.
|
|
12
|
+
- **Writer fencing via CAS manifests.** A writer holds a lease (kept alive by a heartbeat driver) and advances the log with compare-and-swap on the manifest, so a stale writer is fenced out (`FencedError`, graceful shutdown) instead of corrupting the log. A crashed writer's lease expires on its own and the next boot takes over.
|
|
13
|
+
- **Sharded lanes.** A single node can own multiple object-storage lanes (`--shards N`), partitioning writes across per-shard logs, with an offline reshard path (`reshardObjectStore`) to change the count on a stopped deployment.
|
|
14
|
+
- **Replica serving.** Read-only replicas tail the bucket's log into their own local SQLite and serve queries and reactive subscriptions from it, optionally forwarding mutations to the writer.
|
|
15
|
+
- **Garbage collection.** A background GC driver compacts and reclaims superseded segments (cadence via `HELIPOD_OBJECTSTORE_GC_MS`, default ~60 s).
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
Install alongside `helipod` in the project you deploy:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
bun add helipod @helipod/objectstore-substrate
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Object-store mode is activated by `helipod serve --object-store <url>` (or `HELIPOD_OBJECT_STORE`; the flag wins). The CLI has no static dependency on this package — it loads `@helipod/objectstore-substrate` via dynamic import when `--object-store` is set and fails fast with an actionable message if it is not installed. `--object-store` is mutually exclusive with `--fleet`.
|
|
26
|
+
|
|
27
|
+
Accepted URL forms:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
helipod serve --object-store file:///data/objects # filesystem (a bare path also works)
|
|
31
|
+
helipod serve --object-store s3://key:secret@minio:9000/helipod-objects
|
|
32
|
+
helipod serve --object-store "s3:///my-bucket?region=us-west-2" # AWS S3, credentials from env
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`s3+http://` / `s3+https://` pin the endpoint protocol; credentials fall back to `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`. Run the writer with `--shards N` for multiple lanes, and point read nodes at the same bucket with `--replica` (plus `--writer-url <url>` to forward writes).
|
|
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/objectstore-substrate",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -25,20 +25,20 @@
|
|
|
25
25
|
"clean": "rm -rf dist .turbo"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@helipod/component": "0.1.
|
|
29
|
-
"@helipod/docstore": "0.1.
|
|
30
|
-
"@helipod/docstore-sqlite": "0.1.
|
|
31
|
-
"@helipod/id-codec": "0.1.
|
|
32
|
-
"@helipod/index-key-codec": "0.1.
|
|
33
|
-
"@helipod/objectstore": "0.1.
|
|
34
|
-
"@helipod/values": "0.1.
|
|
28
|
+
"@helipod/component": "0.1.2",
|
|
29
|
+
"@helipod/docstore": "0.1.2",
|
|
30
|
+
"@helipod/docstore-sqlite": "0.1.2",
|
|
31
|
+
"@helipod/id-codec": "0.1.2",
|
|
32
|
+
"@helipod/index-key-codec": "0.1.2",
|
|
33
|
+
"@helipod/objectstore": "0.1.2",
|
|
34
|
+
"@helipod/values": "0.1.2"
|
|
35
35
|
},
|
|
36
36
|
"devDependencies": {
|
|
37
37
|
"@aws-sdk/client-s3": "^3.1079.0",
|
|
38
|
-
"@helipod/executor": "0.1.
|
|
39
|
-
"@helipod/objectstore-fs": "0.1.
|
|
40
|
-
"@helipod/objectstore-s3": "0.1.
|
|
41
|
-
"@helipod/runtime-embedded": "0.1.
|
|
38
|
+
"@helipod/executor": "0.1.2",
|
|
39
|
+
"@helipod/objectstore-fs": "0.1.2",
|
|
40
|
+
"@helipod/objectstore-s3": "0.1.2",
|
|
41
|
+
"@helipod/runtime-embedded": "0.1.2",
|
|
42
42
|
"@types/node": "^22.10.5",
|
|
43
43
|
"tsup": "^8.3.5",
|
|
44
44
|
"typescript": "^5.7.2",
|