multiaddr

package module
v0.0.0-...-8c3eb5d Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2018 License: MIT Imports: 10 Imported by: 0

README

go-multiaddr

Travis CI codecov.io

multiaddr implementation in go

Multiaddr is a standard way to represent addresses that:

  • Support any standard network protocols.
  • Self-describe (include protocols).
  • Have a binary packed format.
  • Have a nice string representation.
  • Encapsulate well.

Table of Contents

Install

go get github.com/multiformats/go-multiaddr

Usage

Example
Simple
import ma "github.com/multiformats/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
m1.Protocols()
// []Protocol{
//   Protocol{ Code: 4, Name: 'ip4', Size: 32},
//   Protocol{ Code: 17, Name: 'udp', Size: 16},
// }
En/decapsulate
import ma "github.com/multiformats/go-multiaddr"

m, err := ma.NewMultiaddr("/ip4/127.0.0.1/udp/1234")
// <Multiaddr /ip4/127.0.0.1/udp/1234>

sctpMA, err := ma.NewMultiaddr("/sctp/5678")

m.Encapsulate(sctpMA)
// <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>

udpMA, err := ma.NewMultiaddr("/udp/1234")

m.Decapsulate(udpMA) // 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

Maintainers

Captain: @whyrusleeping.

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 © 2014 Juan Batiz-Benet

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/multiformats/multiaddr

Basic Use: 

import (
  "bytes"
  "strings"
  ma "github.com/multiformats/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

View Source 
const (
	P_IP4     = 0x0004
	P_TCP     = 0x0006
	P_UDP     = 0x0111
	P_DCCP    = 0x0021
	P_IP6     = 0x0029
	P_IP6ZONE = 0x002A
	P_QUIC    = 0x01CC
	P_SCTP    = 0x0084
	P_UDT     = 0x012D
	P_UTP     = 0x012E
	P_UNIX    = 0x0190
	P_P2P     = 0x01A5
	P_IPFS    = 0x01A5 // alias for backwards compatability
	P_HTTP    = 0x01E0
	P_HTTPS   = 0x01BB
	P_ONION   = 0x01BC
)

You **MUST** register your multicodecs with https://github.com/multiformats/multicodec before adding them here.

TODO: Use a single source of truth for all multicodecs instead of distributing them like this...

View Source 
const (
	LengthPrefixedVarSize = -1
)

These are special sizes

Variables

View Source 
var ErrProtocolNotFound = fmt.Errorf("protocol not found in multiaddr")
View Source 
var Protocols = []Protocol{}

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

View Source 
var TranscoderIP4 = NewTranscoderFromFunctions(ip4StB, ip4BtS, nil)
View Source 
var TranscoderIP6 = NewTranscoderFromFunctions(ip6StB, ip6BtS, nil)
View Source 
var TranscoderIP6Zone = NewTranscoderFromFunctions(ip6zoneStB, ip6zoneBtS, ip6zoneVal)
View Source 
var TranscoderOnion = NewTranscoderFromFunctions(onionStB, onionBtS, nil)
View Source 
var TranscoderP2P = NewTranscoderFromFunctions(p2pStB, p2pBtS, p2pVal)
View Source 
var TranscoderPort = NewTranscoderFromFunctions(portStB, portBtS, nil)
View Source 
var TranscoderUnix = NewTranscoderFromFunctions(unixStB, unixBtS, nil)

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 ForEach 

func ForEach(m Multiaddr, cb func(c Component) bool)

ForEach walks over the multiaddr, component by component.

This function iterates over components *by value* to avoid allocating.

func ReadVarintCode 

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

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

func SplitFirst 

func SplitFirst(m Multiaddr) (*Component, Multiaddr)

SplitFirst returns the first component and the rest of the multiaddr.

func SplitFunc 

func SplitFunc(m Multiaddr, cb func(Component) bool) (Multiaddr, Multiaddr)

SplitFunc splits the multiaddr when the callback first returns true. The component on which the callback first returns will be included in the *second* multiaddr.

func SplitLast 

func SplitLast(m Multiaddr) (Multiaddr, *Component)

SplitLast returns the rest of the multiaddr and the last component.

func SwapToP2pMultiaddrs 

func SwapToP2pMultiaddrs()

SwapToP2pMultiaddrs is a function to make the transition from /ipfs/... multiaddrs to /p2p/... multiaddrs easier The first stage of the rollout is to ship this package to all users so that all users of multiaddr can parse both /ipfs/ and /p2p/ multiaddrs as the same code (P_P2P). During this stage of the rollout, all addresses with P_P2P will continue printing as /ipfs/, so that older clients without the new parsing code won't break. Once the network has adopted the new parsing code broadly enough, users of multiaddr can add a call to this method to an init function in their codebase. This will cause any P_P2P multiaddr to print out as /p2p/ instead of /ipfs/. Note that the binary serialization of this multiaddr does not change at any point. This means that this code is not a breaking network change at any point

func VarintSize 

func VarintSize(num int) int

VarintSize returns the size (in bytes) of `num` encoded as a varint.

func VarintToCode 

func VarintToCode(buf []byte) int

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

Types

type Component 

type Component struct {
	// contains filtered or unexported fields
}

Component is a single multiaddr Component.

func NewComponent 

func NewComponent(protocol, value string) (*Component, error)

NewComponent constructs a new multiaddr component

func (*Component) Bytes 

func (c *Component) Bytes() []byte

func (*Component) Decapsulate 

func (c *Component) Decapsulate(o Multiaddr) Multiaddr

func (*Component) Encapsulate 

func (c *Component) Encapsulate(o Multiaddr) Multiaddr

func (*Component) Equal 

func (c *Component) Equal(o Multiaddr) bool

func (*Component) Protocol 

func (c *Component) Protocol() Protocol

func (*Component) Protocols 

func (c *Component) Protocols() []Protocol

func (*Component) RawValue 

func (c *Component) RawValue() []byte

func (*Component) String 

func (c *Component) String() string

func (*Component) Value 

func (c *Component) Value() string

func (*Component) ValueForProtocol 

func (c *Component) ValueForProtocol(code int) (string, error)

type Multiaddr 

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

	// Bytes returns the []byte representation of this Multiaddr
	//
	// This function may expose immutable, internal state. Do not modify.
	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
	//
	// Note: protocols can appear multiple times in a single multiaddr.
	// Consider using `ForEach` to walk over the addr manually.
	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/multiformats/multiaddr

Multiaddrs have both a binary and string representation. 

import ma "github.com/multiformats/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) (a Multiaddr, err error)

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

func NewMultiaddrBytes 

func NewMultiaddrBytes(b []byte) (a Multiaddr, err 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 {
	// Name is the string representation of the protocol code. E.g., ip4,
	// ip6, tcp, udp, etc.
	Name string

	// Code is the protocol's multicodec (a normal, non-varint number).
	Code int

	// VCode is a precomputed varint encoded version of Code.
	VCode []byte

	// Size is the size of the argument to this protocol.
	//
	// * Size == 0 means this protocol takes no argument.
	// * Size >  0 means this protocol takes a constant sized argument.
	// * Size <  0 means this protocol takes a variable length, varint
	//             prefixed argument.
	Size int // a size of -1 indicates a length-prefixed variable size

	// Path indicates a path protocol (e.g., unix). When parsing multiaddr
	// strings, path protocols consume the remainder of the address instead
	// of stopping at the next forward slash.
	//
	// Size must be LengthPrefixedVarSize.
	Path bool

	// Transcoder converts between the byte representation and the string
	// representation of this protocol's argument (if any).
	//
	// This should only be non-nil if Size != 0
	Transcoder Transcoder
}

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.

type Transcoder 

type Transcoder interface {
	StringToBytes(string) ([]byte, error)
	BytesToString([]byte) (string, error)
	ValidateBytes([]byte) error
}

func NewTranscoderFromFunctions 

func NewTranscoderFromFunctions(
	s2b func(string) ([]byte, error),
	b2s func([]byte) (string, error),
	val func([]byte) error,
) Transcoder

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.