docs(sip-trunking): UDP is accepted; document fragmentation as the real hazard - #411
docs(sip-trunking): UDP is accepted; document fragmentation as the real hazard#411abhishekmishragithub wants to merge 2 commits into
Conversation
…al hazard The transport contract shipped in #400 stated the SIP ingress accepts TCP and TLS only and drops UDP INVITEs without a response. A live OPTIONS probe over UDP against the production ingress returns 200 OK, and the SIP infrastructure accepts all three transports. The failure #400 documented is real but has a different cause: full-size INVITEs fragment over UDP and fragments are silently discarded on many paths, while small requests (OPTIONS pings) go through, so the trunk looks healthy while calls vanish. Reframe the transport table (UDP: accepted, not recommended), the silence-no-response troubleshooting section, the duplicate-INVITE section, the FAQ entry, and the Twilio/Telnyx/Vonage callouts. The recommendation is unchanged: TLS preferred, TCP fallback, avoid UDP for signalling. Also correct adjacent wire facts on the page: codecs offered are G.722 and G.711 PCMU/PCMA (not Opus), DTMF is RFC 2833/4733 telephone-event only (SIP INFO removed), add the RTP keepalive rule (15 s mid-call / 30 s at setup), the early-offer requirement, X-* header passthrough into agent variables, and how transfers appear on a trunk (second outbound call, no SIP REFER, two channels per transferred call). Changelog entry included.
|
crim doesn't review pull requests automatically here. Comment |
|
crim doesn't review pull requests automatically here. Comment |
|
crim review |
|
crim is reviewing this pull request. Findings will be posted shortly. |
Hold off on mergingA thorough correction that fixed the UDP story on five pages and even wrote itself a changelog confessing the old sin, then left one page still preaching the heresy. Patch the last stray "UDP not accepted" and this ships clean. |
![crim-app[bot]](https://avatars.githubusercontent.com/u/64185252?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation-only PR that corrects the SIP transport guidance from "UDP is rejected" to "UDP is accepted but not recommended (fragmentation hazard)."
What this PR does: Rewrites the transport contract, troubleshooting, and limitations sections of the SIP Trunking page; adjusts the Twilio/Telnyx/Vonage setup guides and the FAQ to match; adds custom-header, RTP-keepalive, early-offer, and call-transfer details; corrects codecs (G.722/G.711, Opus removed) and DTMF (RFC 2833/4733, SIP INFO removed); and adds a changelog entry.
Findings
- Medium:
fern/products/atoms/pages/platform/deployment/phone-numbers.mdx:78still states "our ingress does not accept UDP," contradicting the correction this PR makes across every other page.
Findings outside the diff
These concern lines GitHub won't allow inline comments on (unchanged or outside this PR's diff).
-
fern/products/atoms/pages/platform/deployment/phone-numbers.mdx:78— Medium: This page still asserts the old, now-corrected claim that "our ingress does not accept UDP."The entire point of this PR is to replace that statement (UDP is in fact accepted; fragmentation of large INVITEs is the real hazard). This page was not included in the change set, and the changelog's "Pages updated" list omits it, so a reader here gets the exact guidance the PR declares wrong and links to the transport-contract section that now says the opposite. Suggest aligning the wording, e.g.:
Append `;transport=tls` (preferred) or `;transport=tcp` before pasting; UDP is accepted but not recommended (large INVITEs can fragment and be lost silently).
…ed UDP guidance The Import SIP field table on the Phone Numbers page still said the ingress does not accept UDP, contradicting the correction applied to every other page in this branch. Reword to match (accepted, not recommended, fragmentation risk) and add the page to the changelog entry's updated list.
|
Addressed the review: the Phone Numbers page (Import SIP field table, line 78) now matches the corrected transport guidance, and the changelog's updated-pages list includes it. Repo-wide sweep for the old wording ("not accept UDP", "TCP and TLS only", "silently dropped") finds no remaining instances outside historical changelog entries. |
|
crim review again |
|
crim is reviewing this pull request. Findings will be posted shortly. |
There was a problem hiding this comment.
LGTM
One-sentence assessment: A clean, internally consistent documentation correction that reframes UDP from "rejected" to "accepted but fragmentation-prone," with no factual contradictions left in the tree.
What this PR does
Corrects the SIP trunking docs across the main deep-dive page, the Twilio/Telnyx/Vonage setup guides, the Phone Numbers import page, and the FAQ. The old claim that the ingress rejects UDP outright is replaced with the accurate story: UDP is accepted, but full-size INVITEs can fragment and be silently dropped on the path, so TCP/TLS remain the recommendation. It also adds a changelog entry and folds in several related corrections on the main page (codecs G.722/G.711 not Opus, DTMF RFC 2833/4733 only, RTP keepalive timeouts, early-offer requirement, X-* custom header passthrough, and call-transfer behavior).
Findings
No issues found. The previously reported concern at phone-numbers.mdx:78 is resolved. Transport tables, prose, troubleshooting, and limitations are consistent across all files, and internal anchor links resolve to the corrected section.
Good to mergeThis PR admits the ingress was never actually slamming the door on UDP — it was just letting the fragments wander off and never come home. Honest, thorough, and consistent to the last table cell; nicely done. |
1 participant
Summary
Corrects the transport contract shipped in #400. That rewrite said the SIP ingress accepts TCP and TLS only and that UDP INVITEs are dropped with no response. Verified against the production ingress: a SIP OPTIONS probe over UDP (port 5060) returns
SIP/2.0 200 OK, same as TCP. All three transports are accepted.The incident behind #400 (PRO-2478: days lost on silent INVITEs, fixed by a transport swap) is consistent with the corrected explanation: full-size INVITEs fragment over UDP and fragments are silently discarded on many paths, while small requests like OPTIONS pings go through, so the trunk looks reachable while calls vanish. The fix (switch to TCP/TLS) was right; the stated reason was not. The recommendation is unchanged everywhere: TLS preferred, TCP fallback, avoid UDP for signalling.
Changes
sip-trunking.mdx: transport table row for UDP (accepted, not recommended), fragmentation-based silence troubleshooting, duplicate-INVITE section, SBC accordion, limitations.telephone-eventonly. SIP INFO removed.X-*header passthrough into agent variables, transfer semantics on the trunk (second outbound call, no SIP REFER, two channels per transferred call).twilio-sip-setup.mdx,telnyx-sip-setup.mdx,vonage-sip-setup.mdx: corrected the UDP callout, kept the TLS-first guidance and cross-links.faq.mdx: silence-no-response answer now explains the fragmentation signature (OPTIONS works, INVITEs vanish).2026-09-02-sip-trunking-udp-corrected.mdx.Test plan
#transport-contractanchor still resolves from provider pages and FAQ.sipsak -vv -s 'sip:<ingress-host>'over UDP returns 200 OK; a full INVITE over UDP through a fragmenting path times out while the same INVITE over TCP completes.