mirror of
https://github.com/IS1DI/x0gp.git
synced 2026-07-16 20:47:55 +00:00
feat(server): initial implementation
This commit captures the full server code accumulated across
several development sessions. It includes the following layers,
applied in roughly this order during development:
1. Base infrastructure
- cmd/poc-server HTTP+WebSocket server, /health, /stats
- internal/transport wire types (Envelope + all message types)
- internal/catalog, internal/realtime, internal/stats
- internal/storage/postgres with migrations 001-004
- .env, .env.example, docker-compose, Dockerfile, scripts/
2. Swagger documentation
- go get github.com/swaggo/http-swagger
- swag init produces docs/docs.go
- /swagger/index.html UI, /swagger/doc.json spec
- annotations on health/stats/ws and catalog handlers
3. Races API
- internal/races/{store,service,keyset,types}.go
- migration 005_races.sql: finished_races, race_plans, race_queue
- GET /api/races with keyset pagination, status filter
- GET /api/races/upcoming
- POST /api/races/queue/join, GET, DELETE
- POST/GET /api/races/plans, DELETE /{id}
- lobby.RaceMeta simplification (no host_id/host_name)
4. Races seeder
- internal/races/seed with deterministic generator
- --seed-races / --reset CLI flags in main.go
- 30 finished + 5 live + 5 plans + 4 queue entries
5. Drivers and clans
- internal/drivers, internal/clans (CRUD, validation)
- migration 008_drivers_clans.sql
- /api/clans and /api/drivers endpoints
- 3-letter uppercase nickname/tag validation
- lobby.DriverMeta: Nickname, AvatarURL, ClanID, ClanTag
6. Podium
- internal/transport.RacePodiumEntry
- lobby.SetDriverProfile for in-memory metadata sync
- migration 007_podium.sql (podium JSONB column)
- seeder populates top-3 per finished race
7. Live races persistence
- migration 009_live_persistence.sql: live_races,
live_race_drivers, lobby_drivers
- internal/races/live_store.go: LiveStore with write-side
mirror for lobby.Service mutations
- Service.collectLive and Upcoming read from Postgres
- main.go RestoreFromDB rehydrates lobby on startup
8. Unify live + finished into one races table
- migration 010_unify_races.sql: rename finished_races to
races, expand status CHECK, merge live rows
- PgStore now hosts both write paths; LiveStore is a
thin facade implementing lobby.Persistence
- seeder resetAll drops only finished/cancelled rows and
race_plans / race_queue / lobby_drivers
Each layer is consistent on its own; cross-layer changes are
visible in the file history. A future refactor may split this
commit into the per-stage boundaries listed above.
This commit is contained in:
x0gp
@@ -0,0 +1,10 @@
|
||||
version: v2
|
||||
plugins:
|
||||
- local: protoc-gen-go
|
||||
out: gen
|
||||
opt:
|
||||
- paths=source_relative
|
||||
- local: protoc-gen-go-grpc
|
||||
out: gen
|
||||
opt:
|
||||
- paths=source_relative
|
||||
@@ -0,0 +1,9 @@
|
||||
version: v2
|
||||
modules:
|
||||
- path: .
|
||||
lint:
|
||||
use:
|
||||
- STANDARD
|
||||
breaking:
|
||||
use:
|
||||
- FILE
|
||||
@@ -0,0 +1,145 @@
|
||||
syntax = "proto3";
|
||||
|
||||
package x0gp.v1;
|
||||
|
||||
option go_package = "github.com/x0gp/server/proto/gen/clientserverpb";
|
||||
|
||||
// ============================================================
|
||||
// Wire protocol between client (browser / mobile) and server.
|
||||
// ============================================================
|
||||
//
|
||||
// In PoC we use JSON via transport/codec.go. This file is the formal spec
|
||||
// for the binary protobuf wire format we'll switch to in MVP/prod. The
|
||||
// generated code lives in proto/gen/ and will replace transport/.
|
||||
//
|
||||
// Packet envelope (oneof payload):
|
||||
// message Packet {
|
||||
// uint64 seq = 1;
|
||||
// int64 ts_ms = 2;
|
||||
// oneof payload {
|
||||
// ClientHello client_hello = 10;
|
||||
// ServerHello server_hello = 11;
|
||||
// JoinRace join_race = 12;
|
||||
// LeaveRace leave_race = 13;
|
||||
// InputState input_state = 14;
|
||||
// RaceSnapshot race_snapshot = 15;
|
||||
// InputAck input_ack = 16;
|
||||
// Correction correction = 17;
|
||||
// RaceEvent race_event = 18;
|
||||
// Ping ping = 19;
|
||||
// Pong pong = 20;
|
||||
// ErrorMsg error_msg = 21;
|
||||
// ChatMessage chat_message = 22;
|
||||
// }
|
||||
// }
|
||||
|
||||
// --- Client -> Server ---
|
||||
|
||||
message ClientHello {
|
||||
string version = 1;
|
||||
string token = 2; // JWT in prod; empty in dev
|
||||
string locale = 3;
|
||||
string client_id = 4; // for reconnect
|
||||
}
|
||||
|
||||
message JoinRace {
|
||||
string race_id = 1;
|
||||
int32 car_slot = 2; // 0..3
|
||||
string car_name = 3;
|
||||
}
|
||||
|
||||
message LeaveRace {
|
||||
string race_id = 1;
|
||||
}
|
||||
|
||||
// High-rate control packet (60-120 Hz).
|
||||
message InputState {
|
||||
float steering = 1; // -1.0 .. 1.0
|
||||
float throttle = 2; // 0.0 .. 1.0
|
||||
float brake = 3; // 0.0 .. 1.0
|
||||
int32 gear = 4; // -1 reverse, 0 neutral, 1..6 forward
|
||||
uint32 buttons = 5;
|
||||
}
|
||||
|
||||
message Ping {
|
||||
int64 client_ts_ms = 1;
|
||||
}
|
||||
|
||||
message ChatMessage {
|
||||
string text = 1;
|
||||
}
|
||||
|
||||
// --- Server -> Client ---
|
||||
|
||||
message ServerHello {
|
||||
string session_id = 1;
|
||||
uint64 race_tick = 2;
|
||||
string server_version = 3;
|
||||
ServerConfig config = 4;
|
||||
}
|
||||
|
||||
message ServerConfig {
|
||||
int32 tick_rate_hz = 1;
|
||||
int32 snapshot_rate_hz = 2;
|
||||
int32 max_cars = 3;
|
||||
}
|
||||
|
||||
message RaceSnapshot {
|
||||
uint64 tick = 1;
|
||||
int64 ts_ms = 2;
|
||||
double elapsed_s = 3;
|
||||
repeated CarInfo cars = 4;
|
||||
}
|
||||
|
||||
message CarInfo {
|
||||
string id = 1;
|
||||
string driver_name = 2;
|
||||
double x = 3; // metres
|
||||
double y = 4; // metres
|
||||
double heading = 5; // radians
|
||||
double speed = 6; // m/s
|
||||
int32 lap = 7;
|
||||
int32 sector = 8; // 0..2
|
||||
int64 last_lap_ms = 9;
|
||||
int64 best_lap_ms = 10;
|
||||
AppliedInput input_applied = 11;
|
||||
bool dnf = 12;
|
||||
}
|
||||
|
||||
message AppliedInput {
|
||||
double steering = 1;
|
||||
double throttle = 2;
|
||||
double brake = 3;
|
||||
}
|
||||
|
||||
message InputAck {
|
||||
uint64 seq = 1;
|
||||
int64 applied_at_ms = 2;
|
||||
int64 server_tick_ms = 3;
|
||||
}
|
||||
|
||||
message Correction {
|
||||
uint64 tick = 1;
|
||||
double delta_steering = 2;
|
||||
double delta_throttle = 3;
|
||||
string reason = 4;
|
||||
}
|
||||
|
||||
message RaceEvent {
|
||||
string race_id = 1;
|
||||
string event = 2; // "start" | "lap" | "sector" | "dnf" | "finish" | "joined" | "left"
|
||||
string car_id = 3;
|
||||
int32 sector = 4;
|
||||
int64 lap_ms = 5;
|
||||
int64 ts_ms = 6;
|
||||
}
|
||||
|
||||
message Pong {
|
||||
int64 client_ts_ms = 1;
|
||||
int64 server_ts_ms = 2;
|
||||
}
|
||||
|
||||
message ErrorMsg {
|
||||
string code = 1;
|
||||
string message = 2;
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
syntax = "proto3";
|
||||
|
||||
package x0gp.v1;
|
||||
|
||||
option go_package = "github.com/x0gp/server/proto/gen/serveragentpb";
|
||||
|
||||
// ============================================================
|
||||
// Wire protocol between server (Edge / agent-linker) and the
|
||||
// on-board agent (ESP32-S3 in PoC).
|
||||
// ============================================================
|
||||
//
|
||||
// The agent runs MicroPython (PoC) or ESP-IDF C (prod). It connects via
|
||||
// Wi-Fi to the gateway-агент (in MVP) or directly to this server (in PoC)
|
||||
// over WebSocket using the same envelope pattern as client_server.proto.
|
||||
|
||||
// --- Server -> Agent ---
|
||||
|
||||
message AgentHelloAck {
|
||||
string agent_id = 1;
|
||||
int32 fw_version_major = 2;
|
||||
int32 fw_version_minor = 3;
|
||||
ServerConfig config = 4;
|
||||
}
|
||||
|
||||
message ServerConfig {
|
||||
int32 tick_rate_hz = 1;
|
||||
int32 telemetry_rate_hz = 2;
|
||||
}
|
||||
|
||||
message AgentCommand {
|
||||
string car_id = 1;
|
||||
float steering = 2; // -1.0 .. 1.0
|
||||
float throttle = 3; // 0.0 .. 1.0
|
||||
float brake = 4; // 0.0 .. 1.0
|
||||
int32 gear = 5;
|
||||
uint32 flags = 6; // bit0: E-stop, bit1: lights, ...
|
||||
int64 expires_at_ms = 7; // safety: drop if older than this
|
||||
}
|
||||
|
||||
message AgentConfig {
|
||||
string car_id = 1;
|
||||
float max_steering_rate = 2; // per second
|
||||
float max_throttle_rate = 3;
|
||||
RampLimits ramp = 4;
|
||||
}
|
||||
|
||||
message RampLimits {
|
||||
float throttle_up_per_s = 1;
|
||||
float throttle_down_per_s = 2;
|
||||
float brake_per_s = 3;
|
||||
}
|
||||
|
||||
// --- Agent -> Server ---
|
||||
|
||||
message AgentHello {
|
||||
string car_id = 1;
|
||||
string fw_version = 2;
|
||||
string hw_id = 3;
|
||||
int32 rssi = 4; // dBm
|
||||
}
|
||||
|
||||
message AgentTelemetry {
|
||||
string car_id = 1;
|
||||
int64 ts_ms = 2;
|
||||
float steering_actual = 3;
|
||||
float throttle_actual = 4;
|
||||
int32 rpm = 5;
|
||||
float voltage_v = 6;
|
||||
float current_a = 7;
|
||||
float temp_esc_c = 8;
|
||||
float temp_motor_c = 9;
|
||||
Imu imu = 10;
|
||||
IrLine ir = 11;
|
||||
float battery_pct = 12; // 0..100
|
||||
}
|
||||
|
||||
message Imu {
|
||||
float ax = 1; float ay = 2; float az = 3;
|
||||
float gx = 4; float gy = 5; float gz = 6;
|
||||
}
|
||||
|
||||
message IrLine {
|
||||
bool front = 1;
|
||||
bool rear = 2;
|
||||
}
|
||||
|
||||
message AgentHeartbeat {
|
||||
int64 ts_ms = 1;
|
||||
int64 uptime_s = 2;
|
||||
repeated string errors = 3;
|
||||
}
|
||||
|
||||
message AgentLog {
|
||||
string level = 1; // "debug" | "info" | "warn" | "error"
|
||||
string msg = 2;
|
||||
}
|
||||
Reference in New Issue
Block a user