Building a Processor

Processors are how we extend the signaling functionality of Routr. Processors are where we can add new SIP headers, modify existing ones, add endpoints to the Location Service, etc. Processors are implemented as gRPC services and use the Alterations API to modify SIP messages. A Processor is the last stop for a SIP message before it is sent out to the network.

Here is a non-exhaustive list of things you can do with a Processor:

• Build an instant messaging application
• Create a custom logic for a SCAIP system
• Build a SIP Recorder when combined with RTPEngine
• Doorbell Camera System integration
• Custom logic for a SIP IoT system

Processor Contract

A Processor is a gRPC service that implements the Processor interface. The interface is defined in the processor.proto file.

Here is the definition of the Processor interface:

syntax = "proto3";

package fonoster.routr.processor.v2beta1;

import "common.proto";
import "sipmessage.proto";

// Processor service
service Processor {
  // Process Message Request
  rpc ProcessMessage (MessageRequest) returns (MessageResponse) {}
}

enum Method {
  UNKNOWN = 0;
  // Communicates user location (hostname, IP)
  REGISTER = 1;
  // Establishes a session
  INVITE = 2;
  // Transports Instant Messages
  MESSAGE = 3;
  // Publishes an event to the Server
  PUBLISH = 4;
  // Notifies the subscriber of a new event
  NOTIFY = 5;
  // Subscribes for Notification from the notifier
  SUBSCRIBE = 6;
  // Confirms an INVITE request
  ACK = 7;
  // Terminates a session
  BYE = 8;
  // Cancels establishing of a session
  CANCEL = 9;
  // Communicates information about the capabilities of the calling and receiving SIP phones
  OPTIONS = 10;
  // Provisional Acknowledgement
  PRACK = 11;
  // Sends mid session information
  INFO = 12;
  // Asks the recipient to issue call transfer
  REFER = 13;
  // Modifies the state of a session
  UPDATE = 14;
}

message NetInterface {
  string host = 1;
  int32 port = 2;
  fonoster.routr.common.v2beta1.Transport transport = 3;
}

message MessageRequest {
  // Same as the Call-Id header 
  string ref = 1;
  string edge_port_ref = 2;
  Method method = 3;
  NetInterface sender = 4;
  repeated NetInterface listening_points = 5;
  repeated string external_addrs = 6;
  repeated string localnets = 7;
  fonoster.routr.sipmessage.v2beta1.SIPMessage message = 8;
  map<string, string> metadata = 9;
}

message MessageResponse {
  NetInterface sender = 1;
  fonoster.routr.sipmessage.v2beta1.SIPMessage message = 2;
  map<string, string> metadata = 3;
}

As you can see in the protobuf, the message contains the SIP message and metadata about the message. It includes things like the sender, the method, the listening points, etc. This metadata is necessary because it is how Routr processes messages statelessly.

You can write processors in any language that supports gRPC. However, at the moment, we provide better support for NodeJS.

One feature of using NodeJS is receiving the JSON representation of the gRPC message. That makes it easier to work with the message in JavaScript.

As an example, here is the JSON representation of a SIP REGISTER message:

{
  "ref": "AynhXaFtbdXwHrUEzt_rUQ..",
  "edgePortRef": "edgeport-01",
  "method": "REGISTER",
  "externalAddrs": ["200.22.21.42"],
  "localnets": ["127.0.0.1/8", "10.100.42.127/24", "10.100.43.128/31"],
  "listeningPoints": [
    {
      "host": "0.0.0.0",
      "port": 5060,
      "transport": "TCP"
    },
    {
      "host": "0.0.0.0",
      "port": 5060,
      "transport": "UDP"
    }
  ],
  "sender": {
    "host": "127.0.0.1",
    "port": 36214,
    "transport": "TCP"
  },
  "message": {
    "via": [
      {
        "host": "proxy",
        "port": 5060,
        "branch": "z9hG4bK-524287-1---7315a24d84546819",
        "transport": "TCP"
      },
      {
        "host": "127.0.0.1",
        "port": 36214,
        "branch": "z9hG4bK-524287-1---7315a24d84546819",
        "transport": "TCP"
      }
    ],
    "extensions": [
      {
        "name": "CSeq",
        "value": "14 REGISTER"
      },
      {
        "name": "Allow",
        "value": "INVITE"
      },
      {
        "name": "User-Agent",
        "value": "Z 5.4.12 v2.10.13.2"
      },
      {
        "name": "Allow-Events",
        "value": "presence"
      }
    ],
    "from": {
      "address": {
        "uri": {
          "user": "1001",
          "userPassword": "",
          "host": "sip.local",
          "transportParam": "UDP",
          "mAddrParam": "",
          "methodParam": "",
          "userParam": "",
          "ttlParam": -1,
          "port": 5060,
          "lrParam": false,
          "secure": false
        },
        "displayName": "John Doe",
        "wildcard": false
      },
      "tag": "9041462a"
    },
    "to": {
      "address": {
        "uri": {
          "user": "1001",
          "userPassword": "",
          "host": "sip.local",
          "transportParam": "TCP",
          "mAddrParam": "",
          "methodParam": "",
          "userParam": "",
          "ttlParam": -1,
          "port": 5060,
          "lrParam": false,
          "secure": false
        },
        "displayName": "",
        "wildcard": false
      },
      "tag": ""
    },
    "contact": {
      "address": {
        "uri": {
          "user": "1001",
          "userPassword": "",
          "host": "127.0.0.1",
          "transportParam": "TCP",
          "mAddrParam": "",
          "methodParam": "",
          "userParam": "",
          "ttlParam": -1,
          "port": 36214,
          "lrParam": false,
          "secure": false
        },
        "displayName": "",
        "wildcard": false
      },
      "expires": -1,
      "qValue": -1
    },
    "callId": {
      "callId": "AynhXaFtbdXwHrUEzt_rUQ.."
    },
    "contentLength": {
      "contentLength": 0
    },
    "maxForwards": {
      "maxForwards": 70
    },
    "expires": {
      "expires": 60
    },
    "recordRoute": [
      {
        "parameters": {
          "a": "1",
          "b": "2"
        },
        "address": {
          "uri": {
            "user": "",
            "userPassword": "",
            "host": "sip.local",
            "transportParam": "TCP",
            "mAddrParam": "",
            "methodParam": "",
            "userParam": "",
            "ttlParam": -1,
            "port": 5060,
            "lrParam": false,
            "secure": false
          },
          "displayName": "",
          "wildcard": false
        }
      }
    ],
    "route": [
      {
        "parameters": null,
        "address": {
          "uri": {
            "user": "",
            "userPassword": "",
            "host": "10.100.42.127",
            "transportParam": "TCP",
            "mAddrParam": "",
            "methodParam": "",
            "userParam": "",
            "ttlParam": -1,
            "port": 5060,
            "lrParam": false,
            "secure": false
          },
          "displayName": "",
          "wildcard": false
        }
      },
      {
        "parameters": null,
        "address": {
          "uri": {
            "user": "",
            "userPassword": "",
            "host": "10.100.42.128",
            "transportParam": "TCP",
            "mAddrParam": "",
            "methodParam": "",
            "userParam": "",
            "ttlParam": -1,
            "port": 5060,
            "lrParam": false,
            "secure": false
          },
          "displayName": "",
          "wildcard": false
        }
      }
    ],
    "authorization": {
      "realm": "sip.local",
      "scheme": "Digest",
      "cNonce": "acbcc60094edde23f49b01e18bafd34e",
      "nonce": "b8fe2321cf489ac475c80c6e5cfa1c22",
      "algorithm": "MD5",
      "qop": "",
      "opaque": "",
      "response": "227fe247ff0b9fa4fcf2706b587bf995",
      "username": "1001",
      "uri": "sip:sip.local;transport=TCP",
      "nonceCount": 13
    },
    "requestUri": {
      "user": "",
      "userPassword": "",
      "host": "sip.local",
      "transportParam": "TCP",
      "mAddrParam": "",
      "methodParam": "",
      "userParam": "",
      "ttlParam": -1,
      "port": 5060,
      "lrParam": false,
      "secure": false
    },
    "messageType": "REQUEST"
  }
}

Building a Processor from a Template

To make it easier to build processors, we provide a template you can use to get started. The template is available in the routr-processor-template.

To use the template, you must have NodeJS installed in your system. Once you have NodeJS installed, you can use the following command to create a new processor:

npx degit fonoster/nodejs-processor my-processor

The previous command will create a new folder called my-processor with the following structure:

.
├── CONTRIBUTING.md
├── Dockerfile
├── LICENSE
├── README.md
├── commitlint.config.js
├── compose.yaml
├── package-lock.json
├── package.json
├── src
│   ├── envs.ts
│   ├── handlers.ts
│   └── index.ts
├── test
│   └── unit.test.ts
└── tsconfig.json

The most important file is the handlers.ts file. This file is where you will write your processor logic. Feel free to review the file, as it contains an example of how to write an instant messaging processor.

From there, you can install the dependencies and start the processor:

cd my-processor
npm install
npm start

You may now start sending SIP messages to your processor from EdgePort or Dispatcher.