update: protocols overview #287

salmad3 · 2023-01-09T03:55:48Z

Context

Replaces update: fundamentals protocols doc #201 and enhances various sections
Part of a "Protocol Basics" sub-section under "Introduction"
Part of Improve Protocol Documentation. #120

Latest preview

Fleek preview unavailable as PR not against master.

content/concepts/introduction/protocols/overview.md

p-shahi · 2023-01-12T04:16:39Z

content/concepts/introduction/protocols/overview.md

-There are protocols everywhere you look when you're writing network applications, and libp2p is
-especially thick with them.
+libp2p is composed of various core abstractions, such as
+[peer identity](../core-abstractions/peers.md#peer-id),
+and [addressing](../core-abstractions/addressing.md/), and
+relies on protocols to facilitate communication between peers.

-The kind of protocols this article is concerned with are the ones built with libp2p itself,
-using the core libp2p abstractions like [transport](/concepts/transport), [peer identity](/concepts/peers#peer-id/), [addressing](/concepts/addressing/), and so on.
-
-Throughout this article, we'll call this kind of protocol that is built with libp2p
-a **libp2p protocol**, but you may also see them referred to as "wire protocols" or "application protocols".
-
-These are the protocols that define your application and provide its core functionality.
-
-This article will walk through some of the key [defining features of a libp2p protocol](#what-is-a-libp2p-protocol), give an overview of the [protocol negotiation process](#protocol-negotiation), and outline some of the [core libp2p protocols](#core-libp2p-protocols) that are included with libp2p and provide key functionality.
-
-## What is a libp2p protocol?
-
-A libp2p protocol has these key features:
+A libp2p protocol is a network protocol that operates within
+the libp2p network and follows certain conventions.


I think the previous intro was better and did a good job, the new lines are a bit too succinct imo.

A libp2p protocol is a network protocol that operates within the libp2p network and follows certain conventions.

This is a very circular definition. 😵‍💫

That's fair.

This is trying to be direct and point out exactly what a libp2p protocol is. I simplified it.

p-shahi

I think based on the current content, this document is trying more to be the lifecycle of a libp2p protocol?
It includes the handler, negotiation, and dialing as well as content about streams

It doesn't truly answer what is a libp2p protocol nor does it differentiate between different kinds i.e. transports, mulitplexers, secure channels, messaging protocols, etc.

I'm a bit confused as to which direction this document wants to go in.

If we want to keep it as what's a protocol at minimum I think we should state that there are n different types of protocols in libp2p

p-shahi · 2023-02-02T18:59:51Z

content/concepts/introduction/protocols/overview.md

+libp2p is composed of various core abstractions, such as
+[peer identity](../core-abstractions/peers.md#peer-id),
+and [addressing](../core-abstractions/addressing.md/), and
+relies on protocols to facilitate communication between peers.
+These protocols are networking protocol that follows certain conventions
+to allow for peer-to-peer networking.


Suggested change

libp2p is composed of various core abstractions, such as

[peer identity](../core-abstractions/peers.md#peer-id),

and [addressing](../core-abstractions/addressing.md/), and

relies on protocols to facilitate communication between peers.

These protocols are networking protocol that follows certain conventions

to allow for peer-to-peer networking.

There are protocols everywhere you look when you're writing network applications, and libp2p is

especially thick with them.

The kind of protocols this article is concerned with are the ones built with libp2p itself,

using the core libp2p abstractions like [transports](/concepts/transport), [peer identity](/concepts/peers#peer-id/), [addressing](/concepts/addressing/), and so on.

Throughout this article, we'll call this kind of protocol that is built with libp2p

a **libp2p protocol**, but you may also see them referred to as "wire", "application" or "networking" protocols.

Together these libp2p protocols enable decentralized peer-to-peer networking and a wide variety of use cases to be built.

I prefer this.

p-shahi · 2023-02-02T19:02:20Z

content/concepts/introduction/protocols/overview.md

+Each protocol has a unique string identifier called a protocol ID,
+which negotiates the use of the protocol during the establishment
+of a new stream between two peers.


Suggested change

Each protocol has a unique string identifier called a protocol ID,

which negotiates the use of the protocol during the establishment

of a new stream between two peers.

Each protocol has a unique identifier called a protocol ID.

The protocol ID helps negotiate connection establishment between two peers.

p-shahi · 2023-02-02T19:04:23Z

content/concepts/introduction/protocols/overview.md

+- **Supports backpressure**: Eager writers cannot flood readers with data, as the
+  stream automatically regulates data flow to prevent overload.


Suggested change

- **Supports backpressure**: Eager writers cannot flood readers with data, as the

stream automatically regulates data flow to prevent overload.

- **Supports backpressure**: Eager writers cannot flood readers with data, as the

stream automatically regulates data flow to prevent overload.

Not by default, if TCP + mplex is used, there's no support for backpressure. I think this existed in the legacy document but it should be deleted

p-shahi · 2023-02-02T19:15:39Z

content/concepts/introduction/protocols/overview.md

+### Handler functions
+
+A handler function handles each libp2p protocol, responsible
+for defining the protocol's behavior once the stream has been established.
+The handler function is invoked when an incoming stream is received with a
+registered protocol ID.
+
+The handler function can also specify a match function,
+which allows for the acceptance of non-exact string matches for protocol IDs.
+
+A libp2p application will define a stream handler that takes over the
+stream after protocol negotiation. Everything is sent and received after the
+application protocol defines the negotiation phase.


Suggested change

### Handler functions

A handler function handles each libp2p protocol, responsible

for defining the protocol's behavior once the stream has been established.

The handler function is invoked when an incoming stream is received with a

registered protocol ID.

The handler function can also specify a match function,

which allows for the acceptance of non-exact string matches for protocol IDs.

A libp2p application will define a stream handler that takes over the

stream after protocol negotiation. Everything is sent and received after the

application protocol defines the negotiation phase.

This whole section should be deleted imo. This page starts at a very high level and then dives right into handler functions in a jarring transition. I don't see the usefulness of explaining this concept here anyways.

p-shahi · 2023-02-02T19:28:43Z

content/concepts/introduction/protocols/overview.md

+The medium over which a protocol operates is a bi-directional
+binary stream. This stream provides the following features:


Suggested change

The medium over which a protocol operates is a bi-directional

binary stream. This stream provides the following features:

libp2p is built on top of a stream abstraction.

A stream is a concept in computer science where over time data becomes available between two or more computers/nodes.

p-shahi · 2023-02-02T19:31:23Z

content/concepts/introduction/protocols/overview.md

+The medium over which a protocol operates is a bi-directional
+binary stream. This stream provides the following features:
+
+- **Bidirectional, reliable delivery of binary data**: Both peers can read and write


Suggested change

- **Bidirectional, reliable delivery of binary data**: Both peers can read and write

The primary benefit provided to libp2p protocols by the stream abstraction is:

**Bidirectionality and reliable delivery of binary data**: Both peers can read and write

p-shahi · 2023-02-02T19:31:48Z

content/concepts/introduction/protocols/overview.md

+Behind the scenes, libp2p also ensures that the stream is securely encrypted and
+efficiently multiplexed, allowing multiple logical streams to be multiplexed over


Suggested change

Behind the scenes, libp2p also ensures that the stream is securely encrypted and

efficiently multiplexed, allowing multiple logical streams to be multiplexed over

Behind the scenes, libp2p also ensures that the stream is securely encrypted and

efficiently multiplexed, allowing multiple logical streams to be multiplexed over

link to secure channel and muxer docs?

p-shahi · 2023-02-02T19:33:19Z

content/concepts/introduction/protocols/overview.md

+## Life cycle of a stream
+
+The life cycle of a libp2p stream involves the following steps:
+
+- **Dialing out**: When a peer wants to initiate a new stream with another peer,
+  it sends the protocol ID of the protocol it wants to use over the connection.
+- **Protocol negotiation**: The listening peer on the other end checks the incoming
+  protocol ID against its list of registered protocol handlers. Suppose it does not
+  support the requested protocol. In that case, it sends "na" (not available) on the stream.
+  The dialing peer can try again with a different protocol or a fallback
+  version of the initially requested protocol. If the protocol is supported, the
+  listening peer echoes the protocol ID as a signal that future data sent over
+  the stream will use the agreed-upon protocol semantics.
+- **Stream establishment**: Once peers agree on the protocol ID, the stream is
+  established, and the designated invokes the handler function to take over the stream.
+  Everything sent and received over the stream from this point on is defined by the
+  application-level protocol.
+- **Stream closure**: When either peer finishes using the stream, it can be closed
+  by either side. If the stream is half-closed, the other side can continue to read
+  or write until it is closed.


Suggested change

## Life cycle of a stream

The life cycle of a libp2p stream involves the following steps:

- **Dialing out**: When a peer wants to initiate a new stream with another peer,

it sends the protocol ID of the protocol it wants to use over the connection.

- **Protocol negotiation**: The listening peer on the other end checks the incoming

protocol ID against its list of registered protocol handlers. Suppose it does not

support the requested protocol. In that case, it sends "na" (not available) on the stream.

The dialing peer can try again with a different protocol or a fallback

version of the initially requested protocol. If the protocol is supported, the

listening peer echoes the protocol ID as a signal that future data sent over

the stream will use the agreed-upon protocol semantics.

- **Stream establishment**: Once peers agree on the protocol ID, the stream is

established, and the designated invokes the handler function to take over the stream.

Everything sent and received over the stream from this point on is defined by the

application-level protocol.

- **Stream closure**: When either peer finishes using the stream, it can be closed

by either side. If the stream is half-closed, the other side can continue to read

or write until it is closed.

I would move this to the stream multiplexing document in a stream overview subsection
Is the protocols overview a good place for this?

p-shahi · 2023-02-23T18:58:50Z

Will reopen after some changes

revamp protocol overview

2dbc5fe

salmad3 added the ready for review PR is ready for review label Jan 9, 2023

salmad3 requested review from marten-seemann and p-shahi January 10, 2023 08:50

p-shahi reviewed Jan 12, 2023

View reviewed changes

salmad3 added 2 commits January 12, 2023 12:05

incorporate PR feedback - tweaks

98d56e5

edits

6264fb5

salmad3 requested a review from p-shahi January 12, 2023 17:21

salmad3 added the P1 High label Jan 26, 2023

p-shahi reviewed Feb 2, 2023

View reviewed changes

salmad3 added change request PR requires changes. and removed ready for review PR is ready for review labels Feb 2, 2023

p-shahi closed this Feb 23, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

update: protocols overview #287

update: protocols overview #287

Uh oh!

salmad3 commented Jan 9, 2023 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

p-shahi Jan 12, 2023

Uh oh!

salmad3 Jan 12, 2023

Uh oh!

p-shahi left a comment

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi Feb 2, 2023

Uh oh!

p-shahi commented Feb 23, 2023

Uh oh!

Uh oh!

		- Supports backpressure: Eager writers cannot flood readers with data, as the
		stream automatically regulates data flow to prevent overload.

		The medium over which a protocol operates is a bi-directional
		binary stream. This stream provides the following features:

	- Bidirectional, reliable delivery of binary data: Both peers can read and write
	The primary benefit provided to libp2p protocols by the stream abstraction is:
	Bidirectionality and reliable delivery of binary data: Both peers can read and write

		Behind the scenes, libp2p also ensures that the stream is securely encrypted and
		efficiently multiplexed, allowing multiple logical streams to be multiplexed over

update: protocols overview #287

update: protocols overview #287

Uh oh!

Conversation

salmad3 commented Jan 9, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Latest preview

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

p-shahi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

p-shahi commented Feb 23, 2023

Uh oh!

Uh oh!

salmad3 commented Jan 9, 2023 •

edited

Loading