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.psgithen accessing, for example:
http://127.0.0.1:5000/?topic=test
http://127.0.0.1:5000/?topic=test&mxhr=1The 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.