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.

cpanm Plack::App::MQTT

perl -MCPAN -e shell
install Plack::App::MQTT