package module
v0.5.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Sep 6, 2023 License: MIT Imports: 9 Imported by: 233



GoDoc Travis CI

an implementation of the multistream protocol in go

This package implements a simple stream router for the multistream-select protocol. The protocol is defined here.

Table of Contents


go-multistream is a standard Go module which can be installed with:

go get



This example shows how to use a multistream muxer. A muxer uses user-added handlers to handle different "protocols". The first step when interacting with a connection handler by the muxer is to select the protocol (the example uses SelectProtoOrFail). This will then let the muxer use the right handler.

package main

import (

	ms ""

// This example creates a multistream muxer, adds handlers for the protocols
// "/cats" and "/dogs" and exposes it on a localhost:8765. It then opens connections
// to that port, selects the protocols and tests that the handlers are working.
func main() {
	mux := ms.NewMultistreamMuxer[string]()
	mux.AddHandler("/cats", func(proto string, rwc io.ReadWriteCloser) error {
		fmt.Fprintln(rwc, proto, ": HELLO I LIKE CATS")
		return rwc.Close()
	mux.AddHandler("/dogs", func(proto string, rwc io.ReadWriteCloser) error {
		fmt.Fprintln(rwc, proto, ": HELLO I LIKE DOGS")
		return rwc.Close()

	list, err := net.Listen("tcp", ":8765")
	if err != nil {

	go func() {
		for {
			con, err := list.Accept()
			if err != nil {

			go mux.Handle(con)

	// The Muxer is ready, let's test it
	conn, err := net.Dial("tcp", ":8765")
	if err != nil {

	// Create a new multistream to talk to the muxer
	// which will negotiate that we want to talk with /cats
	mstream := ms.NewMSSelect(conn, "/cats")
	cats, err := ioutil.ReadAll(mstream)
	if err != nil {
	fmt.Printf("%s", cats)

	// A different way of talking to the muxer
	// is to manually selecting the protocol ourselves
	conn, err = net.Dial("tcp", ":8765")
	if err != nil {
	defer conn.Close()
	err = ms.SelectProtoOrFail("/dogs", conn)
	if err != nil {
	dogs, err := ioutil.ReadAll(conn)
	if err != nil {
	fmt.Printf("%s", dogs)


Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.


MIT © 2016 Jeromy Johnson



Package multistream implements a simple stream router for the multistream-select protocoli. The protocol is defined at



View Source
const ProtocolID = "/multistream/1.0.0"

ProtocolID identifies the multistream protocol itself and makes sure the multistream muxers on both sides of a channel can work with each other.


View Source
var ErrIncorrectVersion = errors.New("client connected with incorrect version")

ErrIncorrectVersion is an error reported when the muxer protocol negotiation fails because of a ProtocolID mismatch.

View Source
var ErrNoProtocols = errors.New("no protocols specified")

ErrNoProtocols is the error returned when the no protocols have been specified.

View Source
var ErrTooLarge = errors.New("incoming message was too large")

ErrTooLarge is an error to signal that an incoming message was too large


func ReadNextToken

func ReadNextToken[T StringLike](r io.Reader) (T, error)

ReadNextToken extracts a token from a Reader. It is used during protocol negotiation and returns a string.

func ReadNextTokenBytes

func ReadNextTokenBytes(r io.Reader) ([]byte, error)

ReadNextTokenBytes extracts a token from a Reader. It is used during protocol negotiation and returns a byte slice.

func SelectOneOf

func SelectOneOf[T StringLike](protos []T, rwc io.ReadWriteCloser) (proto T, err error)

SelectOneOf will perform handshakes with the protocols on the given slice until it finds one which is supported by the muxer.

func SelectProtoOrFail

func SelectProtoOrFail[T StringLike](proto T, rwc io.ReadWriteCloser) (err error)

SelectProtoOrFail performs the initial multistream handshake to inform the muxer of the protocol that will be used to communicate on this ReadWriteCloser. It returns an error if, for example, the muxer does not know how to handle this protocol.


type ErrNotSupported

type ErrNotSupported[T StringLike] struct {

	// Slice of protocols that were not supported by the muxer
	Protos []T

ErrNotSupported is the error returned when the muxer doesn't support the protocols tried for the handshake.

func (ErrNotSupported[T]) Error added in v0.4.0

func (e ErrNotSupported[T]) Error() string

func (ErrNotSupported[T]) Is added in v0.4.1

func (e ErrNotSupported[T]) Is(target error) bool

type Handler

type Handler[T StringLike] struct {
	MatchFunc func(T) bool
	Handle    HandlerFunc[T]
	AddName   T

Handler is a wrapper to HandlerFunc which attaches a name (protocol) and a match function which can optionally be used to select a handler by other means than the name.

type HandlerFunc

type HandlerFunc[T StringLike] func(protocol T, rwc io.ReadWriteCloser) error

HandlerFunc is a user-provided function used by the MultistreamMuxer to handle a protocol/stream.

type LazyConn added in v0.2.0

type LazyConn interface {
	// Flush flushes the lazy negotiation, if any.
	Flush() error

LazyConn is the connection type returned by the lazy negotiation functions.

func NewMSSelect

func NewMSSelect[T StringLike](c io.ReadWriteCloser, proto T) LazyConn

NewMSSelect returns a new Multistream which is able to perform protocol selection with a MultistreamMuxer.

func NewMultistream

func NewMultistream[T StringLike](c io.ReadWriteCloser, proto T) LazyConn

NewMultistream returns a multistream for the given protocol. This will not perform any protocol selection. If you are using a MultistreamMuxer, use NewMSSelect.

type MultistreamMuxer

type MultistreamMuxer[T StringLike] struct {
	// contains filtered or unexported fields

MultistreamMuxer is a muxer for multistream. Depending on the stream protocol tag it will select the right handler and hand the stream off to it.

func NewMultistreamMuxer

func NewMultistreamMuxer[T StringLike]() *MultistreamMuxer[T]

NewMultistreamMuxer creates a muxer.

func (*MultistreamMuxer[T]) AddHandler

func (msm *MultistreamMuxer[T]) AddHandler(protocol T, handler HandlerFunc[T])

AddHandler attaches a new protocol handler to the muxer.

func (*MultistreamMuxer[T]) AddHandlerWithFunc

func (msm *MultistreamMuxer[T]) AddHandlerWithFunc(protocol T, match func(T) bool, handler HandlerFunc[T])

AddHandlerWithFunc attaches a new protocol handler to the muxer with a match. If the match function returns true for a given protocol tag, the protocol will be selected even if the handler name and protocol tags are different.

func (*MultistreamMuxer[T]) Handle

func (msm *MultistreamMuxer[T]) Handle(rwc io.ReadWriteCloser) error

Handle performs protocol negotiation on a ReadWriteCloser (i.e. a connection). It will find a matching handler for the incoming protocol and pass the ReadWriteCloser to it.

func (*MultistreamMuxer[T]) Negotiate

func (msm *MultistreamMuxer[T]) Negotiate(rwc io.ReadWriteCloser) (proto T, handler HandlerFunc[T], err error)

Negotiate performs protocol selection and returns the protocol name and the matching handler function for it (or an error).

func (*MultistreamMuxer[T]) Protocols

func (msm *MultistreamMuxer[T]) Protocols() []T

Protocols returns the list of handler-names added to this this muxer.

func (*MultistreamMuxer[T]) RemoveHandler

func (msm *MultistreamMuxer[T]) RemoveHandler(protocol T)

RemoveHandler removes the handler with the given name from the muxer.

type StringLike added in v0.4.0

type StringLike interface {

StringLike is an interface that supports all types with underlying type string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL