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 "gitlab.dms3.io/mf/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 CodeToVarint(num int) []byte
- 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 (c *Component) Bytes() []byte
- func (c *Component) Decapsulate(o Multiaddr) Multiaddr
- func (c *Component) Encapsulate(o Multiaddr) Multiaddr
- func (c *Component) Equal(o Multiaddr) bool
- func (c *Component) MarshalBinary() ([]byte, error)
- func (c *Component) MarshalJSON() ([]byte, error)
- func (c *Component) MarshalText() ([]byte, error)
- 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 (m *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 (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
- type Protocol
- type Transcoder
Constants ¶
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 compatibility P_HTTP = 0x01E0 P_HTTPS = 0x01BB // deprecated alias for /tls/http P_ONION = 0x01BC // also for backwards compatibility P_ONION3 = 0x01BD P_GARLIC64 = 0x01BE P_GARLIC32 = 0x01BF P_P2P_WEBRTC_DIRECT = 0x0114 P_TLS = 0x01c0 P_NOISE = 0x01c6 P_WS = 0x01DD P_WSS = 0x01DE // deprecated alias for /tls/ws // // reference: https://github.com/multiformats/multicodec // Reserved Code Ranges // The following code ranges have special meaning and may only have // meanings assigned to as specified in their description: // // Private Use Area // Range: 0x300000 – 0x3FFFFF // // Codes in this range are reserved for internal use by applications and will // never be assigned any meaning as part of the Multicodec specification. P_DMS3 = 0x3E01A5 // public codec to be reserved later )
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 TranscoderDMS3 = NewTranscoderFromFunctions(dms3StB, dms3BtS, dms3Val)
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)
Functions ¶
func AddProtocol ¶
func CodeToVarint ¶
CodeToVarint converts an integer to a varint-encoded []byte
func ForEach ¶
ForEach walks over the multiaddr, component by component.
This function iterates over components *by value* to avoid allocating.
func SplitFirst ¶
SplitFirst returns the first component and the rest of the multiaddr.
Types ¶
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 (*Component) Decapsulate ¶
func (*Component) Encapsulate ¶
func (*Component) MarshalBinary ¶
func (*Component) MarshalJSON ¶
func (*Component) MarshalText ¶
func (*Component) UnmarshalBinary ¶
func (*Component) UnmarshalJSON ¶
func (*Component) UnmarshalText ¶
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.
type Multiaddr ¶
type Multiaddr interface { json.Marshaler json.Unmarshaler encoding.TextMarshaler encoding.TextUnmarshaler encoding.BinaryMarshaler encoding.BinaryUnmarshaler // 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 "gitlab.dms3.io/mf/go-multiaddr" addr, err := ma.NewMultiaddr("/ip4/1.2.3.4/tcp/80") // err non-nil when parsing failed.
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.
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 }