websocket

Documentation

Overview

Package websocket implements a WebSocket transport for XMPP.

Index

• Constants
• func Dial(ctx context.Context, origin string, addr jid.JID) (net.Conn, error)
• func DialDirect(ctx context.Context, origin, addr string) (net.Conn, error)
• func DialSession(ctx context.Context, origin string, addr jid.JID, ...) (*xmpp.Session, error)
• func Negotiator(cfg func(*xmpp.Session, *xmpp.StreamConfig) xmpp.StreamConfig) xmpp.Negotiator
• func NewClient(ctx context.Context, origin, location string, addr jid.JID, ...) (*xmpp.Session, error)
• func NewSession(ctx context.Context, addr jid.JID, rw io.ReadWriter, ...) (*xmpp.Session, error)
• func ReceiveSession(ctx context.Context, rw io.ReadWriter, features ...xmpp.StreamFeature) (*xmpp.Session, error)
• type Dialer
  • func (d *Dialer) Dial(ctx context.Context, addr jid.JID) (net.Conn, error)
  • func (d *Dialer) DialDirect(_ context.Context, addr string) (net.Conn, error)

Constants

const (
	// NS is the XML namespace used by the XMPP subprotocol framing.
	NS = "urn:ietf:params:xml:ns:xmpp-framing"

	// WSProtocol is the protocol string used during the WebSocket handshake.
	WSProtocol = "xmpp"
)

Various constants used by this package, provided as a convenience.

Functions

func Dial

func Dial(ctx context.Context, origin string, addr jid.JID) (net.Conn, error)

Dial discovers WebSocket endpoints associated with the given address and attempts to make a connection to one of them (with appropriate fallback behavior).

Calling Dial is the equivalent of creating a Dialer type with only the Origin option set and calling its Dial method.

func DialDirect

func DialDirect(ctx context.Context, origin, addr string) (net.Conn, error)

DialDirect dials the provided WebSocket endpoint without performing any Web Host Metadata file lookup.

Calling DialDirect is the equivalent of creating a Dialer type with only the Origin option set and calling its DialDirect method.

func DialSession

func DialSession(ctx context.Context, origin string, addr jid.JID, features ...xmpp.StreamFeature) (*xmpp.Session, error)

DialSession uses a default dialer to create a WebSocket connection and attempts to negotiate an XMPP session over it.

If the provided context is canceled after stream negotiation is complete it has no effect on the session.

func Negotiator

func Negotiator(cfg func(*xmpp.Session, *xmpp.StreamConfig) xmpp.StreamConfig) xmpp.Negotiator

Negotiator is like xmpp.NewNegotiator except that it uses the websocket subprotocol.

func NewClient

func NewClient(ctx context.Context, origin, location string, addr jid.JID, rwc io.ReadWriteCloser, features ...xmpp.StreamFeature) (*xmpp.Session, error)

NewClient performs the WebSocket handshake on rwc and then attempts to establish an XMPP session on top of it. Location is the WebSocket location and addr is the actual JID expected at the XMPP layer.

func NewSession

func NewSession(ctx context.Context, addr jid.JID, rw io.ReadWriter, features ...xmpp.StreamFeature) (*xmpp.Session, error)

NewSession establishes an XMPP session from the perspective of the initiating client on rw using the WebSocket subprotocol. It does not perform the WebSocket handshake.

func ReceiveSession

func ReceiveSession(ctx context.Context, rw io.ReadWriter, features ...xmpp.StreamFeature) (*xmpp.Session, error)

ReceiveSession establishes an XMPP session from the perspective of the receiving server on rw using the WebSocket subprotocol. It does not perform the WebSocket handshake.

Types

type Dialer

type Dialer struct {
	// A WebSocket client origin.
	Origin string

	// TLS config for secure WebSocket (wss).
	// If TLSConfig is nil a default config is used.
	TLSConfig *tls.Config

	// Allow falling back to insecure WebSocket connections without TLS.
	// If endpoint discovery is used and a secure WebSocket endpoint is available
	// it will still be prioritized.
	//
	// The WebSocket transport does not support StartTLS so this value will fall
	// back to using bare WebSockets (a scheme of ws:) and is therefore insecure
	// and should never be used.
	InsecureNoTLS bool

	// Additional header fields to be sent in WebSocket opening handshake.
	Header http.Header

	// Dialer used when opening websocket connections.
	Dialer *net.Dialer

	// HTTP Client to use when looking up Web Host Metadata files.
	Client *http.Client
}

Dialer discovers and connects to the WebSocket address on the named network. The zero value for each field is equivalent to dialing without that option with the exception of Origin (which is required). Dialing with the zero value of Dialer (except Origin) is equivalent to calling the Dial function.

func (*Dialer) Dial

func (d *Dialer) Dial(ctx context.Context, addr jid.JID) (net.Conn, error)

Dial opens a new client connection to a WebSocket. It finds the WebSocket endpoint to connect to by looking up the XML Web Host Metadata (XRD) file present on the https://domainpart.

func (*Dialer) DialDirect

func (d *Dialer) DialDirect(_ context.Context, addr string) (net.Conn, error)

DialDirect dials the websocket endpoint without performing any Web Host Metadata file lookup.

Context is currently not used due to restrictions in the underlying WebSocket implementation. This may change in the future.