Socket.IO connections and responses

Network uses Socket.IO with Engine.IO path /socket and WebSocket without polling. Path and namespace are separate settings. See the event list and JSON.

Network namespaces

Namespace	Client	Auth
/client	.web staff panel	auth.token: personal RS256 panel scope with exact pid/sid or legacy scoped token
/front	Account/public frontend with an account	auth.token, supported account/network token; anonymous access is not established

Namespace / is not a fallback public API. User connections check project, server, session validity, permissions and subscription.

Panel client example

Example for socket.io-client 4.x after obtaining a valid scoped token. Your normal auth flow supplies networkOrigin and panelToken; keep credentials out of source:

import { io } from 'socket.io-client'

const socket = io(`${networkOrigin}/client`, {
  path: '/socket',
  transports: ['websocket'],
  auth: { token: panelToken }
})

socket.on('connected', async () => {
  try {
    const result = await socket.timeout(10000).emitWithAck('server.getConfig', {})
    if (result.status !== 'success') {
      showError(result.error?.name, result.error?.message)
      return
    }
    applyConfig(result.response)
  } catch {
    showConnectionTimeout()
  }
})

Display/application functions belong to your app, not an ozProtect SDK. Register listeners once; do not accumulate another handler on every reconnect. Client option sources: Socket.IO client options, ack API.

Request responses

A normal client request to a Network handler receives an ACK:

{"status":"success","response":{}}

{"status":"error","error":{"name":"access_denied","message":"..."}}

Application connected means the user context is ready after checks. Transport connect alone does not establish panel readiness.

Large identifiers and retries

Minecraft player IDs are always 19-digit strings. Do not use Number, parseInt or a JSON parser that already lost precision from a numeric literal. The backend supports bigint-safe parsing for its raw payload contract; senders must still retain string IDs.

Do not automatically retry punishment or uploads after an uncertain ACK. Read state/history first; losing a response does not undo persistence. Redis adapter supports ACK within a cluster; global cross-region notifications do not guarantee responses.

Only the permitted user-facing panel and account interface is published. Internal application protocols are not described here.