---
name: "Message::Passing"
section: "3pm"
platform: "linux"
package: "libmessage-passing-perl"
version: "0.117-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Message::Passing"
---

# Message::Passing(3pm)

a simple way of doing messaging.

## NAME

Message::Passing - a simple way of doing messaging.

## SYNOPSIS

```
    message-pass --input STDIN --output STDOUT
    {"foo": "bar"}
    {"foo":"bar"}
```

## DESCRIPTION

A library for building high performance, loosely coupled and reliable/resilient applications, structured as small services which communicate over the network by passing messages.

### BASIC PREMISE

You have data for discrete events, represented by a hash (and serialized as JSON).

This could be a text log line, an audit record of an API event, a metric emitted from your application that you wish to aggregate and process - anything that can be a simple hash really..

You want to be able to shove these events over the network easily, and aggregate them / filter and rewrite them / split them into worker queues.

This module is designed as a simple framework for writing components that let you do all of these things, in a simple and easily extensible manor.

For a practical example, You generate events from a source (e.g. ZeroMQ output of logs and performance metrics from your Catalyst FCGI or Starman workers) and run one script that will give you a central application log file, or push the logs into Elasticsearch.

There are a growing set of components you can plug together to make your solution.

Getting started is really easy - you can just use the `"message-pass"` command installed by the distribution. If you have a common config that you want to repeat, or you want to write your own server which does something more flexible than the normal script allows, then see Message::Passing::DSL.

To dive straight in, see the documentation for the command line utility message-pass, and see the examples in Message::Passing::Manual::Cookbook.

For more about how the system works, see Message::Passing::Manual::Concepts.

## COMPONENTS

Below is a non-exhaustive list of components available.

### INPUTS

Inputs receive data from a source (usually a network protocol).

They are responsible for decoding the data into a hash before passing it onto the next stage.

Inputs include:

- Message::Passing::Input::STDIN

  - Message::Passing::Input::ZeroMQ

  - Message::Passing::Input::STOMP

  - Message::Passing::Input::AMQP

  - Message::Passing::Input::Syslog

  - Message::Passing::Input::Redis

  - Message::Passing::Input::Test

  You can easily write your own input, just use AnyEvent, and consume Message::Passing::Role::Input.

### FILTER

Filters can transform a message in any way.

Examples include:

- Message::Passing::Filter::Null - Returns the input unchanged.

  - Message::Passing::Filter::All - Stops any messages it receives from being passed to the output. I.e. literally filters all input out.

  - Message::Passing::Filter::T - Splits the incoming message to multiple outputs.

  You can easily write your own filter, just consume Message::Passing::Role::Filter.

Note that filters can be chained, and a filter can return undef to stop a message being passed to the output.

### OUTPUTS

Outputs send data to somewhere, i.e. they consume messages.

- Message::Passing::Output::STDOUT

  - Message::Passing::Output::AMQP

  - Message::Passing::Output::STOMP

  - Message::Passing::Output::ZeroMQ

  - Message::Passing::Output::WebHooks

  - Message::Passing::Output::Search::Elasticsearch

  - Message::Passing::Output::Redis

  - Message::Passing::Output::Test

  ## SEE ALSO

- Message::Passing::Manual - The manual (contributions cherished).

  - \<http://www.slideshare.net/bobtfish/messaging-interoperability-and-log-aggregation-a-new-framework\> - Slide deck!

  - Log::Message::Structured - For creating your log messages.

  - Log::Dispatch::Message::Passing - use Message::Passing outputs from Log::Dispatch.

  ## THIS MODULE

This is a simple MooX::Options script, with one input, one filter and one output. To build your own similar scripts, see:

- Message::Passing::DSL - To declare your message chains.

  - Message::Passing::Role::CLIComponent - To provide "foo" and "foo\_options" attribute pairs.

  - Message::Passing::Role::Script - To provide daemonization features.

  ### METHODS

*build\_chain*

Builds and returns the configured chain of input =\> filter =\> output.

*start*

Class method to call the run\_message\_server function with the results of having constructed an instance of this class, parsed command line options and constructed a chain.

This is the entry point for the script.

## AUTHOR

Tomas (t0m) Doran \<bobtfish@bobtfish.net\>

## SUPPORT

### Bugs

Please log bugs at rt.cpan.org. Each distribution has a bug tracker link in its metacpan.org page.

### Discussion

\#message-passing on irc.perl.org.

### Source code

Source code for all modules is available at \<http://github.com/suretec\> and forks/patches are very welcome.

## SPONSORSHIP

This module exists due to the wonderful people at Suretec Systems Ltd. \<http://www.suretecsystems.com/\> who sponsored its development for its VoIP division called SureVoIP \<http://www.surevoip.co.uk/\> for use with the SureVoIP API - \<http://www.surevoip.co.uk/support/wiki/api\_documentation\>

## COPYRIGHT

Copyright Suretec Systems Ltd. 2012.

Logstash (upon which many ideas for this project are based, but from which we do not reuse any code) is copyright 2010 Jorden Sissel.

## LICENSE

GNU Library General Public License, Version 2.1