Repository layout
| Path | Responsibility |
|---|---|
zeedb.go | Public API, budgets, commit visibility, recovery, checkpoints |
internal/storage/codec.go | Versioned batch/frame encoding and checksums |
internal/storage/table.go | Sorted table blocks, index, Bloom filter, verification |
internal/storage/lock_*.go | Platform process locks and directory sync behavior |
cmd/zeedb/ | Local CLI parsing, file input, output, and errors |
zeedb_test.go | Model/concurrency/recovery/kill tests and benchmarks |
examples/ | Runnable embedded usage, JSON store, pagination, lifecycle |
docs/ | Repository specifications and historical validation records |
website/ | Independent Astro documentation frontend |
The HTTP handler lives in internal/httpapi/, with lifecycle/flags in cmd/zeedb/serve.go. Runnable JavaScript/Python integration examples live in examples/http/. SyncPath and FastPath remain proposals.
Run Go checks
go test ./...
go vet ./...
go run ./examples/basic
go run ./examples/jsonstore
go run ./examples/pagination
go run ./examples/lifecycleThe example programs create and clean up their own temporary directories. go test ./... compiles the example packages; go run additionally executes their demonstrated behavior.
With a supported C compiler and CGO enabled:
go test -race ./...Do not claim a race run passed if the environment only compiled ordinary tests. The validation page distinguishes actual environments and checks.
Format and fuzz
Use gofmt on changed Go files. Relevant fuzz targets are:
go test ./internal/storage -run='^$' -fuzz=FuzzDecode -fuzztime=30s
go test ./internal/storage -run='^$' -fuzz=FuzzReadFrame -fuzztime=30sKeep crashing inputs as regressions when they expose real defects. A fuzz smoke run or a suite with passing examples does not establish arbitrary filesystem-fault or power-loss safety.
Review storage changes
For a commit/recovery change, state which writes can be acknowledged, which files are synced before publication, what happens after each failure boundary, and whether old formats remain readable.
Useful regression cases include repeated keys, failed validation, old WAL after checkpoint publication, complete-frame corruption, incomplete final frames, missing files, record-boundary table truncation, and concurrent visibility.
A file-format change needs explicit versioning and compatibility/migration behavior. An API change needs documented semantics and meaningful behavioral coverage. Optimization should start with profiling and equivalent durability comparisons.
Work on the website
From website/ with the documented Node version:
npm ci
npm run dev
npm run build
npm run format:checkMarkdown frontmatter controls sidebar grouping, ordering, page descriptions, search, and pagination. The build validates content schemas, local links/assets/headings, and search destinations. Test both a root build and a BASE_PATH subdirectory build when changing routing.
Document implemented behavior from the source. Label proposed sync, indexes, snapshots, and FastPath features as planned. The HTTP server does not implement tenant authorization or synchronization. Never invent a supported method to make a sample shorter.
Submit a change
Use a focused branch and describe the problem, final behavior, validation, compatibility implications, and any remaining uncertainty. See CONTRIBUTING.md for the repository workflow.