171 lines
3.7 KiB
Markdown
171 lines
3.7 KiB
Markdown
# 4NK Protocol Server
|
|
|
|
A high-availability server that automatically handles protocol operations for the 4NK network.
|
|
|
|
## Features
|
|
|
|
- **High Availability**: Runs continuously on a server
|
|
- **Automatic Operations**: Handles UPDATE_PROCESS, NOTIFY_UPDATE, and VALIDATE_STATE operations
|
|
- **Protocol Compatible**: Uses the same message format as the browser client
|
|
- **WebSocket Interface**: Real-time communication with clients
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install Dependencies
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 2. Build the Server
|
|
```bash
|
|
npm run build:server
|
|
```
|
|
|
|
### 3. Start the Server
|
|
```bash
|
|
npm run start:server
|
|
```
|
|
|
|
### 4. Development Mode
|
|
```bash
|
|
npm run dev:server
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file in the root directory:
|
|
|
|
```env
|
|
PORT=9090
|
|
JWT_SECRET_KEY=your-secret-key-here
|
|
DATABASE_PATH=./data/server.db
|
|
RELAY_URLS=ws://localhost:8090,ws://relay2.example.com:8090
|
|
LOG_LEVEL=info
|
|
```
|
|
|
|
## API Usage
|
|
|
|
Connect to the WebSocket server and send messages in the same format as the browser client:
|
|
|
|
### Example: Update Process
|
|
```javascript
|
|
const ws = new WebSocket('ws://localhost:9090');
|
|
|
|
ws.onopen = () => {
|
|
ws.send(JSON.stringify({
|
|
type: 'UPDATE_PROCESS',
|
|
processId: 'your-process-id',
|
|
newData: { field: 'value' },
|
|
privateFields: [],
|
|
roles: {},
|
|
accessToken: 'your-access-token',
|
|
messageId: 'unique-message-id'
|
|
}));
|
|
};
|
|
|
|
ws.onmessage = (event) => {
|
|
const response = JSON.parse(event.data);
|
|
console.log('Response:', response);
|
|
};
|
|
```
|
|
|
|
### Example: Notify Update
|
|
```javascript
|
|
ws.send(JSON.stringify({
|
|
type: 'NOTIFY_UPDATE',
|
|
processId: 'your-process-id',
|
|
stateId: 'your-state-id',
|
|
accessToken: 'your-access-token',
|
|
messageId: 'unique-message-id'
|
|
}));
|
|
```
|
|
|
|
### Example: Validate State
|
|
```javascript
|
|
ws.send(JSON.stringify({
|
|
type: 'VALIDATE_STATE',
|
|
processId: 'your-process-id',
|
|
stateId: 'your-state-id',
|
|
accessToken: 'your-access-token',
|
|
messageId: 'unique-message-id'
|
|
}));
|
|
```
|
|
|
|
## Deployment
|
|
|
|
### Systemd Service (Linux)
|
|
```bash
|
|
# Create service file
|
|
sudo tee /etc/systemd/system/4nk-server.service > /dev/null <<EOF
|
|
[Unit]
|
|
Description=4NK Protocol Server
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=4nk
|
|
WorkingDirectory=/opt/4nk-server
|
|
ExecStart=/usr/bin/node server-dist/server/server.js
|
|
Restart=always
|
|
RestartSec=5
|
|
Environment=NODE_ENV=production
|
|
Environment=JWT_SECRET_KEY=your-secret-key
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
# Enable and start service
|
|
sudo systemctl enable 4nk-server.service
|
|
sudo systemctl start 4nk-server.service
|
|
```
|
|
|
|
### Docker
|
|
```dockerfile
|
|
FROM node:18-alpine
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci --only=production
|
|
COPY server-dist ./server-dist
|
|
EXPOSE 9090
|
|
CMD ["node", "server-dist/server/server.js"]
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
The server logs all operations with timestamps and client IDs:
|
|
|
|
```
|
|
🚀 Initializing 4NK Protocol Server...
|
|
📡 Connecting to protocol relays...
|
|
✅ Server running on port 9090
|
|
📋 Supported operations: UPDATE_PROCESS, NOTIFY_UPDATE, VALIDATE_STATE
|
|
🔗 Client connected: client_1234567890_abc123 from 192.168.1.100
|
|
📨 Received message from client_1234567890_abc123: UPDATE_PROCESS
|
|
```
|
|
|
|
## Security
|
|
|
|
- All operations require valid JWT tokens
|
|
- Client IDs are tracked for audit logs
|
|
- Graceful shutdown handling
|
|
- Error handling and logging
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Port already in use**: Change the PORT environment variable
|
|
2. **JWT validation fails**: Check JWT_SECRET_KEY configuration
|
|
3. **Relay connection fails**: Verify RELAY_URLS configuration
|
|
4. **Permission denied**: Check file permissions for database directory
|
|
|
|
### Logs
|
|
Check server logs for detailed error information:
|
|
```bash
|
|
# If using systemd
|
|
sudo journalctl -u 4nk-server.service -f
|
|
|
|
# If running directly
|
|
npm run start:server
|
|
``` |