NAME
Message::Passing::Manual::Components - Writing inputs, outputs and filters
Writing your own scripts
The supplied message-pass script is useful for testing, and is also fine for production use in simple cases, however, for less simple cases (for example scripts with multiple inputs or outputs), then the default script isn't suitable.
Like the message-pass script
If you just want to override some of the behavior of the message-pass script, to provide different details etc, then this is easy to do by subclassing the script.
An example of doing this is:
package Message::Passing::Script::WebHooks;
use Moo;
use MooX::Options;
use namespace::clean -except => 'meta';
extends 'Message::Passing';
option '+encoder' => (
init_arg => undef,
default => '+Message::Passing::Filter::Encoder::Null',
nogetopt => 1,
);
option '+output' => (
nogetopt => 1,
);
__PACKAGE__->start( output => 'WebHooks' ) unless caller;This shows overriding the default command line options, as this script is dedicated to Message::Passing::Output::WebHooks.
Different scripts
If you want a more complex example, rather than just overriding some of the functionality from the default script, then you're better off writing your own script.
See Message::Passing:Role::Script, for a basic role you are likely to want to use to do this. You'll also want to use Message::Passing::DSL, as shown in the example documentation for the script role..
If you are writing your own script, want some components to be completely configurable (as per the default script), then see Message::Passing::Role::CLIComponent, which implements attributes to help you do this in the same way as the normal script (i.e. thing, and thing_options).
Writing Filters
A filter is just a class which consumes both Message::Passing::Role::Input and Message::Passing::Role::Output.
Simple filters can just consume Log::Stash::Role::Filter, and implement a filter method. Please see the documentation for that Role for more information.
More complex filters can compose the input and output roles themselves, and consume / emit messages as they choose. For a simple example of this type of filter, see Message::Passing::Filter::Delay.
Encoders and Decoders
Encoders and Decoders are just implemented the same as standard filters.
The only difference is the default namespace supplied by the DSL, which appends Encoder:: or Decoder:: to the standard filter prefix.
Writing Inputs and Outputs
The interface for both inputs and outputs is conceptually very simple, however there are some gotchas to watch out for which are described below.
Use common attributes.
Please try to keep the names of your component's attributes in keeping with the other inputs and outputs in the framework.
To help with this, a number of simple roles with attributes you may want are included in the distribution:
MUST by asynchronous.
Your input or output MUST NOT block in the course of it's normal operation. You should use AnyEvent to make your input or output asynchronous.
If you are trying to convert a synchronous module into being an input, then you can often make it 'asynchronous enough' by grabbing the file descriptor and setting up an IO watcher on it. Message::Passing::Input::Freeswitch is an example of an input implemented like this.
Connecting to a server.
If your input or output connects to a server, you should be using the connection manager role supplied to manage this connection, rather than trying to manage it in your component directly.
This is so that users can have multiple inputs and outputs which share the same connection, which is both possible and desirable with a number of protocols.
Roles are provided to help component authors with this, please see the documentation in:
- Message::Passing::Role::HasAConnection - for your component
- Message::Passing::Role::ConnectionManager - to implement your connection manager.
For example code using these roles, see Message::Passing::STOMP, which implements a simple example.
AUTHOR, COPYRIGHT & LICENSE
See Message::Passing.