144 lines
3.9 KiB
Markdown
144 lines
3.9 KiB
Markdown
|
# Bridge Worker
|
||
|
|
|
||
|
|
Background job processor for handling asynchronous tasks in the CDR Link communication bridge system.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
Bridge Worker uses Graphile Worker to process queued jobs for message handling, media conversion, webhook notifications, and scheduled tasks. It manages the flow of messages between various communication channels (Signal, WhatsApp, Facebook, Voice) and the Zammad ticketing system.
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **Message Processing**: Handle incoming/outgoing messages for all supported channels
|
||
|
|
- **Media Conversion**: Convert audio/video files between formats
|
||
|
|
- **Webhook Notifications**: Notify external systems of events
|
||
|
|
- **Scheduled Tasks**: Cron-based job scheduling
|
||
|
|
- **Job Queue Management**: Reliable job processing with retries
|
||
|
|
- **Multi-Channel Support**: Signal, WhatsApp, Facebook, Voice (Twilio)
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
### Prerequisites
|
||
|
|
|
||
|
|
- Node.js >= 20
|
||
|
|
- npm >= 10
|
||
|
|
- PostgreSQL database
|
||
|
|
- Redis (for caching)
|
||
|
|
- FFmpeg (for media conversion)
|
||
|
|
|
||
|
|
### Setup
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install dependencies
|
||
|
|
npm install
|
||
|
|
|
||
|
|
# Build TypeScript
|
||
|
|
npm run build
|
||
|
|
|
||
|
|
# Run development server with auto-reload
|
||
|
|
npm run dev
|
||
|
|
|
||
|
|
# Start production worker
|
||
|
|
npm run start
|
||
|
|
```
|
||
|
|
|
||
|
|
### Environment Variables
|
||
|
|
|
||
|
|
Required environment variables:
|
||
|
|
|
||
|
|
- `DATABASE_URL` - PostgreSQL connection string
|
||
|
|
- `GRAPHILE_WORKER_CONCURRENCY` - Number of concurrent jobs (default: 10)
|
||
|
|
- `GRAPHILE_WORKER_POLL_INTERVAL` - Job poll interval in ms (default: 1000)
|
||
|
|
- `ZAMMAD_URL` - Zammad instance URL
|
||
|
|
- `ZAMMAD_API_TOKEN` - Zammad API token
|
||
|
|
- `TWILIO_ACCOUNT_SID` - Twilio account SID
|
||
|
|
- `TWILIO_AUTH_TOKEN` - Twilio auth token
|
||
|
|
- `SIGNAL_CLI_URL` - Signal CLI REST API URL
|
||
|
|
- `WHATSAPP_SERVICE_URL` - WhatsApp bridge service URL
|
||
|
|
- `FACEBOOK_APP_SECRET` - Facebook app secret
|
||
|
|
- `FACEBOOK_PAGE_ACCESS_TOKEN` - Facebook page token
|
||
|
|
|
||
|
|
### Available Scripts
|
||
|
|
|
||
|
|
- `npm run build` - Compile TypeScript
|
||
|
|
- `npm run dev` - Development mode with watch
|
||
|
|
- `npm run start` - Start production worker
|
||
|
|
|
||
|
|
## Task Types
|
||
|
|
|
||
|
|
### Signal Tasks
|
||
|
|
- `receive-signal-message` - Process incoming Signal messages
|
||
|
|
- `send-signal-message` - Send outgoing Signal messages
|
||
|
|
- `fetch-signal-messages` - Fetch messages from Signal CLI
|
||
|
|
|
||
|
|
### WhatsApp Tasks
|
||
|
|
- `receive-whatsapp-message` - Process incoming WhatsApp messages
|
||
|
|
- `send-whatsapp-message` - Send outgoing WhatsApp messages
|
||
|
|
|
||
|
|
### Facebook Tasks
|
||
|
|
- `receive-facebook-message` - Process incoming Facebook messages
|
||
|
|
- `send-facebook-message` - Send outgoing Facebook messages
|
||
|
|
|
||
|
|
### Voice Tasks
|
||
|
|
- `receive-voice-message` - Process incoming voice calls/messages
|
||
|
|
- `send-voice-message` - Send voice messages via Twilio
|
||
|
|
- `twilio-recording` - Handle Twilio call recordings
|
||
|
|
- `voice-line-audio-update` - Update voice line audio
|
||
|
|
- `voice-line-delete` - Delete voice line
|
||
|
|
- `voice-line-provider-update` - Update voice provider settings
|
||
|
|
|
||
|
|
### Common Tasks
|
||
|
|
- `notify-webhooks` - Send webhook notifications
|
||
|
|
- `import-label-studio` - Import Label Studio annotations
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Job Processing
|
||
|
|
|
||
|
|
Jobs are queued in PostgreSQL using Graphile Worker:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
await addJob('send-signal-message', {
|
||
|
|
to: '+1234567890',
|
||
|
|
message: 'Hello world'
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
### Cron Schedule
|
||
|
|
|
||
|
|
Scheduled tasks are configured in `crontab`:
|
||
|
|
- Periodic message fetching
|
||
|
|
- Cleanup tasks
|
||
|
|
- Health checks
|
||
|
|
|
||
|
|
### Error Handling
|
||
|
|
|
||
|
|
- Automatic retries with exponential backoff
|
||
|
|
- Dead letter queue for failed jobs
|
||
|
|
- Comprehensive logging with winston
|
||
|
|
|
||
|
|
## Media Handling
|
||
|
|
|
||
|
|
Supports conversion between formats:
|
||
|
|
- Audio: MP3, OGG, WAV, M4A
|
||
|
|
- Uses fluent-ffmpeg for processing
|
||
|
|
- Automatic format detection
|
||
|
|
|
||
|
|
## Integration Points
|
||
|
|
|
||
|
|
- **Zammad**: Creates/updates tickets via API
|
||
|
|
- **Signal CLI**: REST API for Signal messaging
|
||
|
|
- **WhatsApp Bridge**: HTTP API for WhatsApp
|
||
|
|
- **Twilio**: Voice and SMS capabilities
|
||
|
|
- **Facebook**: Graph API for Messenger
|
||
|
|
|
||
|
|
## Docker Support
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Build image
|
||
|
|
docker build -t link-stack/bridge-worker .
|
||
|
|
|
||
|
|
# Run with docker-compose
|
||
|
|
docker-compose -f docker/compose/bridge.yml up
|
||
|
|
```
|
||
|
|
|
||
|
|
The worker includes cron support via built-in crontab.
|