surgemq

README

SurgeMQ

Warning

This implementation might not be compatible with original. Original has not been updated since 2014 thus I forked to improve

It's currently in active development thus highly not recommended for production

This project should be considered unstable until further notice.

SurgeMQ is a high performance MQTT broker that aims to be fully compliant with MQTT 3.1 and 3.1.1 specs.

Features, Limitations, and Future

Features

• MQTT v3.1 - V3.1.1 compliant
• Full support of WebSockets transport
• SSL for both plain tcp and WebSockets transports
• Independent auth providers for each transport
• Persistence provider by BoltDB

Future

• $SYS topics
• Cluster
• Bridge
• Ack timeout/retry

Performance

TBD

Compatibility

In addition, SurgeMQ has been tested with the following client libraries and it seems to work:

• libmosquitto 1.3.5 (in C)
  • Tested with the bundled test programs msgsps_pub and msgsps_sub
• Paho MQTT Conformance/Interoperability Testing Suite (in Python)
  • Tested with all 10 test cases. Publish results TBD
• Paho C Client library (in C)
  • Tested with all of the test cases. Publish results TBD

License

Copyright (c) 2016 Artur Troian. All rights reserved.
Copyright (c) 2014 Dataence, LLC. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Examples

Look into examples/surgemq

Contributing guidelines

Documentation

Overview

Package surgemq is a high performance MQTT broker and client library that aims to be fully compliant with MQTT 3.1 and 3.1.1 specs.

The primary package that's of interest is package service. It provides the MQTT Server and Client services in a library form.

MQTT is a Client Server publish/subscribe messaging transport protocol. It is
light weight, open, simple, and designed so as to be easy to implement. These
characteristics make it ideal for use in many situations, including constrained
environments such as for communication in Machine to Machine (M2M) and Internet
of Things (IoT) contexts where a small code footprint is required and/or network
bandwidth is at a premium.

The protocol runs over TCP/IP, or over other network protocols that provide
ordered, lossless, bi-directional connections. Its features include:

- Use of the publish/subscribe message pattern which provides one-to-many
  message distribution and decoupling of applications.
- A messaging transport that is agnostic to the content of the payload.
- Three qualities of service for message delivery:
- "At most once", where messages are delivered according to the best efforts
  of the operating environment. Message loss can occur. This level could be
  used, for example, with ambient sensor data where it does not matter if an
  individual reading is lost as the next one will be published soon after.
  - "At least once", where messages are assured to arrive but duplicates can occur.
  - "Exactly once", where message are assured to arrive exactly once. This
    level could be used, for example, with billing systems where duplicate or
    lost messages could lead to incorrect charges being applied.
- A small transport overhead and protocol exchanges minimized to reduce
  network traffic.
- A mechanism to notify interested parties when an abnormal disconnection occurs.

Current performance benchmark of SurgeMQ, running all publishers, subscribers and broker on a single 4-core (2.8Ghz i7) MacBook Pro, is able to achieve:

• over 400,000 MPS in a 1:1 single publisher and single producer configuration
• over 450,000 MPS in a 20:1 fan-in configuration
• over 750,000 MPS in a 1:20 fan-out configuration
• over 700,000 MPS in a full mesh configuration with 20 clients

In addition, SurgeMQ has been tested with the following client libraries and it _seems_ to work:

• libmosquitto 1.3.5 (C)
• Tested with the bundled test programs msgsps_pub and msgsps_sub
• Paho MQTT Conformance/Interoperability Testing Suite (Python)
• Tested with all 10 test cases, 3 did not pass. They are 1) offline_message_queueing_test which is not supported by SurgeMQ, 2) redelivery_on_reconnect_test which is not yet implemented by SurgeMQ, 3) run_subscribe_failure_test which is not a valid test.
• Paho Go Client Library (Go)
• Tested with one of the tests in the library, in fact, that tests is now part of the tests for SurgeMQ
• Paho C Client library (C)
• Tested with most of the test cases and failed the same ones as the conformance test because the features are not yet implemented.
• Actually I think there's a bug in the test suite as it calls the PUBLISH handler function for non-PUBLISH messages.

Index

• Variables
• type Server
  • func NewServer(config *ServerConfig) (Server, error)
• type ServerConfig
  • func NewServerConfig() *ServerConfig

Variables

var (
	// ErrInvalidNodeName node name does not follow requirements
	ErrInvalidNodeName = errors.New("node name is invalid")
)

Types

type Server

type Server interface {
	// ListenAndServe configures transport according to provided config
	// This is non blocking function. It returns nil if listener started
	// or error if any happened during configuration.
	// Transport status reported over TransportStatus callback in server configuration
	ListenAndServe(interface{}) error

	// Close terminates the server by shutting down all the client connections and closing
	// configured listeners. It does full clean up of the resources and
	Close() error
}

Server server API

func NewServer

func NewServer(config *ServerConfig) (Server, error)

NewServer allocate server object

type ServerConfig

type ServerConfig struct {
	// Configuration of persistence provider
	Persistence persistTypes.ProviderConfig

	// OnDuplicate notify if there is attempt connect client with id that already exists and active
	// If not not set than defaults to mock function
	OnDuplicate func(string, bool)

	// TransportStatus user provided callback to track transport status
	// If not set than defaults to mock function
	TransportStatus func(id string, status string)

	// ConnectTimeout The number of seconds to wait for the CONNACK message before disconnecting.
	// If not set then default to 2 seconds.
	ConnectTimeout int

	// KeepAlive The number of seconds to keep the connection live if there's no data.
	// If not set then defaults to 5 minutes.
	KeepAlive int

	// SystreeUpdateInterval
	SystreeUpdateInterval time.Duration

	// NodeName
	NodeName string

	// Authenticator is the authenticator used to check username and password sent
	// in the CONNECT message. If not set then defaults to "mockSuccess".
	Authenticators string

	// AllowedVersions what protocol version server will handle
	// If not set than defaults to 0x3 and 0x04
	AllowedVersions map[message.ProtocolVersion]bool

	// AllowOverlappingSubscriptions tells server how to handle overlapping subscriptions from within one client
	// if true server will send only one publish with max subscribed QoS even there are n subscriptions
	// if false server will send as many publishes as amount of subscriptions matching publish topic exists
	// If not set than default is false
	AllowOverlappingSubscriptions bool

	// RewriteNodeName
	RewriteNodeName bool

	// OfflineQoS0 tell server to either persist (true) or not persist (false) QoS 0 messages for non-clean sessions
	// If not set than default is false
	OfflineQoS0 bool

	// AllowDuplicates Either allow or deny replacing of existing session if there new client with same clientID
	// If not set than default is false
	AllowDuplicates bool

	WithSystree bool
}

ServerConfig configuration of the MQTT server

func NewServerConfig

func NewServerConfig() *ServerConfig

NewServerConfig with default values. It's highly recommended to use that function to allocate config rather than directly ServerConfig structure