Support TCP for protocol messages by softins · Pull Request #3636 · jamulussoftware/jamulus

softins · 2026-03-11T14:36:42Z

Short description of changes

Support fallback to TCP for protocol messages, in order to overcome potential loss of large messages due to UDP fragmentation. Currently an incomplete draft, for comment as development continues.

CHANGELOG: Client/Server: Support TCP fallback for protocol messages.

Context: Fixes an issue?

Discussed in issue #3242.

Does this change need documentation? What needs to be documented and how?

It will need documentation once design and development are complete. Particularly need to explain the firewall requirements for a server or directory.

Status of this Pull Request

~~Incomplete, still under development. Main server side complete and working. Client side development in progress.~~ Complete and ready for review and testing. Still marked draft as it needs some of the debug messages to be commented out before merging.

What is missing until this pull request can be merged?

A lot of testing of both server and client. Intended for Jamulus 4.0.0.

Checklist

I've verified that this Pull Request follows the general code principles
I tested my code and it does what I want
My code follows the style guide
I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
I've filled all the content above

softins · 2026-03-11T14:40:45Z

So far, this implements the server side of the design described here and here

softins · 2026-03-28T12:07:21Z

So the next stage of implementation has been achieved: client-side support in the Connect dialog.

If the server list has not been received via UDP when the associated message indicating TCP support has arrived, the client will retry fetching the server list over TCP.
If the client list for a server has not been received via UDP when the associated message indicating TCP support has arrived, the client will retry fetching the client list over TCP, and will continue to use TCP for that server while the Connect dialog is open.
A directory or server that does not have TCP support will not send the TCP supported message, and will continue to be handled as in current versions.
If the server list or client list is successfully received over UDP, there is no need for the client to try TCP.

It has been tested by using nft to drop outbound Jamulus UDP messages with a specific message ID, to simulate loss due to fragmentation.

Examples for a directory-enabled server running on port 22120:

drop UDP server list: nft add rule inet filter output udp sport 22120 @ih,16,16 0xee03 drop
drop UDP client list: nft add rule inet filter output udp sport 22120 @ih,16,16 0xf503 drop
drop UDP "TCP supported" msg: nft add rule inet filter output udp sport 22120 @ih,16,16 0xfb03 drop

Note that nft rules require network byte order (big-endian), but Jamulus IDs are little-endian:

CLM_SERVER_LIST = 1006 = 0x03ee => 0xee03 (LE byte order)
CLM_RED_SERVER_LIST = 1018 = 0x03fa => 0xfa03 (LE byte order)
CLM_CONN_CLIENTS_LIST = 1013 = 0x03f5 => 0xf503 (LE byte order)
CLM_TCP_SUPPORTED = 1019 = 0x03fb => 0xfb03 (LE byte order)

softins · 2026-03-28T17:56:02Z

The next step is to try implementing the connected-mode TCP described here

src/tcpserver.h

ann0see · 2026-04-07T14:55:58Z

src/main.cpp

    bool         bUseTranslation             = true;
    bool         bCustomPortNumberGiven      = false;
    bool         bEnableIPv6                 = false;
+    bool         bEnableTcp                  = false;


Since we'll have a long time for the 4.0 release, I'd enable it by default soon (of course once we've tested that the basics work)

No, I disagree. It's a server-only option, and most servers operators will not need to enable TCP support. Only those running large directories or large servers will need to, and they also need to understand and configure their firewall requirements.

TCP support in the client will indeed be enabled by default, but will only take effect when talking to a directory or server that has enabled it.

If a server operator enables TCP without having configured their firewall correctly, client users could have problems as the server would advertise TCP support to the client, but the client could be unable to connect.

Can we not give an error message or fallback procedure in case the TCP connection timed out?

Yes, I'm sure we can. I haven't yet tested that scenario.

But it doesn't negate my view that server-side TCP support needs to be an explicit option.

src/connectdlg.cpp

softins · 2026-04-09T22:48:19Z

Well I've finished implementing everything I intended to, for directory, server and client, so it's ready for reviewing and trying out, as and when time permits (post 3.12.0).

I have a private directory and server built and running with TCP support, at newjam.softins.co.uk on the standard port 22124.

In order to demonstrate the use of TCP in a new client's connect dialog, it will be necessary to use custom firewall filters on the client end to temporarily drop incoming UDP Jamulus protocol messages containing a server list or connected clients list.

There is full forward and backward compatibility between clients and servers built with TCP support and older versions.

softins · 2026-04-10T06:34:38Z

Keeping as draft, because it will need quite a few debug messages removed before merging.

To provide three modes: UDP, TCP once or TCP long connection.

Constructor for CTcpConnection made polymorphic for client and server.

pljones · 2026-04-10T15:53:00Z

Minor question... At some point, would we consider removing 150 Server cap on Directories? It was put in place to help prevent fragmentation (but it turned out to be too high anyway, IIRC).

softins · 2026-04-10T19:04:05Z

Minor question... At some point, would we consider removing 150 Server cap on Directories? It was put in place to help prevent fragmentation (but it turned out to be too high anyway, IIRC).

Could do. Although the biggest public directory, Any Genre 1, is currently only at 105 servers registered.

Maybe we could make the limit configurable via a command-line option?

softins added this to the Release 4.0.0 milestone Mar 11, 2026

softins self-assigned this Mar 11, 2026

softins mentioned this pull request Mar 11, 2026

Support TCP for protocol messages #3242

Open

softins force-pushed the tcp-protocol branch 4 times, most recently from 5e1a658 to 0ae51e2 Compare March 16, 2026 13:05

softins linked an issue Mar 16, 2026 that may be closed by this pull request

Support TCP for protocol messages #3242

Open

softins added the feature request Feature request label Mar 16, 2026

softins force-pushed the tcp-protocol branch 3 times, most recently from 7ad1d1f to d939e5b Compare March 26, 2026 17:38

ann0see self-requested a review April 7, 2026 14:51

ann0see reviewed Apr 7, 2026

View reviewed changes

src/tcpserver.h Show resolved Hide resolved

ann0see reviewed Apr 7, 2026

View reviewed changes

src/connectdlg.cpp Outdated Show resolved Hide resolved

ann0see reviewed Apr 7, 2026

View reviewed changes

src/connectdlg.cpp Outdated Show resolved Hide resolved

ann0see assigned ann0see and pljones Apr 9, 2026

ann0see added the bug Something isn't working label Apr 9, 2026

github-project-automation bot added this to Tracking Apr 9, 2026

github-project-automation bot moved this to Triage in Tracking Apr 9, 2026

ann0see moved this from Triage to In Progress in Tracking Apr 9, 2026

softins marked this pull request as ready for review April 9, 2026 22:48

softins marked this pull request as draft April 10, 2026 06:30

softins added 26 commits April 10, 2026 16:22

Request server list via TCP if required

f37b065

Add message context parameter for CLM_TCP_SUPPORTED

7c54222

Add Qt version check for errorOccurred()

11bff37

Fetch client list over TCP when necessary for a server

2b51b13

Create CLM_CLIENT_ID and related methods

bbcbeb3

Add OnClientIDReceived slot to CChannel

d068fb4

Skeleton support for connected mode TCP

6826d4b

Move TCP debug message from connectdlg to client

ca86215

Add missing return

2c13829

Remove unneeded #include from tcpconnection

d1c8229

Send client list via TCP when connection available

11768e9

Add skeleton handler for CLClientID to CServer

80644be

Add disconnecFromHost method to CTcpConnection

7322345

Mods to CTcpConnection for future use

739fe04

In server, link TCP channel to UDP channel by client ID

0bcd7ad

Replace boolean TCP flag with multimode enum

5e7a8ca

To provide three modes: UDP, TCP once or TCP long connection.

Add creation of session-long TCP connection

f2e59a5

Route CLConnClientList depending on whether connected

fc65fe3

Be specific about bDisconAfterRecv for TCP

db7437c

Rework TCP session-mode connection

9447816

Minor comment updates

c0960fe

Add support for sending Empty Message over TCP

7a85d0a

Implement keepalive over session long TCP connection

a621461

Clarify comment

1934beb

Make CTcpConnection work in serveronly mode.

e644eab

Constructor for CTcpConnection made polymorphic for client and server.

Add timeout for TCP connection

0858dda

softins force-pushed the tcp-protocol branch from fc7654e to 0858dda Compare April 10, 2026 15:22

ann0see moved this from In Progress to Waiting on Team in Tracking Apr 10, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support TCP for protocol messages#3636

Support TCP for protocol messages#3636
softins wants to merge 40 commits intojamulussoftware:mainfrom
softins:tcp-protocol

softins commented Mar 11, 2026 •

edited

Loading

Uh oh!

softins commented Mar 11, 2026

Uh oh!

softins commented Mar 28, 2026

Uh oh!

softins commented Mar 28, 2026

Uh oh!

Uh oh!

ann0see Apr 7, 2026

Uh oh!

softins Apr 7, 2026

Uh oh!

ann0see Apr 7, 2026

Uh oh!

softins Apr 7, 2026

Uh oh!

Uh oh!

Uh oh!

softins commented Apr 9, 2026

Uh oh!

softins commented Apr 10, 2026

Uh oh!

pljones commented Apr 10, 2026

Uh oh!

softins commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

softins commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

softins commented Mar 11, 2026

Uh oh!

softins commented Mar 28, 2026

Uh oh!

softins commented Mar 28, 2026

Uh oh!

Uh oh!

ann0see Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

softins Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

ann0see Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

softins Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

softins commented Apr 9, 2026

Uh oh!

softins commented Apr 10, 2026

Uh oh!

pljones commented Apr 10, 2026

Uh oh!

softins commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

softins commented Mar 11, 2026 •

edited

Loading