Printer Agent

Windows LAN Receipt Printer Client Agent for Neko Coffee.

Overview

The Printer Agent is a Node.js service that connects to the Neko Coffee backend via WebSocket and handles receipt printing on LAN thermal printers. It supports automatic token rotation for secure authentication.

Features

• WebSocket connection to backend
• Automatic token rotation via configUpdate messages
• Grace period support for seamless token transitions
• Heartbeat mechanism for connection health
• Automatic reconnection with exponential backoff

Token Rotation

The agent supports automatic token rotation managed by the backend:

1. Initial Token: Agent starts with a token from environment variables
2. Token Update: Backend sends configUpdate message with new token
3. Grace Period: Both old and new tokens are accepted during the transition period
4. Cleanup: Old tokens are automatically discarded after grace period

Token Rotation Flow

1. Agent connects with initial token
2. Backend sends configUpdate with newToken, validFrom, validUntil
3. Agent stores new token and old token
4. From validFrom: Agent uses new token for authentication
5. During grace period (validFrom to validUntil): Both tokens accepted
6. After validUntil: Old token discarded, only new token used

Installation

npm install

Configuration

Set the following environment variables:

• BACKEND_WS_URL (required): WebSocket URL to backend
• CLIENT_TOKEN (required): Initial authentication token
• MACHINE_ID (required): Unique machine identifier
• LOG_LEVEL (optional): Log level (error, warn, info, debug), default: info
• PRINTER_CONNECT_TIMEOUT_MS (optional): TCP connection timeout, default: 5000
• PRINT_RETRY_COUNT (optional): Number of retry attempts, default: 2
• HEARTBEAT_INTERVAL_MS (optional): Heartbeat interval, default: 30000

Development

# Build
npm run build

# Run
npm start

# Watch mode
npm run watch:build

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Project Structure

printer-agent/
├── src/
│   ├── index.ts              # Main entry point
│   ├── config.ts             # Configuration loading
│   ├── logger.ts             # Logging utility
│   ├── tokenManager.ts       # Token rotation logic
│   ├── websocketClient.ts    # WebSocket client
│   ├── types.ts              # TypeScript types
│   └── __tests__/
│       ├── config.test.ts
│       ├── tokenManager.test.ts
│       ├── websocketClient.test.ts
│       └── e2e/
│           └── token-rotation.e2e.test.ts
├── package.json
├── tsconfig.json
└── jest.config.js

Token Rotation Implementation

TokenManager

The TokenManager class handles all token rotation logic:

• getCurrentToken(): Returns the active token to use
• getAcceptedTokens(): Returns all tokens valid during grace period
• updateToken(): Updates token from configUpdate message
• cleanupExpiredTokens(): Removes expired tokens
• isInGracePeriod(): Checks if currently in grace period

WebSocketClient

The WebSocketClient class handles WebSocket communication:

• Handles configUpdate messages
• Verifies machineId matches
• Updates token via TokenManager
• Reconnects if new token is immediately valid
• Sends hello message with current token on connect

E2E Tests

The e2e tests verify the complete token rotation flow:

1. Connection and authentication
2. Receiving and processing configUpdate
3. Ignoring configUpdate with wrong machineId
4. Using new token after rotation
5. Handling future-dated tokens
6. Grace period management
7. Token cleanup after expiration

License

ISC