Skip to content

Release v3.0.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 22:40
· 6 commits to main since this release

Upgrading from Routr 2? Start with Upgrade from Routr 2 to Routr 3.

Routr 3 is Routr rewritten in Go. It runs on the Routr 2 database, plus three numbering migrations, and keeps the gRPC APIs, so rctl, the SDK and existing processors keep working. See Upgrade from Routr 2 to Routr 3.

  • Breaking: every setting moves from environment variables into YAML: routr.yaml for RoutrOne, one file per standalone component. Secrets are ${VAR} placeholders or secret:// references. The standalone EdgePort's variables are keys of edgeport.yaml too (events, health, sipTrace, stripSessionProgressSdp, ignoreLoopbackFromLocalnets), and no OTEL_* variable changes how telemetry exports. See routr.yaml and Environment variables
  • Breaking: the Data API and the Requester refuse to start beyond loopback without an API key, a client CA or insecure: true. rctl takes --api-key (or ROUTR_API_KEY), the SDK apiKey
  • Breaking: a component's client auth (apiAuth, locationAuth, requesterAuth, processorAuth, backendAuth, verifierAuth) with apiKey, no tls and an address that isn't loopback refuses to start: add tls, or insecure: true to send the key in clear. The Helm chart writes insecure: true on the Registry's requesterAuth and, with apiserver.tlsOn: false, on every apiAuth
  • Breaking: rctl trace send and rctl trace compat --against open TLS by default and take --insecure and --cacert: a Dispatcher without tls needs --insecure. With an API key (or a username and password), ALLOW_INSECURE=true toward a host that isn't loopback is refused by rctl and the SDK unless --insecure or insecure: true is given, and --cacert or cacert wins over the variable
  • Breaking: rctl and the SDK refuse --insecure / insecure: true together with --cacert / cacert instead of connecting in plaintext with the CA certificate ignored: rctl exits with an error, the SDK's constructor throws. Keep one: --cacert for TLS verified with that CA, --insecure for plaintext
  • Breaking: the Data API is on 51907 only; the external port 51908 is gone from the images (the Helm chart's Service keeps it). rctl defaults to localhost:51907
  • Breaking: RoutrOne has no internal PostgreSQL and no one.yaml. The Node services, the Java EdgePort, simpledata, heplify, Log4j2 and the Fluentd log transport are removed; echo and simpleauth remain as example processors
  • Breaking: a standalone Connect with a Registry must set trustedRegistryAddresses; X-Gateway-Auth is honored from nobody else
  • Breaking: every standalone component file must set apiVersion to v2beta1, v2 or v3 (v3 is new); a Connect or Data file without it now fails to load
  • Breaking: a Domain's or a Peer's ACL is enforced: its Agents, or the Peer, get 403 from an address it doesn't allow. A Peer whose accessControlListRef names no ACL fails to load from resource files
  • Breaking: an Agent's INVITE to an Agent of another Domain gets 403 Forbidden instead of ringing it. Domains are now isolated; to call across them, go through a Peer or a Number.
  • Breaking: a disabled Agent (enabled: false) can't register or call (403), and calls to it from other Agents get 480. In resource files an Agent without enabled is enabled
  • Breaking: EdgePort applies methods and unknownMethodAction to out-of-dialog requests. With the default Discard, a method outside methods gets no answer (it got 501); OPTIONS is now in the default and shipped lists, so keepalive pings are answered. Add any other out-of-dialog method your endpoints use
  • Breaking: the Data API's enforceE164Numbers defaults to true: creating a Number whose telUrl isn't tel:+ and 2 to 15 digits (the first not 0) fails with INVALID_ARGUMENT, and the files backend refuses to load one. Set spec.data.enforceE164Numbers: false (Helm: apiserver.enforceE164Numbers: false) to keep Routr 2's check. See spec.data
  • Breaking: the Trunk's normalizeToE164 is removed: the proto field is reserved, and a resource file that sets it fails to load. Use calledNumberFormat and callerNumberFormat: e164 instead. On calls from a Trunk, From, To and the Request-URI reach your application as the carrier sent them; the called Number is in X-DID-Number. The Go SDK's NormalizeToE164 is removed too (pkg/processor)
  • Breaking: a call on a Trunk to a Number with no Trunk, or on another Trunk, gets 404 No Number found instead of 403. The Trunk alone decides the callee, among its own Numbers
  • Breaking: a Number's countryIsoCode must be a country with a numbering plan; XX and three-letter codes are rejected, and rctl no longer offers Unknown
  • Breaking: a Trunk number prefix with no format, or with e164, is rejected; a prefix needs e164-without-plus, national or international
  • CLOAK_ENCRYPTION_KEY becomes spec.data.encryptionKey; with no key and encrypted passwords in the database, the Data API refuses to start. DATABASE_URL works as it is, ?schema=public included
  • In-dialog requests that match no dialog this EdgePort proxied get 481, BYE after an EdgePort restart included, unless the dialog table is in Redis: with the new cache key (provider: redis; spec.edgeport.cache in routr.yaml) EdgePorts keep their established dialogs in Redis, so a call set up before a restart, or through another replica behind the same address, can still send its BYE. The Helm chart turns it on when the release has a Redis (redis.enabled, or edgeport.cache.parameters for your own)
  • A REGISTER whose To isn't the authenticated Agent gets 403
  • Deleting Credentials or an ACL a Trunk references answers INVALID_ARGUMENT
  • The Data API accepts a Trunk URI transport in any case and answers in upper case. A value PostgreSQL refuses (an unknown transport, privacy or balancingAlgorithm, or a value too long for its column) answers INVALID_ARGUMENT naming the problem, where it answered Unknown error
  • The Data API answers an Update that collides with another resource's unique value with ALREADY_EXISTS naming the field, as Create does, where it answered Unknown error; a database not migrated yet answers UNAVAILABLE and logs a warning instead of an error with the SQL. Builds use Go 1.26.11 and pgx 5.9.2 (GO-2026-6809, GO-2026-5004)
  • Location with Redis starts without waiting for it, as before, and indexes the stored bindings as soon as Redis answers, retrying with backoff and logging a warning until then, where it logged an error and waited five minutes
  • EdgePort keeps only the final response of a non-INVITE request answered over UDP, not its whole transaction, for the 32 s it answers retransmissions: about a sixth of the memory at a steady request rate, and the transaction table no longer fills at about 15,600 requests a second
  • Privacy toward a Trunk follows the caller's setting instead of always none
  • A dead next hop gets 408 (INVITE timeout) or 503 (transport failure)
  • least-sessions balancing takes effect; the Registry backs off 30 s after a failed refresh and honors Min-Expires
  • A Trunk whose URI uses TLS registers when sendRegister is set: the Registry's REGISTER reaches the EdgePort over UDP, and the EdgePort opens the TLS connection, as for a call. Routr 2 never sent it
  • Telemetry is telemetry.otlpEndpoint and telemetry.sampleRatio
  • Helm chart: connect.trustedEdgePortAddresses names the release's own EdgePorts (Connect now resolves DNS names there), so a call that crosses two EdgePorts completes; edgeport.podCIDR, off by default, gives the EdgePorts localnets that cover the pod network for user agents inside the cluster; labels are quoted, so a release named n or 123 renders; the Requester's autoscaler is opt-in (requester.autoscaling.enabled)
  • fonoster/routr-pgdata-migrations is built from Routr 3 (ops/pgdata-migrations): Routr 2's migrations unchanged, then the numbering ones (Number aliases and Trunk number formats as in Routr 2.33, and Routr 3's own: the INTERNATIONAL format and an index of Numbers by Trunk), with the Prisma CLI in the image instead of fetched from npm on each run. The chart's migrations hook follows appVersion again instead of pinning 2.32.2
  • Helm chart 0.5: config files from values, an API key and Data API certificate generated once, apiserver.apiKeySecret to take the key from a Secret of your own, a NetworkPolicy on every internal gRPC service, connect.trustedRegistryAddresses and the Connect settings as values. See Helm values
  • The SDK throws an Error (code "ENOENT") when the cacert file doesn't exist instead of exiting the process that uses it; rctl keeps exiting 1
  • @routr/processor's removeSelfRoutes keeps a Route whose transport the EdgePort doesn't listen on instead of throwing NoListeningPointError, as Connect and the Go SDK do
  • Processors can be written in Go with github.com/fonoster/routr/pkg/processor, versioned on its own. See the Go tabs of Build a processor
  • Both processor SDKs add Connect's functions for calls that cross EdgePorts sharing one external address: addRouteToPeerEdgePortOwnAddress, addSelfRecordRouteToPeer, addSelfRecordRouteFromPeer, addSelfViaTowardNextHop, removeRoutesUpToOwn, Helper.sourceAddress and Helper.createRouteFromPeer (Go: the same names, capitalized). The existing functions are unchanged. See Dialogs across EdgePorts
  • In-dialog requests of any method (INFO, UPDATE, PRACK…) are forwarded instead of answered 501, and RTPRelay anchors SDP in UPDATE and PRACK
  • EdgePort closes a TCP, TLS, WS or WSS connection that receives nothing for 65 minutes (connectionIdleTimeout; raise it above the longest Expires your phones register with over those transports) and accepts at most 20,000 at once (maxConnections); past the cap a connection is closed and counted as routr.sip.overflows{limit="connections"}
  • Calls to the PSTN choose a Trunk's outbound URI by enabled, priority and weight, where they always used the first; REGISTER still goes to the first URI. In resource files, a URI without enabled is enabled
  • In-dialog requests have the untrusted platform headers removed, so the carrier or a Connect Token client can't add them after the call is set up
  • A UDP datagram that isn't SIP is counted in routr.sip.malformed and logged at Warn once per 1,000, without its payload (at Debug, every one with its payload), where every one was an Error line
  • A WebSocket client that sends nothing, or sends its upgrade request slowly, no longer keeps other WebSocket clients from connecting; it is closed after 10 s
  • A call to the PSTN moves to the Trunk's next enabled URI when the first answers 503 or can't be reached
  • A call from a Trunk finds its Number however the carrier writes it, among the Trunk's own Numbers only: exactly, the same digits without +, national form (02079460018), international form with the country's own international prefix (00442079460018, 011… from the US), or one of the Number's aliases. The match is in the trace as numberMatch. See A Number written another way
  • Numbers take aliases: labels or other forms a Trunk sends for them, unique per Trunk. rctl numbers create and update ask for them
  • An update can empty a Number's extra headers, a Domain's egress policies and a Trunk's outbound URIs with clearExtraHeaders, clearEgressPolicies and clearUris, as clearAliases does for aliases. rctl numbers update asks Remove all extra headers?, rctl domains update Remove all Egress Policies? and rctl trunks update Remove all Outbound SIP URIs?, each only when there is something to remove
  • Trunks take calledNumberFormat and callerNumberFormat: e164, e164-without-plus, national or international, each with an optional prefix of digits, * and # (a # goes out as %23). Unset sends numbers as dialed, as before. See Number formats
  • Every call Connect routes from a Trunk carries X-DID-Number with the Number's +E.164, replacing a copy the carrier sent. See SIP headers
  • The EdgePort recognizes a Route that names it by any hostname resolving to one of its addresses; aliases is needed only for names that resolve to a load balancer or a Service IP (edgeport)
  • A request that EdgePort sent to itself is answered 482 Loop Detected instead of being processed again (edgeport)
  • forwardConnectToken (spec.connect in routr.yaml, spec in connect.yaml) keeps a verified X-Connect-Token on the INVITE it authorized toward the token's own Peer, as Routr 2 forwarded it. Default false removes it once verified. See X-Connect-Token

Full changelog: https://docs.routr.io/changelog