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 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

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
)

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.

Variables

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_UTP, 0, "utp", CodeToVarint(P_UTP)},
	&Protocol{P_UDT, 0, "udt", CodeToVarint(P_UDT)},
}

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

Functions

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
}

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
	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.