NetCore

NetCore is a standalone Java 21 player-data platform for Minecraft networks.

Implemented v1

• Multi-module architecture:

  • netcore-api (domain + gRPC contract)
  • netcore-storage-postgres (Postgres source of truth + optimistic locking + idempotency + outbox)
  • netcore-cache-redis (L2 cache)
  • netcore-events (Redis stream publisher + in-memory fanout)
  • netcore-service (REST + gRPC + auth + rate limits + outbox relay)
  • netcore-sdk-core (async Java SDK with L1 cache + single-flight)
  • netcore-sdk-velocity-bungee
  • netcore-sdk-paper-spigot
  • netcore-sdk-ts (TypeScript SDK with L1 cache + single-flight + SSE subscription)

• REST API (/v1):

  • GET /v1/players/{uuid}?modules=...
  • POST /v1/players/{uuid}/mutations
  • POST /v1/players:batchGet
  • GET /v1/events/stream (SSE)

• gRPC API (netcore.v1.PlayerDataService):

  • GetPlayer
  • BatchGetPlayers
  • MutatePlayer
  • SubscribePlayerEvents

Build

cd Z:\Projects\SunHaven\netcore
.\gradlew.bat build

TypeScript SDK

Run SDK tests:

cd Z:\Projects\SunHaven\netcore\netcore-sdk-ts
npm install
npm run test

Examples

• Cross-platform examples are available in examples/README.md
• Paper/Spigot sample: examples/paper-spigot/PlayerSettingsServiceExample.java
• Velocity/Bungee sample: examples/velocity-bungee/ProxyProfileCommandExample.java
• TypeScript samples: examples/typescript/README.md

Local Run

1. Start infrastructure:

cd Z:\Projects\SunHaven\netcore\deploy\docker-compose
docker compose up -d postgres redis

2. Start service:

cd Z:\Projects\SunHaven\netcore
.\gradlew.bat :netcore-service:bootRun

Service ports:

• REST: 8080
• gRPC: 9090

Alternative (all-in-docker):

cd Z:\Projects\SunHaven\netcore\deploy\docker-compose
docker compose up -d --build postgres redis netcore-service

Auth Defaults

• API key header: X-Api-Key
• Default local key in application.yml: dev-key-read-write
• Scopes:
  • players:read
  • players:write
  • events:read

Notes

• Concurrency control is per player via optimistic locking (expectedVersion).
• Idempotency is enforced per player + idempotency key.
• Outbox relay publishes to Redis stream: netcore.player.events.

API Smoke Checks

REST:

curl -H "X-Api-Key: dev-key-read-write" http://localhost:8080/v1/players/00000000-0000-0000-0000-000000000001

gRPC (with grpcurl):

grpcurl -plaintext localhost:9090 list
grpcurl -plaintext localhost:9090 describe netcore.v1.PlayerDataService

Production Use Cases

• Cross-server gameplay settings:
  • Keep preferences (chat, ui, social) synchronized between lobby, minigame and survival servers.
• Moderation and support dashboards:
  • Read and update user flags/settings from web panels without direct DB/Redis access.
• Discord or website account tooling:
  • Trigger user preference changes from bots and backend jobs through stable API contracts.
• Real-time profile propagation:
  • Subscribe to event stream and invalidate/update local server caches in near real time.

Production Hardening Checklist

• Run at least 2 NetCore service instances behind a load balancer.
• Use managed PostgreSQL backups with PITR and periodic restore tests.
• Configure Redis persistence (AOF) and memory limits/eviction policy intentionally.
• Rotate API keys/JWT secrets and store them only in secret management.
• Add tracing/metrics/log correlation (request ID, actor, player ID) for every mutation.
• Apply retry with backoff only on safe operations and always keep idempotency keys stable per request.

Production Deployment Notes

• Prefer 2+ NetCore instances behind a load balancer.
• Use rolling deploys and keep idempotency keys stable across retries.
• Keep Redis Streams retention high enough for consumer lag and replay windows.
• Define SLOs for:
  • mutation latency (p95, p99)
  • event propagation lag
  • conflict rate (409/ABORTED) per endpoint/client