siujamo
e070a3fb5f
OTA update server designed for high-concurrency, low-bandwidth deployments. GORM-backed PostgreSQL, JWT auth, device management, artefact versioning, deployment rollout with gated rate-limited downloads, and a React admin panel.
54 lines
3.1 KiB
Markdown
54 lines
3.1 KiB
Markdown
# CLAUDE.md - Project Guidelines for OTA Micro-Server
|
|
|
|
## Project Overview
|
|
This project is a high-concurrency, low-bandwidth OTA (Over-the-Air) management and distribution server built in Go. It is specifically designed to distribute updates to thousands of devices under a highly constrained network pipelining landscape (**10 Mbps bandwidth ceiling**). It manages binary/Jar delta file generation, gating rollouts, and concurrent rate-limiting.
|
|
|
|
## Technology Stack
|
|
- **Backend Language:** Go (Golang)
|
|
- **Database:** PostgreSQL (with migration tool e.g., Flyway/Golang-migrate)
|
|
- **Key Algorithms/Protocols:** BSDiff/VCDIFF for delta generation, HTTP Range requests for resumable downloads.
|
|
- **Documentation & Code Comments:** Strictly adhere to **British English** spelling conventions (e.g., `colour`, `centre`, `optimise`, `standardisation`).
|
|
|
|
---
|
|
|
|
## Build, Test & Run Commands
|
|
|
|
### Development
|
|
- **Run the server:** `go run cmd/server/main.go`
|
|
- **Build the binary:** `go build -o bin/ota-server cmd/server/main.go`
|
|
- **Format code:** `go fmt ./...`
|
|
- **Lint code:** `golangci-lint run`
|
|
|
|
### Testing
|
|
- **Run all tests:** `go test ./...`
|
|
- **Run with coverage:** `go test -coverprofile=coverage.out ./...`
|
|
|
|
---
|
|
|
|
## Code Architecture & Design Principles
|
|
|
|
### 1. 10M Bandwidth Strategy (Hard Constraints)
|
|
- **Gated Rollout (Token-based):** Devices must acquire a download token before pulling updates. Keep concurrent downloads limited (e.g., max 50 concurrent streams).
|
|
- **Rate Limiting:** Implement token bucket or leaky bucket algorithms at the application/middleware layer to throttle download speed per connection.
|
|
- **Resumable Downloads:** The download endpoint **must** support HTTP 206 Partial Content and handle `Range` headers properly.
|
|
|
|
### 2. Jar/Zip Delta Logic
|
|
- **Do not perform direct binary diffs on raw `.jar` files.**
|
|
- To generate a delta:
|
|
1. Unzip the old Jar and new Jar into isolated temporary directories.
|
|
2. Compare files sequentially. Identify new, deleted, and modified files.
|
|
3. Apply binary diff (like BSDiff) **only** on modified `.class` or resource files.
|
|
4. Packaging: Zip the modified patches, new files, and a `manifest.json` describing the deletion/replacement steps into a final `.patch` package.
|
|
|
|
### 3. Database & Concurrency
|
|
- Optimise SQL queries to prevent connection pooling bottlenecks under thousands of periodic heartbeats/checking requests.
|
|
- Use explicit transactions when updating device upgrade status (`Checking` -> `Downloading` -> `Verifying` -> `Upgraded`).
|
|
|
|
---
|
|
|
|
## Code Style & Conventions
|
|
- **Naming:** Idiomatic Go (camelCase for internal variables, PascalCase for exported identifiers). Short but descriptive context names.
|
|
- **Error Handling:** Handle all errors explicitly. Wrap errors with meaningful context using `fmt.Errorf("context: %w", err)`.
|
|
- **Concurrency:** Ensure goroutines are safe, utilize `sync.Pool` for heavy allocations (like decompression buffers), and use `context.Context` for cancellation propagation.
|
|
- **Spelling:** Always double-check spelling in logs, errors, and variable definition to ensure **British English** alignment (e.g., use `optimised_delta_buffer` instead of `optimized_delta_buffer`).
|