DOCSEARCHbyAlgolia
Submit Docs

Routr Documentation

repository·main·Indexed 23 days ago

https://github.com/fonoster/routr

A lightweight, cloud-native SIP proxy, location server, and registrar for telephony carriers and communication service providers. Features programmable routing and scalable SIP infrastructure for Docker and Kubernetes. Includes documentation for the rctl CLI, the @routr/sdk for managing ACLs, Agents, Credentials, and Domains, and internal modules like @routr/echo and @routr/location.

Tokens
82.1K
Snippets
197
Records
371
Agent score
82%

What's inside Routr

  2. Overview of the Routr SIP Server

    main

    Routr is a SIP Server (SIP Proxy) designed to manage SIP requests within a network, handling the placement and termination of calls and other request types. It is built using a microservice architecture to maximize scalability and extensibility, allowing logical components to be deployed independently.

    Key capabilities include:

    • Protocol Support: The system MUST accept SIP messages via UDP, TCP, TLS, WS, and WSS.
    • Extensibility: It includes a mechanism to replace SIP message processing without requiring a full system update.
    • Multi-tenancy: Supports multiple tenants using a Role-based Access Control (RBAC) system.
    • External Integration: Facilitates communication with external systems for Authentication, Authorization, and Accounting (AAA).

  3. What is Routr?

    main
    Routr is a lightweight SIP proxy, location server, and registrar designed to serve as a foundational element for SIP infrastructure. It is built with a modular design that allows developers to extend its capabilities by integrating custom modules known as Processors and Middlewares. Its primary purpose is to enable the incorporation of real-time communication into applications and services.

  4. Routr Core Features Overview

    main

    Routr is a lightweight SIP proxy, location server, and registrar designed for scalable telephony infrastructure. Key features include:

    • SIP Functions: Proxy, Registrar, and Location Service.
    • Programmable Routing: Configurable strategies including Intra-Domain, Domain Ingress, Domain Egress, and Peer Egress.
    • Load Balancing: Strategies against media servers like Asterisk and FreeSWITCH.
    • Multi-Tenancy: Multi-domain support with Domain-level Access Control Lists (ACL).
    • Transports: Support for TCP, UDP, TLS, WS, and WSS.
    • Data Sources: Support for JSON, YAML, and Postgres.
    • Management: Server management via gRPC API, NodeSDK, and a Command-Line Tool (CTL).
    • Security: Endpoint Authentication with JWT (for web phones) and RTPEngine Middleware.

  5. What is a Processor and how is it used?

    main

    Processors are gRPC services used to extend Routr's signaling functionality. They act as the final stop for a SIP message before it is sent out to the network.

    Common use cases include:

    • Adding or modifying SIP headers.
    • Adding endpoints to the Location Service.
    • Building instant messaging applications.
    • Implementing custom logic for SCAIP or SIP IoT systems.
    • Building SIP Recorders (when combined with RTPEngine).
    • Integrating doorbell camera systems.

  6. What is the Requester service?

    main
    The Requester service is an optional component used to reach an EdgePort using gRPC instead of SIP. It acts as a bridge: services communicate with the Requester via gRPC, and the Requester then communicates with the EdgePort using the SIP protocol. Currently, it is primarily used when the network requires a Registry Service.

  7. What is EdgePort and how does it work?

    main

    EdgePort is a component that acts as a SIP entry point. It accepts SIP Messages, parses them into protobuf format, and sends them to a downstream service (either a Message Dispatcher or a Processor) via gRPC. After the downstream service responds, EdgePort forwards the original SIP Message to the next hop.

    When to use a Dispatcher vs. a Processor

    • Use a Dispatcher if you need to route messages to multiple Processors (e.g., one for INVITE and another for MESSAGE) or if you want to use Middleware.
    • Use a Processor directly if you only have one Processor and no Middleware. This simplifies and speeds up your deployment.
    ┌──────────┐  ┌────────┐ ┌──────────────────┐
│SIP Client│  │EdgePort│ │Message Dispatcher│
└────┬─────┘  └───┬────┘ └──────┬───────────┐
     │            │             │        
     │SIP request │             │        
     │───────────>│             │        
     │            │            │gRPC request
     │            │            │────────────>
     │            │            │gRPC response
     │            │<────────────│        
     │SIP response│             │        
     │<───────────│             │        
┌────┴─────┐  ┌───┴────┐ ┌──────┴───────────┐
│SIP Client│  │EdgePort│ │Message Dispatcher│
└──────────┘  └────────┘ ──────────────────┘

  8. What is the Message Dispatcher and when to use it

    main

    The Message Dispatcher (or Dispatcher) is a component that receives messages from the EdgePort and routes them to the appropriate Processor and Middleware.

    When to use it:

    • You have more than one Processor in your deployment.
    • You have at least one Middleware in your deployment.

    When to skip it:

    • If your deployment has exactly one Processor and no Middleware, you can connect the EdgePort directly to the Processor to simplify the architecture.

  9. What is RTPRelay and when to use it

    main

    RTPRelay is an optional middleware service designed to control RTPEngine instances. It serves two primary purposes:

    1. WebRTC Interoperability: It enables communication between WebRTC-based clients (like SIP.js) and legacy SIP clients.
    2. Media Assistance: It helps SIP clients that are unable to send or receive media directly.

    RTPRelay communicates with RTPEngine using the "ng protocol" and exposes a gRPC interface for other Routr components.

  11. What is EdgePort?

    main

    EdgePort is a component at the network's edge responsible for receiving and forwarding SIP Messages. It converts SIP Messages into protobuf messages and adds metadata (like the entry point IP) required for stateless routing.

    EdgePort components cooperate to ensure messages follow the correct path, which can eliminate the need for a specialized load balancer in front of Routr. For transport, it is recommended to use connection-oriented protocols such as TCP, TLS, WS, or WSS.

    # 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

  12. Understand the Routr platform architecture

    main

    Routr is composed of several specialized components that handle message ingress, processing, and data integration. The high-level flow follows this architecture:

    1. EdgePort: Acts as the entry point for messages (e.g., EdgePort 001, EdgePort 002).
    2. Message Dispatcher: Receives messages from EdgePorts and routes them to the appropriate processors.
    3. Processors: Specialized components that handle specific logic:
      • IM Processor: Handles Instant Messaging.
      • Connect Processor: Handles voice/connection logic.
      • Twilio Processor: Handles Twilio-specific integrations.
    4. Data APIs & External Services: The final layer for data persistence and external service interaction.

    Each component is a distinct unit that can be run, configured, and scaled independently.

    ┌────────────┐┌────────────┐                           
│EdgePort 001││EdgePort 002│                           
└┬───────────┘└┬───────────┘                           
┌▽─────────────▽───────────────────────┐               
│Message Dispatcher                    │               
└┬────────────────┬───────────────────┬┘               
┌▽──────────────┐┌▽─────────────────┐┌▽───────────────┐
│IM Processor   ││Connect Processor ││Twilio Processor│
└┬──────────────┘└──────────────────┘└────────────────┘
┌▽────────────────────────────┐                        
│Data APIs & External Services│                        
└─────────────────────────────┘