Socket Connections

Socket Integration Specification

For high-performance, real-time ticket delivery (such as KDS or local printer controllers), our system establishes a TCP/IP connection to the integrator's service. The connection is a fire and forget methodology, following a CONNECT → SEND → DISCONNECT pattern. NX does not maintain a persistent connection to integrator's services.

1. Connection Architecture

Protocol: TCP/IP
Role: Our system acts as the Client (Sender); your integration acts as the Server (Listener).
Port: Default is 9100 (standard for raw printing), but configurable via the IPrinterDevice settings.
Persistence: Connections are not persistent. NX expects integrators services to be able to handle quick connection, receive and disconnect, freeing the service for a subsequent connection from client(s).

2. Message Framing (The "Envelope")

Because TCP is a stream-oriented protocol, multiple PRINT_REQUEST records may arrive in the same buffer. We use a Length-Prefix framing strategy to ensure reliable message reconstruction.

Each transmission consists of:

Header: A 4-byte big-endian integer representing the length of the following JSON string.
Payload: The UTF-8 encoded JSON string (the IPrintRequest object).

Segment	Data Type	Description
Length Prefix	`Int32` (BE)	The total byte count of the JSON payload.
JSON Payload	`String`	The raw string containing the `records` array.

3. Reliability & Error Handling

To ensure no tickets are lost in transit, integrators must adhere to the following:

Idempotency: Use the id (Print Request ID) and printSessionId to de-duplicate requests. If a socket reconnects and resends a payload, the id will remain identical.
Backpressure: If your KDS/Printer is busy, avoid blocking the socket read. Buffer the incoming JSON into a local queue to prevent the sender's TCP window from filling up.
ACK Pattern (Optional): If the integration requires a "Printed" confirmation, the integrator should send a 1-byte acknowledgement (0x06 for ACK) back through the socket after the JSON is successfully parsed.

4. Socket Status Mapping

Integrators should map the socket state to the status field within the model:

Socket Event	Model Status	Action
Initial Connection	`PENDING`	Connection established, awaiting data.
Packet Received	`CREATED`	JSON parsed successfully.
ACK Sent/Successful Print	`CONSUMED`	Item is now visible on KDS or printed to paper.

5. Test Utility

To aid developers in their integration, NX offers a simple Javascript/Node test utility:

https://github.com/nx-systems/nx-socket-printing-test-server