transport

package
v0.14.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2021 License: Apache-2.0 Imports: 12 Imported by: 22

Documentation

Overview

Package transport implements functionality for handling MQTT connections.

Example
// launch server
server, err := Launch("tcp://localhost:1337")
if err != nil {
	panic(err)
}

go func() {
	// accept next incoming connection
	conn, err := server.Accept()
	if err != nil {
		panic(err)
	}

	// receive next packet
	pkt, err := conn.Receive()
	if err != nil {
		panic(err)
	}

	// check packet type
	if _, ok := pkt.(*packet.Connect); ok {
		// send a connack packet
		err = conn.Send(packet.NewConnack(), false)
		if err != nil {
			panic(err)
		}
	} else {
		panic("unexpected packet")
	}
}()

// dial to server
conn, err := Dial("tcp://localhost:1337")
if err != nil {
	panic(err)
}

// send connect packet
err = conn.Send(packet.NewConnect(), false)
if err != nil {
	panic(err)
}

// receive next packet
pkt, err := conn.Receive()
if err != nil {
	panic(err)
}

// check packet type
if connackPacket, ok := pkt.(*packet.Connack); ok {
	fmt.Println(connackPacket)

	// close connection
	err = conn.Close()
	if err != nil {
		panic(err)
	}
} else {
	panic("unexpected packet")
}

// close server
err = server.Close()
if err != nil {
	panic(err)
}
Output:

<Connack SessionPresent=false ReturnCode=0>

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrNotBinary = errors.New("received web socket message is not binary")

ErrNotBinary may be returned by WebSocket connection when a message is received that is not binary.

View Source
var ErrUnsupportedProtocol = errors.New("unsupported protocol")

ErrUnsupportedProtocol is returned if either the launcher or dialer couldn't infer the protocol from the URL.

Functions

This section is empty.

Types

type BaseConn

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

A BaseConn manages the low-level plumbing between the Carrier and the packet Stream.

func NewBaseConn

func NewBaseConn(c Carrier) *BaseConn

NewBaseConn creates a new BaseConn using the specified Carrier.

func (*BaseConn) Close

func (c *BaseConn) Close() error

Close will close the underlying connection and cleanup resources. It will return any error encountered while closing the underlying connection.

func (*BaseConn) Receive

func (c *BaseConn) Receive() (packet.Generic, error)

Receive will read from the underlying connection and return a fully read packet. It will return any error encountered while decoding or reading from the underlying connection.

Note: Only one goroutine can receive at the same time.

func (*BaseConn) Send

func (c *BaseConn) Send(pkt packet.Generic, async bool) error

Send will write the packet to an internal buffer. It will either flush the internal buffer immediately or asynchronously in the background when it gets stale. Encoding errors are directly returned, but any network errors caught while flushing the buffer asynchronously will be returned on the next call.

Note: Only one goroutine can send at the same time.

func (*BaseConn) SetMaxWriteDelay added in v0.13.0

func (c *BaseConn) SetMaxWriteDelay(delay time.Duration)

SetMaxWriteDelay will set the maximum amount of time allowed to pass until an asynchronous write is flushed.

func (*BaseConn) SetReadLimit

func (c *BaseConn) SetReadLimit(limit int64)

SetReadLimit sets the maximum size of a packet that can be received. If the limit is greater than zero, Receive will close the connection and return an error if receiving the next packet will exceed the limit.

func (*BaseConn) SetReadTimeout

func (c *BaseConn) SetReadTimeout(timeout time.Duration)

SetReadTimeout sets the maximum time that can pass between reads. If no data is received in the set duration the connection will be closed and Read returns an error.

type Carrier

type Carrier interface {
	io.ReadWriteCloser
	SetReadDeadline(time.Time) error
}

A Carrier is a generalized stream that can be used with BaseConn.

type Conn

type Conn interface {
	// Send will write the packet to an internal buffer. It will either flush the
	// internal buffer immediately or asynchronously in the background when it gets
	// stale. Encoding errors are directly returned, but any network errors caught
	// while flushing the buffer asynchronously will be returned on the next call.
	//
	// Note: Only one goroutine can send at the same time.
	Send(pkt packet.Generic, async bool) error

	// Receive will read from the underlying connection and return a fully read
	// packet. It will return any error encountered while decoding or reading
	// from the underlying connection.
	//
	// Note: Only one goroutine can receive at the same time.
	Receive() (packet.Generic, error)

	// Close will close the underlying connection and cleanup resources. It will
	// return any error encountered while closing the underlying connection.
	Close() error

	// SetReadLimit sets the maximum size of a packet that can be received.
	// If the limit is greater than zero, Receive will close the connection and
	// return an error if receiving the next packet will exceed the limit.
	SetReadLimit(limit int64)

	// SetReadTimeout sets the maximum time that can pass between reads.
	// If no data is received in the set duration the connection will be closed
	// and Read returns an error.
	SetReadTimeout(timeout time.Duration)

	// SetMaxWriteDelay will set the maximum amount of time allowed to pass until
	// an asynchronous write is flushed.
	SetMaxWriteDelay(delay time.Duration)

	// LocalAddr will return the underlying connection's local net address.
	LocalAddr() net.Addr

	// RemoteAddr will return the underlying connection's remote net address.
	RemoteAddr() net.Addr
}

A Conn is a connection between a client and a broker. It abstracts an existing underlying stream connection.

func Dial

func Dial(address string) (Conn, error)

Dial is a shorthand function.

type DialConfig added in v0.13.0

type DialConfig struct {
	// The TLS config to be used with secure connections.
	TLSConfig *tls.Config

	// The additional request headers for web socket connections.
	RequestHeader http.Header

	// The time after which a dial attempt is cancelled.
	//
	// Default: No timeout.
	Timeout time.Duration

	// The default ports to be uses if no port has been specified.
	//
	// Defaults: 1883, 8883, 80, 443.
	DefaultTCPPort string
	DefaultTLSPort string
	DefaultWSPort  string
	DefaultWSSPort string
}

DialConfig is used to configure a dialer.

type Dialer

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

The Dialer handles connecting to a server and creating a connection.

func NewDialer

func NewDialer(config DialConfig) *Dialer

NewDialer returns a new Dialer.

func (*Dialer) Dial

func (d *Dialer) Dial(address string) (Conn, error)

Dial initiates a connection based in information extracted from a URL.

type LaunchConfig added in v0.13.0

type LaunchConfig struct {
	// The TLS config to be used with secure servers.
	TLSConfig *tls.Config

	// The fallback to be used id a request is not a web socket upgrade.
	WebSocketFallback http.Handler
}

LaunchConfig is used to configure a launcher.

type Launcher

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

The Launcher helps with launching a server and accepting connections.

func NewLauncher

func NewLauncher(config LaunchConfig) *Launcher

NewLauncher returns a new Launcher.

func (*Launcher) Launch

func (l *Launcher) Launch(address string) (Server, error)

Launch will launch a server based on information extracted from the address.

type NetConn

type NetConn struct {
	*BaseConn
	// contains filtered or unexported fields
}

A NetConn is a wrapper around a basic TCP connection.

func NewNetConn

func NewNetConn(conn net.Conn) *NetConn

NewNetConn returns a new NetConn.

func (*NetConn) LocalAddr

func (c *NetConn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*NetConn) RemoteAddr

func (c *NetConn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*NetConn) UnderlyingConn

func (c *NetConn) UnderlyingConn() net.Conn

UnderlyingConn returns the underlying net.Conn.

type NetServer

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

A NetServer accepts net.Conn based connections.

func CreateNetServer added in v0.9.1

func CreateNetServer(address string) (*NetServer, error)

CreateNetServer creates a new TCP server that listens on the provided address.

func CreateSecureNetServer added in v0.9.1

func CreateSecureNetServer(address string, config *tls.Config) (*NetServer, error)

CreateSecureNetServer creates a new TLS server that listens on the provided address.

func NewNetServer

func NewNetServer(listener net.Listener) *NetServer

NewNetServer wraps the provided listener.

func (*NetServer) Accept

func (s *NetServer) Accept() (Conn, error)

Accept will return the next available connection or block until a connection becomes available, otherwise returns an error.

func (*NetServer) Addr

func (s *NetServer) Addr() net.Addr

Addr returns the server's network address.

func (*NetServer) Close

func (s *NetServer) Close() error

Close will close the underlying listener and cleanup resources. It will return an error if the underlying listener didn't close cleanly.

type Server

type Server interface {
	// Accept will return the next available connection or block until a
	// connection becomes available, otherwise returns an error.
	Accept() (Conn, error)

	// Close will close the underlying listener and cleanup resources. It will
	// return an error if the underlying listener didn't close cleanly.
	Close() error

	// Addr returns the server's network address.
	Addr() net.Addr
}

A Server is a local port on which incoming connections can be accepted.

func Launch

func Launch(address string) (Server, error)

Launch is a shorthand function.

type WebSocketConn

type WebSocketConn struct {
	*BaseConn
	// contains filtered or unexported fields
}

The WebSocketConn wraps a websocket.Conn. The implementation supports packets that are chunked over several WebSocket messages and packets that are coalesced to one WebSocket message.

func NewWebSocketConn

func NewWebSocketConn(conn *websocket.Conn) *WebSocketConn

NewWebSocketConn returns a new WebSocketConn.

func (*WebSocketConn) LocalAddr

func (c *WebSocketConn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*WebSocketConn) RemoteAddr

func (c *WebSocketConn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*WebSocketConn) UnderlyingConn

func (c *WebSocketConn) UnderlyingConn() *websocket.Conn

UnderlyingConn returns the underlying websocket.Conn.

type WebSocketServer

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

The WebSocketServer accepts websocket.Conn based connections.

func CreateSecureWebSocketServer added in v0.9.1

func CreateSecureWebSocketServer(address string, config *tls.Config, fallback http.Handler) (*WebSocketServer, error)

CreateSecureWebSocketServer creates a new WSS server that listens on the provided address.

func CreateWebSocketServer added in v0.9.1

func CreateWebSocketServer(address string, fallback http.Handler) (*WebSocketServer, error)

CreateWebSocketServer creates a new WS server that listens on the provided address.

func NewWebSocketServer

func NewWebSocketServer(listener net.Listener, fallback http.Handler) *WebSocketServer

NewWebSocketServer wraps the provided listener.

func (*WebSocketServer) Accept

func (s *WebSocketServer) Accept() (Conn, error)

Accept will return the next available connection or block until a connection becomes available, otherwise returns an error.

func (*WebSocketServer) Addr

func (s *WebSocketServer) Addr() net.Addr

Addr returns the server's network address.

func (*WebSocketServer) Close

func (s *WebSocketServer) Close() error

Close will close the underlying listener and cleanup resources. It will return an error if the underlying listener didn't close cleanly.

func (*WebSocketServer) Upgrader added in v0.13.0

func (s *WebSocketServer) Upgrader() *WebSocketUpgrader

Upgrader returns the used WebSocketUpgrader.

type WebSocketUpgrader added in v0.13.0

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

The WebSocketUpgrader upgrades HTTP requests to WebSocket connections.

func NewWebSocketUpgrader added in v0.13.0

func NewWebSocketUpgrader(fallback http.Handler) *WebSocketUpgrader

NewWebSocketUpgrader creates a new upgrader with the provided optional fallback.

func (*WebSocketUpgrader) UnderlyingUpgrader added in v0.13.0

func (u *WebSocketUpgrader) UnderlyingUpgrader() *websocket.Upgrader

UnderlyingUpgrader returns the underlying websocket.Upgrader.

func (*WebSocketUpgrader) Upgrade added in v0.13.0

Upgrade will attempt to upgrade the request and return the connection. If the request is not an upgrade it will use the fallback handler if available. Encountered errors are already written to the client.

Directories

Path Synopsis
Package flow can be used to test MQTT packet flows.
Package flow can be used to test MQTT packet flows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL