Towards API stability

[thomaseizinger]

Libp2p is a modular networking library. One benefit of this modularity is that community members should be able to maintain their own transports. See the recent discussion in #2899 for an example.

Maintaining such crates out-of-tree is only really viable if we provide a commitment towards API stability. In my opinion, releasing a 1.0 should come with such a commitment.

Currently, there are many things in the works in rust-libp2p and breaking changes in certain interfaces like NetworkBehaviour are still frequent. Consequently, I'd like to focus this discussion on the Transport API.

Everything in libp2p is driven by a Transport, thus I think it makes sense to try and stabilize this API first. I believe it will take something like #2829 to pull this off.

Overall, the approach I'd take is:

1. Figure out, what the minimal set of functionality is that we need to expose for libp2p-swarm to work.
   • It would be great if APIs such as StreamMuxer would become an implementation detail of the libp2p-core API.
     • This may require moving StreamMuxer into a different crate.
   • Should there even be a single Transport trait? It is quite an OOP-influenced design¹. Perhaps this trait should be split into multiple smaller ones?
   • Focusing on the main consumer (Swarm) should give us a good indication on what libp2p-core should provide.
2. Design an API that is as close to this functionality as possible.
   • The current Transport API is pretty generic. It allows for "stacking" of Transports which makes it very flexible. However, at the same time, this makes it harder to provide more discoverable interfaces or implement functionality like Consider verifying expected PeerId as part of auth upgrades #2946.
   • An open question is how Transports like libp2p-deflate should be treated.

Footnotes

1. This isn't necessarily bad but I've found it useful in the past to split larger traits into more focused ones when it comes to optimising for modularity. ↩

[mxinden]

Maintaining such crates out-of-tree is only really viable if we provide a commitment towards API stability.

In my eyes it is viable to maintain a Transport implementation outside of the rust-libp2p monorepository without an increased commitment towards API stability from our end.

Examples of things I maintain outside of this repository building on top of rust-libp2p:

• https://github.com/mxinden/kademlia-exporter
• https://github.com/mxinden/libp2p-lookup
• https://github.com/mxinden/rust-libp2p-server/

In my opinion, releasing a 1.0 should come with such a commitment.

For me a 1.0 is first and foremost a statement that this is production ready. API stability might be a byproduct of that.

I am in favor of releasing a 1.0. I am not in favor of increasing our commitment to API stability. In my eyes, as long as we provide easy upgrade paths, it is fine to do breaking changes, i.e. release 2.0, 3.0, 4.0 etc.

[thomaseizinger]

Examples of things I maintain outside of this repository building on top of rust-libp2p:

• https://github.com/mxinden/kademlia-exporter
• https://github.com/mxinden/libp2p-lookup
• https://github.com/mxinden/rust-libp2p-server/

That comparison isn't quite adequate because those are applications, not libraries and thus don't get released to crates.io themselves.

For a 3rd party Transport, our rate of breaking changes is really cumbersome because it adds an entire release cycle to another crate before you can update libp2p in your application (assuming you depend on both).

In my opinion, releasing a 1.0 should come with such a commitment.

For me a 1.0 is first and foremost a statement that this is production ready. API stability might be a byproduct of that.

I am aware that this part of the semver spec and I agree that it should have weight when we make the decision on when to release 1.0.

"Production readiness" however is just another way of saying "You can rely on this library". But relying on a library also means not creating excess amounts of churn in the form of release cycles.

I am in favor of releasing a 1.0. I am not in favor of increasing our commitment to API stability. In my eyes, as long as we provide easy upgrade paths, it is fine to do breaking changes, i.e. release 2.0, 3.0, 4.0 etc.

I don't think it is that simple. For applications, a version bump from 0.49 -> 0.50 might be no different than 1.0 -> 2.0 assuming an easy upgrade path.

The problem starts to arise once you have other libraries building on top of yours. Every major semver bump causes a cascade in bumps unless you wrap all types.

I am not saying we can never release a 2.0. I am just saying that I'd want us to be conscious of the churn that comes out of a major semver bump and thus avoid them for as long as possible once we decide to to 1.0.

[rkuhn]

Fully agreed! FWIW it takes me about half a day to upgrade and release all the intermediary libraries before I can upgrade Actyx — unless there are bigger changes involved or I skipped some versions. So while I do see good improvements currently bought by those breaking changes, it would be great to have some roadmap towards a stable core set of APIs (preferably after they have been outfitted with support for back-pressure 😉) upon which then a rich ecosystem of protocols can grow and evolve (→ protocol negotiation).

[thomaseizinger]

As I mentioned in #3225, I think we should start to consider, which breaking changes are worth introducing and optimise for shipping as many features as possible in patch releases. As several breaking changes pile up that we'd like to make, we can then plan for a release that includes several of them at once, thus reducing the churn for users that build libraries on top of rust-libp2p.

[thomaseizinger]

Yesterday, @mxinden and I discussed something that is relevant to this post. We talked about the idea of re-arranging the contents of our crates such that they only depend on the stuff they need and thus breaking changes to one part are less intrusive.

Most prominently, the idea was to separate NetworkBehaviour from libp2p-swarm. Protocols only need to depend on the NetworkBehaviour trait and should not be affected by the changes to Swarm, SwarmBuilder etc. The same thing goes for transports, they should only depend on the Transport interface and what is immediately related.

Whilst this doesn't change the number of breaking changes, it at least isolates them. For example, we are changing the NetworkBehaviour interface a lot less frequently than we do the API of Swarm. Similarly, Transport hasn't changed in a while but other parts in libp2p-core have.

[thomaseizinger]

In a forth step, we can now extract libp2p-muxer from libp2p-core which only needs to depend in libp2p-upgrade but nothing else. libp2p-yamux and libp2p-mplex can then be updated to remove the dependency on libp2p-core and replace it with libp2p-upgrade instead.

[thomaseizinger]

The modules remaining in libp2p-core after this are:

• identity
• peer_record
• signed_envelope
• peer_id

These are actually fairly entangled with each other and I think that is okay. We can look at libp2p-core being a set of primitive types for the libp2p ecosystem.

[thomaseizinger]

Hmm, perhaps identity should be split out into its own crate (including PeerId in it). Those types are used by several transports (noise, tls, quic, webrtc). Having those depend on libp2p_core again would defeat some of the purpose of this although at least libp2p_core is much smaller at that point and no longer contains stuff like StreamMuxer and other utility types.

[thomaseizinger]

In a similar fashion, we would then split NetworkBehaviour and ConnectionHandler out of libp2p-swarm into libp2p-behaviour. It would depend on:

• libp2p-upgrade: Obvious, protocols need to define how they can be upgraded.
• libp2p-core: For PeerId.
• libp2p-transport: For ListenerId until we fix Deprecate NetworkBehaviour listener callback methods #3040.

A few types are rather tricky:

• ConnectionId: Issued by the Pool (which is an implementation detail). It is part of the NetworkBehaviour interface so it should probably move into libp2p-behaviour.
• ConnectedPoint & TransportError: Force a dependency on libp2p-transport although NetworkBehaviours shouldn't really care which transport they run on and what their interface is. My initial thought is that libp2p-behaviour can define its own ConnectedPoint and libp2p-swarm simply has to map back and forth between the one from libp2p-transport and the one in libp2p-behaviour. TransportError we might be able to get rid of by boxing it or hiding it behind io::Error. The concrete error is already hidden within io::Error today and likely, a behaviour doesn't care about MultiaddressNotSupported.

[thomaseizinger]

Relevant post on rust-multiaddr: multiformats/rust-multiaddr#73

[Hedzer]

Go online, find a blog with an example, it doesn't work.

Do a search for libp2p, find an archived repo.

The documentation and example drift from the API changes makes it seem like libp2p doesn't work except for the few people developing it.

API stability would go a long way towards fixing that reputational damage.

[thomaseizinger]

YMMV but lots has improved since this discussion was opened!

Go online, find a blog with an example, it doesn't work.

If the blog doesn't use pinned versions of dependencies, then that is a pretty bad blog, regardless of which language or library you are using.

All our examples are CI tested so those always reflect the latest API :)

[Hedzer]

I just realized this is a 2 year old discussion 🤦.
Something missing from my previous statement is praise. Libp2p is a massive undertaking, and the dedication to keeping it alive is appreciated ❤️. It's easy to focus on the negatives. My previous experience was with the JavaScript versions, I'm going to try with Rust now. I suspect it'll much easier to catch drift there.