mirror of
https://github.com/buckit-io/buckit.git
synced 2026-09-21 01:53:31 +00:00
abuckit
104 lines
4.4 KiB
Markdown
104 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Buckit is a high-performance, S3-compatible object storage server written in Go (module path: `github.com/buckit-io/buckit`). The built binary is named `buckit`. Minimum Go version: 1.25.
|
|
|
|
## Common Commands
|
|
|
|
```sh
|
|
# Build
|
|
make build # build ./buckit binary
|
|
go build -tags kqueue -trimpath --ldflags "$(go run buildscripts/gen-ldflags.go)" -o buckit
|
|
```
|
|
# Install to $GOPATH/bin
|
|
make install
|
|
|
|
# Run unit tests (requires kqueue build tag)
|
|
make test
|
|
CGO_ENABLED=0 go test -v -tags kqueue,dev ./...
|
|
|
|
# Run a single test
|
|
CGO_ENABLED=0 go test -v -tags kqueue,dev -run TestFoo ./cmd/
|
|
|
|
# Run IAM-specific tests
|
|
MINIO_API_REQUESTS_MAX=10000 CGO_ENABLED=0 go test -timeout 15m -tags kqueue,dev -v -run TestIAM* ./cmd
|
|
|
|
# Lint (downloads golangci-lint if needed)
|
|
make lint
|
|
|
|
# Run all verifiers (lint + check-gen)
|
|
make verifiers
|
|
|
|
# Regenerate auto-generated files (must be committed)
|
|
go generate ./...
|
|
make check-gen
|
|
|
|
# Race-enabled build
|
|
make install-race
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Entry Point & Package Structure
|
|
|
|
- `main.go` → `cmd.Main(os.Args)` (package `github.com/buckit-io/buckit/cmd`)
|
|
- `cmd/` — all server logic: HTTP handlers, routing, storage engines, background ops
|
|
- `internal/` — reusable supporting packages (no circular dependencies with `cmd/`)
|
|
|
|
### Storage Layer Hierarchy
|
|
|
|
The `ObjectLayer` interface (`cmd/object-api-interface.go`) is the central abstraction. Implementations from top to bottom:
|
|
|
|
1. **`erasureServerPools`** (`cmd/erasure-server-pool.go`) — manages multiple independent server pools, routes requests to the correct pool
|
|
2. **`erasureSets`** (`cmd/erasure-sets.go`) — manages N erasure sets within a pool; hashes object names to select a set
|
|
3. **`erasureObjects`** (`cmd/erasure-object.go`) — implements reads/writes for a single erasure set using Reed-Solomon coding
|
|
4. **`xlStorage`** (`cmd/xl-storage.go`) — local disk I/O; stores objects in `xl.meta` format (msgpack)
|
|
5. **`storageRESTClient/storageRESTServer`** (`cmd/storage-rest-*.go`) — RPC shim for remote disks in distributed deployments
|
|
|
|
### HTTP Request Flow
|
|
|
|
Routing is assembled in `cmd/routers.go`:
|
|
- **S3 API**: `cmd/api-router.go` → `cmd/object-handlers.go`, `cmd/bucket-handlers.go`, `cmd/bucket-*-handlers.go`
|
|
- **Admin API**: `cmd/admin-router.go` → `cmd/admin-handlers*.go`
|
|
- **Metrics**: `cmd/metrics-router.go` → `cmd/metrics-v3*.go`
|
|
- **Peer/Storage RPC**: `cmd/peer-rest-*.go`, `cmd/storage-rest-*.go`
|
|
|
|
### Inter-Server Communication
|
|
|
|
- **`internal/grid/`** — custom multiplexed WebSocket connection layer for intra-cluster RPC (preferred for small/frequent messages; not for large payloads). See `internal/grid/README.md`.
|
|
- **`peer-rest-client/server`** — peer API for cluster coordination (healing, notifications, config sync)
|
|
- **`storage-rest-client/server`** — remote disk access
|
|
|
|
### Key Internal Packages
|
|
|
|
| Package | Purpose |
|
|
|---|---|
|
|
| `internal/auth` | Root credential management |
|
|
| `internal/bucket/lifecycle` | ILM/expiry rules |
|
|
| `internal/bucket/replication` | Replication config and status |
|
|
| `internal/bucket/versioning` | Versioning state |
|
|
| `internal/bucket/object/lock` | Object lock / WORM |
|
|
| `internal/config/` | Subsystem configuration (compress, storageclass, drive, etc.) |
|
|
| `internal/crypto` | SSE-C / SSE-S3 / SSE-KMS encryption |
|
|
| `internal/event` | S3 event notification dispatch |
|
|
| `internal/grid` | Low-latency intra-cluster RPC |
|
|
| `internal/kms` | Key management service integration |
|
|
| `internal/logger` | Structured audit and application logging |
|
|
| `internal/s3select` | S3 Select (SQL-on-objects) |
|
|
| `internal/dsync` | Distributed lock implementation |
|
|
|
|
## Code Generation
|
|
|
|
Files ending in `_gen.go` are auto-generated via `msgp` (MessagePack serialization). Files ending in `_string.go` are generated by `stringer`. Run `go generate ./...` after modifying types annotated with `//go:generate msgp` or `//go:generate stringer`. Generated files must be committed — `make check-gen` verifies this.
|
|
|
|
## Build Tags
|
|
|
|
Always include `-tags kqueue` when building or testing. Use `-tags kqueue,dev` for tests that require the `dev` tag (e.g., IAM tests, race tests).
|
|
|
|
## Linting
|
|
|
|
Configuration in `.golangci.yml`. Key enabled linters: `staticcheck`, `revive`, `govet`, `unused`, `misspell`, `gocritic`. Formatters: `gofumpt`, `goimports`. Run `make lint` which installs golangci-lint into `.bin/golangci/`.
|