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/ipfs/fs-repo-migrations/ipfs-10-to-11/_vendor/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 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)
- func SwapToP2pMultiaddrs()
- 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) AddDialFilter(f *net.IPNet)deprecated
- func (fs *Filters) AddFilter(ipnet net.IPNet, action Action)
- func (fs *Filters) AddrBlocked(a Multiaddr) (deny bool)
- func (fs *Filters) Filters() (result []*net.IPNet)deprecated
- func (fs *Filters) FiltersForAction(action Action) (result []net.IPNet)
- func (fs *Filters) Remove(ipnet *net.IPNet) (removed bool)deprecated
- 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 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
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 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.
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 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
DEPRECATED: this is now the default
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) AddDialFilter
deprecated
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 ¶
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) Remove
deprecated
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 "github.com/ipfs/fs-repo-migrations/ipfs-10-to-11/_vendor/github.com/multiformats/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 }