feat(http/api): full http api expansion (config, status, bedrock players, lite routing)

[dilllxd]

Summary

This PR delivers a major expansion of the Gate HTTP API, enabling full lifecycle config management, bedrock player insights, and dynamic Lite route operations.

Changes Made

🟢 Status RPC

• Added GetStatus endpoint for lightweight health/metadata checks
• Exposes proxy version, operation mode, player/server counts
• Useful for monitoring integrations and automated health checks

🔧 Config Management

• ValidateConfig: Dry-run validation of incoming JSON/YAML configs with detailed warnings/errors
• ApplyConfig:
  • In-memory application (default) for ephemeral changes
  • Persistent mode ("persist": true) to overwrite existing config file while preserving original format (YAML/JSON)
• Clear oneof design: choose json_config (structured, snake_case) or yaml_config (string, camelCase)

🎮 Player Management

• Bedrock Player Data Integration:
  • Rich bedrock sub-object for cross-play users, including:
    • XUID (Xbox User ID)
    • Device OS, language, UI profile, input mode
    • Proxy/VPN detection
    • Linked Java account (if available)
  • Transparent support via Geyser/Floodgate, no impact on Java-only users

🌐 Lite Route Management

• ListLiteRoutes / GetLiteRoute: Inspect current Lite routes
• AddLiteRouteBackend / RemoveLiteRouteBackend: Dynamically adjust backend pools
• UpdateLiteRouteStrategy: Control balancing (e.g., least-connections, round-robin)
• UpdateLiteRouteOptions: Fine-tune route behavior (e.g., proxy protocol, ping cache TTL)
• UpdateLiteRouteFallback: Define MOTD, version, and player list for unavailable routes
• Enables real-time backend scaling and failover handling without restarts

🧪 Testing & Quality

• Config validation with both JSON and YAML formats
• Persistent config overwrite tested against existing YAML/JSON files
• Bedrock player data confirmed through Geyser/Floodgate connections

API Examples

Status Check

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/GetStatus   -H 'Content-Type: application/json' -d '{}'

Example Response

{
  "version": "0.57.0",
  "mode": "standard",
  "players_online": 5,
  "servers_registered": 3
}

---

Validate Config (JSON)

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ValidateConfig   -H 'Content-Type: application/json'   -d '{
    "json_config": {
      "api": { "enabled": true, "bind": "localhost:8080" },
      "config": {
        "bind": "0.0.0.0:25565",
        "online_mode": true,
        "forwarding": { "mode": "legacy" },
        "servers": { "server1": "localhost:25566" },
        "try": ["server1"]
      }
    }
  }'

Example Response

{
  "valid": true,
  "warnings": []
}

---

Apply Config (In-Memory)

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ApplyConfig   -H 'Content-Type: application/json'   -d '{ "json_config": { ... } }'

Example Response

{
  "applied": true,
  "persisted": false
}

---

Apply Config (Persistent, YAML)

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ApplyConfig   -H 'Content-Type: application/json'   -d '{
    "yaml_config": "api:\n  enabled: true\n  bind: localhost:8080\n\nconfig:\n  bind: 0.0.0.0:25565\n  onlineMode: true\n  servers:\n    lobby: localhost:25565\n  try:\n    - lobby",
    "persist": true
  }'

Example Response

{
  "applied": true,
  "persisted": true
}

---

List Players

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ListPlayers   -H 'Content-Type: application/json' -d '{}' | jq

Example Response

{
  "players": [
    { "id": "uuid-1", "username": "Steve" },
    { "id": "uuid-2", "username": ".BedrockPlayer" }
  ]
}

---

Get Player (with Bedrock Data)

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/GetPlayer   -H 'Content-Type: application/json'   -d '{"username": ".BedrockPlayer"}'

Example Response

{
  "player": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": ".BedrockPlayer",
    "bedrock": {
      "xuid": 2533274792395724,
      "device_os": "Android",
      "language": "en_US",
      "ui_profile": 1,
      "input_mode": 2,
      "behind_proxy": false,
      "linked_player": "JavaAccount123"
    }
  }
}

---

List Lite Routes

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ListLiteRoutes   -H 'Content-Type: application/json' -d '{}' | jq

Example Response

{
  "routes": [
    { "host": "mc.example.com", "backends": ["127.0.0.1:25570"] }
  ]
}

---

Add Lite Backend

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/AddLiteRouteBackend   -H 'Content-Type: application/json'   -d '{"host": "mc.example.com", "backend": "127.0.0.1:25570"}'

Example Response

{
  "success": true
}

---

Remove Lite Backend

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/RemoveLiteRouteBackend   -H 'Content-Type: application/json'   -d '{"host": "mc.example.com", "backend": "127.0.0.1:25570"}'

Example Response

{
  "success": true
}

---

Update Lite Strategy

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/UpdateLiteRouteStrategy   -H 'Content-Type: application/json'   -d '{"host": "mc.example.com", "strategy": "least-connections"}'

Example Response

{
  "updated": true
}

---

Update Lite Options

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/UpdateLiteRouteOptions   -H 'Content-Type: application/json'   -d '{
    "host": "mc.example.com",
    "options": {
      "proxyProtocol": true,
      "cachePingTtlMs": 20000
    }
  }'

Example Response

{
  "updated": true
}

---

Update Lite Fallback

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/UpdateLiteRouteFallback   -H 'Content-Type: application/json'   -d '{
    "host": "mc.example.com",
    "fallback": {
      "motdJson": "\"Temporarily Offline\"",
      "version": { "name": "Gate Lite", "protocol": 764 },
      "players": { "online": 0, "max": 100 }
    }
  }'

Example Response

{
  "updated": true
}

Attribution

This PR was prepared with assistance from Codex & Claude Code. All code changes were reviewed by the author.

[robinbraemer]

Left some comments. Didn’t looked at api implementation yet since that likely changes

[dilllxd]

Left some comments. Didn’t looked at api implementation yet since that likely changes

Sounds good, will look into later and resolve.

[dilllxd]

Review Writeup

🔧 L51 - Lite Mode Inconsistency

Issue: "The servers and players fields would be inconsistent when in lite mode."

✅ Solution: Complete redesign of status API

• Before: Tried to force classic mode concepts onto lite mode (misleading data)
• After: Mode-specific response structure using protobuf oneof
• Classic mode: {"classic": {"players": N, "servers": N}}
• Lite mode: {"lite": {"connections": N, "routes": N}}
• Implementation: Fixed connection tracking to work across all lite strategies, not just least-connections
• Result: Crystal clear, accurate metrics for each mode

🔐 L56 - Secret Redacting

Issue: "Which secrets?"

✅ Solution: Removed all secret redacting functionality

• Before: Confusing references to "secrets redacted" without clear purpose
• After: GetConfig returns full configuration without redacting
• Files modified: Removed redacting logic from handlers and protobuf comments
• Result: Simplified, predictable API behavior

🏗️ L66 - Service Separation

Issue: "All Lite RPCs would be better in a dedicated GateLiteService."

✅ Solution: Created separate service for lite operations

• Before: All RPCs mixed in single GateService
• After: Clean separation into two services:
  • GateService: Core proxy management (status, config, players, servers)
  • GateLiteService: Lite route management (routes, backends, strategies, fallbacks)
• Files created: Updated protobuf definitions and service handlers
• Result: Clear architectural separation, easier to understand and maintain

📝 L123 - DisconnectPlayerRequest Comment Formatting

Issue: "Be careful why did this got formatted"

✅ Solution: Reverted accidental escape formatting

• Before: Example JSON text component was auto-escaped to {\"text\":\"Hello\"}
• After: Restored to correct readable form: {"text":"Hello"}
• Cause: Accidental auto-fix from previous tool run
• Result: Clear example JSON in comments, no misleading escaping

🎮 L237, L244, L499 - Enum Implementation

Issues:

• L237: "Not sure if this can be an enum or must stay flexible string" (device_os)
• L244: "Can definitely be an enum" (input_mode)
• L499: "Also should be enum" (route strategy)

✅ Solution: Implemented proper enums for all identified fields

• BedrockDeviceOS: Android, iOS, Xbox, PlayStation, Switch, Windows, etc.
• BedrockInputMode: Mouse, Touch, Gamepad, Motion Controller
• BedrockUIProfile: Classic, Pocket
• LiteRouteStrategy: Sequential, Random, Round-Robin, Least-Connections, Lowest-Latency
• Implementation: Full enum definitions with conversion functions
• Result: Type safety, better API documentation, eliminated magic strings

📝 L270 - Config API Simplification

Issue: "Since json is a superset of yaml I would be curious to drop this and always parse the config input with a yaml decoder. Or auto detect json/yaml… As long as we can simplify the api."

✅ Solution: Eliminated ConfigFormat enum, simplified to single field

• Before: Separate yaml_config/json_config fields plus format enum
• After: Single config string field with YAML decoder (auto-handles JSON)
• GetConfig: Always returns YAML format
• ValidateConfig/ApplyConfig: Accept single config field
• Result: Much simpler API, eliminates format confusion

🗑️ L285 - Obsolete Code Removal

Issue: "This health service is obsolete code in gate."

✅ Solution: Removed HealthServiceConfig entirely

• Before: HealthServiceConfig field in GateConfig
• After: Completely removed from protobuf definitions
• Result: Cleaner config structure, no dead code

📖 L315 - Documentation Coverage

Issue: "I'm missing doc comments above the fields. That goes with all fields in the PR."

✅ Solution: Added comprehensive field documentation

• Before: Many fields lacked proper documentation
• After: Every field has detailed comments explaining purpose and usage
• Coverage: All protobuf messages, fields, enums, and RPC methods
• Result: Self-documenting API, clear usage guidance

🔧 L344 - StringList Helper Removal

Issue: "Not sure what the real benefit is."

✅ Solution: Removed StringList helper, simplified approach

• Before: Custom StringList helper message
• After: Direct use of standard protobuf types and JSON strings where needed
• Result: Less complexity, standard protobuf patterns

⚠️ L372 - Error Array Handling

Issue: "We also have an array of errors right? Or does the rpc fail then. How would we report multiple errors."

✅ Solution: Added proper error array to validation responses

• Before: Unclear error handling for multiple validation issues
• After: ValidateConfigResponse has both warnings and errors arrays
• Implementation: Multiple config errors properly collected and returned
• Result: Better error reporting, doesn't fail on first error

🏛️ convert.go L19 - Comment Accuracy

Issue: "Invalid comment. We use the context helper as done right."

✅ Solution: Fixed comment to reflect actual implementation

• Before: Inaccurate comment about Bedrock player detection
• After: "Try to get the Geyser connection from the player's context" using Geyser context helper
• Result: Code comments match actual implementation

🔨 service.go L27 - Architecture Fix

Issue: "Not fan of funcs in struct approach."

✅ Solution: Eliminated anti-pattern, implemented proper interfaces

• Before: ServiceHandlers struct with function fields (anti-pattern)
• After: Clean interface-based architecture:
  • ConfigHandler interface for config operations
  • LiteHandler interface for lite operations
  • Concrete implementations: ConfigHandlerImpl, LiteHandlerImpl
• Implementation: Proper dependency injection with interfaces
• Result: Clean Go patterns, testable, maintainable code

🎯 Summary

All 14 review points addressed with comprehensive solutions:

• ✅ Fixed architectural issues (service separation, interface design)
• ✅ Added proper type safety (enums for all data types)
• ✅ Simplified API design (config handling, status structure)
• ✅ Removed obsolete/confusing code (health service, secret redacting)
• ✅ Enhanced documentation (comprehensive field docs)
• ✅ Improved error handling (multiple error reporting)
• ✅ Fixed implementation details (comments, connection tracking, formatting)

[dilllxd]

New API Docs:

🟢 Status Check

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/GetStatus \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Response (Classic Mode)

{
  "version": "0.57.0",
  "mode": "PROXY_MODE_CLASSIC",
  "classic": {
    "players": 5,
    "servers": 3
  }
}

Example Response (Lite Mode)

{
  "version": "0.57.0",
  "mode": "PROXY_MODE_LITE",
  "lite": {
    "connections": 12,
    "routes": 2
  }
}

ℹ️ Response structure changes depending on proxy mode.

---

📑 Validate Config (YAML / JSON)

YAML Example

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ValidateConfig \
  -H 'Content-Type: application/json' \
  -d '{
    "config": "api:\n  enabled: true\n  bind: localhost:8080\n\nconfig:\n  bind: 0.0.0.0:25565\n  onlineMode: true\n  forwarding:\n    mode: legacy\n  servers:\n    server1: localhost:25566\n  try:\n    - server1"
  }'

JSON Example

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ValidateConfig \
  -H 'Content-Type: application/json' \
  -d '{
    "config": "{\"api\":{\"enabled\":true,\"bind\":\"localhost:8080\"},\"config\":{\"bind\":\"0.0.0.0:25565\",\"onlineMode\":true,\"forwarding\":{\"mode\":\"legacy\"},\"servers\":{\"server1\":\"localhost:25566\"},\"try\":[\"server1\"]}}"
  }'

Example Response

{
  "warnings": [],
  "errors": []
}

ℹ️ The config field accepts YAML and JSON strings. YAML parser supports JSON as a superset.

---

⚙️ Apply Config

In-Memory

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ApplyConfig \
  -H 'Content-Type: application/json' \
  -d '{
    "config": "api:\n  enabled: true\n  bind: localhost:8080\n\nconfig:\n  bind: 0.0.0.0:25565\n  onlineMode: true\n  forwarding:\n    mode: legacy\n  servers:\n    server1: localhost:25566\n  try:\n    - server1",
    "persist": false
  }'

Persistent

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ApplyConfig \
  -H 'Content-Type: application/json' \
  -d '{
    "config": "api:\n  enabled: true\n  bind: localhost:8080\n\nconfig:\n  bind: 0.0.0.0:25565\n  onlineMode: true\n  forwarding:\n    mode: legacy\n  servers:\n    server1: localhost:25566\n  try:\n    - server1",
    "persist": true
  }'

Example Response

{
  "warnings": ["config persisted to disk"]
}

---

📂 Get Current Config

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/GetConfig \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Response

{
  "payload": "api:\n  enabled: true\n  bind: localhost:8080\n\nconfig:\n  bind: 0.0.0.0:25565\n  onlineMode: true\n  forwarding:\n    mode: legacy\n  servers:\n    lobby: localhost:25565\n  try:\n    - lobby\n  lite:\n    enabled: false\n    routes: []"
}

ℹ️ Config is always returned as YAML, regardless of the original format.

---

👥 Player Management

List Players

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/ListPlayers \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

Get Player (with Bedrock Data)

curl -X POST http://localhost:8080/minekube.gate.v1.GateService/GetPlayer \
  -H 'Content-Type: application/json' \
  -d '{"username": ".BedrockPlayer"}'

Example Response

{
  "player": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": ".BedrockPlayer",
    "bedrock": {
      "xuid": 2533274792395724,
      "deviceOs": "BEDROCK_DEVICE_OS_ANDROID",
      "language": "en_US",
      "uiProfile": "BEDROCK_UI_PROFILE_POCKET",
      "inputMode": "BEDROCK_INPUT_MODE_TOUCH",
      "behindProxy": false,
      "linkedPlayer": "JavaAccount123"
    }
  }
}

ℹ️ Bedrock fields now return enum values instead of raw strings/numbers.

---

🛠️ Lite Route Management

List Lite Routes

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/ListLiteRoutes \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

Example Response

{
  "routes": [
    {
      "hosts": ["mc.example.com"],
      "backends": [
        { "address": "127.0.0.1:25570", "activeConnections": 5 }
      ],
      "strategy": "LITE_ROUTE_STRATEGY_SEQUENTIAL",
      "options": {
        "proxyProtocol": false,
        "tcpShieldRealIp": false,
        "modifyVirtualHost": true,
        "cachePingTtlMs": 10000
      }
    }
  ]
}

Add Lite Backend

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/AddLiteRouteBackend \
  -H 'Content-Type: application/json' \
  -d '{"host": "mc.example.com", "backend": "127.0.0.1:25570"}'

Remove Lite Backend

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/RemoveLiteRouteBackend \
  -H 'Content-Type: application/json' \
  -d '{"host": "mc.example.com", "backend": "127.0.0.1:25570"}'

Update Lite Strategy

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/UpdateLiteRouteStrategy \
  -H 'Content-Type: application/json' \
  -d '{"host": "mc.example.com", "strategy": "LITE_ROUTE_STRATEGY_LEAST_CONNECTIONS"}'

Update Lite Options

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/UpdateLiteRouteOptions \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "mc.example.com",
    "options": {
      "proxyProtocol": true,
      "cachePingTtlMs": 20000
    },
    "updateMask": {
      "paths": ["proxy_protocol", "cache_ping_ttl_ms"]
    }
  }'

Update Lite Fallback

curl -X POST http://localhost:8080/minekube.gate.v1.GateLiteService/UpdateLiteRouteFallback \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "mc.example.com",
    "fallback": {
      "motdJson": "\"Temporarily Offline\"",
      "version": { "name": "Gate Lite", "protocol": 764 },
      "players": { "online": 0, "max": 100 }
    },
    "updateMask": {
      "paths": ["motd_json", "version", "players"]
    }
  }'

[dilllxd]

Files Modified

Core Changes

• pkg/gate/gate.go: Added ConfigFilePath field to Options struct and passed config file path through the system
• pkg/gate/api.go: Modified setupAPI to accept and pass config file path to handlers
• pkg/gate/api_handlers.go: NEW FILE - Complete API handler implementations with proper config file path handling

API Infrastructure Fixes

• pkg/internal/api/server.go: Added GateLiteService handler registration to expose lite mode endpoints
• pkg/internal/api/service.go: Added interface assertion to ensure Service implements GateLiteServiceHandler

Build/Development

• .gitignore: Removed gate binary from gitignore (if this is needed for some reason we can revert, was messing with me uploading api_handlers.go)

Key Implementation Details

1. Config Path Propagation: Start() → New() → setupAPI() → NewConfigHandler()
2. API Endpoint Registration: Fixed missing GateLiteService endpoints that were returning 404
3. Interface Compliance: Added explicit interface assertions to catch compilation issues early
4. Error Handling: Returns clear error when config file path is unavailable
5. Format Support: ApplyConfig RPC accepts both YAML and JSON input, but always persists as .yml/.yaml files only
6. Backward Compatibility: Default behavior (no --config flag) works unchanged

API Handler Features

The new api_handlers.go implements full config and lite mode management:

• Config validation, application, and persistence
• Lite route management (CRUD operations)
• Server status reporting
• Proper error handling and warnings

[robinbraemer]

Next quest would be to add tests to this baby to make sure this massive PR works

[dilllxd]

Next quest would be to add tests to this baby to make sure this massive PR works

On it, will make the two changes you requested then work on tests.

[dilllxd]

Test Coverage for HTTP API Expansion

Overview

Added comprehensive test coverage for the HTTP API expansion feature, ensuring all new functionality is thoroughly tested and follows Gate's established testing patterns.

New Test Files Added

1. pkg/gate/api_handlers_test.go

Purpose: Tests for ConfigHandlerImpl covering config management APIs

• ✅ GetStatus - Tests both classic and lite mode status reporting
• ✅ GetConfig - YAML serialization and config retrieval
• ✅ ValidateConfig - Config validation with proper error/warning handling
• ✅ ApplyConfig - Config application with and without persistence
• ✅ Persistence error scenarios (invalid paths, unsupported file types)

2. pkg/gate/api_handlers_lite_test.go

Purpose: Tests for LiteHandlerImpl covering all lite route management APIs

• ✅ ListLiteRoutes - Route listing with proper proto conversion
• ✅ GetLiteRoute - Individual route lookup with host matching (case-insensitive)
• ✅ UpdateLiteRouteStrategy - Strategy updates (round-robin, sequential, etc.)
• ✅ AddLiteRouteBackend - Backend addition with duplicate prevention
• ✅ RemoveLiteRouteBackend - Backend removal (case-insensitive)
• ✅ UpdateLiteRouteOptions - Field mask-based option updates
• ✅ UpdateLiteRouteFallback - MOTD, version, and player fallback configuration

3. pkg/internal/api/service_test.go

Purpose: API service integration tests following Gate's patterns (no mocks)

• ✅ Service layer integration with config and lite handlers
• ✅ Error handling for missing handlers
• ✅ Proper Connect RPC response handling
• ✅ Uses simple test handlers instead of mocking (Gate convention)

4. pkg/internal/api/convert_test.go

Purpose: Proto conversion function validation

• ✅ Strategy enum conversions (string ↔ proto enum, both directions)
• ✅ Round-trip conversion validation ensuring no data loss
• ✅ Bedrock data conversions (DeviceOS, UIProfile, InputMode)
• ✅ Edge case handling (unknown values, defaults)

Test Design Principles

Follows Gate's Established Patterns

• Real Objects: Uses actual config objects and handlers instead of mocks
• Table-Driven Tests: Comprehensive test scenarios in structured format
• Helper Functions: createValidTestConfig() and createValidLiteTestConfig() for proper setup
• Error Scenarios: Tests both success and failure paths extensively

Comprehensive Coverage Areas

• Config Management: Validation, application, persistence scenarios
• Route Management: All CRUD operations for lite routes and backends
• Proto Integration: Ensures API contracts work correctly
• Error Handling: Invalid inputs, missing resources, permission issues
• Integration: Service layer connects handlers correctly

Why These Tests Were Added

1. API Reliability: New HTTP endpoints need validation to prevent runtime failures
2. Data Integrity: Config and route management operations must preserve data correctly
3. Proto Contracts: API responses must match expected format for client compatibility
4. Error Scenarios: Robust error handling prevents crashes and provides useful feedback
5. Regression Prevention: Comprehensive tests catch future breaking changes

Integration with Existing Tests

The new tests integrate seamlessly with Gate's existing test suite:

• Connection Tracking: Changes to pkg/edition/java/lite/forward.go are covered by existing lite tests
• Config Validation: Builds on patterns from pkg/gate/config/api_config_test.go
• No Conflicts: All existing tests continue to pass (verified)

Test Results

• Total New Test Cases: ~50+ individual scenarios
• Pass Rate: 100% - all tests passing
• Coverage: Complete coverage of all HTTP API expansion functionality
• Pattern Compliance: ✅ Follows Gate's testing conventions

These tests ensure the HTTP API expansion is production-ready with comprehensive validation of all new functionality.

[robinbraemer]

Currently a bit overloaded by volume of this PR so will take longer :)
Will try by next release.

[robinbraemer]

@cursor can you run the tests to check if they not block forever. Also provide tips to make the PR cleaner it looks a bit bloated and incomplete (hard to review) also regarding what futures it adds, and describe the value-add/use cases. Maybe also update our .web/docs for our users in the http api sections