Repository navigation
Release v3.0.0
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.yamlfor RoutrOne, one file per standalone component. Secrets are${VAR}placeholders orsecret://references. The standalone EdgePort's variables are keys ofedgeport.yamltoo (events,health,sipTrace,stripSessionProgressSdp,ignoreLoopbackFromLocalnets), and noOTEL_*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.rctltakes--api-key(orROUTR_API_KEY), the SDKapiKey - Breaking: a component's client auth (
apiAuth,locationAuth,requesterAuth,processorAuth,backendAuth,verifierAuth) withapiKey, notlsand an address that isn't loopback refuses to start: addtls, orinsecure: trueto send the key in clear. The Helm chart writesinsecure: trueon the Registry'srequesterAuthand, withapiserver.tlsOn: false, on everyapiAuth - Breaking:
rctl trace sendandrctl trace compat --againstopen TLS by default and take--insecureand--cacert: a Dispatcher withouttlsneeds--insecure. With an API key (or a username and password),ALLOW_INSECURE=truetoward a host that isn't loopback is refused byrctland the SDK unless--insecureorinsecure: trueis given, and--cacertorcacertwins over the variable - Breaking:
rctland the SDK refuse--insecure/insecure: truetogether with--cacert/cacertinstead of connecting in plaintext with the CA certificate ignored:rctlexits with an error, the SDK's constructor throws. Keep one:--cacertfor TLS verified with that CA,--insecurefor plaintext - Breaking: the Data API is on
51907only; the external port51908is gone from the images (the Helm chart's Service keeps it).rctldefaults tolocalhost: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;echoandsimpleauthremain as example processors - Breaking: a standalone Connect with a Registry must set
trustedRegistryAddresses;X-Gateway-Authis honored from nobody else - Breaking: every standalone component file must set
apiVersiontov2beta1,v2orv3(v3is 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
403from an address it doesn't allow. A Peer whoseaccessControlListRefnames no ACL fails to load from resource files - Breaking: an Agent's INVITE to an Agent of another Domain gets
403 Forbiddeninstead 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 get480. In resource files an Agent withoutenabledis enabled - Breaking: EdgePort applies
methodsandunknownMethodActionto out-of-dialog requests. With the defaultDiscard, a method outsidemethodsgets 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
enforceE164Numbersdefaults totrue: creating a Number whosetelUrlisn'ttel:+and 2 to 15 digits (the first not0) fails withINVALID_ARGUMENT, and thefilesbackend refuses to load one. Setspec.data.enforceE164Numbers: false(Helm:apiserver.enforceE164Numbers: false) to keep Routr 2's check. Seespec.data - Breaking: the Trunk's
normalizeToE164is removed: the proto field is reserved, and a resource file that sets it fails to load. UsecalledNumberFormatandcallerNumberFormat: e164instead. On calls from a Trunk, From, To and the Request-URI reach your application as the carrier sent them; the called Number is inX-DID-Number. The Go SDK'sNormalizeToE164is removed too (pkg/processor) - Breaking: a call on a Trunk to a Number with no Trunk, or on another Trunk, gets
404 No Number foundinstead of403. The Trunk alone decides the callee, among its own Numbers - Breaking: a Number's
countryIsoCodemust be a country with a numbering plan;XXand three-letter codes are rejected, andrctlno longer offersUnknown - Breaking: a Trunk number prefix with no format, or with
e164, is rejected; a prefix needse164-without-plus,nationalorinternational CLOAK_ENCRYPTION_KEYbecomesspec.data.encryptionKey; with no key and encrypted passwords in the database, the Data API refuses to start.DATABASE_URLworks as it is,?schema=publicincluded- 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 newcachekey (provider: redis;spec.edgeport.cacheinroutr.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, oredgeport.cache.parametersfor 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
transportin any case and answers in upper case. A value PostgreSQL refuses (an unknown transport,privacyorbalancingAlgorithm, or a value too long for its column) answersINVALID_ARGUMENTnaming the problem, where it answeredUnknown error - The Data API answers an Update that collides with another resource's unique value with
ALREADY_EXISTSnaming the field, as Create does, where it answeredUnknown error; a database not migrated yet answersUNAVAILABLEand 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
Privacytoward a Trunk follows the caller's setting instead of alwaysnone- A dead next hop gets
408(INVITE timeout) or503(transport failure) least-sessionsbalancing takes effect; the Registry backs off 30 s after a failed refresh and honorsMin-Expires- A Trunk whose URI uses TLS registers when
sendRegisteris 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.otlpEndpointandtelemetry.sampleRatio - Helm chart:
connect.trustedEdgePortAddressesnames 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 namednor123renders; the Requester's autoscaler is opt-in (requester.autoscaling.enabled) fonoster/routr-pgdata-migrationsis 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: theINTERNATIONALformat 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 followsappVersionagain instead of pinning2.32.2- Helm chart 0.5: config files from values, an API key and Data API certificate generated once,
apiserver.apiKeySecretto take the key from a Secret of your own, a NetworkPolicy on every internal gRPC service,connect.trustedRegistryAddressesand the Connect settings as values. See Helm values - The SDK throws an
Error(code"ENOENT") when thecacertfile doesn't exist instead of exiting the process that uses it;rctlkeeps exiting1 @routr/processor'sremoveSelfRouteskeeps a Route whose transport the EdgePort doesn't listen on instead of throwingNoListeningPointError, 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.sourceAddressandHelper.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 asroutr.sip.overflows{limit="connections"} - Calls to the PSTN choose a Trunk's outbound URI by
enabled,priorityandweight, where they always used the first; REGISTER still goes to the first URI. In resource files, a URI withoutenabledis 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.malformedand 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'saliases. The match is in the trace asnumberMatch. See A Number written another way - Numbers take
aliases: labels or other forms a Trunk sends for them, unique per Trunk.rctl numbers createandupdateask for them - An update can empty a Number's extra headers, a Domain's egress policies and a Trunk's outbound URIs with
clearExtraHeaders,clearEgressPoliciesandclearUris, asclearAliasesdoes for aliases.rctl numbers updateasksRemove all extra headers?,rctl domains updateRemove all Egress Policies?andrctl trunks updateRemove all Outbound SIP URIs?, each only when there is something to remove - Trunks take
calledNumberFormatandcallerNumberFormat:e164,e164-without-plus,nationalorinternational, 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-Numberwith 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;
aliasesis 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 Detectedinstead of being processed again (edgeport) forwardConnectToken(spec.connectinroutr.yaml,specinconnect.yaml) keeps a verifiedX-Connect-Tokenon the INVITE it authorized toward the token's own Peer, as Routr 2 forwarded it. Defaultfalseremoves it once verified. See X-Connect-Token
Full changelog: https://docs.routr.io/changelog