node-sbc/README.md

# NexusVoice SBC - Drachtio Migration

This directory contains the Drachtio-based implementation of the NexusVoice SIP Border Controller, migrated from the original Kamailio configuration.

## Overview

The Drachtio implementation provides equivalent functionality to the Kamailio SBC configuration:

- **SIP Proxy and Registrar**: User registration and location management
- **Security Features**: User-Agent filtering, SIP validation, request sanitization
- **Call Routing**: Local user lookup, special number routing, external trunk integration
- **Media Handling**: RTP proxy integration for media relay
- **Logging**: Comprehensive SIP traffic logging

## Directory Structure

```
drachtio-migration/
├── config/
│   └── default.json              # Main configuration file
├── middleware/
│   ├── validation.js            # Request validation middleware
│   ├── userAgentFilter.js       # User-Agent filtering middleware
│   └── requestProcessor.js      # Main request processing pipeline
├── routes/
│   ├── registration.js          # SIP REGISTER handling
│   ├── invite.js               # SIP INVITE handling
│   └── indialog.js             # In-dialog request handling
├── utils/
│   └── logger.js               # Logging utility
├── server.js                   # Main server application
├── package.json               # Node.js dependencies
└── README.md                  # This file
```

## Installation and Setup

### Prerequisites

- Node.js 14.0 or higher
- Drachtio server installed and running
- RTP proxy server (optional, for media handling)

### Installation

1. Navigate to the migration directory:
```bash
cd drachtio-migration
```

2. Install dependencies:
```bash
npm install
```

3. Configure your settings in `config/default.json`:
   - SIP listening parameters
   - RTP proxy configuration
   - Asterisk server addresses
   - Security settings

### Configuration

Key configuration sections:

```json
{
  "sip": {
    "host": "0.0.0.0",
    "port": 5060,
    "transport": "udp"
  },
  "rtpProxy": {
    "enabled": true,
    "host": "rtpproxy",
    "port": 7722
  },
  "security": {
    "enableUAFilter": true,
    "blockedUserAgents": [...],
    "allowedUserAgents": [...]
  }
}
```

### Running the Server

**Development mode:**
```bash
npm run dev
```

**Production mode:**
```bash
npm start
```

## Migration Mapping

### Kamailio to Drachtio Equivalents

| Kamailio Component | Drachtio Implementation |
|-------------------|------------------------|
| `request_route` | `RequestProcessor.middleware()` |
| `route[REQINIT]` | `RequestValidator.middleware()` |
| `route[UA_FILTER]` | `UserAgentFilter.middleware()` |
| `route[REGISTRAR]` | `RegistrationHandler.handleRegister()` |
| `route[INCOMING_INVITE]` | `InviteHandler.handleInvite()` |
| `route[WITHINDLG]` | `InDialogHandler.handleInDialog()` |
| `usrloc` module | `RegistrationHandler.registry` (in-memory Map) |
| `rtpproxy` module | RTP proxy integration (placeholder) |
| `dispatcher` module | Round-robin Asterisk server selection |

### Key Differences

1. **Configuration**: JSON-based instead of Kamailio script syntax
2. **Language**: JavaScript/Node.js instead of Kamailio configuration language
3. **Architecture**: Middleware pattern instead of procedural routes
4. **Persistence**: In-memory registry instead of database-backed usrloc
5. **Logging**: Winston-based logging instead of xlog

## Features Implemented

### ✅ Request Processing Pipeline
- [x] Max-Forwards validation
- [x] SIP message sanity checks
- [x] Method-specific routing
- [x] Enhanced logging
- [x] Retransmission handling

### ✅ Security Features
- [x] User-Agent filtering with allow/block lists
- [x] Empty User-Agent blocking
- [x] Attack tool pattern detection
- [x] Request validation and sanitization

### ✅ Registration System
- [x] SIP REGISTER handling
- [x] In-memory user registry
- [x] Registration expiry management
- [x] Automatic cleanup of expired registrations

### ✅ Call Routing
- [x] Local user lookup
- [x] Special number routing (3179, 8000, *600, 888)
- [x] Asterisk server integration
- [x] Round-robin load balancing

### ✅ In-Dialog Handling
- [x] BYE request processing
- [x] ACK handling
- [x] Route header processing
- [x] Media teardown handling

## Testing

The migration is ready for functional testing. Key test scenarios:

1. **Registration Tests**
   - User registration and authentication
   - Registration expiry and cleanup
   - Unregistration handling

2. **Call Routing Tests**
   - Local user calls
   - Special number calls
   - External trunk routing

3. **Security Tests**
   - User-Agent filtering
   - Request validation
   - Attack prevention

4. **Media Tests**
   - RTP proxy integration
   - SDP processing

## Next Steps

### 🔄 In Progress
- RTP proxy integration for media handling
- SDP processing and modification
- Media relay configuration

### ⏳ Planned Features
- Redis integration for multi-instance support
- Enhanced logging and monitoring
- API endpoints for management
- Performance optimization
- Load testing and validation

## Troubleshooting

### Common Issues

1. **Port already in use**: Ensure no other SIP server is running on port 5060
2. **Drachtio connection failed**: Verify drachtio server is running and accessible
3. **Registration fails**: Check From header format and contact headers
4. **Call routing fails**: Verify user registration and Asterisk server connectivity

### Logs

Check the logs directory for detailed information:
```bash
tail -f logs/sbc.log
```

## Contributing

This migration maintains the same functionality as the original Kamailio configuration while leveraging Drachtio's modern JavaScript-based architecture. All existing features should work equivalently.