tt

README

gregoryv/tt - package provides components for writing mqtt-v5.0 clients and servers

Quick start

$ go install github.com/gregoryv/tt/cmd/tt@latest
$ tt -h

Even though this repository provides a basic client/server(WIP) command it's main purpose is to provide capabilities for others to write their own clients depending on their situation.

NOTE! this module is still not ready for public use. I'm experimenting with the design, so major changes will occur.

This package uses the sibling package gregoryv/mq for encoding control packets on the wire.

The design focuses on decoupling each specific feature as much as possible. One example being the creation of a network connection is not enforced, which makes it easy to create inmemory clients and servers during testing.

Documentation

Overview

Package tt provides components for writing mqtt-v5 clients.

Example (Client)

Example shows a simple client for connect, publish a QoS 0 and disconnect.

package main

import (
	"context"

	"github.com/gregoryv/mq"
	"github.com/gregoryv/tt"
	"github.com/gregoryv/tt/event"
)

func main() {
	client := tt.Client{
		Server: "tcp://localhost:1883",
	}
	ctx := context.Background()
	client.Start(ctx)

	// v is either an packet or a event type
	for v := range client.Signal() {
		switch v := v.(type) {
		case event.ClientUp:
			_ = client.Send(ctx, mq.NewConnect())

		case event.ClientConnect:
			// do something once you are connected
			p := mq.Pub(0, "gopher/happy", "yes")
			_ = client.Send(ctx, p)

		case *mq.Publish:
			_ = v // do something the received packet

		case event.ClientStop:
			// do some clean up maybe
		}
	}
}

Example (Server)

Example shows how to run the provided server.

package main

import (
	"context"

	"github.com/gregoryv/tt"
	"github.com/gregoryv/tt/event"
)

func main() {
	var srv tt.Server
	ctx, cancel := context.WithCancel(context.Background())
	srv.Start(ctx)

	for v := range srv.Signal() {
		switch v.(type) {
		case event.ServerStop:
			cancel()
		}
	}
}

Index

• Variables
• type Bind
• type Client
  • func (c *Client) Send(ctx context.Context, p mq.Packet) error
  • func (c *Client) Signal() <-chan interface{}
  • func (c *Client) Start(ctx context.Context)
• type Server
  • func (s *Server) SetLogger(v *log.Logger)
  • func (s *Server) Signal() <-chan interface{}
  • func (s *Server) Start(ctx context.Context)

Examples

• Package (Client)
• Package (Server)

Variables

var ErrClientStopped = fmt.Errorf("Client stopped")

var ErrIDPoolEmpty = fmt.Errorf("no available packet ids")

Types

type Bind

type Bind struct {
	// eg. tcp://localhost:
	URL string

	// eg. 500ms
	AcceptTimeout string
}

Bind holds server listening settings

type Client

type Client struct {
	// Server to connect to, defaults to tcp://localhost:1883
	Server string

	// Set to true to include more log output
	Debug bool

	// optional logger, leave empty for no logging
	*log.Logger `json:-`

	// Outgoing packets use ids from 1..MaxPacketID, this limits the
	// number of packets in flight.
	MaxPacketID uint16

	// show settings on client.Run
	ShowSettings bool
	// contains filtered or unexported fields
}

Client implements a mqtt-v5 client. Public fields should be set before calling Run.

func (*Client) Send

func (c *Client) Send(ctx context.Context, p mq.Packet) error

Send returns when the packet was successfully encoded on the wire. Returns ErrClientStopped if not running.

func (*Client) Signal

func (c *Client) Signal() <-chan interface{}

Signal returns a channel used by client to inform application layer of packets and events. E.g. event.ClientUp

func (*Client) Start

func (c *Client) Start(ctx context.Context)

Start returns a channel where client pushes incoming packets or events.

type Server

type Server struct {
	// bind configuration where server listens for connections, empty
	// defaults to random port on localhost
	Binds []*Bind

	// client has to send the initial connect packet, default 200ms
	ConnectTimeout time.Duration

	// set to true for additional log information
	Debug bool

	ShowSettings bool
	// contains filtered or unexported fields
}

func (*Server) SetLogger

func (s *Server) SetLogger(v *log.Logger)

func (*Server) Signal

func (s *Server) Signal() <-chan interface{}

Signal returns a channel used by server to inform the application layer of events. E.g event.ServerStop

func (*Server) Start

func (s *Server) Start(ctx context.Context)

Start runs the server in a separate go routine. Use Server.Signal