jid

Documentation

Overview

Package jid implements the XMPP address format.

XMPP addresses, more often called "JID's" (Jabber ID's) for historical reasons, comprise three parts: The localpart represents a specific user account, the domainpart is the domain, host name, or IP address of a server hosting the account, and the resourcepart which represents a specific client connected to an account (eg. the users phone or a web browser). Only the domainpart is required, and together they are formatted like an email with the resourcepart appended after a forward slash. For example, the following are all valid JIDs:

shakespeare@example.net
shakespeare@example.net/phone-b5c93ded
example.net

The first represents the account "shakespeare" on the service "example.net", the second represents a specific phone connected to that account, and the third represents the server running the service at example.net. This means that clients connected to the XMPP network are individually and globally addressable.

The jid package also implements the escaping mechanism defined in XEP-0106: JID Escaping. This can be used to expand the supported characters in the username of a JID.

Be advised: This API is still unstable and is subject to change.

Index

• func SplitString(s string) (localpart, domainpart, resourcepart string, err error)
• type JID
  • func MustParse(s string) JID
  • func New(localpart, domainpart, resourcepart string) (JID, error)
  • func Parse(s string) (JID, error)
  • func (j JID) Bare() JID
  • func (j JID) Copy() JID
  • func (j JID) Domain() JID
  • func (j JID) Domainpart() string
  • func (j JID) Equal(j2 JID) bool
  • func (j JID) Localpart() string
  • func (j JID) MarshalXML(e *xml.Encoder, start xml.StartElement) (err error)
  • func (j JID) MarshalXMLAttr(name xml.Name) (xml.Attr, error)
  • func (JID) Network() string
  • func (j JID) Resourcepart() string
  • func (j JID) String() string
  • func (j *JID) UnmarshalXML(d *xml.Decoder, start xml.StartElement) (err error)
  • func (j *JID) UnmarshalXMLAttr(attr xml.Attr) error
  • func (j JID) WithDomain(domainpart string) (JID, error)
  • func (j JID) WithLocal(localpart string) (JID, error)
  • func (j JID) WithResource(resourcepart string) (JID, error)
• type Transformer
  • func (t Transformer) Bytes(b []byte) []byte
  • func (t Transformer) Reset()
  • func (t Transformer) Span(src []byte, atEOF bool) (n int, err error)
  • func (t Transformer) String(s string) string
  • func (t Transformer) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)
• type Unsafe
  • func NewUnsafe(localpart, domainpart, resourcepart string) Unsafe
  • func ParseUnsafe(s string) (Unsafe, error)

Functions

func SplitString

func SplitString(s string) (localpart, domainpart, resourcepart string, err error)

SplitString splits out the localpart, domainpart, and resourcepart from a string representation of a JID. The parts are not guaranteed to be valid, and each part must be 1023 bytes or less.

Types

type JID

type JID struct {
	// contains filtered or unexported fields
}

JID represents an XMPP address (Jabber ID) comprising a localpart, domainpart, and resourcepart. All parts of a JID are guaranteed to be valid UTF-8 and will be represented in their canonical form which gives comparison the greatest chance of succeeding.

func MustParse

func MustParse(s string) JID

MustParse is like Parse but panics if the JID cannot be parsed. It simplifies safe initialization of JIDs from known-good constant strings.

func New

func New(localpart, domainpart, resourcepart string) (JID, error)

New constructs a new JID from the given localpart, domainpart, and resourcepart.

func Parse

func Parse(s string) (JID, error)

Parse constructs a new JID from the given string representation.

func (JID) Bare

func (j JID) Bare() JID

Bare returns a copy of the JID without a resourcepart. This is sometimes called a "bare" JID.

func (JID) Copy

func (j JID) Copy() JID

Copy makes a copy of the given JID. j.Equal(j.Copy()) will always return true.

func (JID) Domain

func (j JID) Domain() JID

Domain returns a copy of the JID without a resourcepart or localpart.

func (JID) Domainpart

func (j JID) Domainpart() string

Domainpart gets the domainpart of a JID (eg. "example.net").

func (JID) Equal

func (j JID) Equal(j2 JID) bool

Equal performs an octet-for-octet comparison with the given JID.

func (JID) Localpart

func (j JID) Localpart() string

Localpart gets the localpart of a JID (eg "username").

func (JID) MarshalXML

func (j JID) MarshalXML(e *xml.Encoder, start xml.StartElement) (err error)

MarshalXML satisfies the xml.Marshaler interface and marshals the JID as XML chardata.

func (JID) MarshalXMLAttr

func (j JID) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr satisfies the xml.MarshalerAttr interface and marshals the JID as an XML attribute.

func (JID) Network

func (JID) Network() string

Network satisfies the net.Addr interface by returning the name of the network ("xmpp").

func (JID) Resourcepart

func (j JID) Resourcepart() string

Resourcepart gets the resourcepart of a JID.

func (JID) String

func (j JID) String() string

String converts an JID to its string representation.

func (*JID) UnmarshalXML

func (j *JID) UnmarshalXML(d *xml.Decoder, start xml.StartElement) (err error)

UnmarshalXML satisfies the xml.Unmarshaler interface and unmarshals the JID from the elements chardata.

func (*JID) UnmarshalXMLAttr

func (j *JID) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr satisfies the xml.UnmarshalerAttr interface and unmarshals an XML attribute into a valid JID (or returns an error).

func (JID) WithDomain

func (j JID) WithDomain(domainpart string) (JID, error)

WithDomain returns a copy of the JID with a new domainpart. This elides validation of the localpart and resourcepart.

func (JID) WithLocal

func (j JID) WithLocal(localpart string) (JID, error)

WithLocal returns a copy of the JID with a new localpart. This elides validation of the domainpart and resourcepart.

func (JID) WithResource

func (j JID) WithResource(resourcepart string) (JID, error)

WithResource returns a copy of the JID with a new resourcepart. This elides validation of the localpart and domainpart.

type Transformer

type Transformer struct {
	// contains filtered or unexported fields
}

Transformer implements the transform.Transformer and transform.SpanningTransformer interfaces.

For more information see golang.org/x/text/transform or the predefined Escape and Unescape transformers.

var (
	// Escape is a transform that maps escapable runes to their escaped form as
	// defined in XEP-0106: JID Escaping.
	Escape Transformer = Transformer{escapeMapping{}}

	// Unescape is a transform that maps valid escape sequences to their unescaped
	// form as defined in XEP-0106: JID Escaping.
	Unescape Transformer = Transformer{unescapeMapping{}}
)

func (Transformer) Bytes

func (t Transformer) Bytes(b []byte) []byte

Bytes returns a new byte slice with the result of applying t to b.

func (Transformer) Reset

func (t Transformer) Reset()

Reset implements the transform.Transformer interface.

func (Transformer) Span

func (t Transformer) Span(src []byte, atEOF bool) (n int, err error)

Span implements the transform.SpanningTransformer interface.

func (Transformer) String

func (t Transformer) String(s string) string

String returns a string with the result of applying t to s.

func (Transformer) Transform

func (t Transformer) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)

Transform implements the transform.Transformer interface.

type Unsafe

type Unsafe struct {
	JID
}

Unsafe is a JID that has not had any normalization, length checks, UTF-8 validation, or other safety measures applied.

It can be a source of bugs, or even a security risk, if used improperly.

func NewUnsafe

func NewUnsafe(localpart, domainpart, resourcepart string) Unsafe

NewUnsafe constructs a new unsafe JID. For more information, see the Unsafe type.

func ParseUnsafe

func ParseUnsafe(s string) (Unsafe, error)

ParseUnsafe constructs a new unsafe JID from a string. For more information, see the Unsafe type.