multiaddr

README

go-multiaddr

multiaddr implementation in Go.

Example

Simple

import ma "github.com/jbenet/go-multiaddr"

// construct from a string (err signals parse failure)
m1, err := ma.NewMultiaddr("/ip4/127.0.0.1/udp/1234")

// construct from bytes (err signals parse failure)
m2, err := ma.NewMultiaddrBytes(m1.Bytes())

// true
strings.Equal(m1.String(), "/ip4/127.0.0.1/udp/1234")
strings.Equal(m1.String(), m2.String())
bytes.Equal(m1.Bytes(), m2.Bytes())
m1.Equal(m2)
m2.Equal(m1)

Protocols

// get the multiaddr protocol description objects
addr.Protocols()
// []Protocol{
//   Protocol{ Code: 4, Name: 'ip4', Size: 32},
//   Protocol{ Code: 17, Name: 'udp', Size: 16},
// }

En/decapsulate

m.Encapsulate(ma.NewMultiaddr("/sctp/5678"))
// <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
m.Decapsulate(ma.NewMultiaddr("/udp")) // up to + inc last occurrence of subaddr
// <Multiaddr /ip4/127.0.0.1>

Tunneling

Multiaddr allows expressing tunnels very nicely.

printer, _ := ma.NewMultiaddr("/ip4/192.168.0.13/tcp/80")
proxy, _ := ma.NewMultiaddr("/ip4/10.20.30.40/tcp/443")
printerOverProxy := proxy.Encapsulate(printer)
// /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80

proxyAgain := printerOverProxy.Decapsulate(printer)
// /ip4/10.20.30.40/tcp/443

Documentation

Overview

Package multiaddr provides an implementation of the Multiaddr network address format. Multiaddr emphasizes explicitness, self-description, and portability. It allows applications to treat addresses as opaque tokens, and to avoid making assumptions about the address representation (e.g. length). Learn more at https://github.com/jbenet/multiaddr

Basic Use:

import (
  "bytes"
  "strings"
  ma "github.com/jbenet/go-multiaddr"
)

// construct from a string (err signals parse failure)
m1, err := ma.NewMultiaddr("/ip4/127.0.0.1/udp/1234")

// construct from bytes (err signals parse failure)
m2, err := ma.NewMultiaddrBytes(m1.Bytes())

// true
strings.Equal(m1.String(), "/ip4/127.0.0.1/udp/1234")
strings.Equal(m1.String(), m2.String())
bytes.Equal(m1.Bytes(), m2.Bytes())
m1.Equal(m2)
m2.Equal(m1)

// tunneling (en/decap)
printer, _ := ma.NewMultiaddr("/ip4/192.168.0.13/tcp/80")
proxy, _ := ma.NewMultiaddr("/ip4/10.20.30.40/tcp/443")
printerOverProxy := proxy.Encapsulate(printer)
proxyAgain := printerOverProxy.Decapsulate(printer)

Index

• Constants
• Variables
• func AddProtocol(p Protocol) error
• func CodeToVarint(num int) []byte
• func ReadVarintCode(buf []byte) (int, int)
• func VarintToCode(buf []byte) int
• type Multiaddr
  • func Cast(b []byte) Multiaddr
  • func Join(ms ...Multiaddr) Multiaddr
  • func NewMultiaddr(s string) (Multiaddr, error)
  • func NewMultiaddrBytes(b []byte) (Multiaddr, error)
  • func Split(m Multiaddr) []Multiaddr
  • func StringCast(s string) Multiaddr
• type Protocol
  • func ProtocolWithCode(c int) Protocol
  • func ProtocolWithName(s string) Protocol
  • func ProtocolsWithString(s string) ([]Protocol, error)

Constants

const (
	P_IP4   = 4
	P_TCP   = 6
	P_UDP   = 17
	P_DCCP  = 33
	P_IP6   = 41
	P_SCTP  = 132
	P_UTP   = 301
	P_UDT   = 302
	P_IPFS  = 421
	P_HTTP  = 480
	P_HTTPS = 443
	P_ONION = 444
)

replicating table here to: 1. avoid parsing the csv 2. ensuring errors in the csv don't screw up code. 3. changing a number has to happen in two places.

const (
	LengthPrefixedVarSize = -1
)

These are special sizes

Variables

var ErrProtocolNotFound = fmt.Errorf("protocol not found in multiaddr")

var Protocols = []Protocol{
	Protocol{P_IP4, 32, "ip4", CodeToVarint(P_IP4)},
	Protocol{P_TCP, 16, "tcp", CodeToVarint(P_TCP)},
	Protocol{P_UDP, 16, "udp", CodeToVarint(P_UDP)},
	Protocol{P_DCCP, 16, "dccp", CodeToVarint(P_DCCP)},
	Protocol{P_IP6, 128, "ip6", CodeToVarint(P_IP6)},

	Protocol{P_SCTP, 16, "sctp", CodeToVarint(P_SCTP)},
	Protocol{P_ONION, 80, "onion", CodeToVarint(P_ONION)},
	Protocol{P_UTP, 0, "utp", CodeToVarint(P_UTP)},
	Protocol{P_UDT, 0, "udt", CodeToVarint(P_UDT)},
	Protocol{P_HTTP, 0, "http", CodeToVarint(P_HTTP)},
	Protocol{P_HTTPS, 0, "https", CodeToVarint(P_HTTPS)},
	Protocol{P_IPFS, LengthPrefixedVarSize, "ipfs", CodeToVarint(P_IPFS)},
}

Protocols is the list of multiaddr protocols supported by this module.

Functions

func AddProtocol

func AddProtocol(p Protocol) error

func CodeToVarint

func CodeToVarint(num int) []byte

CodeToVarint converts an integer to a varint-encoded []byte

func ReadVarintCode

func ReadVarintCode(buf []byte) (int, int)

ReadVarintCode reads a varint code from the beginning of buf. returns the code, and the number of bytes read.

func VarintToCode

func VarintToCode(buf []byte) int

VarintToCode converts a varint-encoded []byte to an integer protocol code

Types

type Multiaddr

type Multiaddr interface {
	// Equal returns whether two Multiaddrs are exactly equal
	Equal(Multiaddr) bool

	// Bytes returns the []byte representation of this Multiaddr
	Bytes() []byte

	// String returns the string representation of this Multiaddr
	// (may panic if internal state is corrupted)
	String() string

	// Protocols returns the list of Protocols this Multiaddr includes
	// will panic if protocol code incorrect (and bytes accessed incorrectly)
	Protocols() []Protocol

	// Encapsulate wraps this Multiaddr around another. For example:
	//
	//      /ip4/1.2.3.4 encapsulate /tcp/80 = /ip4/1.2.3.4/tcp/80
	//
	Encapsulate(Multiaddr) Multiaddr

	// Decapsultate removes a Multiaddr wrapping. For example:
	//
	//      /ip4/1.2.3.4/tcp/80 decapsulate /ip4/1.2.3.4 = /tcp/80
	//
	Decapsulate(Multiaddr) Multiaddr

	// ValueForProtocol returns the value (if any) following the specified protocol
	ValueForProtocol(code int) (string, error)
}

Multiaddr is a cross-protocol, cross-platform format for representing internet addresses. It emphasizes explicitness and self-description. Learn more here: https://github.com/jbenet/multiaddr

Multiaddrs have both a binary and string representation.

import ma "github.com/jbenet/go-multiaddr"

addr, err := ma.NewMultiaddr("/ip4/1.2.3.4/tcp/80")
// err non-nil when parsing failed.

func Cast

func Cast(b []byte) Multiaddr

Cast re-casts a byte slice as a multiaddr. will panic if it fails to parse.

func Join

func Join(ms ...Multiaddr) Multiaddr

Join returns a combination of addresses.

func NewMultiaddr

func NewMultiaddr(s string) (Multiaddr, error)

NewMultiaddr parses and validates an input string, returning a *Multiaddr

func NewMultiaddrBytes

func NewMultiaddrBytes(b []byte) (Multiaddr, error)

NewMultiaddrBytes initializes a Multiaddr from a byte representation. It validates it as an input string.

func Split

func Split(m Multiaddr) []Multiaddr

Split returns the sub-address portions of a multiaddr.

func StringCast

func StringCast(s string) Multiaddr

StringCast like Cast, but parses a string. Will also panic if it fails to parse.

type Protocol

type Protocol struct {
	Code  int
	Size  int // a size of -1 indicates a length-prefixed variable size
	Name  string
	VCode []byte
}

Protocol is a Multiaddr protocol description structure.

func ProtocolWithCode

func ProtocolWithCode(c int) Protocol

ProtocolWithCode returns the Protocol description with given protocol code.

func ProtocolWithName

func ProtocolWithName(s string) Protocol

ProtocolWithName returns the Protocol description with given string name.

func ProtocolsWithString

func ProtocolsWithString(s string) ([]Protocol, error)

ProtocolsWithString returns a slice of protocols matching given string.