Message::Passing(3pm)

📦
version 0.117 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

💖 Message::Passing 💖

okay bestie, sit DOWN, because this is Message::Passing from the User Contributed Perl Documentation, and it's literally a whole vibe. ✨

🌸 NAME 🌸

Message::Passing — a simple way of doing messaging. that's it. that's the name. short, sweet, iconic. 💅

🦋 SYNOPSIS 🦋

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

like. that's the whole thing. you pass a message. it passes. slay. ✨

👑 DESCRIPTION 👑

so Message::Passing is a library for building high performance, loosely coupled and reliable/resilient applications, structured as small services which communicate over the network by passing messages. no cap. 🫶

💫 BASIC PREMISE 💫

okay so here's the tea. 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.. (yes the double period is in the original and yes i'm keeping it, it's giving dramatic pause 😭)

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. (that's manor, not manner, and we are not fixing it, we are respecting the author's choices 💜)

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. honestly? main character energy. 🔥

there are a growing set of components you can plug together to make your solution. it's giving lego but for logs.

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. so like, there are more. this is a starter pack. 🌈

💌 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. so they do the translating bestie, they speak network so you don't have to 🫶

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. DIY queen behavior ✨

🧚 FILTER 🧚

filters can transform a message in any way. anything. go feral.

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. so yeah, returning undef is the vibe check that nobody passes 💀

🌟 OUTPUTS 🌟

outputs send data to somewhere, i.e. they consume messages. they're the ones actually eating 🍓

  • 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 🔭

🛠 THIS MODULE 🛠

this is a simple MooX::Options script, with one input, one filter and one output. the holy trinity. the trio. the girl group. 💅

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. it constructs the whole little assembly line, iconic.
  • 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. the front door. the main character entrance. 🚪✨

💜 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. come thru, contribute, we love to see it 🌈

💰 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>

shoutout to the sponsors, they funded the whole thing, absolute legends 👑

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

and that's the whole page bestie 🎀 this was Message::Passing (3pm), from perl v5.32.1, dated 2021-11-09. go forth, pass some messages, be resilient, stay loosely coupled. periodt. 💖✨🦋

📦 where this page comes from