mirror of
https://github.com/logos-storage/logos-storage-nim.git
synced 2026-06-26 12:29:30 +00:00
83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# First-time setup (initializes nimbus-build-system submodule)
|
|
make update && make
|
|
|
|
# Parallel build (faster)
|
|
make -j$(nproc) update && make -j$(nproc)
|
|
|
|
# Build the storage binary only
|
|
make
|
|
|
|
# Build the C shared/static library
|
|
make libstorage # dynamic (.so/.dylib/.dll)
|
|
make STATIC=1 libstorage # static (.a)
|
|
|
|
# Format code with nph
|
|
make build-nph # build nph formatter first
|
|
make nph/<path> # format a specific file or folder
|
|
make format # format all nim sources
|
|
make install-nph-hook # install git pre-commit hook for auto-formatting
|
|
```
|
|
|
|
## Test Commands
|
|
|
|
```bash
|
|
# Run unit tests (tests/storage/)
|
|
make test
|
|
|
|
# Run integration tests (spawns real node processes)
|
|
make testIntegration
|
|
|
|
# Run all tests
|
|
make testAll
|
|
|
|
# Run a single test file directly
|
|
$(ENV_SCRIPT) nim c -r tests/storage/testblockexchange.nim
|
|
|
|
# Run C bindings test
|
|
make testLibstorage
|
|
|
|
# Coverage report (requires lcov)
|
|
make coverage && make show-coverage
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Core node** (`storage/node.nim`): `StorageNode` composes all subsystems — a libp2p `Switch`, `NetworkStore`, `BlockExcEngine`, `Discovery`, `ManifestProtocol`, and `Taskpool`.
|
|
|
|
**Storage layer** (`storage/stores/`):
|
|
- `BlockStore` — abstract base type with virtual methods
|
|
- `RepoStore` — persistent LevelDB-backed store
|
|
- `CacheStore` — in-memory cache
|
|
- `NetworkStore` — wraps a local store with block exchange to fetch from the network
|
|
|
|
**Block exchange** (`storage/blockexchange/`): BitSwap-inspired protocol with an engine, network layer, and peer tracking. Blocks are identified by CID (Content Identifier).
|
|
|
|
**Manifest & Merkle tree** (`storage/manifest/`, `storage/merkletree/`): Files are split into chunks, organized in a Merkle tree, and described by a `Manifest`. The manifest CID is the user-facing handle for a stored file.
|
|
|
|
**REST API** (`storage/rest/`): HTTP API surface. See `openapi.yaml` for the full spec.
|
|
|
|
**C library bindings** (`library/`): `libstorage.nim` exposes a C ABI via `storage_new / storage_start / storage_stop / storage_destroy`. All API calls are async and deliver results via a `StorageCallback`. Callbacks must be fast and non-blocking (they run on the worker thread).
|
|
|
|
**Integration tests** (`tests/integration/`): Tests that spawn actual node processes. `twonodessuite` / `multinodesuite` macros set up N nodes and `StorageClient` (HTTP client) for interacting with them.
|
|
|
|
**Unit tests** (`tests/storage/`): Auto-discovered by the `importTests` macro — any file named `test*.nim` in that directory is included automatically in `testStorage`.
|
|
|
|
**Distributed tests** (`https://github.com/logos-storage/logos-storage-nim-cs-dist-tests): Uses Kubernetes to deploy a cluster either locally on Docker Desktop or on Google Cloud Platoform (using .github/workflows/release.yml in the logos-storage-nim repo).
|
|
|
|
## Key Development Notes
|
|
|
|
- **Nim version**: pinned to `v2.2.10` (see `Makefile`). Override with `NIM_COMMIT=<version>`.
|
|
- **Memory model**: ORC (`--mm:orc`) for Nim ≥ 2.0, refc for the C library build.
|
|
- **Error handling**: uses `questionable/results` (`?!T`, `?T`) throughout — avoid bare exceptions. The codebase enforces `{.push raises: [].}` broadly.
|
|
- **Logging**: uses `chronicles` with runtime filtering. Topics are set per-module via `logScope`. Build with `-d:chronicles_log_level=TRACE` to enable all log levels.
|
|
- **Style**: `--styleCheck:error` is enabled — identifiers must match declaration casing exactly.
|
|
- **Formatting**: `nph` is the mandatory formatter. Run `make nph/<file>` before committing, or install the pre-commit hook.
|
|
- **Chronicles sinks**: configured in `config.nims` as `textlines[dynamic],json[dynamic],textlines[dynamic]`. Adjust runtime behavior with the `CHRONICLES_LOG_LEVEL` env var or `--log-level` CLI flag.
|