init

2026-05-26 12:26:05 +02:00
parent db83c00ac7
commit 7de6864f70
24 changed files with 1156 additions and 1 deletions
@@ -1,2 +1,100 @@
-# mc-computer-craft-api-backend
+# Minecraft ComputerCraft ME API — Backend

+TypeScript backend that collects Minecraft ME system data pushed by a
+ComputerCraft computer and exposes it over **HTTPS** (REST) and **WSS**
+(live websocket feed).
+
+This is the TypeScript rewrite of the original Rust/Axum + SQLite backend.
+
+## Stack
+
+- **[Fastify 5](https://fastify.dev/)** — HTTP + WebSocket server. Chosen over
+  Express/Nest because it has first-class WebSocket, JSON-schema validation and
+  OpenAPI support built in, which keeps the project small for this scope.
+- **PostgreSQL** — runs in Docker via `docker-compose`.
+- **`@fastify/swagger` + `@fastify/swagger-ui`** — OpenAPI docs at `/api/docs`.
+- **TypeBox** — schemas used both for request validation and OpenAPI generation.
+- **`selfsigned`** — generates a self-signed TLS certificate on first start.
+
+## Data model
+
+Two tables, mirroring the original design:
+
+| Table               | Purpose                                            |
+| ------------------- | -------------------------------------------------- |
+| `me_system_live`    | current contents — one row per item (`name` unique) |
+| `me_system_history` | historic snapshots — references `me_system_live.id` |
+
+The `mod` of each item (the namespace before the `:` in `minecraft:iron_ingot`)
+is derived on ingest and stored on the live row so it can be filtered cheaply.
+
+## Quick start (Docker)
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+This starts PostgreSQL and the backend. A self-signed certificate is generated
+into `./certs` automatically.
+
+## Quick start (local dev)
+
+```bash
+cp .env.example .env          # adjust DATABASE_URL to your local Postgres
+npm install
+npm run dev
+```
+
+## Accept the self-signed certificate
+
+Because the certificate is self-signed, browsers reject it until trusted.
+**Open <https://localhost:3000/api/docs> once and accept the warning** — this
+also makes `fetch` and `wss://` calls from the frontend work.
+
+## Endpoints
+
+| Method | Path                       | Description                                    |
+| ------ | -------------------------- | ---------------------------------------------- |
+| `POST` | `/api/me-system/update`    | Ingest a full snapshot (called by ComputerCraft) |
+| `GET`  | `/api/me-system/live`      | Current contents — `search`, `mod`, `sort`, `order` |
+| `GET`  | `/api/me-system/mods`      | Aggregated per-mod overview                    |
+| `GET`  | `/api/me-system/history`   | History points for one item — `name`, `limit` |
+| `GET`  | `/api/health`              | Health and runtime metrics                     |
+| `WS`   | `/api/ws/live`             | Live data feed (see below)                     |
+| `GET`  | `/api/docs`                | OpenAPI / Swagger UI                           |
+
+### WebSocket protocol — `/api/ws/live`
+
+- On connect the server sends a `snapshot` message.
+- The client may send `{ "type": "setFilters", "filters": { "search": "iron",
+  "mod": "minecraft", "sort": "amount", "order": "desc" } }`.
+- The server replies with a fresh `snapshot` and keeps the filter for every
+  later `update` message — so filters persist across data updates.
+- On every ingest the server pushes an `update` message to each client, with
+  that client's filter already applied.
+
+Message shape:
+
+```json
+{ "type": "snapshot|update", "items": [...], "mods": [...], "filters": {...} }
+```
+
+## Configuration
+
+See `.env.example`. Key variables: `PORT`, `DATABASE_URL`,
+`HISTORY_INTERVAL_SECONDS`, `TLS_ENABLED`, `CORS_ORIGIN`.
+
+## ComputerCraft uploader
+
+An example uploader script is provided in `computercraft/me_uploader.lua`.
+See the comment at the top of that file regarding the self-signed certificate.
+
+## Scripts
+
+| Command            | Description                       |
+| ------------------ | --------------------------------- |
+| `npm run dev`      | Watch-mode dev server (`tsx`)     |
+| `npm run build`    | Compile TypeScript to `dist/`     |
+| `npm start`        | Run the compiled server           |
+| `npm run typecheck`| Type-check without emitting       |