go-multiaddr: github.com/jbenet/go-multiaddr Index | Files | Directories

package multiaddr

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

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 (
  ma "github.com/multiformats/go-multiaddr"

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

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

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

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


Package Files

codec.go component.go doc.go filter.go interface.go multiaddr.go protocol.go protocols.go transcoders.go util.go varint.go


const (
    P_IP4               = 0x0004
    P_TCP               = 0x0006
    P_DNS               = 0x0035 // 4 or 6
    P_DNS4              = 0x0036
    P_DNS6              = 0x0037
    P_DNSADDR           = 0x0038
    P_UDP               = 0x0111
    P_DCCP              = 0x0021
    P_IP6               = 0x0029
    P_IP6ZONE           = 0x002A
    P_QUIC              = 0x01CC
    P_SCTP              = 0x0084
    P_CIRCUIT           = 0x0122
    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 // also for backwards compatibility
    P_ONION3            = 0x01BD
    P_GARLIC64          = 0x01BE
    P_GARLIC32          = 0x01BF
    P_P2P_WEBRTC_DIRECT = 0x0114
    P_WS                = 0x01DD
    P_WSS               = 0x01DE

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

const (
    LengthPrefixedVarSize = -1

These are special sizes


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

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

var TranscoderDns = NewTranscoderFromFunctions(dnsStB, dnsBtS, dnsVal)
var TranscoderGarlic32 = NewTranscoderFromFunctions(garlic32StB, garlic32BtS, garlic32Validate)
var TranscoderGarlic64 = NewTranscoderFromFunctions(garlic64StB, garlic64BtS, garlic64Validate)
var TranscoderIP4 = NewTranscoderFromFunctions(ip4StB, ip4BtS, nil)
var TranscoderIP6 = NewTranscoderFromFunctions(ip6StB, ip6BtS, nil)
var TranscoderIP6Zone = NewTranscoderFromFunctions(ip6zoneStB, ip6zoneBtS, ip6zoneVal)
var TranscoderOnion = NewTranscoderFromFunctions(onionStB, onionBtS, nil)
var TranscoderOnion3 = NewTranscoderFromFunctions(onion3StB, onion3BtS, nil)
var TranscoderP2P = NewTranscoderFromFunctions(p2pStB, p2pBtS, p2pVal)
var TranscoderPort = NewTranscoderFromFunctions(portStB, portBtS, nil)
var TranscoderUnix = NewTranscoderFromFunctions(unixStB, unixBtS, nil)

func AddProtocol Uses

func AddProtocol(p Protocol) error

func CodeToVarint Uses

func CodeToVarint(num int) []byte

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

func ForEach Uses

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 Uses

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

func SplitFirst Uses

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

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

func SplitFunc Uses

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 Uses

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

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

func SwapToP2pMultiaddrs Uses

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

DEPRECATED: this is now the default

type Action Uses

type Action int32

Action is an enum modelling all possible filter actions.

const (
    ActionNone Action = iota // zero value.

type Component Uses

type Component struct {
    // contains filtered or unexported fields

Component is a single multiaddr Component.

func NewComponent Uses

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

NewComponent constructs a new multiaddr component

func (*Component) Bytes Uses

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

func (*Component) Decapsulate Uses

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

func (*Component) Encapsulate Uses

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

func (*Component) Equal Uses

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

func (*Component) MarshalBinary Uses

func (c *Component) MarshalBinary() ([]byte, error)

func (*Component) MarshalJSON Uses

func (c *Component) MarshalJSON() ([]byte, error)

func (*Component) MarshalText Uses

func (c *Component) MarshalText() ([]byte, error)

func (*Component) Protocol Uses

func (c *Component) Protocol() Protocol

func (*Component) Protocols Uses

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

func (*Component) RawValue Uses

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

func (*Component) String Uses

func (c *Component) String() string

func (*Component) UnmarshalBinary Uses

func (c *Component) UnmarshalBinary(data []byte) error

func (*Component) UnmarshalJSON Uses

func (m *Component) UnmarshalJSON(data []byte) error

func (*Component) UnmarshalText Uses

func (c *Component) UnmarshalText(data []byte) error

func (*Component) Value Uses

func (c *Component) Value() string

func (*Component) ValueForProtocol Uses

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

type Filters Uses

type Filters struct {
    DefaultAction Action
    // contains filtered or unexported fields

Filters is a structure representing a collection of accept/deny net.IPNet filters, together with the DefaultAction flag, which represents the default filter policy.

Note that the last policy added to the Filters is authoritative.

func NewFilters Uses

func NewFilters() *Filters

NewFilters constructs and returns a new set of net.IPNet filters. By default, the new filter accepts all addresses.

func (*Filters) ActionForFilter Uses

func (fs *Filters) ActionForFilter(ipnet net.IPNet) (action Action, ok bool)

func (*Filters) AddDialFilter Uses

func (fs *Filters) AddDialFilter(f *net.IPNet)

AddDialFilter adds a deny rule to this Filters set. Hosts matching the given net.IPNet filter will be denied, unless another rule is added which states that they should be accepted.

No effort is made to prevent duplication of filters, or to simplify the filters list.

Deprecated: Use AddFilter().

func (*Filters) AddFilter Uses

func (fs *Filters) AddFilter(ipnet net.IPNet, action Action)

AddFilter adds a rule to the Filters set, enforcing the desired action for the provided IPNet mask.

func (*Filters) AddrBlocked Uses

func (fs *Filters) AddrBlocked(a Multiaddr) (deny bool)

AddrBlocked parses a ma.Multiaddr and, if a valid netip is found, it applies the Filter set rules, returning true if the given address should be denied, and false if the given address is accepted.

If a parsing error occurs, or no filter matches, the Filters' default is returned.

TODO: currently, the last filter to match wins always, but it shouldn't be that way.

Instead, the highest-specific last filter should win; that way more specific filters
override more general ones.

func (*Filters) Filters Uses

func (fs *Filters) Filters() (result []*net.IPNet)

Filters returns the list of DENY net.IPNet masks. For backwards compatibility.

A copy of the filters is made prior to returning, so the inner state is not exposed.

Deprecated: Use FiltersForAction().

func (*Filters) FiltersForAction Uses

func (fs *Filters) FiltersForAction(action Action) (result []net.IPNet)

FiltersForAction returns the filters associated with the indicated action.

func (*Filters) Remove Uses

func (fs *Filters) Remove(ipnet *net.IPNet) (removed bool)

RemoveLiteral removes the first filter associated with the supplied IPNet, returning whether something was removed or not. It makes no distinction between whether the rule is an accept or a deny.

Deprecated: use RemoveLiteral() instead.

func (*Filters) RemoveLiteral Uses

func (fs *Filters) RemoveLiteral(ipnet net.IPNet) (removed bool)

RemoveLiteral removes the first filter associated with the supplied IPNet, returning whether something was removed or not. It makes no distinction between whether the rule is an accept or a deny.

type Multiaddr Uses

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/ encapsulate /tcp/80 = /ip4/
    Encapsulate(Multiaddr) Multiaddr

    // Decapsultate removes a Multiaddr wrapping. For example:
    //      /ip4/ decapsulate /ip4/ = /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/")
// err non-nil when parsing failed.

func Cast Uses

func Cast(b []byte) Multiaddr

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

func Join Uses

func Join(ms ...Multiaddr) Multiaddr

Join returns a combination of addresses.

func NewMultiaddr Uses

func NewMultiaddr(s string) (a Multiaddr, err error)

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

func NewMultiaddrBytes Uses

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 Uses

func Split(m Multiaddr) []Multiaddr

Split returns the sub-address portions of a multiaddr.

func StringCast Uses

func StringCast(s string) Multiaddr

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

type Protocol Uses

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 Uses

func ProtocolWithCode(c int) Protocol

ProtocolWithCode returns the Protocol description with given protocol code.

func ProtocolWithName Uses

func ProtocolWithName(s string) Protocol

ProtocolWithName returns the Protocol description with given string name.

func ProtocolsWithString Uses

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

ProtocolsWithString returns a slice of protocols matching given string.

type Transcoder Uses

type Transcoder interface {
    // Validates and encodes to bytes a multiaddr that's in the string representation.
    StringToBytes(string) ([]byte, error)
    // Validates and decodes to a string a multiaddr that's in the bytes representation.
    BytesToString([]byte) (string, error)
    // Validates bytes when parsing a multiaddr that's already in the bytes representation.
    ValidateBytes([]byte) error

func NewTranscoderFromFunctions Uses

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


netPackage manet provides Multiaddr specific versions of common functions in stdlib's net package.

Package multiaddr imports 16 packages (graph) and is imported by 28 packages. Updated 2021-01-28. Refresh now. Tools for package owners.