multistream

README

go-multistream

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

• Install
• Usage
• Maintainers
• Contribute
• License

Install

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

go get github.com/multiformats/go-multistream

Usage

Example

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 (
	"fmt"
	"io"
	"io/ioutil"
	"net"

	ms "github.com/multiformats/go-multistream"
)

// 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 {
		panic(err)
	}

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

			go mux.Handle(con)
		}
	}()

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

	// 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 {
		panic(err)
	}
	fmt.Printf("%s", cats)
	mstream.Close()

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

Contribute

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.

License

MIT © 2016 Jeromy Johnson

Documentation

Overview

Package multistream implements a simple stream router for the multistream-select protocoli. The protocol is defined at https://github.com/multiformats/multistream-select

Index

• Constants
• Variables
• func ReadNextToken(r io.Reader) (T, error)
• func ReadNextTokenBytes(r io.Reader) ([]byte, error)
• func SelectOneOf(protos []T, rwc io.ReadWriteCloser) (proto T, err error)
• func SelectProtoOrFail(proto T, rwc io.ReadWriteCloser) (err error)
• func SelectWithSimopenOrFail(protos []T, rwc io.ReadWriteCloser) (proto T, isServer bool, err error)
• type ErrNotSupported
  • func (e ErrNotSupported[T]) Error() string
  • func (e ErrNotSupported[T]) Is(target error) bool
• type Handler
• type HandlerFunc
• type LazyConn
  • func NewMSSelect(c io.ReadWriteCloser, proto T) LazyConn
  • func NewMultistream(c io.ReadWriteCloser, proto T) LazyConn
• type MultistreamMuxer
  • func NewMultistreamMuxer() *MultistreamMuxer[T]
  • func (msm *MultistreamMuxer[T]) AddHandler(protocol T, handler HandlerFunc[T])
  • func (msm *MultistreamMuxer[T]) AddHandlerWithFunc(protocol T, match func(T) bool, handler HandlerFunc[T])
  • func (msm *MultistreamMuxer[T]) Handle(rwc io.ReadWriteCloser) error
  • func (msm *MultistreamMuxer[T]) Negotiate(rwc io.ReadWriteCloser) (proto T, handler HandlerFunc[T], err error)
  • func (msm *MultistreamMuxer[T]) Protocols() []T
  • func (msm *MultistreamMuxer[T]) RemoveHandler(protocol T)
• type StringLike

Constants

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.

Variables

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.

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

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

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

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

Functions

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.

func SelectWithSimopenOrFail

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

SelectWithSimopenOrFail performs protocol negotiation with the simultaneous open extension. The returned boolean indicator will be true if we should act as a server.

Types

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

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

func (ErrNotSupported[T]) Is

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

type LazyConn interface {
	io.ReadWriteCloser
	// 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

type StringLike interface {
	~string
}

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