feat(edge): Edge HTTP Server with MessageBus, middleware, CORS, rate limiting, OpenAPI spec

[tanmayxchoudhary]

Summary

Implements the Edge HTTP Server bounty from Clawland-AI#22 — adding 4 new API endpoints to turn PicoClaw into a full L1 edge node.

Endpoints

Method	Path	Description
GET	/api/health	Health check (also at /healthz)
GET	/api/status	Node status (also at /api/v1/status)
POST	/api/command	Receive fleet commands, queued on MessageBus (also at /api/v1/command)
POST	/api/message	Receive operator messages, queued on MessageBus

Key changes

• pkg/edge/server.go — Complete rewrite with:

  • 4 bounty-required endpoints + backward-compatible /healthz and /api/v1/* aliases
  • MessageBus integration via WithMessageBus() option (backward-compatible with NewServer(cfg, msgBus) variadic)
  • Middleware stack: request logging (with request IDs), panic recovery, CORS, rate limiting
  • Graceful shutdown via StartWithContext(ctx)
  • Consistent JSON error responses ({"error": "...", "code": N})
  • Functional options pattern: WithMessageBus(), WithRateLimit(rps, burst)
  • Comprehensive request normalization with default values

• pkg/edge/server_test.go — 16 table-driven tests covering:

  • Health and status endpoints (including all legacy aliases)
  • Command acceptance with full and minimal payloads
  • Message acceptance with metadata and media
  • Error cases: missing type, missing content, empty body, null body, boolean body, malformed JSON
  • CORS preflight and response headers
  • Wrong HTTP methods returning non-200
  • Rate limiter unit test and integration test
  • Concurrent access safety
  • Backward compatibility of NewServer signatures
  • Content-Type header verification
  • Error response format verification

• pkg/edge/openapi.json — OpenAPI 3.0 specification for all endpoints

• cmd/picoclaw/main.go — Wired MessageBus into edge server

• README.md — Updated endpoint documentation

• pkg/gene/selector.go — Deterministic gene sort tie-breaker so go test ./... passes repository-wide

Differentiation from existing PRs (Clawland-AI#19, Clawland-AI#23, Clawland-AI#27)

Feature	This PR	PR Clawland-AI#19	PR Clawland-AI#23	PR Clawland-AI#27
All 4 bounty endpoints	✅	✅	✅	✅
MessageBus integration	✅	✅	✅	✅
Backward-compatible API	✅	✅	✅	✅
Request logging with IDs	✅	❌	❌	❌
Panic recovery middleware	✅	❌	❌	❌
CORS support	✅	❌	❌	❌
Rate limiting	✅	❌	❌	❌
Graceful shutdown	✅	❌	❌	❌
OpenAPI 3.0 spec	✅	❌	❌	❌
Structured error responses	✅	❌	❌	❌
Functional options pattern	✅	❌	❌	❌
Table-driven tests	✅	❌	❌	❌
Test count	16	7	4	5
Concurrent access test	✅	❌	❌	❌
Wrong method tests	✅	❌	❌	❌
Gene tie-breaker fix	✅	✅	❌	✅
go test ./... passes	✅	✅	❌ (no Go env)	✅

Validation

$ go test ./...
?   	github.com/sipeed/picoclaw/cmd/picoclaw	[no test files]
ok  	github.com/sipeed/picoclaw/pkg/edge	0.017s
ok  	github.com/sipeed/picoclaw/pkg/gene	0.080s
ok  	github.com/sipeed/picoclaw/pkg/logger	0.006s

$ go vet ./...
(all packages pass)

Closes Clawland-AI#22

Race status: I am aware of 3 existing open PRs for this bounty (Clawland-AI#19, Clawland-AI#23, Clawland-AI#27). This PR aims to differentiate on code quality, test coverage, observability, and documentation.