Network operations
This section is for the ozProtect team. Network runs on our infrastructure; granting a game server owner access does not require distributing backend source.
Services and status
Network uses Node.js, MySQL primary/read, Redis and Socket.IO. HTTP, cron-worker and Telegram-worker have separate entry points. Shared and dedicated k3s manifests have different scopes; customer-specific settings belong to dedicated configuration.
| Check | Meaning | Does not establish |
|---|---|---|
/healthz | HTTP process liveness | Plugin connection and every dependency |
/readyz | Dependency readiness state | A complete game flow, data correctness or external notifications |
/metrics | Prometheus metrics | A public player API |
/status.json, status/admin | Observability and service management with their checks | Permission to publish internal data or call admin routes without a session |
Status UI has its own authentication/unlock and visibility configuration. Keep service URLs/passwords/tokens out of user guides. Old-environment CORS and host lists do not establish a future domain's readiness.
MySQL and replicas
Writes and read-after-write flows use primary. A read connection suits heavy lists when replica lag is acceptable. Minecraft IDs are allocated only in a primary transaction; replica reads there undermine confirmed-result semantics.
Avoid frequent SQL health queries in hot methods. Use pool/connection state and existing status/metrics checks. Back up game_player_ids with history: clearing UUID mappings and reissuing IDs is unsafe.
Migrations
Network uses Knex/mysql2, immutable timestamped migrations and native Knex metadata. App startup does not migrate schema. Operator example after selecting and checking the target database:
$env:MIGRATION_ENV_FILE = 'C:\private\chosen.env'
npm run migrate:status
npm run migrate:latestmigrate:status can create Knex metadata on an unmanaged database; it is not strictly read-only. MIGRATION_ALLOW_ENV=1 permits explicitly prepared environment values instead of a file. --env production does not select a safe separate credentials file.
The baseline contains only 69 ozprotect_net table definitions, without data rows or ozprotect_ac. Existing tables are not rewritten, but adoption does not compare their full schema. MySQL DDL may commit partially; inspect failures before a forward repair. Initial identity/history migrations deliberately reject destructive down. Use unlock only after confirming the previous migration process stopped.
Redis and background jobs
Internal Redis adapter supports fanout and callbacks/acknowledgements. Global Redis is notify-only across regions. A response needs a designed HTTP/persisted-state flow. A delivered notification does not establish remote command application.
Do not duplicate cron cleanup in every pod without the intended coordination. Follow _docs/k3s/cron-worker.md and existing locks. Telegram for RU uses an NL worker agent for the RU cluster; routing changes require queue and deployment review together.
Diagnostics
Record timestamp, commit/build, project/server, method/event, error type, persistence stage and ACK. Remove tokens, passwords, webhooks and session codes. Distinguish diagnostic snapshots from real game acceptance.
Sources: Network common/server/metricsAndStatusRoutes.js, common/server/statusAuth.js, _docs/sql/MIGRATIONS.md, _docs/k3s/{cron-worker,telegram-worker,global-events,DB_REPLICA}.md.