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

ok bestie, vibe check 💅 this is the Web::M...source(3pm) page — yes, the title up top is literally truncated like that, we don't make the rules — and it lives in the User Contributed Perl Documentation. It's giving "the HTTP request/response cycle, explained by your bestie who is also, unfortunately, extremely good at this." Let's go. 🫶

---

🌸 NAME 🌸

App::MREST::Resource — the HTTP request/response cycle, babe. 🦋

---

✨ SYNOPSIS ✨

Over in YourApp/Resource.pm, you go:

use parent 'Web::MREST::Resource';

And in your PSGI file:

use Web::Machine;

Web::Machine->new(
    resource => 'App::YourApp::Resource',
)->to_app;

Now here's the thing you absolutely need to internalize, no cap: the Web::Machine object that gets created is actually blessed into YourApp::Resource. The line of inheritance goes like this:

YourApp::Resource
    -> Web::MREST::Resource
        -> Web::Machine::Resource
            -> Plack::Component

---

💖 DESCRIPTION 💖

Your application should not be calling any of the routines in this module directly. Periodt. Web::Machine is the one calling them, during the course of request processing.

What your app can do is bring its own versions of selected routines. That's it, that's the deal. 👑

---

🎀 METHODS 🎀

🧚 Context methods

These ones are for manipulating the context — a hash where we accumulate all the info about the request.

context

Constructor/accessor. (Two jobs, one method, she's versatile.)

push_onto_context

Takes a hashref and "pushes" it onto $self->{'context'} so it's there for you later on, in the course of processing the request.

💅 Status declaration methods

So Web::Machine does take care of setting the HTTP response status code… but sometimes we have to override what Web::Machine came up with, and that's why we have this "MREST declared status" mechanism. It places a declared_status property in the context. During finalization, the HTTP status code sitting in that property overrides the one Web::Machine came up with. Iconic honestly. ✨

mrest_declare_status

This method takes either a ready-made App::CELL::Status object, or — alternatively — a PARAMHASH.

If you hand it the object, an HTTP status code can be "forced" onto the response by including an http_code property in that object.

If you hand it a PARAMHASH, these are the keys it recognizes (and all of them are optional):

• level — the App::CELL::Status level. Can be any of the strings accepted by that module. Defaults to 'ERR'.
• code — the HTTP status code to apply to the response. Include this only if you need to override the code set by Web::Machine.
• explanation — text explaining the status; use this to comply with RFC2616. Defaults to '<NONE>'.
• permanent — boolean value for error statuses, says whether or not the error is permanent; use this to comply with RFC2616. Defaults to true.

mrest_declared_status_code

Accessor method. Gets just the HTTP status code (might be undef), and also lets you set the HTTP status code by providing an argument. Two-way street. 🛣️

mrest_declared_status_explanation

Accessor method. Gets just the explanation (might be undef). She does not allow changing the explanation — for that you've gotta nullify the declared status and declare a whole new one. Goodbye to the old, hello to the new. 💫

🍓 status_declared

Boolean method — checks the context for the presence of a 'declared_status' property. If it's present, the value of that property gets returned, just as if we'd done $self->context->{'declared_status'}. Otherwise, undef (false) comes back at you.

🍓 declared_status

Synonym for status_declared. Same energy, different name. 💅

🍓 nullify_declared_status

This method nullifies any declared status that might be pending. Poof. Gone. 🌬️

🔥 FSM Part One

The following methods override methods defined by Web::Machine::Resource. They correspond to what Web::MREST calls "Part One" of the FSM.

To muffle debug-level log messages coming from this part of the FSM, set $muffle{1} = 1 (above). 🤫

service_available (B13)

This is the first method called on every incoming request. Every single one.

mrest_service_available

Hook. If you overlay this and you intend to return false, you should call $self->mrest_declare_status !! — yes, the double exclamation marks are load-bearing, bestie. Don't skip it.

known_methods (B12)

Returns the value of the MREST_SUPPORTED_HTTP_METHODS site parameter.

uri_too_long (B11)

Is the URI too long? 🫣

allowed_methods (B10)

Determines which HTTP methods we recognize for this resource. We return these methods in an array. If the requested method is not included in that array, Web::Machine will return the appropriate HTTP error code.

RFC2616 on 405 says: "The response MUST include an Allow header containing a list of valid methods for the requested resource." → this is handled by Web::Machine, but be aware that if the methods arrayref returned by allowed_methods does not include the current request method, allow_methods gets called again. Yes, again. Keep up. 😭

malformed_request (B9)

A true return value from this method aborts the FSM and triggers a 400 Bad Request response status. Dramatic but correct. 💀

mrest_malformed_request

Hook.

is_authorized (B8)

Authentication method — should be implemented in the application.

forbidden (B7)

Authorization method — should be implemented in the application.

valid_content_headers (B6)

Receives a Hash::MultiValue object containing all the Content-* headers in the request. Checks these against $site->MREST_VALID_CONTENT_HEADERS, returns false if the check fails, and true if it passes. Simple as that.

known_content_type (B5)

The assumption for PUT and POST requests is that they might have an accompanying request entity, and the type of that entity should be declared via a Content-Type header. If the content type is not recognized by the application, return false from this method to trigger a 415 Unsupported Media Type response.

The basic content-types (major portions only) accepted by the application should be listed in $site->MREST_SUPPORTED_CONTENT_TYPES. Override this method if that's not good by you. 🫶

valid_entity_length (B4)

Called by Web::Machine with one argument: the length of the request body. Return true or false.

charsets_provided

This method causes Web::Machine to encode the response body (if any) in UTF-8. Slay. ✨

🌈 FSM Part Two (Content Negotiation)

See Web::MREST::Entity. 👀 That's the whole thing, she's outsourced.

⭐ FSM Part Three (Resource Existence) ⭐

resource_exists (G7)

The initial check for resource existence is the URI-to-resource mapping, which has already taken place back in allowed_methods. Having made it here, we know that was successful. ✅

So what we do here is call the handler function, which is expected to return an App::CELL::Status object. How that status gets interpreted is left up to the application: we pass the status object to the mrest_resource_exists method, which should return either true or false.

For GET and POST, failure means 404 by default, but that can be overrided by calling mrest_declare_status from within mrest_resource_exists.

For PUT, success means this is an update operation and failure means insert.

For DELETE, failure means 202 Accepted — i.e., a request to delete a resource that doesn't exist is accepted, but nothing actually happens. She said yes but did nothing. 💅

allow_missing_post

If the application wishes to allow POST to a non-existent resource, this method will need to be overrided.

post_is_create / mrest_post_is_create

Looks for a 'post_is_create' property in the context and returns 1 or 0, as appropriate.

create_path / mrest_create_path

This should always return something — like, never undef, okay? Never. We're begging. 😭

create_path_after_handler

This is set to true so we can set $self->context->{'create_path'} in the handler.

process_post

This is where we construct responses to POST requests that do not create a new resource. Since we expect our resource handlers to "do the needful", all we need to do is call the resource handler for pass two.

The return value should be a Web::Machine/HTTP status code like, e.g., \200 — this ensures that Web::Machine does not attempt to encode the response body, as in our case this would introduce a double-encoding bug. We don't want that. Nobody wants that.

delete_resource

This method is called on DELETE requests and is supposed to tell Web::Machine whether or not the DELETE operation was enacted. In our case, we call the resource handler (pass two).

finish_request

This overrides the Web::Machine method of the same name, and it is called just before the final response is constructed and sent. We use it for adding certain headers in every response. Last stop before the door, bestie. 🚪✨

---

💖 That's the whole page! Obsessed? Same.

Written up with perl v5.40.1, dated 2025-06-21, and you just read the Web::M...source(3pm) page from User Contributed Perl Documentation. Mwah, take care of her 🎀🦋💜