From 015f70e3d686899dce35e6e28279e709f857d2f5 Mon Sep 17 00:00:00 2001 From: Jorropo Date: Mon, 13 Mar 2023 16:30:33 +0100 Subject: [PATCH] chore: deprecate the pubsub api --- README.md | 3 +- cmd/ipfs/daemon.go | 2 +- core/commands/pubsub.go | 20 ++++---- docs/changelogs/v0.19.md | 7 +++ docs/config.md | 92 ----------------------------------- docs/experimental-features.md | 31 ------------ 6 files changed, 19 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index e734fef6642e..94e5e42af15a 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Kubo was the first IPFS implementation and is the most widely used one today. Im Featureset - Runs an IPFS-Node as a network service - [Command Line Interface](https://docs.ipfs.tech/reference/kubo/cli/) to IPFS-Nodes -- Local [Web2-to-Web3 HTTP Gateway functionality](https://github.com/ipfs/specs/tree/main/http-gateways#readme) +- Local [Web2-to-Web3 HTTP Gateway functionality](https://github.com/ipfs/specs/tree/main/http-gateways#readme) - HTTP RPC API (`/api/v0`) to access and control the daemon - IPFS's internal Webgui can be used to manage the Kubo nodes @@ -381,7 +381,6 @@ Some places to get you started on the codebase: - libp2p - libp2p: https://github.com/libp2p/go-libp2p - DHT: https://github.com/libp2p/go-libp2p-kad-dht - - PubSub: https://github.com/libp2p/go-libp2p-pubsub - [IPFS : The `Add` command demystified](https://github.com/ipfs/kubo/tree/master/docs/add-code-flow.md) ### Map of Implemented Subsystems diff --git a/cmd/ipfs/daemon.go b/cmd/ipfs/daemon.go index 880d26b0e425..52addcc072ce 100644 --- a/cmd/ipfs/daemon.go +++ b/cmd/ipfs/daemon.go @@ -171,7 +171,7 @@ Headers. cmds.BoolOption(enableGCKwd, "Enable automatic periodic repo garbage collection"), cmds.BoolOption(adjustFDLimitKwd, "Check and raise file descriptor limits if needed").WithDefault(true), cmds.BoolOption(migrateKwd, "If true, assume yes at the migrate prompt. If false, assume no."), - cmds.BoolOption(enablePubSubKwd, "Enable experimental pubsub feature. Overrides Pubsub.Enabled config."), + cmds.BoolOption(enablePubSubKwd, "DEPRECATED"), cmds.BoolOption(enableIPNSPubSubKwd, "Enable IPNS over pubsub. Implicitly enables pubsub, overrides Ipns.UsePubsub config."), cmds.BoolOption(enableMultiplexKwd, "DEPRECATED"), cmds.StringOption(agentVersionSuffix, "Optional suffix to the AgentVersion presented by `ipfs id` and also advertised through BitSwap."), diff --git a/core/commands/pubsub.go b/core/commands/pubsub.go index ef8afcb4458c..ee795e07829b 100644 --- a/core/commands/pubsub.go +++ b/core/commands/pubsub.go @@ -16,14 +16,14 @@ import ( ) var PubsubCmd = &cmds.Command{ - Status: cmds.Experimental, + Status: cmds.Deprecated, Helptext: cmds.HelpText{ Tagline: "An experimental publish-subscribe system on ipfs.", ShortDescription: ` ipfs pubsub allows you to publish messages to a given topic, and also to subscribe to new messages on a given topic. -EXPERIMENTAL FEATURE +DEPRECATED FEATURE (see https://github.com/ipfs/kubo/issues/9717) It is not intended in its current state to be used in a production environment. To use, the daemon must be run with @@ -46,13 +46,13 @@ type pubsubMessage struct { } var PubsubSubCmd = &cmds.Command{ - Status: cmds.Experimental, + Status: cmds.Deprecated, Helptext: cmds.HelpText{ Tagline: "Subscribe to messages on a given topic.", ShortDescription: ` ipfs pubsub sub subscribes to messages on a given topic. -EXPERIMENTAL FEATURE +DEPRECATED FEATURE (see https://github.com/ipfs/kubo/issues/9717) It is not intended in its current state to be used in a production environment. To use, the daemon must be run with @@ -145,14 +145,14 @@ TOPIC AND DATA ENCODING } var PubsubPubCmd = &cmds.Command{ - Status: cmds.Experimental, + Status: cmds.Deprecated, Helptext: cmds.HelpText{ Tagline: "Publish data to a given pubsub topic.", ShortDescription: ` ipfs pubsub pub publishes a message to a specified topic. It reads binary data from stdin or a file. -EXPERIMENTAL FEATURE +DEPRECATED FEATURE (see https://github.com/ipfs/kubo/issues/9717) It is not intended in its current state to be used in a production environment. To use, the daemon must be run with @@ -201,13 +201,13 @@ HTTP RPC ENCODING } var PubsubLsCmd = &cmds.Command{ - Status: cmds.Experimental, + Status: cmds.Deprecated, Helptext: cmds.HelpText{ Tagline: "List subscribed topics by name.", ShortDescription: ` ipfs pubsub ls lists out the names of topics you are currently subscribed to. -EXPERIMENTAL FEATURE +DEPRECATED FEATURE (see https://github.com/ipfs/kubo/issues/9717) It is not intended in its current state to be used in a production environment. To use, the daemon must be run with @@ -273,7 +273,7 @@ func safeTextListEncoder(req *cmds.Request, w io.Writer, list *stringList) error } var PubsubPeersCmd = &cmds.Command{ - Status: cmds.Experimental, + Status: cmds.Deprecated, Helptext: cmds.HelpText{ Tagline: "List peers we are currently pubsubbing with.", ShortDescription: ` @@ -281,7 +281,7 @@ ipfs pubsub peers with no arguments lists out the pubsub peers you are currently connected to. If given a topic, it will list connected peers who are subscribed to the named topic. -EXPERIMENTAL FEATURE +DEPRECATED FEATURE (see https://github.com/ipfs/kubo/issues/9717) It is not intended in its current state to be used in a production environment. To use, the daemon must be run with diff --git a/docs/changelogs/v0.19.md b/docs/changelogs/v0.19.md index fede7a4547f4..b7e94e22b622 100644 --- a/docs/changelogs/v0.19.md +++ b/docs/changelogs/v0.19.md @@ -8,6 +8,7 @@ - [๐Ÿ”ฆ Highlights](#-highlights) - [Improving the libp2p resource management integration](#improving-the-libp2p-resource-management-integration) - [Addition of "autoclient" router type](#addition-of-autoclient-router-type) + - [Deprecation of the `ipfs pubsub` commands and matching HTTP endpoints](#deprecation-of-the-ipfs-pubsub-commands-and-matching-http-endpoints) - [๐Ÿ“ Changelog](#-changelog) - [๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Contributors](#-contributors) @@ -28,6 +29,12 @@ A new routing type "autoclient" has been added. This mode is similar to "auto", See the [Routing.Type documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingtype) for more information. +#### Deprecation of the `ipfs pubsub` commands and matching HTTP endpoints + +We are deprecating `ipfs pubsub` and all `/api/v0/pubsub/` endpoints and will remove them in the next release. + +For more information and rational see [#9717](https://github.com/ipfs/kubo/issues/9717). + ### ๐Ÿ“ Changelog ### ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Contributors diff --git a/docs/config.md b/docs/config.md index 686661918024..d980810f696f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -95,12 +95,6 @@ config file at runtime. - [`Pinning.RemoteServices: Policies.MFS.Enabled`](#pinningremoteservices-policiesmfsenabled) - [`Pinning.RemoteServices: Policies.MFS.PinName`](#pinningremoteservices-policiesmfspinname) - [`Pinning.RemoteServices: Policies.MFS.RepinInterval`](#pinningremoteservices-policiesmfsrepininterval) - - [`Pubsub`](#pubsub) - - [`Pubsub.Enabled`](#pubsubenabled) - - [`Pubsub.Router`](#pubsubrouter) - - [`Pubsub.DisableSigning`](#pubsubdisablesigning) - - [`Pubsub.SeenMessagesTTL`](#pubsubseenmessagesttl) - - [`Pubsub.SeenMessagesStrategy`](#pubsubseenmessagesstrategy) - [`Peering`](#peering) - [`Peering.Peers`](#peeringpeers) - [`Reprovider`](#reprovider) @@ -1163,92 +1157,6 @@ Default: `"5m"` Type: `duration` -## `Pubsub` - -Pubsub configures the `ipfs pubsub` subsystem. To use, it must be enabled by -passing the `--enable-pubsub-experiment` flag to the daemon -or via the `Pubsub.Enabled` flag below. - -### `Pubsub.Enabled` - -**EXPERIMENTAL:** read about current limitations at [experimental-features.md#ipfs-pubsub](./experimental-features.md#ipfs-pubsub). - -Enables the pubsub system. - -Default: `false` - -Type: `flag` - -### `Pubsub.Router` - -Sets the default router used by pubsub to route messages to peers. This can be one of: - -* `"floodsub"` - floodsub is a basic router that simply _floods_ messages to all - connected peers. This router is extremely inefficient but _very_ reliable. -* `"gossipsub"` - [gossipsub][] is a more advanced routing algorithm that will - build an overlay mesh from a subset of the links in the network. - -Default: `"gossipsub"` - -Type: `string` (one of `"floodsub"`, `"gossipsub"`, or `""` (apply default)) - -[gossipsub]: https://github.com/libp2p/specs/tree/master/pubsub/gossipsub - -### `Pubsub.DisableSigning` - -Disables message signing and signature verification. Enable this option if -you're operating in a completely trusted network. - -It is _not_ safe to disable signing even if you don't care _who_ sent the -message because spoofed messages can be used to silence real messages by -intentionally re-using the real message's message ID. - -Default: `false` - -Type: `bool` - -### `Pubsub.SeenMessagesTTL` - -Controls the time window within which duplicate messages, identified by Message -ID, will be identified and won't be emitted again. - -A smaller value for this parameter means that Pubsub messages in the cache will -be garbage collected sooner, which can result in a smaller cache. At the same -time, if there are slower nodes in the network that forward older messages, -this can cause more duplicates to be propagated through the network. - -Conversely, a larger value for this parameter means that Pubsub messages in the -cache will be garbage collected later, which can result in a larger cache for -the same traffic pattern. However, it is less likely that duplicates will be -propagated through the network. - -Default: see `TimeCacheDuration` from [go-libp2p-pubsub](https://github.com/libp2p/go-libp2p-pubsub) - -Type: `optionalDuration` - -### `Pubsub.SeenMessagesStrategy` - -Determines how the time-to-live (TTL) countdown for deduplicating Pubsub -messages is calculated. - -The Pubsub seen messages cache is a LRU cache that keeps messages for up to a -specified time duration. After this duration has elapsed, expired messages will -be purged from the cache. - -The `last-seen` cache is a sliding-window cache. Every time a message is seen -again with the SeenMessagesTTL duration, its timestamp slides forward. This -keeps frequently occurring messages cached and prevents them from being -continually propagated, especially because of issues that might increase the -number of duplicate messages in the network. - -The `first-seen` cache will store new messages and purge them after the -SeenMessagesTTL duration, even if they are seen multiple times within this -duration. - -Default: `last-seen` (see [go-libp2p-pubsub](https://github.com/libp2p/go-libp2p-pubsub)) - -Type: `optionalString` - ## `Peering` Configures the peering subsystem. The peering subsystem configures Kubo to diff --git a/docs/experimental-features.md b/docs/experimental-features.md index 41e72f1df118..296f6ca1e79e 100644 --- a/docs/experimental-features.md +++ b/docs/experimental-features.md @@ -12,7 +12,6 @@ When you add a new experimental feature to kubo or change an experimental feature, you MUST please make a PR updating this document, and link the PR in the above issue. -- [ipfs pubsub](#ipfs-pubsub) - [Raw leaves for unixfs files](#raw-leaves-for-unixfs-files) - [ipfs filestore](#ipfs-filestore) - [ipfs urlstore](#ipfs-urlstore) @@ -31,36 +30,6 @@ the above issue. --- -## ipfs pubsub - -### State - -Candidate, disabled by default but will be enabled by default in 0.6.0. - -### In Version - -0.4.5 (`--enable-pubsub-experiment`) -0.11.0 (`Pubsub.Enabled` flag in config) - -### How to enable - -Run your daemon with the `--enable-pubsub-experiment` flag -or modify your ipfs config and restart the daemon: -``` -ipfs config --json Pubsub.Enabled true -``` - -Then use the `ipfs pubsub` commands. - -NOTE: `--enable-pubsub-experiment` CLI flag overrides `Pubsub.Enabled` config. - -Configuration documentation can be found in [kubo/docs/config.md](./config.md#pubsub) - -### Road to being a real feature - -- [ ] Needs to not impact peers who don't use pubsub: - https://github.com/libp2p/go-libp2p-pubsub/issues/332 - ## Raw Leaves for unixfs files Allows files to be added with no formatting in the leaf nodes of the graph.