Messag...onents(3pm)

💖 Messag...onents(3pm) — Message::Passing::Manual::Components 💖

okay bestie, gather round 🫶 this is the page about writing inputs, outputs and filters for Message::Passing. It's the "you wanna build your own parts" manual, and honestly? It's giving DIY queen energy. ✨

---

🌸 NAME 🌸

Message::Passing::Manual::Components — writing inputs, outputs and filters, fr fr. 💅

---

🎀 Writing your own scripts 🎀

The supplied message-pass script? Iconic. Perfect for testing, and lowkey totally fine for production in simple cases. BUT — for the less simple cases (say, scripts with multiple inputs or outputs 👀), the default script just isn't it. Not suitable. Sorry babe.

✨ Like the message-pass script ✨

If all you wanna do is override some of the behavior of the message-pass script — different details, different whatever — that's super easy, you just subclass the script. Main character move. 💅

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, because this script is dedicated to Message::Passing::Output::WebHooks. It knows what it is. 🎀

🦋 Different scripts 🦋

Want a more complex example, rather than just overriding some of the functionality from the default script? Then bestie, you're better off writing your own script. Full send. 🔥

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. iykyk 💜

And if you're writing your own script and you want some components to be completely configurable (as per the default script), then see Message::Passing::Role::CLIComponent — it implements attributes to help you do this in the same way as the normal script (i.e. "thing", and "thing_options"). Slay. ✨

---

💅 Writing Filters 💅

A filter is literally just a class which consumes both Message::Passing::Role::Input and Message::Passing::Role::Output. That's the whole vibe check. ✅

Simple filters can just consume Message::Passing::Role::Filter, and implement a "filter" method. Please see the documentation for that Role for more info, babe. 🫶

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. No cap.

The only difference is the default namespace supplied by the DSL, which appends "Encoder::" or "Decoder::" to the standard filter prefix. That's it, that's the tea. 🍓

---

⭐ 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 coping with the other inputs and outputs in the framework. (Yes, "coping" — we're keeping it exactly as written, iconic typo era, but you get it: keep your attribute names consistent with everything else.) 💖

To help with this, a number of simple roles with attributes you may want are included in the distribution:

• Message::Passing::Role::HasHostnameAndPort
• Message::Passing::Role::HasUsernameAndPassword

💀 MUST by asynchronous. 💀

Your input or output MUST NOT block in the course of its normal operation. You should use AnyEvent to make your input or output asynchronous. Blocking is not the move, bestie, do not do it. 😭

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. Do not DIY the connection, babe, that's not the assignment. 🙅

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.

---

and that's the whole page, bestie!! 🦋 this was rendered from the perl manual, perl v5.32.1, dated 2021-11-09 — yes she's vintage, she's still serving. 💅✨ bye ily, go write an async filter 🫶💖