drachtio-srf

library5.0.22jsnpmunverified

The `drachtio-srf` package, currently at version 5.0.22, is a Node.js framework for building Signaling Resource Function (SRF) applications, primarily for SIP (Session Initiation Protocol) servers. It provides a high-level API for handling SIP signaling, allowing developers to create complex SIP applications such as proxies, Back-to-Back User Agents (B2BUAs), and custom routing logic. The framework abstracts much of the complexity of the SIP protocol, leveraging a network connection to a separate `drachtio-server` process which handles the underlying SIP transaction processing. It requires Node.js version 18.x or higher and ships with TypeScript types, facilitating modern JavaScript and TypeScript development for real-time communication services.

web-framework communication

npm install drachtio-srf

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DRACHTIO-SRF

drachtio-srf

web-frameworkjavascriptv5.0.22

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Srf

✓ import { Srf } from 'drachtio-srf';

✗ const Srf = require('drachtio-srf');

While CommonJS `require` is shown in older examples, `drachtio-srf` ships with TypeScript types and targets Node.js 18+, making ESM `import` the recommended and modern approach. Ensure your project is configured for ESM (e.g., `"type": "module"` in package.json) for native ESM usage.

Srf, Dialog, Request, Response, SipMessage

✓ import type { Srf, Dialog, Request, Response, SipMessage } from 'drachtio-srf';

For type-safe development, explicitly import types for core classes like Dialog, Request, Response, and SipMessage, which represent key SIP entities and interactions.

Srf constructor with tags

✓ import { Srf } from 'drachtio-srf'; const srf = new Srf('my-app-tag');

✗ const srf = new Srf({ tag: 'my-app-tag' });

The Srf constructor optionally accepts a string or array of strings as a `tag` parameter for routing, not an object.

This quickstart demonstrates setting up a basic Back-to-Back User Agent (B2BUA) with `drachtio-srf`. It connects to a `drachtio-server`, listens for incoming SIP INVITEs, and attempts to establish a call to a specified URI, relaying media and signaling between the two call legs. It includes error handling and proper cleanup on call termination.

import { Srf } from 'drachtio-srf'; const srf = new Srf(); srf.connect({ host: process.env.DRACHTIO_HOST ?? '127.0.0.1', port: parseInt(process.env.DRACHTIO_PORT ?? '9022', 10), secret: process.env.DRACHTIO_SECRET ?? 'cymru' }); srf.on('connect', () => console.log('Connected to drachtio server.')); srf.on('error', (err) => console.error('drachtio-srf error:', err)); srf.invite(async (req, res) => { console.log(`Incoming INVITE from ${req.callingNumber} to ${req.calledNumber}`); try { // Create a Back-to-Back User Agent (B2BUA) // Replace 'sip:1234@10.10.100.1' with an actual SIP URI for the B party const { uas, uac } = await srf.createB2BUA('sip:1234@10.10.100.1', req, res, { localSdpB: req.body, // Offer SDP from incoming INVITE to B-party // Additional options like provisionalTimeout, proxyRequestHeaders can be added }); console.log('Call connected successfully as B2BUA'); // When one side terminates, hang up the other uas.on('destroy', () => { console.log('UAS leg destroyed, destroying UAC leg.'); uac.destroy(); }); uac.on('destroy', () => { console.log('UAC leg destroyed, destroying UAS leg.'); uas.destroy(); }); } catch (err: any) { console.error(`B2BUA call failed to connect: ${err.status || err.message}`); if (!res.headersSent) { res.send(err.status || 500, err.reason || 'B2BUA setup failed'); } } });

Debug

Known issues

breakingWhen upgrading `drachtio-srf` to version 5.0.0 or higher, you MUST also upgrade your `drachtio-server` to version 0.9.0 or higher. Older server versions are incompatible due to significant changes in the wire protocol.

fix

Ensure your `drachtio-server` process is running version 0.9.0 or later. Check the drachtio-server GitHub releases for the latest compatible version.

affects: >=5.0.0

gotchaWhen initiating outbound SIP requests (e.g., `srf.request` or `srf.createUAC`), use the string `'placeholder'` for the host part in `From` and `To` header URIs to allow the `drachtio-server` to automatically insert its local listening IP address. Do not manually set the IP or the `tag` attribute in these headers.

fix

Modify headers like `From` and `To` to use placeholders:
```typescript
  headers: {
    'From': '<sip:user@placeholder>',
    'To': '<sip:target@placeholder>'
  }
```

affects: >=1.0.0

gotchaFor successful (200 OK) responses to an incoming INVITE request that creates a dialog (e.g., via `srf.request` for an INVITE client), the application is responsible for sending the final ACK. The `response` event handler will provide an `ack` function as a second argument which must be called.

fix

Always check the status code in the `response` event handler for INVITEs and call the `ack` function for 200 OK responses:
```typescript
srf.request('sip:target@domain.com', { method: 'INVITE', /* ... */ }, (err, req) => {
  req.on('response', (res, ack) => {
    if (res.status === 200) {
      ack(); // Send the ACK for 200 OK
    }
  });
});
```

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED

The `drachtio-srf` application failed to connect to the `drachtio-server` process, usually because the server is not running, is running on a different host/port, or a firewall is blocking the connection.

fix

Ensure the `drachtio-server` process is running and configured to listen on the host and port specified in `srf.connect()`. Verify network connectivity and firewall rules.

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

This error occurs in Node.js when attempting to use CommonJS `require()` to load an ECMAScript Module (ESM) within a CommonJS context.

fix

If your project uses ESM, ensure you use `import` statements. If your project is CommonJS and you need to load an ESM-only dependency, you may need to convert your project to ESM by adding `"type": "module"` to your `package.json` and adjusting imports/exports, or use dynamic `import()` for the specific module.

Call failed with final status XXX

A SIP transaction (e.g., INVITE, SUBSCRIBE) initiated by `drachtio-srf` resulted in a non-success (non-2xx) final SIP response from the remote endpoint.

fix

Examine the `status` code and `reason` phrase returned in the error object. This indicates a SIP protocol error (e.g., 404 Not Found, 486 Busy Here). Debug the SIP URI, headers, and routing logic. Use SIP trace tools to analyze the full SIP message flow.

Upgrade

Version history

5.0.22latest on npm

Audit

Dependencies

drachtio-serverrequireddrachtio-srf requires a running drachtio-server process to which it connects and delegates SIP transaction processing.

Agent activity

27 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/drachtio/drachtio-srf ↗

packagehttps://www.npmjs.com/package/drachtio-srf ↗

homepagehttps://drachtio.org ↗