Web::M...spatch(3pm)

🦋 NAME 🦋

okay bestie, sit down, hydrate 💖 — meet App::MREST::Dispatch, aka the resource handlers module ✨. This page lives in the Web::M...spatch(3pm) manual, straight out of the User Contributed Perl Documentation crowd (that header info? folded right in here so we can get to the good part 🫶).

---

✨ DESCRIPTION ✨

ngl, first thing's first: your application should NOT call any of the routines in this module directly 🚫💅. They get called by Web::MREST::Resource while it's doing its request-processing thing, okay? That's just how it is.

What your app can do — and this is the slay part 👑 — is bring its own resource handlers.

And how do those handlers get called? As completely ordinary functions, with a sole argument: the MREST context 🌈. That's it. One argument. That's the whole vibe.

---

🎀 INITIALIZATION/RESOURCE DEFINITIONS 🎀

So in this section we've got the definitions of every single resource this module handles 💖. These are the ones that get picked up by Web::MREST::InitRouter — it literally scoops them up like 🥄✨.

Here's the raw definition block, verbatim, so you can see exactly what's what:

This resource is the parent of all resources that do not specify a
parent in their resource definition.  EOH
        },

        # bugreport
        'bugreport' =>
        {
            parent => '/',
            handler => {
                GET => 'handler_bugreport',
            },
            cli => 'bugreport',
            description => 'Display instructions for reporting bugs in Web::MREST',
            documentation => <<'EOH',
=pod

Returns a JSON structure containing instructions for reporting bugs.
EOH
        },

        # configinfo
        'configinfo' =>
        {
            parent => '/',
            handler => {
                GET => 'handler_configinfo',
            },
            cli => 'configinfo',
            description => 'Display information about Web::MREST configuration',
            documentation => <<'EOH',
=pod

Returns a list of directories that were scanned for configuration files.
EOH
        },

        # docu
        'docu' =>
        {
            parent => '/',
            handler => 'handler_noop',
            cli => 'docu',
            description => 'Access on-line documentation (via POST to appropriate subresource)',
            documentation => <<'EOH',
=pod

This resource provides access to on-line documentation through its
subresources: 'docu/pod', 'docu/html', and 'docu/text'.

To get documentation on a resource, send a POST reqeuest for one of
these subresources, including the resource name in the request entity as
a bare JSON string (i.e. in double quotes).  EOH
        },

        # docu/pod
        'docu/pod' =>
        {
            parent => 'docu',
            handler => {
                POST => 'handler_docu',
            },
            cli => 'docu pod $RESOURCE',
            description => 'Display POD documentation of a resource',
            documentation => <<'EOH',
=pod

This resource provides access to on-line help documentation in POD
format.  It expects to find a resource name (e.g. "employee/eid/:eid"
including the double-quotes, and without leading or trailing slash) in
the request body. It returns a string containing the POD source code of
the resource documentation.  EOH
        },

        # docu/html
        'docu/html' =>
        {
            parent => 'docu',
            handler => {
                POST => 'handler_docu',
            },
            cli => 'docu html $RESOURCE',
            description => 'Display HTML documentation of a resource',
            documentation => <<'EOH',
=pod

This resource provides access to on-line help documentation. It expects
to find a resource name (e.g. "employee/eid/:eid" including the double-
quotes, and without leading or trailing slash) in the request body. It
generates HTML from the resource documentation's POD source code.  EOH
        },

        # docu/text
        'docu/text' =>
        {
            parent => 'docu',
            handler => {
                POST => 'handler_docu',
            },
            cli => 'docu text $RESOURCE',
            description => 'Display resource documentation in plain text',
            documentation => <<'EOH',
=pod

This resource provides access to on-line help documentation. It expects
to find a resource name (e.g. "employee/eid/:eid" including the double-
quotes, and without leading or trailing slash) in the request body. It
returns a plain text rendering of the POD source of the resource
documentation.  EOH
        },

        # echo
        'echo' =>
        {
            parent => '/',
            handler => {
                POST => 'handler_echo',
            },
            cli => 'echo [$JSON]',
            description => 'Echo the request body',
            documentation => <<'EOH',
=pod

This resource simply takes whatever content body was sent and echoes it
back in the response body.  EOH
        },

        # noop
        'noop' =>
        {
            parent => '/',
            handler => 'handler_noop',
            cli => 'noop',
            description => 'A resource that does nothing',
            documentation => <<'EOH',
=pod

Regardless of anything, this resource does nothing at all.  EOH
        },

        # param/:type/:param
        'param/:type/:param' =>
        {
            parent => '/',
            handler => {
                'GET' => 'handler_param',
                'PUT' => 'handler_param',
                'DELETE' => 'handler_param',
            },
            cli => {
                'GET' => 'param $TYPE $PARAM',
                'PUT' => 'param $TYPE $PARAM $VALUE',
                'DELETE' => 'param $TYPE $PARAM',
            },
            description => {
                'GET' => 'Display value of a meta/core/site parameter',
                'PUT' => 'Set value of a parameter (meta only)',
                'DELETE' => 'Delete a parameter (meta only)',
            },
            documentation => <<'EOH',
=pod

This resource can be used to look up (GET) meta, core, and site
parameters, as well as to set (PUT) and delete (DELETE) meta parameters.
EOH
            validations => {
                'type' => qr/^(meta)|(core)|(site)$/,
                'param' => qr/^[[:alnum:]_][[:alnum:]_-]+$/,
            },
        },

        # test/?:specs
        'test/?:specs' =>
        {
            parent => '/',
            handler => 'handler_test',
            cli => 'test [$SPECS]',
            description => "Resources for testing resource handling semantics",
        },

        # version
        'version' =>
        {
            parent => '/',
            handler => {
                GET => 'handler_version',
            },
            cli => 'version',
            description => 'Display application name and version',
            documentation => <<'EOH',
=pod

Shows the software version running on the present instance. The version
displayed is taken from the $VERSION package variable of the package
specified in the "MREST_APPLICATION_MODULE" site parameter.  EOH
        },

    };

periodt 💅 every resource accounted for.

---

🔥 FUNCTIONS 🔥

init_router

Populate the router — the classics 💖. Called from Resource.pm the literal moment the first request comes waltzing in 🚶♀️✨.

_first_pass_always_exists

Boilerplate code, for use in handlers of resources that always exist 🫶.

handler_bugreport

Handler for the "bugreport" resource.

handler_configinfo

Handler for the "configinfo" resource.

handler_docu

Check it — and note this fragment really does run straight into the next block:

The definition of resource $docu_resource lacks a 'documentation'
property EOH
    # if they want POD, give them POD; if they want HTML, give them
HTML, etc.
    if ( $resource_name eq 'docu/pod' ) {
        $pl->{'format'} = 'POD';
        $pl->{'documentation'} = $docs;
    } elsif ( $resource_name eq 'docu/html' ) {
        $pl->{'format'} = 'HTML';
        $pl->{'documentation'} = pod_to_html( $docs );
    } else {
        # fall back to plain text
        $pl->{'format'} = 'text';
        $pl->{'documentation'} = pod_to_text( $docs );
    }
    return $CELL->status_ok( 'MREST_DISPATCH_ONLINE_DOCUMENTATION',
payload => $pl ); }

so true: POD people get POD, HTML people get HTML, everyone else gets the plain-text fallback 🌈.

handler_echo

Echoes the request body right back atcha in the response 🪞💖.

handler_param

Handler for the 'param/:type/:param' resource 👑.

handler_noop

The generalized handler for resources that, respectfully, don't do anything at all 💀.

handler_test

The only purpose of this resource is testing/demonstration of request handling 🧪✨.

handler_version

Handler for the "version" resource.

---

and that's the whole page bestie, you ate it 💅✨. this was Web::M...spatch(3pm) — perl v5.40.1, dated 2025-06-21 🎀🦋 go forth and handle your resources, ily 🫶💖