From 82a35d16fbcccf70529315f4a8dc649139c16b9e Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 7 Dec 2022 04:50:07 -0500 Subject: [PATCH 1/7] add short desc. for mplex --- content/concepts/multiplex/mplex.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 8373c522..53c240f4 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -1,14 +1,21 @@ --- -title: "mplex" -description: "mplex is a protocol developed for libp2p." +title: "Mplex" +description: "mplex is a stream multiplexer developed for libp2p." weight: 170 --- -mplex is a protocol developed for libp2p. The [spec](https://github.com/libp2p/specs/tree/master/mplex) defines a -simple protocol for multiplexing that is widely supported across libp2p language implementations: +## What is Mplex? -{{< alert icon="💡" context="note">}} -This section is incomplete, and many of the articles are stubs. To help fill in -the gaps, please see the issues linked in each article to add your input and -help us prioritize the outstanding work. -{{< /alert >}} +Mplex is a stream multiplexer designed for libp2p. +It is a simple protocol that does not provide many features offered by other +stream multiplexers. Notably, mplex does not provide backpressure at the protocol +level. + +Mplex runs over a reliable, ordered pipe between two peers, such as a TCP socket +or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages +with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). + +Every message (one byte) in mplex consists of a header and a length of prefixed data +segment. + +{{< alert icon="💡" context="note" text="See the mplex technical specification for more details." />}} From 9057b4d5d02f36f9c2cc5c5bf15c29923f8999a6 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 08:39:29 -0500 Subject: [PATCH 2/7] incorporate feedback, add drawbacks and edit --- content/concepts/multiplex/mplex.md | 37 +++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 53c240f4..5f25839f 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -1,21 +1,48 @@ --- -title: "Mplex" +title: "mplex" description: "mplex is a stream multiplexer developed for libp2p." weight: 170 --- -## What is Mplex? +## What is mplex? -Mplex is a stream multiplexer designed for libp2p. +mplex is a stream multiplexer designed for libp2p. It is a simple protocol that does not provide many features offered by other stream multiplexers. Notably, mplex does not provide backpressure at the protocol level. -Mplex runs over a reliable, ordered pipe between two peers, such as a TCP socket +mplex runs over a reliable, ordered pipe between two peers, such as a TCP socket or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). -Every message (one byte) in mplex consists of a header and a length of prefixed data +Every message in mplex consists of a header and a length of prefixed data segment. +### Drawbacks + +mplex does not support backpressure because it is designed to be more flexible and +extensible than other multiplexing protocols. Instead of using a flow control mechanism +like [yamux](yamux), mplex uses a message-based framing layer that enables it to multiplex +different types of data streams, including stream-oriented data, datagrams, and other types +of messages. This flexibility comes at the cost of some performance and reliability, as +mplex is less efficient at transferring large amounts of data than other multiplexing +protocols that support backpressure. + +Additionally, mplex has no limits on how many streams a peer can open. This allows mplex +to support a wide range of applications and use cases, but it also means that mplex may +not be as efficient as other multiplexing protocols that limit the number of streams that +can be opened. + +{{< alert icon="" context="">}} +**Yamux should be used over mplex in libp2p**. It is well-suited for applications that +require fast, reliable data transfer, such as real-time communication or streaming media, +as it is optimized for low-latency, high-bandwidth environments. + +Until recently, the reason mplex was still supported was compatibility with js-libp2p, +which didn't have yamux support. +Now that +[js-libp2p has gained yamux support](https://github.com/ChainSafe/js-libp2p-yamux/releases/tag/v1.0.0), +you should only support mplex if you need to deal with legacy nodes. +{{< /alert >}} + {{< alert icon="💡" context="note" text="See the mplex technical specification for more details." />}} From a26bd78276c7570c2e68a4944d8204fbc3138f70 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 17:08:34 -0500 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Marten Seemann --- content/concepts/multiplex/mplex.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 5f25839f..d1bca24c 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -11,7 +11,7 @@ It is a simple protocol that does not provide many features offered by other stream multiplexers. Notably, mplex does not provide backpressure at the protocol level. -mplex runs over a reliable, ordered pipe between two peers, such as a TCP socket +mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). @@ -42,7 +42,7 @@ Until recently, the reason mplex was still supported was compatibility with js-l which didn't have yamux support. Now that [js-libp2p has gained yamux support](https://github.com/ChainSafe/js-libp2p-yamux/releases/tag/v1.0.0), -you should only support mplex if you need to deal with legacy nodes. +mplex should only be used to provide backwards-compatibility with legacy nodes. {{< /alert >}} {{< alert icon="💡" context="note" text="See the mplex technical specification for more details." />}} From 01fd625aa5e8ab9b8b61a2da8e8c5701bb084298 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 17:36:48 -0500 Subject: [PATCH 4/7] incorporate pr feedback --- content/concepts/multiplex/mplex.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index d1bca24c..4f7b6157 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -14,29 +14,23 @@ level. mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). +It uses a message-based framing layer like [yamux](yamux), enabling it to multiplex different +types of data streams, including stream-oriented data and other types of messages. -Every message in mplex consists of a header and a length of prefixed data -segment. +Every message in mplex consists of a header and a length of prefixed data segment. ### Drawbacks -mplex does not support backpressure because it is designed to be more flexible and -extensible than other multiplexing protocols. Instead of using a flow control mechanism -like [yamux](yamux), mplex uses a message-based framing layer that enables it to multiplex -different types of data streams, including stream-oriented data, datagrams, and other types -of messages. This flexibility comes at the cost of some performance and reliability, as -mplex is less efficient at transferring large amounts of data than other multiplexing -protocols that support backpressure. +mplex does not support backpressure or have any flow control. +> Backpressure is a mechanism to prevent one peer to overwhelm a peer that's slow at consuming the data. -Additionally, mplex has no limits on how many streams a peer can open. This allows mplex -to support a wide range of applications and use cases, but it also means that mplex may -not be as efficient as other multiplexing protocols that limit the number of streams that -can be opened. +mplex has no limits on how many streams a peer can open. This allows mplex to support a wide +range of applications and use cases, but it also means that mplex may not be as efficient as other +multiplexing protocols that limit the number of streams that can be opened. {{< alert icon="" context="">}} **Yamux should be used over mplex in libp2p**. It is well-suited for applications that -require fast, reliable data transfer, such as real-time communication or streaming media, -as it is optimized for low-latency, high-bandwidth environments. +require fast, reliable data transfer as it is optimized for low-latency, high-bandwidth environments. Until recently, the reason mplex was still supported was compatibility with js-libp2p, which didn't have yamux support. From 45d865fb26a096fb55af807f96e86d6ab63e9290 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 17:45:59 -0500 Subject: [PATCH 5/7] edits --- content/concepts/multiplex/mplex.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 4f7b6157..8547d495 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -15,14 +15,14 @@ mplex runs over a reliable, ordered pipe between two peers, such as a TCP connec or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). It uses a message-based framing layer like [yamux](yamux), enabling it to multiplex different -types of data streams, including stream-oriented data and other types of messages. +data streams, including stream-oriented data and other types of messages. -Every message in mplex consists of a header and a length of prefixed data segment. +Every message in mplex consists of a header and the prefixed data segment length. ### Drawbacks -mplex does not support backpressure or have any flow control. -> Backpressure is a mechanism to prevent one peer to overwhelm a peer that's slow at consuming the data. +mplex does not have any flow control. +> Backpressure is a mechanism to prevent one peer from overwhelming a slow time consuming the data. mplex has no limits on how many streams a peer can open. This allows mplex to support a wide range of applications and use cases, but it also means that mplex may not be as efficient as other @@ -36,7 +36,7 @@ Until recently, the reason mplex was still supported was compatibility with js-l which didn't have yamux support. Now that [js-libp2p has gained yamux support](https://github.com/ChainSafe/js-libp2p-yamux/releases/tag/v1.0.0), -mplex should only be used to provide backwards-compatibility with legacy nodes. +mplex should only be used to provide backward-compatibility with legacy nodes. {{< /alert >}} {{< alert icon="💡" context="note" text="See the mplex technical specification for more details." />}} From 02b1700ba0135a96099ce0962191093aae3432f1 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Tue, 24 Jan 2023 06:50:04 -0500 Subject: [PATCH 6/7] incorporate PR feedback; tweaks to content --- content/concepts/multiplex/mplex.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 8547d495..f9f275d9 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -1,6 +1,6 @@ --- title: "mplex" -description: "mplex is a stream multiplexer developed for libp2p." +description: "mplex is a simple stream multiplexer that was developed for libp2p." weight: 170 --- @@ -11,26 +11,22 @@ It is a simple protocol that does not provide many features offered by other stream multiplexers. Notably, mplex does not provide backpressure at the protocol level. -mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection -or a Unix pipe. Peers can open, write to, close, and reset a stream by sending messages -with the appropriate [flag value](https://github.com/libp2p/specs/tree/master/mplex#flag-values). -It uses a message-based framing layer like [yamux](yamux), enabling it to multiplex different +mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection. +Peers can open, write to, close, and reset a stream. mplex uses a message-based framing +layer like [yamux](yamux), enabling it to multiplex different data streams, including stream-oriented data and other types of messages. -Every message in mplex consists of a header and the prefixed data segment length. - ### Drawbacks mplex does not have any flow control. > Backpressure is a mechanism to prevent one peer from overwhelming a slow time consuming the data. mplex has no limits on how many streams a peer can open. This allows mplex to support a wide -range of applications and use cases, but it also means that mplex may not be as efficient as other -multiplexing protocols that limit the number of streams that can be opened. +range of applications and use cases. {{< alert icon="" context="">}} **Yamux should be used over mplex in libp2p**. It is well-suited for applications that -require fast, reliable data transfer as it is optimized for low-latency, high-bandwidth environments. +require fast, reliable data transfer. Until recently, the reason mplex was still supported was compatibility with js-libp2p, which didn't have yamux support. From b23c61aa2354b34c276795895f16115d70fb0004 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Tue, 31 Jan 2023 08:30:39 -0500 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Marten Seemann --- content/concepts/multiplex/mplex.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index f9f275d9..3b7cd6de 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -6,10 +6,10 @@ weight: 170 ## What is mplex? -mplex is a stream multiplexer designed for libp2p. +mplex is a simple stream multiplexer that was designed in the early days of libp2p. It is a simple protocol that does not provide many features offered by other -stream multiplexers. Notably, mplex does not provide backpressure at the protocol -level. +stream multiplexers. Notably, mplex does not provide flow control, a feature which +is now considered critical for a stream multiplexer. mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection. Peers can open, write to, close, and reset a stream. mplex uses a message-based framing @@ -21,12 +21,10 @@ data streams, including stream-oriented data and other types of messages. mplex does not have any flow control. > Backpressure is a mechanism to prevent one peer from overwhelming a slow time consuming the data. -mplex has no limits on how many streams a peer can open. This allows mplex to support a wide -range of applications and use cases. +mplex also doesn't limit how many streams a peer can open. {{< alert icon="" context="">}} -**Yamux should be used over mplex in libp2p**. It is well-suited for applications that -require fast, reliable data transfer. +**Yamux should be used over mplex in libp2p**. As it natively supports flow control, it is better suited for applications that require the transfer of large amounts of data. Until recently, the reason mplex was still supported was compatibility with js-libp2p, which didn't have yamux support.