HTTP Bridge

Premium

The purpose of the HTTP Bridge is to bridge data messages between the Mosquitto MQTT broker and a HTTP Webserver. With the current version the user may forward incoming MQTT messages to a HTTP Webserver using REST calls. Each webserver, which should be addressed by the HTTP Bridge, is configured using a remote definition. For each remote definition multiple mappings from a MQTT topic to a HTTP URL may be defined. For each message published to the configured topic the corresponding webservice will be invoked forwarding the MQTT messages as the Webservice body.

Activation and configuration options

Like all other mosquitto plugins the HTTP Bridge plugin needs to be activated in the mosquitto configuration file (by default named mosquitto.conf). To activate the HTTP Bridge plugin you need to add an new plugin entry to the mosquitto.conf pointing to the absolute path of the plugin shared object file. Additionally you have to specify a subsequent new entry plugin_opt_config_file pointing to the name of the plugin configuration file path. The format of the config file is described in the next section. If the config file does not exist the HTTP Bridge plugin will create a new file with an default configuration frame.

For the Cedalo Mosquitto premium dockerfile the additional entry most times looks like:

plugin /usr/lib/cedalo_http_bridge.so
plugin_opt_config_file /mosquitto/data/http-bridge.json

Config file Format

The config file contains a JSON dump of the HTTP Bridge configuration. The config is stored in a single JSON object.

The object must contain an element name remotes, which is of array type. This array contains one JSON object for each remote HTTP server to address. Minimal valid config file will look like:

{"remotes": []}

Remote definition

Overview over all currently supported members:

member	type	description	default
id	string	Unique id of the remote definition.
base_url	string	Base URL for the HTTP requests.
max_concurrent_requests	integer	Max number of concurrent requests.	100
max_queued_requests	integer	Max number of queued requests.	10000
push	array	Array of the push definitions.

Each individual remote definition in the HTTP Bridge configuration is a JSON object and must* have a member id of string type to identify this remote definition. The value of this type has to be unique over all remote definitions.

The remote definition may have an member base_url of type string. The value of the base_url member will be used as the base URL for the HTTP requests. The base_url member may contain variables, which will be replaced for each request (see Variable substitution below).

Each remote definiton may have a member max_concurrent_requests of intger type. This is the number of concurrent HTTP requests performed against this remote server at the same time. If the number of required requests starts exceeding the configured limit the HTTP Bridge will start queuing the requests. The limit may be disabled configuring a value lower than 1. But this may lead to inifite growing memory usage as the server, if the remote server cannot response fast enough. Therefor we highly recommend to configure a limit.

Each remote definiton may have a member max_queued_requests of intger type. This is the number of HTTP requests queued for processing. A HTTP request will pushed into the queue, if a max_concurrent_requests limit is configured. If the number of queued requests exceeds the configured limit the HTTP Birdge will drop the oldest queued request to keep the limit. For the dropped request and error with HTTP status code 400 will be created.

Each remote definition shall have a member push of array type. This array contains one JSON objects response to define which data should be pushed from a broker topic to the remote HTTP server.

Push definition

Each data push definition in the HTTP Bridge configuration is JSON object defining the topic to HTTP request mapping, which will be used to push data to the HTTP server.

Overview over all currently supported members:

member	type	description
id	string	id of the push definition. Has to be unique inside the scope of the remote definition.
topic	string	Topic to subscribe to.
method	string	HTTP request method to be used.
format	string	Format of the messages payload to be pushed.
path	string	Path to be used for the HTTP requests on the server.
query	string	HTTP query part of the URL to be used in the HTTP requests.
error_topic	string	Topic to push error messages to

Each push definition must have a member id of string type. This identifier is used to identify the push definition inside the remote definition. Therefore this member must be unique inside the remote defition. push definitions inside different remote definitions may have the same identifier.

Each push definition must have a member topic of string type. The value of this member is the topic, which the HTTP bridge will to subscribe for incoming messages. The topic may contain wildcard(s) as they are supported by mosquitto. The topic is available in a variable topic, which may be used in the remote definition base_url member, in the push definition path member or the push definition query member.

Each push definition may contain a member method of string type. The value defines the HTTP request method to be used. In the current version only the request method type POST is supported.

Each push definition may contain a member format of string type. The value of this member defines the format of the HTTP request payload to be used in the HTTP request. In the current version for a HTTP POST request only the payload format "JSON" is supported. As the HTTP bridge does not perform any data transformation the message published to the mosquitto broker on the subscribed topic MUST be valid JSON formatted messages.

Each push definition may contain a member path of string type. The value will appended to the base_url of the remote definition adding a slash between the base_url of the remote definition and the path of the push definition. If the remote defition does not specify a base_url the path member is mandatory. The path member may contain variables, which will be replaced for each HTTP request. (see Variable substitution below).

Each push definition may contain a member query ot string type. The value will be appended to the URL build from remote definition base_url and the push definition path member. A question mark will be used to concatenate the URL and the query part of the URL. The query value may contain variables, which will be replaced for each request. Variable values in the query part of the URL will be URL encoded.

Each push definition may contain a member error_topic of string type. If the error_topic is specified the HTTP bridge will publish a message to the secified topic in case of a HTPP request error. The error message will be a JSON object containing the following members:

• topic Topic the message was subscribed from
• http_code HTTP response code from the server. If the request fails before being send a HTTP status code 400 will be set. If the server could no be reached HTTP status code 503 will be given.
• error_op Description of the operation being not successfull during request execution.
• error_text Error text describing the error condition preventing the request execution.
• payload Original subscribed message serialized into a string field.
• response The HTTP server response serialized into a single string field.

Variable substitution

In some config members varialbes may be used, which will be replaced before performing the HTTP request. Each variable is identified by the dollar ($) sign. The HTTP Bridge Plugin supports the following variables:

variable	description
topic	Contains the effective topic of the subscription.

Currently variables may be used in the following config members. And will be substituted with the listed encoding:

definition	member	encoding
remote	base_url	As is.
push	path	As is
push	query	URL encoded