This is the second development snapshot of Aeroduel Server. The app is almost complete, but not quite ready for production yet.

Current API endpoints:

Server-only

Server-only endpoints that can only be accessed from the desktop app, not from the web or external devices. These require a server token that generates automatically when the app opens and gets stored as an env variable.

• POST /api/new-match - Creates a new match lobby room and waits for players to join.
• POST /api/start-match - Starts the current match if in the "waiting" status.
• POST /api/end-match - Ends the current match, whether the timer has reached 0 or not, and returns the match results.
• POST /api/kick - Kicks a player from the waiting room or disqualifies them from the active match. This does not prevent them from re-joining the match again if the match is still waiting for players to join.

Arduino-only

Arduino-only endpoints that only the planes' onboard ESP32 boards can access, as enforced by an auth token assigned in api/register

• POST /api/hit - Registers a hit during the match and updates scores

Mobile-only

Mobile-only endpoints that only the mobile app can access, as enforced by an auth token assigned in api/join-match

• none yet

Note: In the future, the mobile apps may call an endpoint like "api/sign-in" which would assign the auth token and register the user is online. /api/join-match would then become a mobile-only endpoint. However, this is not currently implemented and is not a guaranteed feature.

Public

• POST /api/register - [INTENDED FOR ARDUINO] Registers that a plane is online, but doesn't associate it with the current match yet. Assigns an auth token to be used in all future Arduino-only endpoints.
• POST /api/join-match - [INTENDED FOR MOBILE] Joins a plane to the current match lobby if match has been created but not started yet. Returns an auth token to be used in all future mobile-only endpoints.
• GET /api/planes - Returns a list of all online planes, whether they've joined the current match or not.
• GET /api/match - Returns the current match state.
• POST /api/fire - A joke endpoint that returns error 418 "I'm a teapot" because the server can't fire on the planes.
• GET /api/test - A placeholder testing endpoint that might be removed. Logs and returns the query parameters given. May be used to confirm the server is connecting.

For more API details, see docs/API.md.

Current WebSockets Events

Client → Server

• hello
  • Mobile: { type: "hello", role: "mobile", matchId, userId, authToken }
  • Arduino: { type: "hello", role: "arduino", planeId, authToken }

Currently, other client → server WebSocket messages are ignored after a
successful hello. Game actions (hits, etc.) still go through HTTP APIs.

Server → Any

• system:ack – Successful handshake acknowledgment.
• system:error – Protocol/auth error explanation (often followed by close).

Server → Mobile

• match:update – Live match status and scores.
• plane:hit – Individual hit event (attacker, target, timestamp).
• match:created – A new match is available to join.
• match:end – Final winners and scores.
• plane:kicked – Plane removed from match/lobby; includes reason.
• plane:disqualified – Plane disqualified during an active match; includes reason.

Server → Arduino

• match:state – Global match state: "waiting" | "active" | "ended".
• plane:flash – Command to flash lights because of a hit.
• plane:kicked – Plane removed from match/lobby; includes reason.
• plane:disqualified – Plane disqualified during an active match; includes reason.

For more WebSocket details, see docs/WebSockets.md.

This is the first development snapshot of Aeroduel Server. The app is incomplete and cannot do anything except create new blank matches (and cannot even start them).

Current API endpoints:

• POST /api/new-match - creates a new match lobby room. Can only be accessed from the desktop app, not from the web or external devices.
• POST /api/register - registers that a plane is online, but doesn't associate it with the current match yet
• POST /api/join-match - joins a plane to the current match lobby if match has been created but not started yet
• POST /api/hit - registers a hit during the match and updates scores
• GET /api/test - a placeholder testing endpoint that will be removed. Logs and returns the query parameters given.

For more API details, see docs/API.md.