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 ¶
- Variables
- type BaseConn
- func (c *BaseConn) Close() error
- func (c *BaseConn) Receive() (packet.Generic, error)
- func (c *BaseConn) Send(pkt packet.Generic, async bool) error
- func (c *BaseConn) SetMaxWriteDelay(delay time.Duration)
- func (c *BaseConn) SetReadLimit(limit int64)
- func (c *BaseConn) SetReadTimeout(timeout time.Duration)
- type Carrier
- type Conn
- type DialConfig
- type Dialer
- type LaunchConfig
- type Launcher
- type NetConn
- type NetServer
- type Server
- type WebSocketConn
- type WebSocketServer
- type WebSocketUpgrader
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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.
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 ¶
NewBaseConn creates a new BaseConn using the specified Carrier.
func (*BaseConn) Close ¶
Close will close the underlying connection and cleanup resources. It will return any error encountered while closing the underlying connection.
func (*BaseConn) Receive ¶
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 ¶
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
SetMaxWriteDelay will set the maximum amount of time allowed to pass until an asynchronous write is flushed.
func (*BaseConn) SetReadLimit ¶
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 ¶
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.
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.
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.
type NetConn ¶
type NetConn struct {
*BaseConn
// contains filtered or unexported fields
}
A NetConn is a wrapper around a basic TCP connection.
func (*NetConn) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*NetConn) UnderlyingConn ¶
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
CreateNetServer creates a new TCP server that listens on the provided address.
func CreateSecureNetServer ¶ added in v0.9.1
CreateSecureNetServer creates a new TLS server that listens on the provided address.
func NewNetServer ¶
NewNetServer wraps the provided listener.
func (*NetServer) Accept ¶
Accept will return the next available connection or block until a connection becomes available, otherwise returns an error.
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.
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
func (u *WebSocketUpgrader) Upgrade(w http.ResponseWriter, r *http.Request) (*WebSocketConn, error)
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.
Source Files
Directories