NAME
Plack::App::MQTT - Plack Application to provide AJAX to MQTT bridge
VERSION
version 1.112330
SYNOPSIS
use Plack::App::MQTT;
my $app = Plack::App::MQTT->new(host => 'mqtt.example.com',
allow_publish => 1)->to_app;
# Or mount under /mqtt namespace, subscribe only
use Plack::Builder;
builder {
mount '/mqtt' => Plack::App::MQTT->new();
};
DESCRIPTION
This module is a Plack application that provides an AJAX to MQTT bridge. It can be used on its own or combined with Plack::Builder to provide an AJAX MQTT interface for existing Plack applications (such as Catalyst, Dancer, etc applications).
This distribution includes an example application eg/mqttui.psgi
that can be used for testing by running:
MQTT_SERVER=127.0.0.1 plackup eg/mqttui.psgi
then accessing, for example:
http://127.0.0.1:5000/?topic=test
http://127.0.0.1:5000/?topic=test&mxhr=1
The former provides a simple long poll interface (that will often miss messages - I plan to fix this) and the later provides a more reliable "multipart/mixed" interface using the DUI.Stream library.
METHODS
new(%params)
Constructs a new Plack::App::MQTT
object. The supported parameters are:
host
-
The server host. Defaults to
127.0.0.1
. port
-
The server port. Defaults to
1883
. timeout
-
The timeout for responses from the server.
keep_alive_timer
-
The keep alive timer.
client_id
-
Sets the client id for the client overriding the default which is
Net::MQTT::Message[NNNNN]
where NNNNN is the process id. allow_publish
-
If set to true, then the
'/pub'
requests will be allowed. Otherwise they will result in a '403 forbidden' response. The default is false. mqtt
-
This attribute can be used to provide an AnyEvent::MQTT instance. If it is not supplied an instance is created using the
host
,port
, etc. parameters. If it is supplied those parameters are ignored.
call($env)
This method routes HTTP requests to /pub
, /sub
and /submxhr
to the "publish($env, $req, $topic)", "subscribe($env, $req, $topic)", or "submxhr($env, $req, $topic)" methods respectively.
If the topic fails the "is_valid_topic($topic)" test then a 403 error is returned. If the request is '/pub'
then a 403 error is returned unless the allow_publish
parameter was passed a true value to the constructor.
is_valid_topic($topic)
This helper method returns true if the topic is valid. If the topic_regexp
parameter was passed to the constructor, then the topic is valid if it matches that expression. Otherwise any topic is valid.
return_404([$message])
This helper method constructs a 404 response with the given message or 'not found' if no message is supplied.
return_403([$message])
This helper method constructs a 403 response with the given message or 'forbidden' if no message is supplied.
publish($env, $req, $topic)
This method processes HTTP requests to /pub
. It requires topic
and message
parameters and returns the JSON '{ success: 1 }' when the message has been published.
subscribe($env, $req, $topic)
This method processes HTTP requests to /sub
. It requires a topic
parameter and returns the next MQTT message received on that topic as a JSON record for the form:
{ type: 'mqtt_message', message: 'message', topic: 'topic' }
TODO: need to add per-client backlog to avoid missing messages
submxhr($env, $req, $topic)
This method processes HTTP requests to /submxhr
. It requires a topic
parameter and returns a 'multipart/mixed' response with a series of JSON records for the form:
{ type: 'mqtt_message', message: 'message', topic: 'topic' }
API
This is an early release and the API is very likely to change in subsequent releases.
DISCLAIMER
This is not official IBM code. I work for IBM but I'm writing this in my spare time (with permission) for fun.
AUTHOR
Mark Hindess <soft-cpan@temporalanomaly.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Mark Hindess.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.