go-multiaddr – github.com/multiformats/go-multiaddr Index | Files | Directories

package multiaddr

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

const (
	P_IP4               = 4
	P_TCP               = 6
	P_DNS               = 53 // 4 or 6
	P_DNS4              = 54
	P_DNS6              = 55
	P_DNSADDR           = 56
	P_UDP               = 273
	P_DCCP              = 33
	P_IP6               = 41
	P_IP6ZONE           = 42
	P_IPCIDR            = 43
	P_QUIC              = 460
	P_QUIC_V1           = 461
	P_WEBTRANSPORT      = 465
	P_CERTHASH          = 466
	P_SCTP              = 132
	P_CIRCUIT           = 290
	P_UDT               = 301
	P_UTP               = 302
	P_UNIX              = 400
	P_P2P               = 421
	P_IPFS              = P_P2P // alias for backwards compatibility
	P_HTTP              = 480
	P_HTTP_PATH         = 481
	P_HTTPS             = 443 // deprecated alias for /tls/http
	P_ONION             = 444 // also for backwards compatibility
	P_ONION3            = 445
	P_GARLIC64          = 446
	P_GARLIC32          = 447
	P_P2P_WEBRTC_DIRECT = 276 // Deprecated. use webrtc-direct instead
	P_TLS               = 448
	P_SNI               = 449
	P_NOISE             = 454
	P_WS                = 477
	P_WSS               = 478 // deprecated alias for /tls/ws
	P_PLAINTEXTV2       = 7367777
	P_WEBRTC_DIRECT     = 280
	P_WEBRTC            = 281
	P_MEMORY            = 777
)

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

const (
	LengthPrefixedVarSize = -1
)

These are special sizes

Variables 

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

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

var TranscoderCertHash = NewTranscoderFromFunctions(certHashStB, certHashBtS, validateCertHash)
var TranscoderDns = NewTranscoderFromFunctions(dnsStB, dnsBtS, dnsVal)
var TranscoderGarlic32 = NewTranscoderFromFunctions(garlic32StB, garlic32BtS, garlic32Validate)
var TranscoderGarlic64 = NewTranscoderFromFunctions(garlic64StB, garlic64BtS, garlic64Validate)
var TranscoderHTTPPath = NewTranscoderFromFunctions(httpPathStB, httpPathBtS, validateHTTPPath)
var TranscoderIP4 = NewTranscoderFromFunctions(ip4StB, ip4BtS, nil)
var TranscoderIP6 = NewTranscoderFromFunctions(ip6StB, ip6BtS, nil)
var TranscoderIP6Zone = NewTranscoderFromFunctions(ip6zoneStB, ip6zoneBtS, ip6zoneVal)
var TranscoderIPCIDR = NewTranscoderFromFunctions(ipcidrStB, ipcidrBtS, ipcidrValidate)
var TranscoderMemory = NewTranscoderFromFunctions(memoryStB, memoryBtS, memoryValidate)
var TranscoderOnion = NewTranscoderFromFunctions(onionStB, onionBtS, onionValidate)
var TranscoderOnion3 = NewTranscoderFromFunctions(onion3StB, onion3BtS, onion3Validate)
var TranscoderP2P = NewTranscoderFromFunctions(p2pStB, p2pBtS, p2pVal)
var TranscoderPort = NewTranscoderFromFunctions(portStB, portBtS, nil)
var TranscoderUnix = NewTranscoderFromFunctions(unixStB, unixBtS, unixValidate)

Functions

func AddProtocol 

func AddProtocol(p Protocol) error

func CaptureAddrPort 

func CaptureAddrPort(network *string, ipPort *netip.AddrPort) (capturePattern meg.Pattern)

func CodeToVarint 

func CodeToVarint(num int) []byte

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

func Contains 

func Contains(addrs []Multiaddr, addr Multiaddr) bool

Contains reports whether addr is contained in addrs.

func ForEach 

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

ForEach walks over the multiaddr, component by component.

This function iterates over components. Return true to continue iteration, false to stop.

Prefer a standard for range loop instead e.g. `for _, c := range m { ... }`

func ReadVarintCode 

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

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.

Types

type Action 

type Action int32

Action is an enum modelling all possible filter actions. 

const (
	ActionNone Action = iota // zero value.
	ActionAccept
	ActionDeny
)

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 Split 

func Split(m Multiaddr) []Component

Split returns the sub-address portions of a multiaddr.

func (*Component) Bytes 

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

func (*Component) Code 

func (c *Component) Code() int

func (*Component) Compare 

func (c *Component) Compare(o *Component) int

func (*Component) Decapsulate 

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

func (*Component) Encapsulate 

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

func (*Component) Equal 

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

func (*Component) MarshalBinary 

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

func (*Component) MarshalJSON 

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

func (*Component) MarshalText 

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

func (*Component) Multiaddr 

func (c *Component) Multiaddr() Multiaddr

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

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

func (*Component) UnmarshalJSON 

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

func (*Component) UnmarshalText 

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

func (*Component) Value 

func (c *Component) Value() string

func (*Component) ValueForProtocol 

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

type Filters 

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 

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 

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

func (*Filters) AddFilter 

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 

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

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

FiltersForAction returns the filters associated with the indicated action.

func (*Filters) RemoveLiteral 

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 

type Multiaddr []Component

Multiaddr is the data structure representing a Multiaddr

func Cast 

func Cast(b []byte) Multiaddr

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

func FilterAddrs 

func FilterAddrs(a []Multiaddr, filters ...func(Multiaddr) bool) []Multiaddr

FilterAddrs is a filter that removes certain addresses, according to the given filters. If all filters return true, the address is kept.

func Join 

func Join(msInterfaces ...Multiaddrer) Multiaddr

Join returns a combination of addresses. Note: This copies all the components from the input Multiaddrs. Depending on your use case, you may prefer to use `append(leftMA, rightMA...)` instead.

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 StringCast 

func StringCast(s string) Multiaddr

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

func Unique 

func Unique(addrs []Multiaddr) []Multiaddr

Unique deduplicates addresses in place, leave only unique addresses. It doesn't allocate.

func (Multiaddr) AppendComponent 

func (m Multiaddr) AppendComponent(cs ...*Component) Multiaddr

AppendComponent is the same as using `append(m, *c)`, but with a safety check for a nil Component.

func (Multiaddr) Bytes 

func (m Multiaddr) Bytes() []byte

Bytes returns the []byte representation of this Multiaddr

func (Multiaddr) Compare 

func (m Multiaddr) Compare(o Multiaddr) int

func (Multiaddr) Decapsulate 

func (m Multiaddr) Decapsulate(rightPartsAny Multiaddrer) Multiaddr

Decapsulate unwraps Multiaddr up until the given Multiaddr is found.

func (Multiaddr) Encapsulate 

func (m Multiaddr) Encapsulate(other Multiaddrer) Multiaddr

Encapsulate wraps a given Multiaddr, returning the resulting joined Multiaddr

func (Multiaddr) Equal 

func (m Multiaddr) Equal(m2 Multiaddr) bool

Equal tests whether two multiaddrs are equal

func (Multiaddr) MarshalBinary 

func (m Multiaddr) MarshalBinary() ([]byte, error)

func (Multiaddr) MarshalJSON 

func (m Multiaddr) MarshalJSON() ([]byte, error)

func (Multiaddr) MarshalText 

func (m Multiaddr) MarshalText() ([]byte, error)

func (Multiaddr) Match 

func (m Multiaddr) Match(p ...meg.Pattern) (bool, error)

func (Multiaddr) Multiaddr 

func (m Multiaddr) Multiaddr() Multiaddr

func (Multiaddr) Protocols 

func (m Multiaddr) Protocols() []Protocol

Protocols returns the list of protocols this Multiaddr has. will panic in case we access bytes incorrectly.

func (Multiaddr) String 

func (m Multiaddr) String() string

String returns the string representation of a Multiaddr

func (*Multiaddr) UnmarshalBinary 

func (m *Multiaddr) UnmarshalBinary(data []byte) error

func (*Multiaddr) UnmarshalJSON 

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

func (*Multiaddr) UnmarshalText 

func (m *Multiaddr) UnmarshalText(data []byte) error

func (Multiaddr) ValueForProtocol 

func (m Multiaddr) ValueForProtocol(code int) (value string, err error)

type Multiaddrer 

type Multiaddrer interface {
	// Multiaddr returns the Multiaddr representation
	Multiaddr() Multiaddr
}

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

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

Source Files

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

Directories

PathSynopsis
matestPackage matest provides utilities for testing with multiaddrs.
multiaddr
netPackage manet provides Multiaddr specific versions of common functions in stdlib's net package.
x
x/megpackage meg implements Regular Expressions for multiaddr Components.
Version
v0.16.0 (latest)
Published
Jun 6, 2025
Platform
linux/amd64
Imports
22 packages
Last checked
1 month ago –

Tools for package owners.