Extending the server

This section shows you how to add your own behaviour around a go-ricochet server: carry your app’s GossipSub traffic, serve a new request/response protocol, or run background work next to the server.

“Extending” here means one of three things you can do today. None of them is a plugin. The server is a fixed set of agents (MSA, MAA, MMA, SDA, SFA, SCA) wired together in one place, and you either use its configuration, change its source, or run your own process beside it.

Note

go-ricochet 1.1.0 has no embedding or plugin API. The server lives in internal/server, and Go does not let another module import an internal/ package. The only public packages are pkg/client and pkg/wire. You can’t import the server, register a handler on it, or get at its libp2p host from your own module.

The three options

	Relay a topic	Fork and add a protocol	Run a companion node
What you can change	Which GossipSub topics the server forwards. Nothing else.	Anything: new protocols, new storage tables, changes to existing agents.	Anything in your own process. Nothing inside the server.
Code you write	None. One config key.	A new package under internal/protocol/, a registration line, tests.	A small go-p2p-forge server.
What you get for free	The server’s position in the mesh.	The server’s identity, PostgreSQL storage, access log, metrics, rate limits, admission control and drain.	Forge’s pipeline, framing, DHT and GossipSub. You build the rest.
Upgrade burden	None.	You rebase on every go-ricochet release.	None on the server side. You upgrade forge on your own schedule.
Runs as	Part of the server.	Your build of the server, in place of the official one.	A second process with its own peer ID.
Suits	Apps whose peers reach each other only through your server.	Operators who need something that must live inside the server, such as a query over its own tables.	Most new services: anything that only needs to be reachable on the same network.

Relay a topic

If your app’s peers already talk over GossipSub and the only problem is that they meet through your Ricochet server, you don’t need code. List the topic under pubsub.relay_topics and the server joins the topic’s mesh and forwards its messages without subscribing to them. See Relayed GossipSub topics.

Fork and add a protocol

go-ricochet is assembled from go-p2p-forge parts: each agent is a forge pipeline built from the same middleware, and handlers reach storage through forge’s registry. A new protocol in a fork is a new package that composes that middleware the same way, plus one registration in registerProtocolHandlers(). You get the server’s identity, storage and operational behaviour without writing any of it. In exchange you maintain a fork.

• Built on go-p2p-forge explains how the server is put together.
• Add a protocol (fork) walks through adding one.

Run a companion node

A companion node is your own forge server running as a separate libp2p peer, usually on the same host as Ricochet. It has its own peer ID, its own protocols and its own storage. Clients reach it the way they reach any peer, and it can share GossipSub topics with the server, using relay_topics on the Ricochet side if its peers connect only through Ricochet.

• Run a companion node builds one.

Choosing

Start with the cheapest option that works:

1. If peers only need to hear each other on a topic, relay the topic.
2. If your feature needs its own requests, storage or schedule but not the server’s database, run a companion node. It costs a second process and a second peer ID, and you never have to rebase.
3. Fork only when the feature has to run inside the server: it reads or writes go-ricochet’s own tables, must be authorized against the same mailboxes and documents, or must answer on the server’s peer ID.