Skip to main content
Version: 2.11.5

Concepts

Routr's approach to SIP is different from other SIP servers. For example, Routr aims to be cloud-native first. It is designed to run in a containerized environment, like Docker or Kubernetes, and features a microservices architecture.

The following concepts are essential to understand when working with Routr, but remember that we will cover them in more detail in later sections.

EdgePort

The EdgePort component sits at the network's edge and is part of the CORE specification. It is responsible for receiving and forwarding SIP Messages.

The EdgePort service takes SIP Messages and converts them into protobuf messages. In addition to the SIP Message, we add all the metadata required for routing, including the IP of the entry point of the request, which allows us to calculate the correct path for the message statelessly.

Another essential aspect of EdgePort is that it cooperates to ensure messages follow the correct path. That means you don't need a specialized load balance in front of Routr.

Below is a diagram that demonstrates the collaboration between EdgePort and the Message Dispatcher

EdgePort diagram

One important consideration when deploying a network is the protocol for Transport. We recommend always using a connection-oriented transport such as TCP,TLS, WS, or WSS.

Downstream Processors and Middleware all use the same gRPC interface. Because they all share the same structure, we can create processing services in any programming language while maintaining the same core functionality.

A minimal EdgePort configuration looks as follows:

# Example EdgePort configuration
kind: EdgePort
apiVersion: v2beta1
ref: edgeport-01
metadata:
region: default
spec:
processor:
addr: dispatcher:51901
methods:
- REGISTER
- INVITE
- ACK
- BYE
- CANCEL
transport:
- protocol: udp
port: 5060

Message Dispatcher

The Message Dispatcher, or Dispatcher for short, is a service between the EdgePort and the Processor. It is responsible for routing SIP Messages to the correct Processor.

The Dispatcher is a stateless service that uses a simple algorithm to determine the correct processing service. The component takes the SIP Messages and applies a matching function to choose the proper Processor.

The matching function is a Javascript function that takes the SIP Message and returns a boolean value. The Dispatcher will forward the message to the first Processor that matches the criteria. Therefore, the order of the Processors and the matching function is essential to ensure the correct routing.

The matchFunc is a javascript function that leverages the JSON representation of the SIPMessage protobuf.

This example features a Dispatcher that matches MESSAGE requests to the IM Processor and all others to the Connect Processor.

kind: MessageDispatcher
apiVersion: v2beta1
ref: message-dispatcher
spec:
bindAddr: 0.0.0.0:51901
processors:
- ref: im-processor
addr: im:51904
matchFunc: req => req.method === "MESSAGE"
methods:
- MESSAGE
- ref: connect-processor
addr: connect:51904
matchFunc: req => true
methods:
- REGISTER
- INVITE
- ACK
- BYE
- CANCEL

The following examples show typical matching functions:

Match all SIP Messages.

req => true

Match SIP Messages with a specific method.

req => req.method === "MESSAGE"

Match SIP Messages with a specific method and a specific header.

req => req.method === "MESSAGE" && req.message.from.address.uri.user === "alice"

Match SIP Messages with a specific User-Agent header.

req => req.message.extensions.find(e => e.name === "User-Agent" && e.value.includes("Zoiper"))

Location service

In Routr, the Location Service serves two primary purposes. The first purpose is to locate the route to an endpoint in the location table. The second is to load balance requests.

Routr's load balancing is done at the Location Service level and occurs in the context of Peers. To better explain this, let's take a closer look at some applications where this is useful.

For example, you can create a Peer configuration and share the same credentials if you have multiple Asterisk servers. By doing this, Routr will send a request to the instance of Asterisk according to the load-balancing algorithm you have selected.

Two balancing algorithms are available. The first is round-robin, and the second is least-sessions.

Now, let's consider a situation where you want to deploy the server and send all PSTN traffic to a conference room in Asterisk. For such a scenario, you must configure a Peer to represent your feature server and a Number to route calls from the PSTN.

To do this, create a Peer configuration for your Asterisk server similar to the following:

apiVersion: v2beta1
kind: Peer
ref: peer-01
metadata:
name: Asterisk (Media Server)
spec:
aor: sip:conference@sip.local
username: asterisk
credentialsRef: credentials-01
loadBalancing:
withSessionAffinity: true
algorithm: least-sessions

Notice that the load balancing section sets the withSessionAffinity to true. We need session affinity to ensure that all calls related to the conference arrive on the same Asterisk server.

Every Asterisk server that registers using the asterisk username will join the same group under the sip:conference@sip.local Address of Record (AOR).

Middlewares

Middleware resembles Processors because they both use the same protobuf contract but serve different purposes. While Processors hold feature logic, Middlewares addresses cross-cutting concerns like authentication, authorization, rate limiting, etc.

Some use cases for Middlewares include:

  • Authentication and Authorization
  • Rate limiting
  • Circuit breaking
  • Logging, Metrics, and Tracing
  • Request and response validation
  • Data transformation and normalization
  • CDRs generation

Processors and Middlewares differ in that you execute Middlewares in a chain, making their execution order crucial. Additionally, you can include multiple Middlewares in your deployment but only one Processor.

Processors

Processors are a way to extend the functionality of Routr, and implementors can add custom logic to the system. Processors are implemented as a gRPC service and use the Alterations API to modify SIP messages.

The simplest possible Processor is the "Echo Processor," which returns the SIP Message to the EdgePort. The following example shows how to create an Echo Processor using Node.js.

const Processor = require("@routr/processor").default;
const { MessageRequest, Response } = require("@routr/processor");

new Processor({ bindAddr: "0.0.0.0:51904", name: "echo" }).listen(
(req: MessageRequest, res: Response) => {
logger.verbose("got new request: ")
logger.verbose(JSON.stringify(req, null, " "))
res.sendOk()
}
)

Alterations

Alterations let you modify SIP messages. We implement Alterations as Javascript functions that a Processor or Middleware executes.

The methods for Alterations adhere to a functional programming style. In this approach, one function's output becomes the following function's input. Here's an example of how to use the Alterations API to change a SIP message:

const { Alterations } = require('@routr/processor')
const { pipe } = require("fp-ts/function");

function messageProcessing(req: MessageRequest, route: Route): MessageRequest {
const requestOut = pipe(
reqIn,
//example of an Alteration method with two arities
Alterations.addSelfVia(route),
Alterations.addSelfRecordRoute(route),
Alterations.addRouteToPeerEdgePort(route),
Alterations.addRouteToNextHop(route),
//example of an Alteration method with one arity
Alterations.addXEdgePortRef,
Alterations.decreaseMaxForwards
)

return requestOut
}

If you need to create a new Alteration, we suggest you follow a similar approach to the one used by the Alterations API. That is, create a function that takes a SIP message as input and returns a SIP message as output.

Registry service

The Registry component sends outbound registration to trunking services. You need this component when you set the sendRegister option of your Trunks to true. To send requests to the EdgePort, the Registry service depends on the Requester service.

Available configurations include the following:

PropertyDescriptionRequired
requesterAddrAddress of service to send requestsYes
apiAddrAddress of API serviceYes
registerIntervalInterval to send registration requestsYes
cacheCache configurationYes
methodsAcceptable SIP Methods (reserved for future use)No
edgePortsList of EdgePorts for outbound registrationsYes
edgePorts.addressAddress of EdgePortYes
edgePorts.regionRegion of EdgePort (reserved for future use)No

Here is an example of a Trunk configuration that requires registration:

kind: Registry
apiVersion: v2beta1
spec:
requesterAddr: requester:51909
apiAddr: apiserver:51907
registerInterval: 20
cache:
provider: memory
methods:
- INVITE
- MESSAGE
edgePorts:
- address: sip01.edgeport.net:5060
region: us-east1
- address: sip02.edgeport.net:6060

Requester

The Requester is a service that takes a gRPC request, converts it into a SIP message, and forwards it to its destination. It is a dependency of the Registry service.