An LVM-based per-node storage API. beanstore manages thin logical volumes on the node it runs on and moves detached volumes between nodes. Nothing more.
Status: early development. Not production ready.
- Volumes are LVM thin LVs. A node is authoritative about its own disk.
- Moves require the volume to be detached. There is no live move.
- No coordinator inside beanstore. An orchestrator (any orchestrator) drives the API, nodes enforce the rules. All central state is a rebuildable cache: scanning all nodes yields truth.
- Crash recovery is resolved from on-disk state plus a commit protocol between the two nodes of a move. At most one node ever holds an authoritative copy of a volume.
- Verbs are strict-state: a verb in the wrong state is refused, never absorbed. Idempotency and retries are the calling driver's job.
Not yet. The gRPC API surface (volume lifecycle, attach/detach, the move protocol, and the scan) will be documented here once it exists.
Contributions are welcome, see CONTRIBUTING.md. In
short: commits follow plain Conventional Commits (type: description, no
scopes) and must be DCO signed off (git commit -s). Both rules are
enforced by git hooks.
AI-assisted contributions need to follow these rules:
- Disclose it. Commits with AI-generated code carry a co-author
trailer, e.g.
Co-Authored-By: Claude <noreply@anthropic.com>. - You are the author. The contributor is fully responsible for AI-generated code: its correctness, its license compatibility, and the DCO sign-off certifying the right to submit it. "The AI wrote it" is never an excuse.
- Review it yourself, before pushing. Submit only code you have read, understood, and could explain and defend in review as your own.
Required tooling:
- Go 1.25+: the repo holds two modules, the server at
the root and the client library in
client/. - golangci-lint v2: linting, configured in
.golangci.yml. - buf: protobuf linting and code generation
(
just proto-lint,just proto). - just: task runner.
justlists the available recipes,just ciruns everything that must pass. - lefthook: git hooks (lint on pre-commit, commit message and sign-off checks on commit-msg).
After cloning, run the one-time setup. It creates the local (untracked) go workspace, so the server builds against your working-tree client, and activates the git hooks:
just setup- The beanstore server (this repository's root module) is licensed under AGPL-3.0.
- The Go client library in
client/(protobuf definitions, generated stubs, and the error taxonomy) is a separate module licensed under MIT, so consumers can link it without copyleft obligations. Talking to a beanstore daemon over the wire carries no license obligations either way. - The Go lvm2 library in
lvm/is likewise a separate module licensed under MIT, usable on its own by any project that needs to talk to lvm2 from Go.