supermq

package module
v0.18.3 Latest Latest
Warning

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

Go to latest
Published: Nov 28, 2025 License: Apache-2.0 Imports: 2 Imported by: 44

README ΒΆ

SuperMQ

Planetary event-driven infrastructure

Made with ❀️ by Abstract Machines

Build Status Check License Header Check Generated Files Go Report Card Coverage License Matrix

Guide | Contributing | Website | Chat

Introduction πŸ“–

SuperMQ is a distributed, highly scalable, and secure open-source cloud platform for messaging and event-driven architecture (EDA). It is a planetarily distributed, highly scalable, and secure platform that serves as a robust foundation for building advanced real-time and reactive systems.

Why SuperMQ Stands Out πŸš€

SuperMQ bridges the gap between various network protocols (HTTP, MQTT, WebSocket, CoAP, and more) to provide a seamless messaging experience. Whether you're working on IoT solutions, real-time data pipelines, or event-driven systems, SuperMQ has you covered. 🌐✨

Key Features 🌟

  • Multi-Protocol Connectivity: HTTP, MQTT, WebSocket, CoAP, and more! πŸŒ‰
  • Secure by Design: Mutual TLS (mTLS) with X.509 Certificates, JWT support, and multi-protocol authorization. πŸ”’
  • Fine-Grained Access Control: Support for ABAC and RBAC policies. πŸ“œ
  • Multi-Tenant: Manage multiple domains seamlessly. 🏒
  • Multi-User: Unlimited organizational hierarchies for user management. πŸ‘₯
  • Application Management: Group and share messaging clients for streamlined operations. πŸ“±
  • Ease of Use: Simple and powerful communication channel management, grouping, and sharing. ✨
  • Personal Access Tokens (PATs): Scoped and revocable tokens for enhanced security. πŸ”‘
  • Observability: Integrated logging and instrumentation with Prometheus and OpenTelemetry. πŸ“ˆ
  • Event Sourcing: Build robust and scalable architectures. ⚑
  • Edge and IoT Ready: Supports MQTT and CoAP protocols for seamless IoT gateway and sensor communication and management. 🌍
  • Developer-Friendly: SDKs, CLI tools, and comprehensive documentation to get you started. πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»
  • Production-Ready: Container-based deployment using Docker and Kubernetes. 🐳☸️

Installation πŸ› οΈ

Clone the repository and start SuperMQ services:

git clone https://github.com/absmach/supermq.git
cd supermq
docker compose -f docker/docker-compose.yaml --env-file docker/.env up

Or use the Makefile for a simpler command:

make run

For production deployments, check our Kubernetes guide. βš™οΈ

Usage πŸ“€πŸ“₯
Using the CLI:
make cli
./build/supermq-cli status

This command retrieves the status of the SuperMQ server and outputs it to the console.

Using HTTP with Curl:
curl -X GET http://localhost:8080/status

This request fetches the server status over HTTP and provides a JSON response.

See our CLI documentation for more details.

Documentation πŸ“š

The official documentation is hosted at SuperMQ docs page.

Documentation is auto-generated, check out the instructions in the docs repository. If you spot an error or a need for corrections, please let us know - or even better: send us a PR! πŸ’Œ

Community and Contributing 🀝

Thank you for your interest in SuperMQ and the desire to contribute!

  1. Take a look at our open issues. The good-first-issue label is specifically for issues that are great for getting started.
  2. Checkout the contribution guide to learn more about our style and conventions.
  3. Make your changes compatible to our workflow.

Join our community:

Professional Support πŸ’Ό

Need help deploying SuperMQ or integrating it into your system? Reach out to Abstract Machines for professional support and guidance.

License πŸ“œ

SuperMQ is open-source software licensed under the Apache License 2.0. Contributions are welcome!

Acknowledgments πŸ™Œ

Special thanks to the amazing contributors who make SuperMQ possible. Check out the MAINTAINERS file to see the team behind the magic.

Ready to build the future of messaging and event-driven systems? Let's get started! πŸš€

Documentation ΒΆ

Overview ΒΆ

Package supermq acts as an umbrella package containing multiple different microservices and defines all shared domain concepts. For detailed documentation of the platform, please visit https://docs.supermq.abstractmachines.fr.

Index ΒΆ

Constants ΒΆ

This section is empty.

Variables ΒΆ

View Source
var (
	// Version represents the last service git tag in git history.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.Version=0.0.0'".
	Version = "0.0.0"
	// Commit represents the service git commit hash.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.Commit=ffffffff'".
	Commit = "ffffffff"
	// BuildTime represetns the service build time.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.BuildTime=1970-01-01_00:00:00'".
	BuildTime = "1970-01-01_00:00:00"
)

Functions ΒΆ

func Health ΒΆ

func Health(service, instanceID string) http.HandlerFunc

Health exposes an HTTP handler for retrieving service health.

Types ΒΆ

type HealthInfo ΒΆ

type HealthInfo struct {
	// Status contains service status.
	Status string `json:"status"`

	// Version contains current service version.
	Version string `json:"version"`

	// Commit represents the git hash commit.
	Commit string `json:"commit"`

	// Description contains service description.
	Description string `json:"description"`

	// BuildTime contains service build time.
	BuildTime string `json:"build_time"`

	// InstanceID contains the ID of the current service instance
	InstanceID string `json:"instance_id"`
}

HealthInfo contains version endpoint response.

type IDProvider ΒΆ

type IDProvider interface {
	// ID generates the unique identifier.
	ID() (string, error)
}

IDProvider specifies an API for generating unique identifiers.

type Response ΒΆ

type Response interface {
	// Code returns HTTP response code.
	Code() int

	// Headers returns map of HTTP headers with their values.
	Headers() map[string]string

	// Empty indicates if HTTP response has content.
	Empty() bool
}

Response contains HTTP response specific methods.

Directories ΒΆ

Path Synopsis
api
Package api contains commonly used constants and functions for the HTTP and gRPC API.
Package api contains commonly used constants and functions for the HTTP and gRPC API.
http
Package api contains commonly used constants and functions for the HTTP API.
Package api contains commonly used constants and functions for the HTTP API.
api
Package api contains implementation of Auth service HTTP API.
Package api contains implementation of Auth service HTTP API.
api/grpc/auth
Package auth contains implementation of Auth service gRPC API.
Package auth contains implementation of Auth service gRPC API.
api/grpc/token
Package grpc contains implementation of Auth service gRPC API.
Package grpc contains implementation of Auth service gRPC API.
hasher
Package hasher contains the domain concept definitions needed to support Supermq users password hasher sub-service functionality.
Package hasher contains the domain concept definitions needed to support Supermq users password hasher sub-service functionality.
jwt
middleware
Package middleware provides logging metrics and tracing middleware for SuperMQ Auth service.
Package middleware provides logging metrics and tracing middleware for SuperMQ Auth service.
postgres
Package postgres contains Key repository implementations using PostgreSQL as the underlying database.
Package postgres contains Key repository implementations using PostgreSQL as the underlying database.
api/grpc
Package grpc contains implementation of Auth service gRPC API.
Package grpc contains implementation of Auth service gRPC API.
cache
Package cache contains the domain concept definitions needed to support SuperMQ Channels cache service functionality.
Package cache contains the domain concept definitions needed to support SuperMQ Channels cache service functionality.
events
Package events provides the domain concept definitions needed to support clients events functionality.
Package events provides the domain concept definitions needed to support clients events functionality.
middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Channels Service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Channels Service.
Package cli contains the domain concept definitions needed to support SuperMQ CLI functionality.
Package cli contains the domain concept definitions needed to support SuperMQ CLI functionality.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
api/grpc
Package grpc contains implementation of Auth service gRPC API.
Package grpc contains implementation of Auth service gRPC API.
cache
Package cache contains the domain concept definitions needed to support SuperMQ clients cache service functionality.
Package cache contains the domain concept definitions needed to support SuperMQ clients cache service functionality.
events
Package events provides the domain concept definitions needed to support clients events functionality.
Package events provides the domain concept definitions needed to support clients events functionality.
middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Clients Service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Clients Service.
mocks
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
postgres
Package postgres contains the database implementation of clients repository layer.
Package postgres contains the database implementation of clients repository layer.
private
Private package is a service wrapper around the underlying Repository.
Private package is a service wrapper around the underlying Repository.
standalone
Package standalone contains implementation for auth service in single-user scenario.
Package standalone contains implementation for auth service in single-user scenario.
cmd
auth command
channels command
Package main contains clients main function to start the clients service.
Package main contains clients main function to start the clients service.
cli command
Package main contains cli main function to run the cli.
Package main contains cli main function to run the cli.
clients command
Package main contains clients main function to start the clients service.
Package main contains clients main function to start the clients service.
coap command
Package main contains coap-adapter main function to start the coap-adapter service.
Package main contains coap-adapter main function to start the coap-adapter service.
domains command
groups command
Package main contains groups main function to start the groups service.
Package main contains groups main function to start the groups service.
http command
Package main contains http-adapter main function to start the http-adapter service.
Package main contains http-adapter main function to start the http-adapter service.
journal command
Package main contains journal main function to start the journal service.
Package main contains journal main function to start the journal service.
mqtt command
Package main contains mqtt-adapter main function to start the mqtt-adapter service.
Package main contains mqtt-adapter main function to start the mqtt-adapter service.
notifications command
Package main contains notifications main function to start the notifications service.
Package main contains notifications main function to start the notifications service.
users command
Package main contains users main function to start the users service.
Package main contains users main function to start the users service.
ws command
Package main contains websocket-adapter main function to start the websocket-adapter service.
Package main contains websocket-adapter main function to start the websocket-adapter service.
Package coap contains the domain concept definitions needed to support SuperMQ CoAP adapter service functionality.
Package coap contains the domain concept definitions needed to support SuperMQ CoAP adapter service functionality.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
middleware
Package middleware provides tracing, logging and metrics middleware for SuperMQ COAP service.
Package middleware provides tracing, logging and metrics middleware for SuperMQ COAP service.
Package consumers contain the domain concept definitions needed to support SuperMQ consumer services functionality.
Package consumers contain the domain concept definitions needed to support SuperMQ consumer services functionality.
api/grpc
Package grpc contains implementation of Domains service gRPC API.
Package grpc contains implementation of Domains service gRPC API.
cache
Package cache contains the domain concept definitions needed to support SuperMQ Domains cache service functionality.
Package cache contains the domain concept definitions needed to support SuperMQ Domains cache service functionality.
events
Package events provides the domain concept definitions needed to support SuperMQ auth service functionality.
Package events provides the domain concept definitions needed to support SuperMQ auth service functionality.
middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Domains service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Domains service.
postgres
Package postgres contains Key repository implementations using PostgreSQL as the underlying database.
Package postgres contains Key repository implementations using PostgreSQL as the underlying database.
Package groups contains the domain concept definitions needed to support SuperMQ groups functionality.
Package groups contains the domain concept definitions needed to support SuperMQ groups functionality.
api/grpc
Package grpc contains implementation of Auth service gRPC API.
Package grpc contains implementation of Auth service gRPC API.
api/http
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
events
Package events contains event source Redis client implementation.
Package events contains event source Redis client implementation.
middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Domains service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Domains service.
mocks
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
postgres
Package postgres contains the database implementation of groups repository layer.
Package postgres contains the database implementation of groups repository layer.
Package http contains the domain concept definitions needed to support SuperMQ HTTP Adapter functionality.
Package http contains the domain concept definitions needed to support SuperMQ HTTP Adapter functionality.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
internal
clients
Package clients contains the domain concept definitions needed to support SuperMQ clients functionality for example: postgres, redis, grpc, jaeger.
Package clients contains the domain concept definitions needed to support SuperMQ clients functionality for example: postgres, redis, grpc, jaeger.
clients/redis
Package redis contains the domain concept definitions needed to support SuperMQ redis cache functionality.
Package redis contains the domain concept definitions needed to support SuperMQ redis cache functionality.
email
Package email contains the domain concept definitions needed to support SuperMQ email functionality.
Package email contains the domain concept definitions needed to support SuperMQ email functionality.
nullable
Package nullable contains nullable types used to handle scenarios where default values can't be used to indicate empty, and we want to avoid using pointers for that.
Package nullable contains nullable types used to handle scenarios where default values can't be used to indicate empty, and we want to avoid using pointers for that.
Package journal contains the journal service.
Package journal contains the journal service.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
events
Package events provides the event consumer for the journal service.
Package events provides the event consumer for the journal service.
middleware
Package middleware provides tracing, logging and metrics middleware for SuperMQ Journal service.
Package middleware provides tracing, logging and metrics middleware for SuperMQ Journal service.
mocks
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
postgres
Package postgres provides a postgres implementation of the journal log repository.
Package postgres provides a postgres implementation of the journal log repository.
Package logger contains logger API definition, wrapper that can be used around any other logger.
Package logger contains logger API definition, wrapper that can be used around any other logger.
Package mqtt contains the domain concept definitions needed to support SuperMQ MQTT service functionality.
Package mqtt contains the domain concept definitions needed to support SuperMQ MQTT service functionality.
events
Package events provides the domain concept definitions needed to support mqtt events functionality.
Package events provides the domain concept definitions needed to support mqtt events functionality.
tracing
Package tracing provides tracing instrumentation for SuperMQ MQTT adapter service.
Package tracing provides tracing instrumentation for SuperMQ MQTT adapter service.
Package notifications provides the domain model for the notifications service.
Package notifications provides the domain model for the notifications service.
emailer
Package emailer provides email notification implementation for the notifications service.
Package emailer provides email notification implementation for the notifications service.
events
Package events provides event handling for the notifications service.
Package events provides event handling for the notifications service.
middleware
Package middleware provides middleware for the notifications service.
Package middleware provides middleware for the notifications service.
mocks
Package mocks provides mocks for the notifications service.
Package mocks provides mocks for the notifications service.
pkg
Package pkg contains library packages used by SuperMQ services and external services that integrate with SuperMQ.
Package pkg contains library packages used by SuperMQ services and external services that integrate with SuperMQ.
channels/events
Package events provides the events sourcing of channels to provide replication in other service and definitions needed to support it
Package events provides the events sourcing of channels to provide replication in other service and definitions needed to support it
channels/events/consumer
Package consumer contains events consumer for events published by channels service.
Package consumer contains events consumer for events published by channels service.
clients/events
Package events provides the events sourcing of clients to provide replication in other service and definitions needed to support it
Package events provides the events sourcing of clients to provide replication in other service and definitions needed to support it
clients/events/consumer
Package consumer contains events consumer for events published by clients service.
Package consumer contains events consumer for events published by clients service.
errors
Package errors contains SuperMQ errors definitions.
Package errors contains SuperMQ errors definitions.
events/nats
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
events/rabbitmq
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
events/redis
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
Package redis contains the domain concept definitions needed to support SuperMQ redis events source service functionality.
groups/events
Package events provides the events sourcing of groups to provide listing in clients and channels concept definitions needed to support
Package events provides the events sourcing of groups to provide listing in clients and channels concept definitions needed to support
groups/events/consumer
Package consumer contains events consumer for events published by Bootstrap service.
Package consumer contains events consumer for events published by Bootstrap service.
grpcclient
Package auth contains the domain concept definitions needed to support SuperMQ auth functionality.
Package auth contains the domain concept definitions needed to support SuperMQ auth functionality.
jaeger
Package jaeger contains the domain concept definitions needed to support SuperMQ Jaeger tracing functionality.
Package jaeger contains the domain concept definitions needed to support SuperMQ Jaeger tracing functionality.
messaging/mqtt
Package mqtt hold the implementation of the Publisher and PubSub interfaces for the MQTT messaging system, the internal messaging broker of the SuperMQ IoT platform.
Package mqtt hold the implementation of the Publisher and PubSub interfaces for the MQTT messaging system, the internal messaging broker of the SuperMQ IoT platform.
messaging/nats
Package nats hold the implementation of the Publisher and PubSub interfaces for the NATS messaging system, the internal messaging broker of the SuperMQ IoT platform.
Package nats hold the implementation of the Publisher and PubSub interfaces for the NATS messaging system, the internal messaging broker of the SuperMQ IoT platform.
messaging/nats/tracing
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
messaging/rabbitmq
Package rabbitmq holds the implementation of the Publisher and PubSub interfaces for the RabbitMQ messaging system, the internal messaging broker of the SuperMQ IoT platform.
Package rabbitmq holds the implementation of the Publisher and PubSub interfaces for the RabbitMQ messaging system, the internal messaging broker of the SuperMQ IoT platform.
messaging/rabbitmq/tracing
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
messaging/tracing
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
Package tracing provides tracing instrumentation for SuperMQ clients policies service.
oauth2
Package oauth2 contains the domain concept definitions needed to support SuperMQ ui service OAuth2 functionality.
Package oauth2 contains the domain concept definitions needed to support SuperMQ ui service OAuth2 functionality.
oauth2/google
Package google contains the domain concept definitions needed to support SuperMQ services for Google OAuth2 functionality.
Package google contains the domain concept definitions needed to support SuperMQ services for Google OAuth2 functionality.
policies
Package policies contains SuperMQ policy definitions.
Package policies contains SuperMQ policy definitions.
policies/spicedb
Package server contains the HTTP, gRPC and CoAP server implementation.
Package server contains the HTTP, gRPC and CoAP server implementation.
postgres
Package postgres contains the domain concept definitions needed to support SuperMQ PostgreSQL database functionality.
Package postgres contains the domain concept definitions needed to support SuperMQ PostgreSQL database functionality.
prometheus
Package prometheus provides a framework for defining and collecting metrics for prometheus.
Package prometheus provides a framework for defining and collecting metrics for prometheus.
roles/rolemanager/events
Package events provides the domain concept definitions needed to support SuperMQ auth service functionality.
Package events provides the domain concept definitions needed to support SuperMQ auth service functionality.
roles/rolemanager/middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ RoleManager service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ RoleManager service.
sdk
Package sdk contains SuperMQ SDK.
Package sdk contains SuperMQ SDK.
server
Package server contains the HTTP, gRPC and CoAP server implementation.
Package server contains the HTTP, gRPC and CoAP server implementation.
server/coap
Package coap contains the CoAP server implementation.
Package coap contains the CoAP server implementation.
server/grpc
Package grpc contains the gRPC server implementation.
Package grpc contains the gRPC server implementation.
server/http
Package http contains the HTTP server implementation.
Package http contains the HTTP server implementation.
sid
Package ulid contains ULID generator.
Package ulid contains ULID generator.
transformers
Package transformers contains the domain concept definitions needed to support SuperMQ transformer services functionality.
Package transformers contains the domain concept definitions needed to support SuperMQ transformer services functionality.
transformers/json
Package json contains JSON transformer.
Package json contains JSON transformer.
transformers/senml
Package senml contains SenML transformer.
Package senml contains SenML transformer.
ulid
Package ulid contains ULID generator.
Package ulid contains ULID generator.
uuid
Package uuid contains UUID generator.
Package uuid contains UUID generator.
Package readers provides a set of readers for various formats.
Package readers provides a set of readers for various formats.
mocks
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
Package tools contains tools for SuperMQ.
Package tools contains tools for SuperMQ.
Package users contains the domain concept definitions needed to support SuperMQ users service functionality.
Package users contains the domain concept definitions needed to support SuperMQ users service functionality.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
api/grpc
Package grpc contains implementation of Users service gRPC API.
Package grpc contains implementation of Users service gRPC API.
emailer
Package emailer contains the domain concept definitions needed to support SuperMQ users email service functionality.
Package emailer contains the domain concept definitions needed to support SuperMQ users email service functionality.
events
Package events provides the domain concept definitions needed to support SuperMQ users service functionality.
Package events provides the domain concept definitions needed to support SuperMQ users service functionality.
hasher
Package hasher contains the domain concept definitions needed to support SuperMQ users password hasher sub-service functionality.
Package hasher contains the domain concept definitions needed to support SuperMQ users password hasher sub-service functionality.
middleware
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Users Service.
Package middleware provides authorization, logging, metrics and tracing middleware for SuperMQ Users Service.
mocks
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
postgres
Package postgres contains the database implementation of users repository layer.
Package postgres contains the database implementation of users repository layer.
ws
Package ws provides domain concept definitions required to support SuperMQ WebSocket adapter service functionality.
Package ws provides domain concept definitions required to support SuperMQ WebSocket adapter service functionality.
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
middleware
Package middleware provides logging, metrics and tracing middleware for SuperMQ WebSockets service.
Package middleware provides logging, metrics and tracing middleware for SuperMQ WebSockets service.

Jump to

Keyboard shortcuts

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