161 lines
6.3 KiB
Markdown
161 lines
6.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**kvs-sh** is an interactive CLI shell for the KVS (Key-Value Store) distributed database. Think `mongosh`, `psql`, or `redis-cli` but for KVS. Single Go file implementation (~600 lines) with readline support for command history and auto-completion.
|
|
|
|
## KVS Server Reference
|
|
|
|
The complete KVS server source code is located at `../kvs/` relative to this repository. Reference it when:
|
|
- Understanding API contracts and response formats
|
|
- Verifying authentication/authorization behavior
|
|
- Checking endpoint paths and HTTP methods
|
|
- Understanding data structures (StoredValue, Member, User, Group types)
|
|
- Implementing new shell commands for backend features
|
|
|
|
Key server locations:
|
|
- `../kvs/server/handlers.go` - All API endpoint implementations
|
|
- `../kvs/server/routes.go` - Route definitions and HTTP methods
|
|
- `../kvs/types/types.go` - Canonical type definitions (StoredValue, etc.)
|
|
- `../kvs/auth/` - JWT authentication and permission system details
|
|
- `../kvs/README.md` - Complete API documentation with curl examples
|
|
- `../kvs/CLAUDE.md` - Server architecture and development guidance
|
|
|
|
When adding new commands to kvs-sh, always verify the actual backend implementation in `../kvs/` rather than making assumptions about API behavior.
|
|
|
|
## Build & Run
|
|
|
|
```bash
|
|
# Build
|
|
go build -o kvs-shell
|
|
|
|
# Run
|
|
./kvs-shell
|
|
|
|
# Install to system
|
|
go install
|
|
```
|
|
|
|
## Quick Start with Server
|
|
|
|
```bash
|
|
# 1. Start KVS server (in ../kvs/)
|
|
cd ../kvs && ./kvs config.yaml
|
|
|
|
# 2. Run shell
|
|
./kvs-shell
|
|
|
|
# 3. In shell:
|
|
# connect http://localhost:8080
|
|
# auth $KVS_ROOT_TOKEN
|
|
# put test/data '{"hello":"world"}'
|
|
```
|
|
|
|
**Important:** If auth fails with "token not found", the database has old data. Either:
|
|
- Create a new token via the API, or
|
|
- Wipe database: `rm -rf ../kvs/data && mkdir ../kvs/data` (restart server to generate root token)
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Single-File Design
|
|
Everything lives in `main.go` - intentionally kept simple. The shell is a stateful REPL that maintains:
|
|
- HTTP client connection to KVS backend
|
|
- Current JWT auth token
|
|
- In-memory profile storage (username, token, server URL combinations)
|
|
- Active profile selection
|
|
|
|
### Core Components
|
|
|
|
**KVSClient (main.go:49)**: Central state container holding:
|
|
- `baseURL`: KVS server endpoint
|
|
- `currentToken`: JWT for authentication
|
|
- `profiles`: In-memory map of saved user profiles (NOT persisted to disk yet)
|
|
- `httpClient`: Reusable HTTP client with 30s timeout
|
|
|
|
**Command Router (main.go:465)**: Main loop uses switch statement on first word of input, delegates to `handle*` methods
|
|
|
|
**Command Parser (main.go:527)**: Custom parser respecting quotes - critical for JSON arguments like `put key '{"foo": "bar"}'`
|
|
|
|
**Auto-completion (main.go:503)**: Prefix tree using readline library for tab completion of commands
|
|
|
|
### HTTP Communication Pattern
|
|
All API calls go through `doRequest()` (main.go:85) which:
|
|
1. Serializes body to JSON if present
|
|
2. Sets `Authorization: Bearer <token>` header if token exists
|
|
3. Returns `(body, statusCode, error)` tuple
|
|
4. Delegates HTTP status interpretation to caller
|
|
|
|
### Key Backend API Mappings
|
|
- `GET /kv/<key>` → Returns `StoredValue` with UUID, timestamp, data
|
|
- `PUT /kv/<key>` → Accepts raw JSON, returns UUID + timestamp
|
|
- `DELETE /kv/<key>` → Returns 204 on success
|
|
- `GET /members/` → Returns array of cluster `Member` objects
|
|
- `GET /api/users/<uuid>` → Returns `User` object
|
|
- `GET /health` → Returns service status map
|
|
|
|
### Type Definitions (main.go:18-46)
|
|
Backend response structures are mirrored in the client:
|
|
- `StoredValue`: The core KV response with UUID, timestamp (int64 unix millis), and `json.RawMessage` data
|
|
- `Member`: Cluster member info with ID, address, last_seen timestamp
|
|
- `User`: User record with nickname hash, groups array, created/updated timestamps
|
|
- `Group`: Group definition (defined but not yet used in commands)
|
|
|
|
### Profile System
|
|
Profiles are in-memory only (see roadmap for persistence plan). When you `profile use <name>`, it swaps the client's token, userUUID, and baseURL atomically. The `*` marker in profile listings indicates active profile.
|
|
|
|
### Color Scheme
|
|
Uses fatih/color package with semantic coloring:
|
|
- Cyan: labels, headers, structured data keys
|
|
- Green: success messages, confirmations
|
|
- Yellow: warnings, "not found" states
|
|
- Red: errors, invalid usage
|
|
- Magenta: banner/title text
|
|
|
|
### Command Parsing - Critical Implementation Details
|
|
|
|
**parseCommand()** (main.go:527-570): Handles both single (`'`) and double (`"`) quotes intelligently.
|
|
|
|
**Key behavior:**
|
|
- Quotes are **only stripped** when they delimit an entire argument (start and end)
|
|
- Supports both `'` and `"` as quote delimiters
|
|
- Tracks which quote type started the argument to handle nesting correctly
|
|
- Preserves quotes that appear mid-argument (for unquoted JSON)
|
|
|
|
**Examples:**
|
|
```bash
|
|
put key '{"foo":"bar"}' # ✅ Strips outer ', preserves inner "
|
|
put key {"foo":"bar"} # ✅ Works (no spaces, compact JSON)
|
|
put key {"foo": "bar"} # ❌ Fails - spaces split into multiple args
|
|
put key "{\"foo\":\"bar\"}" # ✅ Works (escaped quotes in double-quoted arg)
|
|
```
|
|
|
|
**JSON Error Handling** (main.go:393-425):
|
|
- `printJSONError()` provides user-friendly error messages with examples
|
|
- Detects error type (invalid chars, incomplete JSON, etc.) and shows context-specific tips
|
|
- Shows what input was received to help debug quoting issues
|
|
|
|
## Backend Assumptions
|
|
|
|
The shell expects the KVS backend to:
|
|
1. Accept JWT tokens in `Authorization: Bearer <token>` header
|
|
2. Return timestamps as Unix milliseconds (int64)
|
|
3. Use standard REST semantics (404 for not found, 204 for delete, 200/201 for success)
|
|
4. Accept raw JSON payloads for PUT operations (not wrapped in metadata)
|
|
|
|
## Known Limitations & Roadmap Items
|
|
|
|
1. **No persistent profiles** - restart loses all `profile add` data (roadmap #1)
|
|
2. **No metadata commands** - backend supports owner/group/permissions but shell doesn't expose yet (roadmap #6)
|
|
3. **No group management** - `Group` type defined but no CRUD operations (roadmap #5)
|
|
4. **No TLS support** - HTTP only, no certificate handling (roadmap #8)
|
|
5. **No tab completion for keys** - only completes command names, not dynamic keys from server (roadmap #10)
|
|
6. **user create not implemented** - Listed in help but just shows "not implemented" message
|