farmcontrol-ws/README.md

FarmControl WebSocket Service

A WebSocket microservice for FarmControl that handles real-time communication and distributed locking using etcd.

Features

• Real-time WebSocket communication
• Distributed locking using etcd
• Keycloak authentication integration
• MongoDB integration for user management
• Event streaming and notifications

Prerequisites

• Node.js (v16 or higher)
• etcd server
• MongoDB server
• Keycloak server (for authentication)

Installation

1. Clone the repository
2. Install dependencies:

   npm install
   

Configuration

The application uses config.json for configuration. Update the following sections:

Etcd Configuration

{
  "database": {
    "etcd": {
      "host": "localhost",
      "port": 2379
    }
  }
}

MongoDB Configuration

{
  "database": {
    "mongo": {
      "url": "mongodb://localhost:27017/farmcontrol"
    }
  }
}

Authentication Configuration

{
  "auth": {
    "enabled": true,
    "keycloak": {
      "url": "https://your-keycloak-server",
      "realm": "your-realm",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }
}

Running the Application

Development

npm run dev

Production

npm start

Etcd Setup

Installation

Using Docker

docker run -d --name etcd \
  -p 2379:2379 \
  -p 2380:2380 \
  quay.io/coreos/etcd:v3.5.0 \
  /usr/local/bin/etcd \
  --advertise-client-urls http://0.0.0.0:2379 \
  --listen-client-urls http://0.0.0.0:2379

Using Homebrew (macOS)

brew install etcd
etcd

Using apt (Ubuntu/Debian)

sudo apt-get install etcd
sudo systemctl start etcd

Verification

Test that etcd is running:

curl http://localhost:2379/version

Migration from Redis

This application was migrated from Redis to etcd. The main changes include:

1. Stream-like functionality: Redis streams are replaced with etcd key-value pairs using a prefix pattern
2. Hash-like functionality: Redis hashes are replaced with etcd key-value pairs using a prefix pattern
3. Pub/Sub: Redis pub/sub is replaced with etcd watchers
4. Connection management: Simplified connection handling with automatic reconnection

Key Differences

• Data structure: etcd uses a flat key-value store, so we simulate Redis data structures using key prefixes
• Streams: Instead of Redis streams, we use etcd keys with timestamps and random suffixes
• Watching: etcd watchers provide real-time notifications for key changes
• Transactions: etcd supports atomic operations for distributed locking

API Endpoints

The service exposes WebSocket endpoints for:

• Lock management: Lock/unlock objects with real-time notifications
• Authentication: Keycloak-based authentication
• Real-time updates: Stream-based event notifications

Development

Project Structure

src/
├── auth/           # Authentication logic
├── database/       # Database connections (etcd, mongo)
├── lock/           # Distributed locking
├── notification/   # Notification management
├── socket/         # WebSocket handling
└── index.js        # Main application entry point

Adding New Features

1. Database operations: Use the etcdServer instance for etcd operations
2. WebSocket events: Extend the SocketClient class
3. Authentication: Extend the KeycloakAuth class

Troubleshooting

Common Issues

1. Etcd connection failed: Ensure etcd is running on the configured host and port
2. Authentication errors: Verify Keycloak configuration and credentials
3. MongoDB connection issues: Check MongoDB server status and connection string

Logging

The application uses log4js for logging. Set the log level in the configuration:

{
  "server": {
    "logLevel": "debug"
  }
}

Available log levels: trace, debug, info, warn, error