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
- Variables
- func AddProtocol(p Protocol) error
- func CaptureAddrPort(network *string, ipPort *netip.AddrPort) (capturePattern meg.Pattern)
- func CodeToVarint(num int) []byte
- func Contains(addrs []Multiaddr, addr Multiaddr) bool
- func ForEach(m Multiaddr, cb func(c Component) bool)
- func ReadVarintCode(b []byte) (int, int, error)
- func SplitFirst(m Multiaddr) (*Component, Multiaddr)
- func SplitFunc(m Multiaddr, cb func(Component) bool) (Multiaddr, Multiaddr)
- func SplitLast(m Multiaddr) (Multiaddr, *Component)
- type Action
- type Component
- func NewComponent(protocol, value string) (*Component, error)
- func Split(m Multiaddr) []Component
- func (c *Component) Bytes() []byte
- func (c *Component) Code() int
- func (c *Component) Compare(o *Component) int
- func (c *Component) Decapsulate(o Multiaddrer) Multiaddr
- func (c *Component) Encapsulate(o Multiaddrer) Multiaddr
- func (c *Component) Equal(o *Component) bool
- func (c *Component) MarshalBinary() ([]byte, error)
- func (c *Component) MarshalJSON() ([]byte, error)
- func (c *Component) MarshalText() ([]byte, error)
- func (c *Component) Multiaddr() Multiaddr
- func (c *Component) Protocol() Protocol
- func (c *Component) Protocols() []Protocol
- func (c *Component) RawValue() []byte
- func (c *Component) String() string
- func (c *Component) UnmarshalBinary(data []byte) error
- func (c *Component) UnmarshalJSON(data []byte) error
- func (c *Component) UnmarshalText(data []byte) error
- func (c *Component) Value() string
- func (c *Component) ValueForProtocol(code int) (string, error)
- type Filters
- func NewFilters() *Filters
- func (fs *Filters) ActionForFilter(ipnet net.IPNet) (action Action, ok bool)
- func (fs *Filters) AddFilter(ipnet net.IPNet, action Action)
- func (fs *Filters) AddrBlocked(a Multiaddr) (deny bool)
- func (fs *Filters) FiltersForAction(action Action) (result []net.IPNet)
- func (fs *Filters) RemoveLiteral(ipnet net.IPNet) (removed bool)
- type Multiaddr
- func Cast(b []byte) Multiaddr
- func FilterAddrs(a []Multiaddr, filters ...func(Multiaddr) bool) []Multiaddr
- func Join(msInterfaces ...Multiaddrer) Multiaddr
- func NewMultiaddr(s string) (a Multiaddr, err error)
- func NewMultiaddrBytes(b []byte) (a Multiaddr, err error)
- func StringCast(s string) Multiaddr
- func Unique(addrs []Multiaddr) []Multiaddr
- func (m Multiaddr) AppendComponent(cs ...*Component) Multiaddr
- func (m Multiaddr) Bytes() []byte
- func (m Multiaddr) Compare(o Multiaddr) int
- func (m Multiaddr) Decapsulate(rightPartsAny Multiaddrer) Multiaddr
- func (m Multiaddr) Encapsulate(other Multiaddrer) Multiaddr
- func (m Multiaddr) Equal(m2 Multiaddr) bool
- func (m Multiaddr) MarshalBinary() ([]byte, error)
- func (m Multiaddr) MarshalJSON() ([]byte, error)
- func (m Multiaddr) MarshalText() ([]byte, error)
- func (m Multiaddr) Match(p ...meg.Pattern) (bool, error)
- func (m Multiaddr) Multiaddr() Multiaddr
- func (m Multiaddr) Protocols() []Protocol
- func (m Multiaddr) String() string
- func (m *Multiaddr) UnmarshalBinary(data []byte) error
- func (m *Multiaddr) UnmarshalJSON(data []byte) error
- func (m *Multiaddr) UnmarshalText(data []byte) error
- func (m Multiaddr) ValueForProtocol(code int) (value string, err error)
- type Multiaddrer
- type Protocol
- func ProtocolWithCode(c int) Protocol
- func ProtocolWithName(s string) Protocol
- func ProtocolsWithString(s string) ([]Protocol, error)
- type Transcoder
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 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 CaptureAddrPort ¶
func CodeToVarint ¶
CodeToVarint converts an integer to a varint-encoded []byte
func Contains ¶
Contains reports whether addr is contained in addrs.
func ForEach ¶
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 SplitFirst ¶
SplitFirst returns the first component and the rest of the multiaddr.
func SplitFunc ¶
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 ¶
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.
type Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component is a single multiaddr Component.
func NewComponent ¶
NewComponent constructs a new multiaddr component
func Split ¶
Split returns the sub-address portions of a multiaddr.
func (*Component) Bytes ¶
func (*Component) Code ¶
func (*Component) Compare ¶
func (*Component) Decapsulate ¶
func (c *Component) Decapsulate(o Multiaddrer) Multiaddr
func (*Component) Encapsulate ¶
func (c *Component) Encapsulate(o Multiaddrer) Multiaddr
func (*Component) Equal ¶
func (*Component) MarshalBinary ¶
func (*Component) MarshalJSON ¶
func (*Component) MarshalText ¶
func (*Component) Multiaddr ¶
func (*Component) Protocol ¶
func (*Component) Protocols ¶
func (*Component) RawValue ¶
func (*Component) String ¶
func (*Component) UnmarshalBinary ¶
func (*Component) UnmarshalJSON ¶
func (*Component) UnmarshalText ¶
func (*Component) Value ¶
func (*Component) ValueForProtocol ¶
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 (*Filters) AddFilter ¶
AddFilter adds a rule to the Filters set, enforcing the desired action for the provided IPNet mask.
func (*Filters) AddrBlocked ¶
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 ¶
FiltersForAction returns the filters associated with the indicated action.
func (*Filters) RemoveLiteral ¶
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 ¶
Cast re-casts a byte slice as a multiaddr. will panic if it fails to parse.
func FilterAddrs ¶
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 ¶
NewMultiaddr parses and validates an input string, returning a *Multiaddr
func NewMultiaddrBytes ¶
NewMultiaddrBytes initializes a Multiaddr from a byte representation. It validates it as an input string.
func StringCast ¶
StringCast like Cast, but parses a string. Will also panic if it fails to parse.
func Unique ¶
Unique deduplicates addresses in place, leave only unique addresses. It doesn't allocate.
func (Multiaddr) AppendComponent ¶
AppendComponent is the same as using `append(m, *c)`, but with a safety check for a nil Component.
func (Multiaddr) Bytes ¶
Bytes returns the []byte representation of this Multiaddr
func (Multiaddr) Compare ¶
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 ¶
Equal tests whether two multiaddrs are equal
func (Multiaddr) MarshalBinary ¶
func (Multiaddr) MarshalJSON ¶
func (Multiaddr) MarshalText ¶
func (Multiaddr) Match ¶
func (Multiaddr) Multiaddr ¶
func (Multiaddr) Protocols ¶
Protocols returns the list of protocols this Multiaddr has. will panic in case we access bytes incorrectly.
func (Multiaddr) String ¶
String returns the string representation of a Multiaddr
func (*Multiaddr) UnmarshalBinary ¶
func (*Multiaddr) UnmarshalJSON ¶
func (*Multiaddr) UnmarshalText ¶
func (Multiaddr) ValueForProtocol ¶
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 ¶
ProtocolWithCode returns the Protocol description with given protocol code.
func ProtocolWithName ¶
ProtocolWithName returns the Protocol description with given string name.
func ProtocolsWithString ¶
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 ¶
Path | Synopsis |
---|---|
matest | Package matest provides utilities for testing with multiaddrs. |
multiaddr | |
net | Package manet provides Multiaddr specific versions of common functions in stdlib's net package. |
x | |
x/meg | package meg implements Regular Expressions for multiaddr Components. |
- Version
- v0.16.0 (latest)
- Published
- Jun 6, 2025
- Platform
- linux/amd64
- Imports
- 22 packages
- Last checked
- 6 days ago –
Tools for package owners.