• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
  • Roles Consumed
• ATTRIBUTES
  • logger
  • destination_path_map
  • one_shot
• METHODS
  • run
  • frame_loop
  • handle_stomp_frame
  • handle_stomp_error
  • handle_stomp_message
  • process_the_message
  • handle_stomp_receipt
  • maybe_send_reply
  • where_should_send_reply
  • send_reply
  • subscribe_single
  • build_psgi_env
• EXAMPLES
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

Plack::Handler::Stomp - adapt STOMP to (almost) HTTP, via Plack

VERSION

version 1.15

SYNOPSIS

  my $runner = Plack::Handler::Stomp->new({
    servers => [ { hostname => 'localhost', port => 61613 } ],
    subscriptions => [
      { destination => '/queue/plack-handler-stomp-test' },
      { destination => '/topic/plack-handler-stomp-test',
        headers => {
            selector => q{custom_header = '1' or JMSType = 'test_foo'},
        },
        path_info => '/topic/ch1', },
      { destination => '/topic/plack-handler-stomp-test',
        headers => {
            selector => q{custom_header = '2' or JMSType = 'test_bar'},
        },
        path_info => '/topic/ch2', },
    ],
  });
  $runner->run(MyApp->get_app());

DESCRIPTION

Sometimes you want to use your very nice web-application-framework dispatcher, module loading mechanisms, etc, but you're not really writing a web application, you're writing a ActiveMQ consumer. In those cases, this module is for you.

This module is inspired by Catalyst::Engine::Stomp, but aims to be usable by any PSGI application.

Roles Consumed

We consume Net::Stomp::MooseHelpers::CanConnect and Net::Stomp::MooseHelpers::CanSubscribe. Read those modules' documentation to see how to configure servers and subscriptions.

ATTRIBUTES

logger

A logger object used by thes handler. Not to be confused by the logger used by the application (either internally, or via a Middleware). Can be any object that can trace, debug, info, warn, error. Defaults to an instance of Log::Any::Proxy. This logger is passed on to the Net::Stomp object held in connection (see Net::Stomp::MooseHelpers::CanConnect).

destination_path_map

A hashref mapping destinations (queues, topics, subscription ids) to URI paths to send to the application. You should not modify this.

one_shot

If true, exit after the first message is consumed. Useful for testing, defaults to false.

METHODS

run

Given a PSGI application, loops forever:

• connect to a STOMP server (see connect and servers in Net::Stomp::MooseHelpers::CanConnect)

• subscribe to whatever needed (see subscribe and subscriptions in Net::Stomp::MooseHelpers::CanSubscribe)

• consume STOMP frames in an inner loop (see "frame_loop")

If the application throws an exception, the loop exits re-throwing the exception. If the STOMP connection has problems, the loop is repeated with a different server (see next_server in Net::Stomp::MooseHelpers::CanConnect).

If "one_shot" is set, this function exits after having consumed exactly 1 frame.

frame_loop

Loop forever receiving frames from the STOMP connection. Call "handle_stomp_frame" for each frame.

If "one_shot" is set, this function exits after having consumed exactly 1 frame.

handle_stomp_frame

Delegates the handling to "handle_stomp_message", "handle_stomp_error", "handle_stomp_receipt", or throws Plack::Handler::Stomp::Exceptions::UnknownFrame if the frame is of some other kind. If you want to handle different kind of frames (maybe because you have some non-standard STOMP server), you can just subclass and add methods; for example, to handle STRANGE frames, add a handle_stomp_strange method.

handle_stomp_error

Logs the error via the "logger", level warn.

handle_stomp_message

Calls "build_psgi_env" to convert the STOMP message into a PSGI environment.

The environment is then passed to "process_the_message", and the frame is acknowledged.

process_the_message

Runs a PSGI environment through the application, then flattens the response body into a simple string.

The response so flattened is sent back via "maybe_send_reply".

handle_stomp_receipt

Logs (level debug) the receipt id. Nothing else is done with receipts.

maybe_send_reply

Calls "where_should_send_reply" to determine if to send a reply, and where. If it returns a true value, "send_reply" is called to actually send the reply.

where_should_send_reply

Returns the header X-Reply-Address or X-STOMP-Reply-Address from the response.

send_reply

Converts the PSGI response into a STOMP frame, by removing the prefix x-stomp- from the key of header fields that have it, removing entirely header fields that don't, and stringifying the body.

Then sends the frame.

subscribe_single

after modifier on the method provided by Net::Stomp::MooseHelpers::CanSubscribe.

It sets the "destination_path_map" to map the destination and the subscription id to the path_info slot of the "subscriptions" element, or to the destination itself if path_info is not defined.

build_psgi_env

Builds a PSGI environment from the message, like:

  # server
  SERVER_NAME => 'localhost',
  SERVER_PORT => 0,
  SERVER_PROTOCOL => 'STOMP',

  # client
  REQUEST_METHOD => 'POST',
  REQUEST_URI => $path_info,
  SCRIPT_NAME => '',
  PATH_INFO => $path_info,
  QUERY_STRING => '',

  # broker
  REMOTE_ADDR => $server_hostname,

  # http
  HTTP_USER_AGENT => 'Net::Stomp',
  CONTENT_LENGTH => length($body),
  CONTENT_TYPE => $content-type,

  # psgi
  'psgi.version' => [1,0],
  'psgi.url_scheme' => 'http',
  'psgi.multithread' => 0,
  'psgi.multiprocess' => 0,
  'psgi.run_once' => 0,
  'psgi.nonblocking' => 0,
  'psgi.streaming' => 1,

In addition, reading from psgi.input will return the message body, and writing to psgi.errors will log via the "logger" at level error.

Finally, every header in the STOMP message will be available in the "namespace" jms., so for example the message type is in jms.type.

The $path_info is obtained from the "destination_path_map" (i.e. from the path_info subscription options) passed through munge_path_info.

EXAMPLES

You can find examples of use in the tests, or at https://github.com/dakkar/CatalystX-StompSampleApps

AUTHOR

Gianni Ceccarelli <gianni.ceccarelli@net-a-porter.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Net-a-porter.com.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.