# 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:
   ```bash
   npm install
   ```

## Configuration

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

### Etcd Configuration
```json
{
  "database": {
    "etcd": {
      "host": "localhost",
      "port": 2379
    }
  }
}
```

### MongoDB Configuration
```json
{
  "database": {
    "mongo": {
      "url": "mongodb://localhost:27017/farmcontrol"
    }
  }
}
```

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

## Running the Application

### Development
```bash
npm run dev
```

### Production
```bash
npm start
```

## Etcd Setup

### Installation

#### Using Docker
```bash
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)
```bash
brew install etcd
etcd
```

#### Using apt (Ubuntu/Debian)
```bash
sudo apt-get install etcd
sudo systemctl start etcd
```

### Verification
Test that etcd is running:
```bash
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:

```json
{
  "server": {
    "logLevel": "debug"
  }
}
```

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