Vonix Server Utilities — Outside-Mod SPI & Developer Notes

Release Line: 2.0.2 Public SPI ContractStandalone Boundary

VSU is a standalone public core. It does not ship, require, or connect to any web service, API key, or proprietary companion mod.

1. SPI Design Principles

To support external web companions (such as web player dashboards) without compromising server security or independence, VSU exposes an outside-mod Service Provider Interface (SPI):

• Optional companions must live in a completely separate repository.
• Companions compile strictly against the public package:

  network.vonix.serverutilities.api

• No credentials, secrets, or remote network calls exist within the VSU core codebase.

---

2. Discoverability & Lifecycle

Companions discover the VSU engine via VonixPanels.current():

import network.vonix.serverutilities.api.VonixPanels;
import network.vonix.serverutilities.api.VonixPanel;

// Query the optional provider:
Optional<VonixPanel> panel = VonixPanels.current();
if (panel.isPresent()) {
    VonixPanel vsu = panel.get();
    // Safely query capabilities or read immutable projections
}

• VonixPanels.current() returns Optional.empty() until VSU completes server initialization.
• The presence of a companion mod does not automatically unlock any feature gate; features remain governed by config/vonix_server_utilities.properties.

---

3. Allowed Surface (Immutable Projections)

The SPI allows reading bounded, read-only snapshots of server state:

1. Immutable State Snapshots:
   • HomeSnapshot — List of named homes and dimensions for a player.
   • LastDeathSnapshot — Coordinates and timestamp of most recent death.
   • PlayerStateSnapshot — Player health, food level, and online status.
   • InventorySnapshot — Read-only items currently held.
   • ServerSnapshot — Current tick rate (TPS) and the in-game online player list from the bound server. This is a local SPI projection, not public telemetry.
2. Capability Reporting:
   • PanelCapabilities & PanelFeatureKeys describe enabled subsystems.
3. Permission-Checked Teleports:
   • PanelTeleportRequest / PanelTeleportResult allow requesting a teleport only to spawn or an already-existing named home. Arbitrary coordinates are strictly rejected.
4. Bounded Lifecycle Events:
   • Companions can register listeners (registerListener) with a hard cap of 8 listeners and a 64-event circular buffer that drops the oldest event if saturated.

---

4. Strictly Rejected APIs (Security Invariants)

The SPI enforces strict isolation:

• ❌ No Direct SQL or Database Access: The SQLite database path, connection pool, and raw queries are private to VSU core.
• ❌ No Arbitrary Commands or Free Coordinates: Companions cannot execute console commands or teleport players to unverified locations.
• ❌ No Permission Bypasses: All actions require active player UUID checks (actorUUID == targetUUID).
• ❌ No HTTP Clients or Secrets: VSU core contains no HTTP connection logic, cookies, bearer tokens, or API keys.

---

5. Concurrency Invariants

• Teleportation requests must execute on the Minecraft main server thread. Off-thread requests from companions are queued for next-tick execution or rejected if no server is bound.
• All feature gates in vonix_server_utilities.properties default to fail-closed (disabled), except panel_death_history_enabled=true.