🛰 go-p2p-message-bus

Idiomatic Go P2P messaging library with auto-discovery, NAT traversal, and channel-based pub/sub

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

• What's Inside?
• Quick Start
• Installation
• Documentation
• How It Works
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

🧩 What's Inside?

Features

• Simple API: Create a client, subscribe to topics, and publish messages with minimal code
• Channel-based: Receive messages through Go channels for idiomatic concurrent programming
• Auto-discovery: Automatic peer discovery via DHT, mDNS, and peer caching
• NAT traversal: Built-in support for hole punching and relay connections
• Persistent peers: Automatically caches and reconnects to known peers

🚀 Quick Start

Get started in 60 seconds

package main

import (
    "fmt"
    "log"

    "github.com/bsv-blockchain/go-p2p-message-bus"
)

func main() {
    // Generate a private key (do this once and save it)
    keyHex, err := p2p.GeneratePrivateKeyHex()
    if err != nil {
        log.Fatal(err)
    }
    // In production, save keyHex to config file, env var, or database

    // Create a P2P client
    client, err := p2p.NewPeer(p2p.Config{
        Name:          "my-node",
        PrivateKeyHex: keyHex,
    })
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Subscribe to a topic
    msgChan := client.Subscribe("my-topic")

    // Receive messages
    go func() {
        for msg := range msgChan {
            fmt.Printf("Received from %s: %s\n", msg.From, string(msg.Data))
        }
    }()

    // Publish a message
    if err := client.Publish("my-topic", []byte("Hello, P2P!")); err != nil {
        log.Printf("Error publishing: %v", err)
    }

    // Get connected peers
    peers := client.GetPeers()
    for _, peer := range peers {
        fmt.Printf("Peer: %s [%s]\n", peer.Name, peer.ID)
    }

    select {} // Wait forever
}

📦 Installation

go-p2p-message-bus requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-p2p-message-bus

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/go-p2p-message-bus
• Usage Examples – Browse practical patterns either the examples directory or the example tests
• Benchmarks – Check the latest numbers in the benchmark results
• Test Suite – Review both the unit tests and fuzz tests (powered by testify)

API Reference

Config

type Config struct {
    Name           string         // Required: identifier for this peer
    BootstrapPeers []string       // Optional: initial peers to connect to
    Logger         Logger         // Optional: custom logger (uses DefaultLogger if not provided)
    PrivateKey     crypto.PrivKey // Required: private key for persistent peer ID
    PeerCacheFile  string         // Optional: file path for peer persistence
    AnnounceAddrs  []string       // Optional: addresses to advertise to peers (for K8s)
}

Logger Interface:

The library defines a Logger interface and provides a DefaultLogger implementation:

type Logger interface {
    Debugf(format string, v ...any)
    Infof(format string, v ...any)
    Warnf(format string, v ...any)
    Errorf(format string, v ...any)
}

// DefaultLogger is provided out of the box
logger := &p2p.DefaultLogger{}

// Or use your own custom logger that implements the interface

Persistent Peer Identity:

The PrivateKeyHex field is required to ensure consistent peer IDs across restarts:

// Generate a new key for first-time setup
keyHex, err := p2p.GeneratePrivateKeyHex()
if err != nil {
    log.Fatal(err)
}
// Save keyHex somewhere (env var, config file, database, etc.)

// Create client with the saved key
client, err := p2p.NewPeer(p2p.Config{
    Name:          "node1",
    PrivateKeyHex: keyHex,
})

// You can also retrieve the key from an existing client
retrievedKey, _ := client.GetPrivateKeyHex()

Peer Persistence:

The PeerCacheFile field is optional and enables peer persistence for faster reconnection:

client, err := p2p.NewPeer(p2p.Config{
    Name:          "node1",
    PrivateKey:    privKey,
    PeerCacheFile: "peers.json", // Enable peer caching
})

When enabled:

• Connected peers are automatically saved to the specified file
• On restart, the client will reconnect to previously known peers
• This significantly speeds up network reconnection
• If not provided, peer caching is disabled

Kubernetes Support:

The AnnounceAddrs field allows you to specify the external addresses that your peer should advertise. This is essential in Kubernetes where the pod's internal IP differs from the externally accessible address:

// Get external address from environment or K8s service
externalIP := os.Getenv("EXTERNAL_IP")      // e.g., "203.0.113.1"
externalPort := os.Getenv("EXTERNAL_PORT")  // e.g., "30001"

client, err := p2p.NewPeer(p2p.Config{
    Name:       "node1",
    PrivateKey: privKey,
    AnnounceAddrs: []string{
        fmt.Sprintf("/ip4/%s/tcp/%s", externalIP, externalPort),
    },
})

Common Kubernetes scenarios:

• LoadBalancer Service: Use the external IP of the LoadBalancer
• NodePort Service: Use the node's external IP and the NodePort
• Ingress with TCP: Use the ingress external IP and configured port

Without AnnounceAddrs, libp2p will announce the pod's internal IP, which won't be reachable from outside the cluster.

Client Methods

GeneratePrivateKeyHex

func GeneratePrivateKeyHex() (string, error)

Generates a new Ed25519 private key and returns it as a hex string. Use this function to create a new key for Config.PrivateKeyHex when setting up a new peer for the first time.

NewPeer

func NewPeer(config Config) (*Client, error)

Creates and starts a new P2P client. The client automatically:

• Creates a libp2p host with NAT traversal support
• Bootstraps to the DHT network
• Starts peer discovery (DHT + mDNS)
• Connects to cached peers from previous sessions

Note: Requires Config.PrivateKeyHex to be set. Use GeneratePrivateKeyHex() to create a new key.

Subscribe

func (c *Client) Subscribe(topic string) <-chan Message

Subscribes to a topic and returns a channel that receives messages. The channel is closed when the client is closed.

Publish

func (c *Client) Publish(topic string, data []byte) error

Publishes a message to a topic. The message is broadcast to all peers subscribed to the topic.

GetPeers

func (c *Client) GetPeers() []PeerInfo

Returns information about all known peers on subscribed topics.

GetID

func (c *Client) GetID() string

Returns this peer's ID as a string.

GetPrivateKeyHex

func (c *Client) GetPrivateKeyHex() (string, error)

Returns the hex-encoded private key for this peer. This can be saved and used in Config.PrivateKey to maintain the same peer ID across restarts.

Close

func (c *Client) Close() error

Shuts down the client and releases all resources.

Data Types

Message

type Message struct {
    Topic     string    // Topic this message was received on
    From      string    // Sender's name
    FromID    string    // Sender's peer ID
    Data      []byte    // Message payload
    Timestamp time.Time // When the message was received
}

PeerInfo

type PeerInfo struct {
    ID    string   // Peer ID
    Name  string   // Peer name (if known)
    Addrs []string // Peer addresses
}

Development Build Commands

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

View all build commands

magex help

Repository Features

• Continuous Integration on Autopilot with GitHub Actions – every push is built, tested, and reported in minutes.
• Pull‑Request Flow That Merges Itself thanks to auto‑merge and hands‑free Dependabot auto‑merge.
• One‑Command Builds powered by battle‑tested MAGE-X targets for linting, testing, releases, and more.
• First‑Class Dependency Management using native Go Modules.
• Uniform Code Style via gofumpt plus zero‑noise linting with golangci‑lint.
• Confidence‑Boosting Tests with testify, the Go race detector, crystal‑clear HTML coverage snapshots, and automatic uploads to Codecov.
• Hands‑Free Releases delivered by GoReleaser whenever you create a new Tag.
• Relentless Dependency & Vulnerability Scans via Dependabot, Nancy and govulncheck.
• Security Posture by Default with CodeQL, OpenSSF Scorecard and secret‑leak detection via gitleaks.
• Automatic Syndication to pkg.go.dev on every release for instant godoc visibility.
• Polished Community Experience using rich templates for Issues & PRs.
• All the Right Meta Files (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, SECURITY.md) pre‑filled and ready.
• Code Ownership clarified through a CODEOWNERS file, keeping reviews fast and focused.
• Zero‑Noise Dev Environments with tuned editor settings (.editorconfig) plus curated ignore files for VS Code, Docker, and Git.
• Label Sync Magic: your repo labels stay in lock‑step with .github/labels.yml.
• Friendly First PR Workflow – newcomers get a warm welcome thanks to a dedicated workflow.
• Standards‑Compliant Docs adhering to the standard‑readme spec.
• Instant Cloud Workspaces via Gitpod – spin up a fully configured dev environment with automatic linting and tests.
• Out‑of‑the‑Box VS Code Happiness with a preconfigured Go workspace and .vscode folder with all the right settings.
• Optional Release Broadcasts to your community via Slack, Discord, or Twitter – plug in your webhook.
• AI Compliance Playbook – machine‑readable guidelines (AGENTS.md, CLAUDE.md, .cursorrules, sweep.yaml) keep ChatGPT, Claude, Cursor & Sweep aligned with your repo's rules.
• Go-Pre-commit System - High-performance Go-native pre-commit hooks with 17x faster execution—run the same formatting, linting, and tests before every commit, just like CI.
• Zero Python Dependencies - Pure Go implementation with environment-based configuration via .env.base.
• DevContainers for Instant Onboarding – Launch a ready-to-code environment in seconds with VS Code DevContainers and the included .devcontainer.json config.

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=main

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via .env.base and can be customized using also using .env.custom and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a single configuration files – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

• .env.base – Default configuration that works for most Go projects
• .env.custom – Optional project-specific overrides

This magical file controls everything from:

• ⚙️ Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🔧 How It Works

Peer Discovery, NAT Traversal, and Message Routing

Peer Discovery

The library uses multiple discovery mechanisms:

• DHT: Connects to IPFS bootstrap peers and advertises topics on the distributed hash table
• mDNS: Discovers peers on the local network
• Peer Cache: Persists peer information to disk for faster reconnection across restarts

NAT Traversal

Automatically handles NAT traversal through:

• Hole Punching: Attempts direct connections between NAT'd peers
• Relay: Falls back to relay connections when direct connections fail
• UPnP/NAT-PMP: Automatically configures port forwarding when possible

Message Routing

Uses GossipSub for efficient topic-based message propagation:

• Messages are distributed using an optimized gossip protocol
• Reduces bandwidth while maintaining reliability
• Automatically handles peer mesh management and scoring

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

Running the Example

See example/main.go for a complete working example.

To run the example:

cd example
go run main.go -name "node1"

In another terminal:

cd example
go run main.go -name "node2"

The two nodes will discover each other and exchange messages.

⚡ Benchmarks

Run the Go benchmarks:

magex bench

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers

MrZ	Siggi

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬.

📝 License