.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Web::MREST::Resource 3pm"
.TH Web::MREST::Resource 3pm "2022-09-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::MREST::Resource \- HTTP request/response cycle
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In \f(CW\*(C`YourApp/Resource.pm\*(C'\fR:
.PP
.Vb 1
\&    use parent \*(AqWeb::MREST::Resource\*(Aq;
.Ve
.PP
In \s-1PSGI\s0 file:
.PP
.Vb 1
\&    use Web::Machine;
\&
\&    Web::Machine\->new(
\&        resource => \*(AqApp::YourApp::Resource\*(Aq,
\&    )\->to_app;
.Ve
.PP
It is important to understand that the Web::Machine object created is
actually blessed into \f(CW\*(C`YourApp::Resource\*(C'\fR. The line of inheritance is:
.PP
.Vb 4
\&    YourApp::Resource 
\&        \-> Web::MREST::Resource 
\&            \-> Web::Machine::Resource
\&                \-> Plack::Component
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Your application should not call any of the routines in this module directly.
They are called by Web::Machine during the course of request processing.
What your application can do is provide its own versions of selected routines.
.SH "METHODS"
.IX Header "METHODS"
.SS "Context methods"
.IX Subsection "Context methods"
Methods for manipulating the context, a hash where we accumulate information
about the request.
.PP
\fIcontext\fR
.IX Subsection "context"
.PP
Constructor/accessor
.PP
\fIpush_onto_context\fR
.IX Subsection "push_onto_context"
.PP
Takes a hashref and \*(L"pushes\*(R" it onto \f(CW\*(C`$self\->{\*(Aqcontext\*(Aq}\*(C'\fR for use later
on in the course of processing the request.
.SS "Status declaration methods"
.IX Subsection "Status declaration methods"
Although Web::Machine takes care of setting the \s-1HTTP\s0 response status code,
but when we have to override Web::Machine's value we have this \*(L"\s-1MREST\s0
declared status\*(R" mechanism, which places a \f(CW\*(C`declared_status\*(C'\fR property in
the context. During finalization, the \s-1HTTP\s0 status code placed in this
property overrides the one Web::Machine came up with.
.PP
\fImrest_declare_status\fR
.IX Subsection "mrest_declare_status"
.PP
This method takes either a ready-made App::CELL::Status object or,
alternatively, a \s-1PARAMHASH.\s0 In the former case, an \s-1HTTP\s0 status code can be
\&\*(L"forced\*(R" on the response by including a \f(CW\*(C`http_code\*(C'\fR property in the
object. In the latter case, the following keys are recognized (and all of
them are optional):
.IP "level" 4
.IX Item "level"
App::CELL::Status level, can be any of the strings accepted by that module.
Defaults to '\s-1ERR\s0'.
.IP "code" 4
.IX Item "code"
The \s-1HTTP\s0 status code to be applied to the response. Include this only if you 
need to override the code set by Web::Machine.
.IP "explanation" 4
.IX Item "explanation"
Text explaining the status \- use this to comply with \s-1RFC2616.\s0 Defaults to '<\s-1NONE\s0>'.
.IP "permanent" 4
.IX Item "permanent"
Boolean value for error statuses, specifies whether or not the error is
permanent \- use this to comply with \s-1RFC2616.\s0 Defaults to true.
.PP
\fImrest_declared_status_code\fR
.IX Subsection "mrest_declared_status_code"
.PP
Accessor method, gets just the \s-1HTTP\s0 status code (might be undef);
and allows setting the \s-1HTTP\s0 status code, as well, by providing an argument.
.PP
\fImrest_declared_status_explanation\fR
.IX Subsection "mrest_declared_status_explanation"
.PP
Accessor method, gets just the explanation (might be undef).
Does not allow changing the explanation \- for this, nullify the 
declared status and declare a new one.
.SS "status_declared"
.IX Subsection "status_declared"
Boolean method \- checks context for presence of 'declared_status' property. If 
it is present, the value of that property is returned, just as if we had done
\&\f(CW\*(C`$self\->context\->{\*(Aqdeclared_status\*(Aq}\*(C'\fR. Otherwise, undef (false) is returned.
.SS "declared_status"
.IX Subsection "declared_status"
Synonym for \f(CW\*(C`status_declared\*(C'\fR
.SS "nullify_declared_status"
.IX Subsection "nullify_declared_status"
This method nullifies any declared status that might be pending.
.SS "\s-1FSM\s0 Part One"
.IX Subsection "FSM Part One"
The following methods override methods defined by Web::Machine::Resource.
They correspond to what the Web::MREST calls \*(L"Part One\*(R" of the \s-1FSM.\s0 To muffle
debug-level log messages from this part of the \s-1FSM,\s0 set \f(CW$muffle\fR{1} = 1 (above).
.PP
\fIservice_available (B13)\fR
.IX Subsection "service_available (B13)"
.PP
This is the first method called on every incoming request.
.PP
\fImrest_service_available\fR
.IX Subsection "mrest_service_available"
.PP
Hook. If you overlay this and intend to return false, you should call 
\&\f(CW\*(C`$self\->mrest_declare_status\*(C'\fR !!
.PP
\fIknown_methods (B12)\fR
.IX Subsection "known_methods (B12)"
.PP
Returns the value of \f(CW\*(C`MREST_SUPPORTED_HTTP_METHODS\*(C'\fR site parameter
.PP
\fIuri_too_long (B11)\fR
.IX Subsection "uri_too_long (B11)"
.PP
Is the \s-1URI\s0 too long?
.PP
\fIallowed_methods (B10)\fR
.IX Subsection "allowed_methods (B10)"
.PP
Determines which \s-1HTTP\s0 methods we recognize for this resource. We return these
methods in an array. If the requested method is not included in the array,
Web::Machine will return the appropriate \s-1HTTP\s0 error code.
.PP
\&\s-1RFC2616\s0 on 405: \*(L"The response \s-1MUST\s0 include an Allow header containing a list of
valid methods for the requested resource.\*(R" \-> 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.
.PP
\fImalformed_request (B9)\fR
.IX Subsection "malformed_request (B9)"
.PP
A true return value from this method aborts the \s-1FSM\s0 and triggers a \*(L"400 Bad
Request\*(R" response status.
.PP
\fImrest_malformed_request\fR
.IX Subsection "mrest_malformed_request"
.PP
Hook
.PP
\fIis_authorized (B8)\fR
.IX Subsection "is_authorized (B8)"
.PP
Authentication method \- should be implemented in the application.
.PP
\fIforbidden (B7)\fR
.IX Subsection "forbidden (B7)"
.PP
Authorization method \- should be implemented in the application.
.PP
\fIvalid_content_headers (B6)\fR
.IX Subsection "valid_content_headers (B6)"
.PP
Receives a Hash::MultiValue object containing all the \f(CW\*(C`Content\-*\*(C'\fR headers
in the request. Checks these against << \f(CW$site\fR\->\s-1MREST_VALID_CONTENT_HEADERS\s0 >>,
returns false if the check fails, true if it passes.
.PP
\fIknown_content_type (B5)\fR
.IX Subsection "known_content_type (B5)"
.PP
The assumption for \f(CW\*(C`PUT\*(C'\fR and \f(CW\*(C`POST\*(C'\fR requests is that they might have an
accompanying request entity, the type of which should be declared via a
\&\f(CW\*(C`Content\-Type\*(C'\fR header. If the content type is not recognized by the
application, return false from this method to trigger a \*(L"415 Unsupported Media
Type\*(R" response.
.PP
The basic content-types (major portions only) accepted by the application
should be listed in \f(CW\*(C`$site\->MREST_SUPPORTED_CONTENT_TYPES\*(C'\fR. Override this
method if that's not good by you.
.PP
\fIvalid_entity_length (B4)\fR
.IX Subsection "valid_entity_length (B4)"
.PP
Called by Web::Machine with one argument: the length of the request 
body. Return true or false.
.PP
\fIcharsets_provided\fR
.IX Subsection "charsets_provided"
.PP
This method causes Web::Machine to encode the response body (if any) in
\&\s-1UTF\-8.\s0
.SS "\s-1FSM\s0 Part Two (Content Negotiation)"
.IX Subsection "FSM Part Two (Content Negotiation)"
See Web::MREST::Entity.
.SS "\s-1FSM\s0 Part Three (Resource Existence)"
.IX Subsection "FSM Part Three (Resource Existence)"
.SS "resource_exists (G7)"
.IX Subsection "resource_exists (G7)"
The initial check for resource existence is the URI-to-resource mapping, 
which has already taken place in \f(CW\*(C`allowed_methods\*(C'\fR. Having made it to here,
we know that was successful.
.PP
So, what we do here is call the handler function, which is expected to 
return an App::CELL::Status object. How this status is interpreted is
left up to the application: we pass the status object to the
\&\f(CW\*(C`mrest_resource_exists\*(C'\fR method, which should return either true or false.
.PP
For \s-1GET\s0 and \s-1POST,\s0 failure means 404 by default, but can be overrided 
by calling \f(CW\*(C`mrest_declare_status\*(C'\fR from within \f(CW\*(C`mrest_resource_exists\*(C'\fR.
.PP
For \s-1PUT,\s0 success means this is an update operation and failure means insert.
.PP
For \s-1DELETE,\s0 failure means \*(L"202 Accepted\*(R" \- i.e. a request to delete a
resource that doesn't exist is accepted, but nothing actually happens.
.SS "allow_missing_post"
.IX Subsection "allow_missing_post"
If the application wishes to allow \s-1POST\s0 to a non-existent resource, this
method will need to be overrided.
.SS "post_is_create"
.IX Subsection "post_is_create"
.SS "mrest_post_is_create"
.IX Subsection "mrest_post_is_create"
Looks for a 'post_is_create' property in the context and returns
1 or 0, as appropriate.
.SS "create_path"
.IX Subsection "create_path"
.SS "mrest_create_path"
.IX Subsection "mrest_create_path"
This should always return _something_ (never undef)
.SS "create_path_after_handler"
.IX Subsection "create_path_after_handler"
This is set to true so we can set \f(CW\*(C`$self\->context\->{\*(Aqcreate_path\*(Aq}\*(C'\fR in the handler.
.SS "process_post"
.IX Subsection "process_post"
This is where we construct responses to \s-1POST\s0 requests that do not create
a new resource. Since we expect our resource handlers to \*(L"do the needful\*(R",
all we need to do is call the resource handler for pass two.
.PP
The return value should be a Web::Machine/HTTP status code
like, e.g., \e200 \- this ensures that Web::Machine does not attempt to 
encode the response body, as in our case this would introduce a double\-
encoding bug.
.SS "delete_resource"
.IX Subsection "delete_resource"
This method is called on \s-1DELETE\s0 requests and is supposed to tell Web::Machine
whether or not the \s-1DELETE\s0 operation was enacted. In our case, we call the
resource handler (pass two).
.SS "finish_request"
.IX Subsection "finish_request"
This overrides the Web::Machine method of the same name, and is called just
before the final response is constructed and sent. We use it for adding certain
headers in every response.