Developer Overview

The LeavePulse Agent uses two primary communication channels for data reporting and command handling.

1. Ingest (HTTP REST API)

Used for asynchronous metrics reporting and player events. This is a reliable channel with disk-based buffering support.

• Endpoint: https://api.leavepulse.com/monitoring/v1/verified/ingest
• Authentication: X-Ingest-Token header.
• Data: JSON payloads containing metrics (TPS, RAM, players) and events (Join/Leave).
• Buffering: If the API is unreachable, the Agent saves data to a buffer folder (up to 10 MB by default) and retries once connectivity is restored.

2. Gateway (WebSocket)

Primary channel for real-time features using a persistent keep-alive connection.

• Endpoint: wss://api.leavepulse.com/agent/ws
• Authentication: JWT token (gateway.token in config).
• Features:
  • Whitelist Sync: Instant updates for access lists.
  • Moderation Commands: Web-to-game actions (Kick, Ban, Mute).
  • Maintenance Control: Enable/disable maintenance mode.
  • Telemetry Snapshots: On-demand server state requests.

Connection Lifecycle

1. Unconnected: Agent is loaded but lacks tokens. Only local diagnostics work.
2. Linked: connect command completed. Agent has a server_id and gateway.token.
3. Enrolled: Agent registered the environment, generated signing keys, and received an environment_id. Active reporting begins.
4. Stable: Gateway session has been active for over 12 seconds. Integration services (e.g., LuckPerms) are started.

Security

• Signing: All critical requests (e.g., whitelist changes) are signed using the Agent's local key.
• Token Scope: Gateway tokens have limited TTL and are bound to a specific server_id.
• Payload Relocation: The Agent uses shading for internal libraries (Jackson, SnakeYAML) to prevent conflicts with other plugins.