Libp2p - A modular network stack #

import peer "github.com/libp2p/go-libp2p-core/peer"

type Node struct {
    // PeerID returns the PeerID associated with this libp2p Node
    PeerID() peer.ID

    // MountProtocol adds given Protocol under specified protocol id.
    MountProtocol(path ProtocolPath, protocol Protocol)

    // ConnectPeerID establishes a connection to peer matching given PeerInfo.
    //
    // peer.AddrInfo may be empty. If so:
    // - Libp2pNode will try to use any Multiaddrs it knows (internal PeerStore)
    // - Libp2pNode may use any `PeerRouting` protocol mounted onto the libp2p node.
    //     TODO: how to define this.
    //     NOTE: probably implies using kad-dht or gossipsub for this.
    //
    // Idempotent. If a connection already exists, this method returns silently.
    Connect(peerInfo peer.AddrInfo)
}

type ProtocolPath string

type Protocol union {
    StreamProtocol
    DatagramProtocol
}

// Stream is an interface to deal with networked processes, which communicate
// via streams of bytes.
//
// See golang.org/pkg/io -- as this is modelled after io.Reader and io.Writer
type Stream struct {
    // Read reads bytes from the underlying stream and copies them to buf.
    // Read returns the number of bytes read (n), and potentially an error
    // encountered while reading. Read reads at most len(buf) byte.
    // Read may read 0 bytes.
    Read(buf Bytes) union {n int, err error}

    // Write writes bytes to the underlying stream, copying them from buf.
    // Write returns the number of bytes written (n), and potentially an error
    // encountered while writing. Write writes at most len(buf) byte.
    // Write may read 0 bytes.
    Write(buf Bytes) union {n int, err error}

    // Close terminates client's use of the stream.
    // Calling Read or Write after Close is an error.
    Close() error
}

type StreamProtocol struct {
    // AcceptStream accepts an incoming stream connection.
    AcceptStream() struct {
        stream    Stream
        peerInfo  peer.AddrInfo
        err       error
    }

    // OpenStream opens a stream to a particular PeerID.
    OpenStream(peerInfo peer.AddrInfo) struct {
        stream  Stream
        err     error
    }
}

// Datagram
type Datagram Bytes

// Datagrams are "messages" in the network packet sense of the word.
//
// "message-oriented network protocols" should use this interface,
// not the StreamProtocol interface.
//
// We call it "Datagram" here because unfortunately the word "Message"
// is very overloaded in Filecoin.
// Suggestion for libp2p: use datagram too.
type DatagramProtocol struct {
    // AcceptDatagram accepts an incoming message.
    AcceptDatagram() struct {
        datagram  Datagram
        peerInfo  peer.AddrInfo
        err       error
    }

    // OpenStream opens a stream to a particular PeerID
    SendDatagram(datagram Datagram, peerInfo peer.AddrInfo) struct {err error}
}

// type StorageDealLibp2pProtocol struct {
//   StreamProtocol StreamProtocol
//   // ---
//   AcceptStream() struct {}
//   OpenStream() struct {}
// }