Skip to content
GitHub no longer supports this web browser. Learn more about the browsers we support.
A decentralized P2P networking stack written in Go.
Go Makefile
Branch: master
Clone or download
iwasaki-kenta gossip: initial impl of gossip package (#272)
kademlia: adjust comments
mod: add dependency for VictoriaMetrics/fastcache for gossiping
Latest commit dcd80aa Feb 4, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github all: reboot noise (#266) Jan 29, 2020
cmd kademlia/events, kademlia/protocol, cmd/chat, examples: allow for cal… Jan 30, 2020
gossip gossip: initial impl of gossip package (#272) Feb 4, 2020
kademlia gossip: initial impl of gossip package (#272) Feb 4, 2020
.codecov.yml cmd/chat: cleanup chat example Jan 30, 2020
.gitignore all: reboot noise (#266) Jan 29, 2020
LICENSE all: reboot noise (#266) Jan 29, 2020
Makefile all: reboot noise (#266) Jan 29, 2020
README.md node, node/opts, error, client, conn, readme: implement option to set… Feb 1, 2020
addr.go all: reboot noise (#266) Jan 29, 2020
aead.go all: reboot noise (#266) Jan 29, 2020
client.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020
codec.go all: reboot noise (#266) Jan 29, 2020
codec_test.go all: reboot noise (#266) Jan 29, 2020
conn.go node, node/opts, error, client, conn, readme: implement option to set… Feb 1, 2020
ecdh.go all: reboot noise (#266) Jan 29, 2020
error.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020
example_codec_messaging_test.go client, map, node/opts/test, mod: tidy up and fix ineffassign and typo Jan 29, 2020
example_codec_rpc_test.go all: reboot noise (#266) Jan 29, 2020
example_discovery_test.go kademlia/events, kademlia/protocol, cmd/chat, examples: allow for cal… Jan 30, 2020
example_messaging_test.go all: reboot noise (#266) Jan 29, 2020
example_rpc_test.go all: reboot noise (#266) Jan 29, 2020
go.mod gossip: initial impl of gossip package (#272) Feb 4, 2020
go.sum gossip: initial impl of gossip package (#272) Feb 4, 2020
id.go id: fix String() and add tests for edge cases while unmarshaling byte… Jan 29, 2020
id_test.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020
keys.go client: if an idle timeout of 0 is specified, do not start the idle t… Jan 29, 2020
map.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020
mod.go kademlia/events, kademlia/protocol, cmd/chat, examples: allow for cal… Jan 30, 2020
mod_test.go all: reboot noise (#266) Jan 29, 2020
msg.go client: silence logger errors if connection was gracefully closed Jan 30, 2020
node.go node, node/opts, error, client, conn, readme: implement option to set… Feb 1, 2020
node_options.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020
node_options_test.go node, node/opts, error, client, conn, readme: implement option to set… Feb 1, 2020
node_test.go requests, client, conn: close all rpc signal channels if handler goro… Feb 1, 2020

README.md

noise

GoDoc Discord MIT licensed Build Status Go Report Card Coverage Status

noise is an opinionated, easy-to-use P2P network stack for decentralized applications, and cryptographic protocols written in Go.

noise is made to be minimal, robust, developer-friendly, performant, secure, and cross-platform across multitudes of devices by making use of a small amount of well-tested, production-grade dependencies.

Features

  • Listen for incoming peers, query peers, and ping peers.
  • Request for/respond to messages, fire-and-forget messages, and optionally automatically serialize/deserialize messages across peers.
  • Optionally cancel/timeout pinging peers, sending messages to peers, receiving messages from peers, or requesting messages from peers via context support.
  • Fine-grained control over a node and peers lifecycle and goroutines and resources (synchronously/asynchronously/gracefully start listening for new peers, stop listening for new peers, send messages to a peer, disconnect an existing peer, wait for a peer to be ready, wait for a peer to have disconnected).
  • Limit resource consumption by pooling connections and specifying the max number of inbound/outbound connections allowed at any given time.
  • Reclaim resources exhaustively by timing out idle peers with a configurable timeout.
  • Establish a shared secret by performing an Elliptic-Curve Diffie-Hellman Handshake over Curve25519.
  • Establish an encrypted session amongst a pair of peers via authenticated-encryption-with-associated-data (AEAD). Built-in support for AES 256-bit Galois Counter Mode (GCM).
  • Peer-to-peer routing, discovery, identities, and handshake protocol via Kademlia overlay network protocol.

Defaults

  • No logs are printed by default. Set a logger via noise.WithNodeLogger(*zap.Logger).
  • A random Ed25519 key pair is generated for a new node.
  • Peers attempt to be dialed at most three times.
  • A total of 128 outbound connections are allowed at any time.
  • A total of 128 inbound connections are allowed at any time.
  • Peers may send in a single message, at most, 2MB worth of data.
  • Connections timeout after 10 seconds if no reads/writes occur.

Dependencies

Setup

noise was intended to be used in Go projects that utilize Go modules. You may incorporate noise into your project as a library dependency by executing the following:

% go get -u github.com/perlin-network/noise

Example

package main

import (
    "context"
    "fmt"
    "github.com/perlin-network/noise"
)

func check(err error) {
    if err != nil {
        panic(err)
    }
}

// This example demonstrates how to send/handle RPC requests across peers, how to listen for incoming
// peers, how to check if a message received is a request or not, how to reply to a RPC request, and
// how to cleanup node instances after you are done using them.
func main() { 
    // Let there be nodes Alice and Bob.

    alice, err := noise.NewNode()
    check(err)

    bob, err := noise.NewNode()
    check(err)

    // Gracefully release resources for Alice and Bob at the end of the example.

    defer alice.Close()
    defer bob.Close()

    // When Bob gets a message from Alice, print it out and respond to Alice with 'Hi Alice!'

    bob.Handle(func(ctx noise.HandlerContext) error {
        if !ctx.IsRequest() {
            return nil
        }

        fmt.Printf("Got a message from Alice: '%s'\n", string(ctx.Data()))

        return ctx.Send([]byte("Hi Alice!"))
    })

    // Have Alice and Bob start listening for new peers.

    check(alice.Listen())
    check(bob.Listen())

    // Have Alice send Bob a request with the message 'Hi Bob!'

    res, err := alice.Request(context.TODO(), bob.Addr(), []byte("Hi Bob!"))
    check(err)

    // Print out the response Bob got from Alice.

    fmt.Printf("Got a message from Bob: '%s'\n", string(res))

    // Output:
    // Got a message from Alice: 'Hi Bob!'
    // Got a message from Bob: 'Hi Alice!'
}

For documentation and more examples, refer to noise's godoc here.

Benchmarks

Benchmarks measure CPU time and allocations of a single node sending messages, requests, and responses to/from itself over 8 logical cores on a loopback adapter.

Take these benchmark numbers with a grain of salt.

% cat /proc/cpuinfo | grep 'model name' | uniq
model name : Intel(R) Core(TM) i7-7700HQ CPU @ 2.80GHz

% go test -bench=. -benchtime=30s -benchmem
goos: linux
goarch: amd64
pkg: github.com/perlin-network/noise
BenchmarkRPC-8           2978550             14136 ns/op            1129 B/op         27 allocs/op
BenchmarkSend-8          9239581              4546 ns/op             503 B/op         12 allocs/op
PASS
ok      github.com/perlin-network/noise 101.966s

Versioning

noise is currently in its initial development phase and therefore does not promise that subsequent releases will not comprise of breaking changes. Be aware of this should you choose to utilize Noise for projects that are in production.

Releases are marked with a version number formatted as MAJOR.MINOR.PATCH. Major breaking changes involve a bump in MAJOR, minor backward-compatible changes involve a bump in MINOR, and patches and bug fixes involve a bump in PATCH starting from v2.0.0.

Therefore, noise mostly respects semantic versioning.

The rationale behind this is due to improper tagging of prior releases (v0.1.0, v1.0.0, v1.1.0, and v1.1.1), which has caused for the improper caching of module information on proxy.golang.org and sum.golang.org.

As a result, noise's initial development phase starts from v1.1.2. Until Noise's API is stable, subsequent releases will only comprise of bumps in MINOR and PATCH.

License

noise, and all of its source code is released under the MIT License.

You can’t perform that action at this time.