Skip to content

Commit

Permalink
chore: deprecate the pubsub api
Browse files Browse the repository at this point in the history
  • Loading branch information
Jorropo committed Mar 13, 2023
1 parent 676e557 commit 015f70e
Show file tree
Hide file tree
Showing 6 changed files with 19 additions and 136 deletions.
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion cmd/ipfs/daemon.go
Original file line number Diff line number Diff line change
Expand Up @@ -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."),
Expand Down
20 changes: 10 additions & 10 deletions core/commands/pubsub.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -273,15 +273,15 @@ 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: `
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
Expand Down
7 changes: 7 additions & 0 deletions docs/changelogs/v0.19.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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
92 changes: 0 additions & 92 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
31 changes: 0 additions & 31 deletions docs/experimental-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand Down

0 comments on commit 015f70e

Please sign in to comment.