stream

Documentation

Overview

Package stream implements stream level functionality.

The various stream errors defined by RFC 6120 § 4.9 are included as a convenience, but most people will want to use the facilities of the mellium.im/xmpp package and not create stream errors directly.

Index

• Constants
• Variables
• type Error
  • func SeeOtherHostError(addr net.Addr) Error
  • func (s Error) ApplicationError(r xml.TokenReader) Error
  • func (s Error) Error() string
  • func (s Error) Is(err error) bool
  • func (s Error) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (s Error) TokenReader() xml.TokenReader
  • func (s *Error) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
  • func (s Error) WriteXML(w xmlstream.TokenWriter) (n int, err error)
• type Info
  • func (i *Info) FromStartElement(s xml.StartElement) error
• type Version
  • func MustParseVersion(s string) Version
  • func ParseVersion(s string) (Version, error)
  • func (v Version) Less(b Version) bool
  • func (v Version) MarshalXMLAttr(name xml.Name) (xml.Attr, error)
  • func (v Version) String() string
  • func (v *Version) UnmarshalXMLAttr(attr xml.Attr) error

Constants

const (
	NS      = "http://etherx.jabber.org/streams"
	NSError = "urn:ietf:params:xml:ns:xmpp-streams"
)

Namespaces used by XMPP streams and stream errors, provided as a convenience.

Variables

var (
	// BadFormat is used when the entity has sent XML that cannot be processed.
	// This error can be used instead of the more specific XML-related errors,
	// such as <bad-namespace-prefix/>, <invalid-xml/>, <not-well-formed/>,
	// <restricted-xml/>, and <unsupported-encoding/>. However, the more specific
	// errors are RECOMMENDED.
	BadFormat = Error{Err: "bad-format"}

	// BadNamespacePrefix is sent when an entity has sent a namespace prefix that
	// is unsupported, or has sent no namespace prefix, on an element that needs
	// such a prefix.
	BadNamespacePrefix = Error{Err: "bad-namespace-prefix"}

	// Conflict is sent when the server either (1) is closing the existing stream
	// for this entity because a new stream has been initiated that conflicts with
	// the existing stream, or (2) is refusing a new stream for this entity
	// because allowing the new stream would conflict with an existing stream
	// (e.g., because the server allows only a certain number of connections from
	// the same IP address or allows only one server-to-server stream for a given
	// domain pair as a way of helping to ensure in-order processing.
	Conflict = Error{Err: "conflict"}

	// ConnectionTimeout results when one party is closing the stream because it
	// has reason to believe that the other party has permanently lost the ability
	// to communicate over the stream.
	ConnectionTimeout = Error{Err: "connection-timeout"}

	// HostGone is sent when the value of the 'to' attribute provided in the
	// initial stream header corresponds to an FQDN that is no longer serviced by
	// the receiving entity.
	HostGone = Error{Err: "host-gone"}

	// HostUnknown is sent when the value of the 'to' attribute provided in the
	// initial stream header does not correspond to an FQDN that is serviced by
	// the receiving entity.
	HostUnknown = Error{Err: "host-unknown"}

	// ImproperAddressing is used when a stanza sent between two servers lacks a
	// 'to' or 'from' attribute, the 'from' or 'to' attribute has no value, or the
	// value violates the rules for XMPP addresses.
	ImproperAddressing = Error{Err: "improper-addressing"}

	// InternalServerError is sent when the server has experienced a
	// misconfiguration or other internal error that prevents it from servicing
	// the stream.
	InternalServerError = Error{Err: "internal-server-error"}

	// InvalidFrom is sent when data provided in a 'from' attribute does not match
	// an authorized JID or validated domain as negotiated (1) between two servers
	// using SASL or Server Dialback, or (2) between a client and a server via
	// SASL authentication and resource binding.
	InvalidFrom = Error{Err: "invalid-from"}

	// InvalidNamespace may be sent when the stream namespace name is something
	// other than "http://etherx.jabber.org/streams" or the content namespace
	// declared as the default namespace is not supported (e.g., something other
	// than "jabber:client" or "jabber:server").
	InvalidNamespace = Error{Err: "invalid-namespace"}

	// InvalidXML may be sent when the entity has sent invalid XML over the stream
	// to a server that performs validation.
	InvalidXML = Error{Err: "invalid-xml"}

	// NotAuthorized may be sent when the entity has attempted to send XML stanzas
	// or other outbound data before the stream has been authenticated, or
	// otherwise is not authorized to perform an action related to stream
	// negotiation; the receiving entity MUST NOT process the offending data
	// before sending the stream error.
	NotAuthorized = Error{Err: "not-authorized"}

	// NotWellFormed may be sent when the initiating entity has sent XML that
	// violates the well-formedness rules of XML or XML namespaces.
	NotWellFormed = Error{Err: "not-well-formed"}

	// PolicyViolation may be sent when an entity has violated some local service
	// policy (e.g., a stanza exceeds a configured size limit).
	PolicyViolation = Error{Err: "policy-violation"}

	// RemoteConnectionFailed may be sent when the server is unable to properly
	// connect to a remote entity that is needed for authentication or
	// authorization
	RemoteConnectionFailed = Error{Err: "remote-connection-failed"}

	// server is closing the stream because it has new (typically
	// security-critical) features to offer, because the keys or certificates used
	// to establish a secure context for the stream have expired or have been
	// revoked during the life of the stream, because the TLS sequence number has
	// wrapped, etc. Encryption and authentication need to be negotiated again for
	// the new stream (e.g., TLS session resumption cannot be used).
	Reset = Error{Err: "reset"}

	// ResourceConstraing may be sent when the server lacks the system resources
	// necessary to service the stream.
	ResourceConstraint = Error{Err: "resource-constraint"}

	// RestrictedXML may be sent when the entity has attempted to send restricted
	// XML features such as a comment, processing instruction, DTD subset, or XML
	// entity reference.
	RestrictedXML = Error{Err: "restricted-xml"}

	// The server will not provide service to the initiating entity but is
	// redirecting traffic to another host under the administrative control of the
	// same service provider.
	// When acting as a server: Creating an error of this type can be done
	// with the SeeOtherHostError() function.
	// When acting as a client: This error can be returned by the stream negotiator.
	// Handling it is up to the client implementation, an example is given in the
	// echo example client.
	SeeOtherHost = Error{Err: "see-other-host"}

	// SystemShutdown may be sent when server is being shut down and all active
	// streams are being closed.
	SystemShutdown = Error{Err: "system-shutdown"}

	// UndefinedCondition may be sent when the error condition is not one of those
	// defined by the other conditions in this list; this error condition should
	// be used in conjunction with an application-specific condition.
	UndefinedCondition = Error{Err: "undefined-condition"}

	// UnsupportedEncoding may be sent when initiating entity has encoded the
	// stream in an encoding that is not UTF-8.
	UnsupportedEncoding = Error{Err: "unsupported-encoding"}

	// UnsupportedFeature may be sent when receiving entity has advertised a
	// mandatory-to-negotiate stream feature that the initiating entity does not
	// support.
	UnsupportedFeature = Error{Err: "unsupported-feature"}

	// UnsupportedStanzaType may be sent when the initiating entity has sent a
	// first-level child of the stream that is not supported by the server, either
	// because the receiving entity does not understand the namespace or because
	// the receiving entity does not understand the element name for the
	// applicable namespace (which might be the content namespace declared as the
	// default namespace).
	UnsupportedStanzaType = Error{Err: "unsupported-stanza-type"}

	// UnsupportedVersion may be sent when the 'version' attribute provided by the
	// initiating entity in the stream header specifies a version of XMPP that is
	// not supported by the server.
	UnsupportedVersion = Error{Err: "unsupported-version"}
)

A list of stream errors defined in RFC 6120 §4.9.3

var (
	DefaultVersion = Version{1, 0} // The default version to send.
	EmptyVersion   = Version{0, 9} // The value of a missing version attribute.
)

Common XMPP versions.

Types

type Error

type Error struct {
	Err  string
	Text []struct {
		Lang  string
		Value string
	}

	// The content of the error condition element.
	// This should only be used by see-other-host errors.
	Content string
	// contains filtered or unexported fields
}

Error represents an unrecoverable stream-level error that may include character data or arbitrary inner XML.

func SeeOtherHostError

func SeeOtherHostError(addr net.Addr) Error

SeeOtherHostError returns a new see-other-host error with the given network address as the host.

func (Error) ApplicationError

func (s Error) ApplicationError(r xml.TokenReader) Error

ApplicationError returns a copy of the Error with the provided application level error included alongside the error condition. Multiple, chained, calls to ApplicationError will replace the payload each time and only the final call will have any effect.

Because the TokenReader will be consumed during marshalling errors created with this method may only be marshaled once.

func (Error) Error

func (s Error) Error() string

Error satisfies the builtin error interface and returns the name of the StreamError. For instance, given the error:

<stream:error>
  <restricted-xml xmlns="urn:ietf:params:xml:ns:xmpp-streams"/>
</stream:error>

Error() would return "restricted-xml".

func (Error) Is

func (s Error) Is(err error) bool

Is will be used by errors.Is when comparing errors. For more information see the errors package.

func (Error) MarshalXML

func (s Error) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML satisfies the xml package's Marshaler interface and allows StreamError's to be correctly marshaled back into XML.

func (Error) TokenReader

func (s Error) TokenReader() xml.TokenReader

TokenReader returns a new xml.TokenReader that returns an encoding of the error.

func (*Error) UnmarshalXML

func (s *Error) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML satisfies the xml package's Unmarshaler interface and allows StreamError's to be correctly unmarshaled from XML.

func (Error) WriteXML

func (s Error) WriteXML(w xmlstream.TokenWriter) (n int, err error)

WriteXML satisfies the xmlstream.WriterTo interface. It is like MarshalXML except it writes tokens to w.

type Info

type Info struct {
	Name    xml.Name
	XMLNS   string
	To      jid.JID
	From    jid.JID
	ID      string
	Version Version
	Lang    string
}

Info contains metadata extracted from a stream start token.

func (*Info) FromStartElement

func (i *Info) FromStartElement(s xml.StartElement) error

FromStartElement sets the data in Info from the provided StartElement.

type Version

type Version struct {
	Major uint8
	Minor uint8
}

Version is a version of XMPP.

func MustParseVersion

func MustParseVersion(s string) Version

MustParseVersion parses a version string and panics if an error is returned.

func ParseVersion

func ParseVersion(s string) (Version, error)

ParseVersion parses a string of the form "Major.Minor" into a Version struct or returns an error.

func (Version) Less

func (v Version) Less(b Version) bool

Less compares the major and minor version numbers, returning true if a is less than b.

func (Version) MarshalXMLAttr

func (v Version) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr satisfies the MarshalerAttr interface and marshals the version as an XML attribute using its string representation.

func (Version) String

func (v Version) String() string

String returns the XMPP version in the form "Major.Minor".

func (*Version) UnmarshalXMLAttr

func (v *Version) UnmarshalXMLAttr(attr xml.Attr) error

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