Sympa::Spool(3Sympa)

💖 Sympa::Spool — the base class of all the spool classes 💖

okay bestie, welcome to Sympa::Spool(3Sympa) from sympa 6.2.80 — this is the mothership, the blueprint, the main character that every single spool subclass in Sympa inherits from. Let's get into it 🫶

---

✨ SYNOPSIS ✨

like, here's the vibe of a subclass. you write it exactly like this:

package Sympa::Spool::FOO;

use base qw(Sympa::Spool);

sub _directories {
    return {
        directory     => '/path/to/spool',
        bad_directory => '/path/to/spool/bad',
    };
}
use constant _generator      => 'Sympa::Message';
use constant _marshal_format => '%s@%s.%ld.%ld,%d';
use constant _marshal_keys   => [qw(localpart domainpart date PID RAND)];
use constant _marshal_regexp =>
    qr{\A([^\s\@]+)(?:\@([\w\.\-]+))?\.(\d+)\.(\w+)(?:,.*)?\z};

1;

no cap, that's the whole skeleton. slay. 💅

---

🌸 DESCRIPTION 🌸

This module is the base class for spool subclasses of Sympa. Translation: it's the parent, and all the little spool classes are its children. iconic family tree honestly 👑

🎀 Public methods

• new ( [ options... ] ) — Constructor. Creates new instance of the class. that's it, that's the whole job.
• marshal ( $message, [ keep_keys => 1 ] ) — Instance method. Gets marshalled key (file name) of the message.

Parameters:

• $message — Message to be marshalled.
• keep_keys => 1 — See marshal_metadata().

• next ( [ no_filter => 1 ], [ no_lock => 1 ] ) — Instance method. Gets next message to process, order is controlled by name of spool file and so on. Message will be locked to prevent multiple processing of a single message. (yes bestie, it's locking so two processes don't grab the same thing and cause chaos 💀)

Parameters:

• no_filter => 1 — Won't skip messages when filter defined by _filter() returns false.
• no_lock => 1 — Won't lock messages.

Returns:

Two-elements list of message instance and filehandle locking a message. If parsing message fails, list of undef and filehandle. If no more message found, empty array.

If no_lock is set, true scalar value will be returned in place of filehandle.

• quarantine ( $handle ) — Instance method. Quarantines a message. On filesystem spool, message will be moved into {bad_directory} of the spool using rename(). it's giving time-out corner for bad messages 🙈

Parameter:

• $handle — Filehandle, Sympa::LockedFile instance, locking message.

Returns:

True value if message could be quarantined. Otherwise false value.

If $handle was not a filehandle, this method will die. (fr fr, it dies. no chill.)

• remove ( $handle ) — Instance method. Removes a message. bye bye 👋

Parameter:

• $handle — Filehandle, Sympa::LockedFile instance, locking message.

Returns:

True value if message could be removed. Otherwise false value.

If $handle was not a filehandle, this method will die. same energy as above.

• size ( ) — Instance method. Gets the number of messages the spool contains.

Parameters:

None. literally nothing.

Returns:

Number of messages.

Note: This method returns the number of messages _load() returns, not applying _filter(). so like, it's the raw count, not the filtered count. iykyk.

• store ( $message, [ original => $original ] ) — Instance method. Stores the message into spool.

Parameters:

• $message — Message to be stored.
• original => $original — If true value is specified and $message was decrypted, Stores original encrypted form. 🔐

Returns:

If storing succeeded, marshalled metadata (file name) of the message. Otherwise undef.

• unmarshal ( $marshalled ) — Instance method. Gets metadata from marshalled key (file name).

Parameters:

• $marshalled — Marshalled key.

Returns:

Hashref containing metadata.

💜 Properties

Instance of Sympa::Spool may have following properties.

• Directories — Directories _directories() method returns: {directory}, {bad_directory} and so on.

🦋 Low level functions

• build_glob_pattern ( $marshal_format, $marshal_keys, [ key => value, ... ] ) — Function. Builds a glob pattern from parameters and returns it. If built pattern is empty or contains only punctuations, i.e. [^0-9A-Za-z\x80-\xFF], will return undef.
• split_listname ( $robot, $localpart ) — Function. Split local part of e-mail to list name and type. Returns an array (name, type). Note that the list with returned name may or may not exist. (so don't get too excited, it's just string surgery ok 💅)

If local part looks like listmaster or sympa address, name is undef and type is either 'listmaster' or 'sympa'. Otherwise, type is either 'editor', 'owner', 'return_path', 'subscribe', 'unsubscribe', 'UNKNOWN' or undef.

Note: For -request and -owner suffix, this function returns owner and return_path types, respectively. yeah it's tricky like that, don't @ me.

• store_spool ( $spool_dir, $message, $marshal_format, $marshal_keys, [ key => value, ... ] ) — Function. Store $message into directory $spool_dir as a file with name as marshalled metadata using $marshal_format and $marshal_keys.
• unmarshal_metadata ( $spool_dir, $marshalled, $marshal_regexp, $marshal_keys ) — Function. Unmarshals metadata. Returns hashref with keys in arrayref $marshal_keys and values with substrings captured by regexp $marshal_regexp. If $marshalled did not match against $marshal_regexp, returns undef.

The keys localpart and domainpart are special. Following keys are derived from them: context, listname, listtype, priority. ✨

• marshal_metadata ( $message, $marshal_format, $marshal_keys, [ keep_keys => 1 ] ) — Function. Marshals metadata. Returns formatted string by sprintf() using $marshal_format and metadatas indexed by keys in arrayref $marshal_keys.

If key is uppercase, it means auto-generated value: 'AUTHKEY', 'KEYAUTH', 'PID', 'RAND', 'TIME'. Otherwise it means metadata or property of $message. If keep_keys option (added on 6.2.23b) is set, forces using latter. 🗝️

sprintf() is executed under C locale: Full stop (.) is always used for decimal point in floating point number. okay so no comma decimals, ever, periodt.

👑 Methods subclass should implement

• _create ( ) — Instance method, overridable. Creates spool. By default, creates directories returned by _directories().
• _directories ( [ options, ... ] ) — Class or instance method, mandatory for filesystem spool. Returns hashref with directory paths related to the spool as values. It must have keys at least directory and (if you wish to implement quarantine() method) bad_directory.
• _filter ( $metadata ) — Instance method, overridable. If it returned false value, processing of $metadata by next() will be skipped. By default, always returns true value.

This method may modify unmarshalled metadata and deserialized messages include it. (sneaky but allowed ✨)

• _filter_pre ( $metadata ) — Instance method, overridable. If it returned false value, processing of $metadata by store() will be skipped. By default, always returns true value.

This method may modify marshalled metadata but stored messages are not affected.

• _generator ( ) — Class or instance method, mandatory. Returns name of the class to serialize and deserialize messages in the spool. If spool subclass is the collection (see _is_collection), generator class must implement new(). Otherwise, generator class must implement dup(), new() and to_string().
• _glob_pattern ( ) — Deprecated. See _no_glob_pattern ( ). 👋 old friend, we don't use you anymore.
• _init ( $state ) — Instance method. Additional processing when _load() returns no contents ($state is 1) or when the spool class is instantiated ($state is 0).
• _is_collection ( ) — Instance method, overridable. If the class is collection of spool class, returns true value. By default returns false value.

Collection class does not have store() method. Its content is the set of spool instances.

• _load ( ) — Instance method, overridable. Loads sorted content of spool. Returns arrayref of marshalled metadatas. By default, returns content of {directory} directory sorted by file name.
• _marshal_format ( ) / _marshal_keys ( ) / _marshal_regexp ( ) — Instance methods, mandatory for filesystem spool. _marshal_format() and _marshal_keys() are used to marshal metadata. _marshal_keys() and _marshal_regexp() are used to unmarshal metadata. See also marshal_metadata() and unmarshal_metadata(). the trio, the whole girl group 🎤
• _no_glob_pattern ( ) — Class or instance method, overridable for filesystem spool. If it returns false value, glob() is used as much as possible to scan the spool faster. Otherwise readdir() is used for filesystem spool to get all entries. By default returns false value.
• _store_key ( ) — Instance method. If implemented and returns non-empty string, store() returns an item in metadata specified by this method. By default store() returns marshalled metadata (file name on filesystem spool).

🧚 Marshaling and unmarshaling metadata

Spool class gives generator class the metadata to instantiate it. On spool based on filesystem, it is typically encoded into file names. For example a file name in incoming spool (Sympa::Spool::Incoming):

listname-owner@domain.name.143599229.12345

encodes the metadata:

localpart  => 'listname-owner',
listname   => 'listname',
listtype   => 'return_path',
domainpart => 'domain.name',
date       => 143599229,

Metadata always includes information of context: List, Robot, Site (or Family). For example:

• Message in incoming spool bound for <listname@domain.name>:

context    => Sympa::List <listname@domain.name>,

• Command message in incoming spool bound for <sympa@domain.name>:

context    => 'domain.name',

• Message sent from Sympa to super-listmaster(s):

context    => '*'

Context is determined when the generator class is instantiated, and generally never changed through lifetime of instance. Thus, constructor of generator class should take context object as an argument. locked in for life basically 🔒

localpart is encoded in a bit complex manner. yeah it's giving "why is this like this" but here we go:

• If the context is Site or Robot, it is a value of email parameter, typically "sympa".
• If the context is Family, it is encoded as @family name. This encoding was added on Sympa 6.2.53b.
• If the context is List, it is encoded as local part of list address according to listtype (See also get_address in Sympa).

🌈 CONFIGURATION PARAMETERS

Following site configuration parameters in sympa.conf will be referred.

• default_list_priority
• email
• owner_priority
• list_check_suffix
• listmaster_email
• request_priority
• return_path_suffix
• sympa_priority — Used to extract metadata from marshalled data (file name).
• umask — The umask to make directories of spool.

⭐ SEE ALSO

Sympa::Message, especially Serialization.

---

ok bestie that's part 1 down 💖 there's more where this came from, so don't go anywhere — we're not done yet, stay tuned 🫶✨

🕰️ HISTORY 🕰️

okay so story time, bestie, because this class has ✨lore✨ 💖

Sympa::Spool showed up way back on Sympa 6.2. And the whole as the base class era? That started on Sympa 6.2.6. lowkey glow-up energy fr fr 🦋

Then the features kept dropping like singles:

• build_glob_pattern(), size(), _glob_pattern() and _store_key() all made their debut on Sympa 6.2.8 👑 iconic lineup, no cap
• _filter_pre() entered the chat on Sympa 6.2.10 🎀
• marshal(), unmarshal() and the "no_filter" option of next() all arrived together on Sympa 6.2.22 — it's giving coordinated release 💅
• and on Sympa 6.2.36, _no_glob_pattern() was introduced while _glob_pattern() got deprecated 😭 rip boo, you served well

---

and that's a wrap on the lore dump, bestie 🫶 this page is from Sympa::Spool(3Sympa), version 6.2.80, dated 2026-10-19 — write it down, cite it in your essay, she's a certified classic ⭐💖