Subject: [hybi] lws-meta: lightweight ws mux subprotocol

From: Andy Green <[email-masked]>
Date: Thu, 17 Aug 2017 18:03:35 +0800

Hi -

FYI libwebsockets ships with a ws subprotocol (not an extension) and 
helper JS since the last release called "lws-meta", which performs ws 
connection muxing.

If you want to make several logical ws connections back to your server 
using different ws subprotocols, ws doesn't give you a way to do it 
without a tcp connection per ws subprotocol.  Either you stick with one 
tcp connection by throwing unrelated subprotocol stuff into a new single 
ws subprotocol and sort out the mess, or you have n tcp connections back 
to the server for n subprotocols.  (n tcp connections also implies n tls 
tunnels for wss case).

"lws-meta" can open one real ws link with one actual tcp connection / 
tls tunnel, and mux n other logical ws connections inside that.

The lws-meta link contains normal ws frames with opaque content and 
follows ws rules about framing, so intermediaries won't care.  After 
some small messages managing child bringup and close (much smaller than 
doing the http/1 ws upgrade each time), there's only 2 bytes overhead 
per child bulk data frame compared to a direct ws link.

JS objects are provided to manage the real link and mux same-basic-api 
child connections in there using the same apis as a direct ws link (ie, 
onopen() / onclose() / onmessage()).  At least in the lws 
implementation, your normal user ws subprotocols that the child 
connections use are unaware if their traffic is coming on a normal tcp 
connection or via lws-meta; for them everything is the same and the same 
protocol handler server-side can accept connections direct and via lws-meta.

The lws-meta subprotocol is very simple, but of course there's some work 
to do server side to have its child IO appear to be coming from a 
discrete connection.

Details here:

https://github.com/warmcat/libwebsockets/blob/master/README.lws-meta.md

Protocol implementation part for lws:

https://github.com/warmcat/libwebsockets/blob/master/plugins/protocol_lws_meta.c

-Andy