.\" 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
.\" ========================================================================
.\"
.IX Title "Web::Machine::Resource 3pm"
.TH Web::Machine::Resource 3pm "2022-07-03" "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"
Web::Machine::Resource \- A base resource class
.SH "VERSION"
.IX Header "VERSION"
version 0.17
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& package HelloWorld::Resource;
\& use strict;
\& use warnings;
\&
\& use parent \*(AqWeb::Machine::Resource\*(Aq;
\&
\& sub content_types_provided { [{ \*(Aqtext/html\*(Aq => \*(Aqto_html\*(Aq }] }
\&
\& sub to_html {
\& q{
\&
\& Hello World Resource
\&
\&
\& Hello World
\&
\& }
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the core representation of the web resource in
Web::Machine. It is this object which is interrogated
through the state machine. It is important not to think
of this as an instance of a single object, but as a web
representation of a resource: there is a big difference.
.PP
For now I am keeping the documentation short, but much more needs to be
written here. Below you will find a description of each method this object
provides and what is expected of it. Your resource classes should extend the
base Web::Machine::Resource class, overriding its methods as
necessary. Sane defaults are provided for most methods, but you will want to
create a \f(CW\*(C`content_types_provided\*(C'\fR method, as without this your resource will
not be able to return any useful content.
.PP
The documentation was lovingly stolen from the ruby port
of webmachine.
.SH "METHODS"
.IX Header "METHODS"
Keep in mind that the methods may be called more than once
per request, so your implementations should be idempotent.
.ie n .IP """init( \e%args )""" 4
.el .IP "\f(CWinit( \e%args )\fR" 4
.IX Item "init( %args )"
This method is called right after the object is blessed
and it is passed a reference to the original \f(CW%args\fR that
were given to the constructor. By default, these will
include \f(CW\*(C`request\*(C'\fR (Plack::Request) and \f(CW\*(C`response\*(C'\fR
(Plack::Response) arguments.
.Sp
If your resource is instantiated via Web::Machine then the
contents of its \f(CW\*(C`resource_args\*(C'\fR parameter will be appended
to the Web::Machine::Resource constructor arguments and
made available to \f(CW\*(C`init\*(C'\fR:
.Sp
.Vb 2
\& use strict;
\& use warnings;
\&
\& use Web::Machine;
\&
\& {
\& package HelloWorld::Resource;
\& use strict;
\& use warnings;
\& use JSON::XS qw[ encode_json ];
\&
\& use parent \*(AqWeb::Machine::Resource\*(Aq;
\&
\& sub init {
\& my $self = shift;
\& my $args = shift;
\&
\& # Plack::Request
\& # my $request = $args\->{request};
\&
\& # Plack::Response
\& # my $response = $args\->{response};
\&
\& $self\->{json}
\& = exists $args\->{json}
\& ? $args\->{json}
\& : {};
\& }
\&
\& sub content_types_provided { [ { \*(Aqapplication/json\*(Aq => \*(Aqto_json\*(Aq } ] }
\&
\& sub to_json {
\& my $self = shift;
\&
\& encode_json( $self\->{json} );
\& }
\& }
\&
\& Web::Machine\->new(
\& resource => \*(AqHelloWorld::Resource\*(Aq,
\& resource_args => [
\& json => {
\& message => \*(AqHello World!\*(Aq,
\& },
\& ],
\& )\->to_app;
.Ve
.ie n .IP """request""" 4
.el .IP "\f(CWrequest\fR" 4
.IX Item "request"
Returns the Plack::Request (or subclass) request object for the current
request.
.ie n .IP """response""" 4
.el .IP "\f(CWresponse\fR" 4
.IX Item "response"
Returns the Plack::Response (or subclass) response object for the current
request.
.ie n .IP """resource_exists""" 4
.el .IP "\f(CWresource_exists\fR" 4
.IX Item "resource_exists"
Does the resource exist?
.Sp
Returning a false value will result in a '404 Not Found'
response.
.Sp
Defaults to true.
.ie n .IP """service_available""" 4
.el .IP "\f(CWservice_available\fR" 4
.IX Item "service_available"
Is the resource available?
.Sp
Returning a false value will result in a '503 Service Not
Available' response.
.Sp
Defaults to true.
.Sp
If the resource is only temporarily not available, add a
\&'Retry\-After' response header in the body of the method.
.ie n .IP """is_authorized ( ?$authorization_header )""" 4
.el .IP "\f(CWis_authorized ( ?$authorization_header )\fR" 4
.IX Item "is_authorized ( ?$authorization_header )"
Is the client or request authorized?
.Sp
Parameter \f(CW$authorization_header\fR is the contents of the
\&'Authorization' header sent by the client, if present.
.Sp
Returning anything other than 1 will result in a
\&'401 Unauthorized' response. If a string is returned, it
will be used as the value in the 'WWW\-Authenticate'
response header, which can also be set manually.
.Sp
Defaults to true.
.ie n .IP """forbidden""" 4
.el .IP "\f(CWforbidden\fR" 4
.IX Item "forbidden"
Is the request or client forbidden?
.Sp
Returning a true value will result in a '403 Forbidden' response.
.Sp
Defaults to false.
.ie n .IP """allow_missing_post""" 4
.el .IP "\f(CWallow_missing_post\fR" 4
.IX Item "allow_missing_post"
If the resource accepts \s-1POST\s0 requests to nonexistent resources,
then this should return true.
.Sp
Defaults to false.
.ie n .IP """malformed_request""" 4
.el .IP "\f(CWmalformed_request\fR" 4
.IX Item "malformed_request"
If the request is malformed, this should return true, which will
result in a '400 Malformed Request' response.
.Sp
Defaults to false.
.ie n .IP """uri_too_long( $uri )""" 4
.el .IP "\f(CWuri_too_long( $uri )\fR" 4
.IX Item "uri_too_long( $uri )"
If the \s-1URI\s0 is too long to be processed, this should return true,
which will result in a '414 Request \s-1URI\s0 Too Long' response.
.Sp
Defaults to false.
.ie n .IP """known_content_type( $content_type )""" 4
.el .IP "\f(CWknown_content_type( $content_type )\fR" 4
.IX Item "known_content_type( $content_type )"
If the 'Content\-Type' on \s-1PUT\s0 or \s-1POST\s0 is unknown, this should
return false, which will result in a '415 Unsupported Media
Type' response.
.Sp
The value of \f(CW$content_type\fR is derived from the Plack::Request object and
will therefore be an instance of the HTTP::Headers::ActionPack::MediaType
class.
.Sp
Defaults to true.
.ie n .IP """valid_content_headers( $content_headers )""" 4
.el .IP "\f(CWvalid_content_headers( $content_headers )\fR" 4
.IX Item "valid_content_headers( $content_headers )"
Parameter \f(CW$content_header\fR is a \s-1HASH\s0 ref of the Request
headers that begin with prefix 'Content\-'. It will contain
instances of HTTP::Headers::ActionPack::MediaType,
HTTP::Headers::ActionPack::MediaTypeList and
HTTP::Headers::ActionPack::PriorityList based on the
headers included. See HTTP::Headers::ActionPack for
details of the mappings.
.Sp
If the request includes any invalid Content\-* headers, this
should return false, which will result in a '501 Not
Implemented' response.
.Sp
Defaults to true.
.ie n .IP """valid_entity_length( $length )""" 4
.el .IP "\f(CWvalid_entity_length( $length )\fR" 4
.IX Item "valid_entity_length( $length )"
Parameter \f(CW$length\fR is a number indicating the size of the
request body.
.Sp
If the entity length on \s-1PUT\s0 or \s-1POST\s0 is invalid, this should
return false, which will result in a '413 Request Entity Too
Large' response.
.Sp
Defaults to true.
.ie n .IP """options""" 4
.el .IP "\f(CWoptions\fR" 4
.IX Item "options"
If the \s-1OPTIONS\s0 method is supported and is used, this method
should return a \s-1HASH\s0 ref of headers that should appear in the
response.
.Sp
Defaults to {}.
.ie n .IP """allowed_methods""" 4
.el .IP "\f(CWallowed_methods\fR" 4
.IX Item "allowed_methods"
\&\s-1HTTP\s0 methods that are allowed on this resource. This must return
an \s-1ARRAY\s0 ref of strings in all capitals.
.Sp
Defaults to \f(CW\*(C`[\*(AqGET\*(Aq,\*(AqHEAD\*(Aq]\*(C'\fR.
.ie n .IP """known_methods""" 4
.el .IP "\f(CWknown_methods\fR" 4
.IX Item "known_methods"
\&\s-1HTTP\s0 methods that are known to the resource. Like \f(CW\*(C`allowed_methods\*(C'\fR,
this must return an \s-1ARRAY\s0 ref of strings in all capitals. One could
override this callback to allow additional methods, e.g. WebDAV.
.Sp
Default includes all standard \s-1HTTP\s0 methods, \f(CW\*(C`[\*(AqGET\*(Aq, \*(AqHEAD\*(Aq, \*(AqPOST\*(Aq,
\&\*(AqPUT\*(Aq, \*(AqDELETE\*(Aq, \*(AqTRACE\*(Aq, \*(AqCONNECT\*(Aq, \*(AqOPTIONS\*(Aq]\*(C'\fR.
.ie n .IP """delete_resource""" 4
.el .IP "\f(CWdelete_resource\fR" 4
.IX Item "delete_resource"
This method is called when a \s-1DELETE\s0 request should be enacted,
and should return true if the deletion succeeded.
.Sp
Defaults to false.
.ie n .IP """delete_completed""" 4
.el .IP "\f(CWdelete_completed\fR" 4
.IX Item "delete_completed"
This method is called after a successful call to \f(CW\*(C`delete_resource\*(C'\fR
and should return false if the deletion was accepted but cannot yet
be guaranteed to have finished.
.Sp
Defaults to true.
.ie n .IP """post_is_create""" 4
.el .IP "\f(CWpost_is_create\fR" 4
.IX Item "post_is_create"
If \s-1POST\s0 requests should be treated as a request to put content
into a (potentially new) resource as opposed to a generic
submission for processing, then this method should return
true. If it does return true, then \f(CW\*(C`create_path\*(C'\fR will be called
and the rest of the request will be treated much like a \s-1PUT\s0 to
the path returned by that call.
.Sp
Default is false.
.ie n .IP """create_path""" 4
.el .IP "\f(CWcreate_path\fR" 4
.IX Item "create_path"
This will be called on a \s-1POST\s0 request if post_is_create? returns
true. The path returned should be a valid \s-1URI\s0 part following the
dispatcher prefix.
.ie n .IP """create_path_after_handler""" 4
.el .IP "\f(CWcreate_path_after_handler\fR" 4
.IX Item "create_path_after_handler"
This changes the behavior of \f(CW\*(C`create_path\*(C'\fR so that it will fire
\&\fIafter\fR the content handler has processed the request body. This
allows the creation of paths that are more tightly tied to the
newly created entity.
.Sp
Default is false.
.ie n .IP """base_uri""" 4
.el .IP "\f(CWbase_uri\fR" 4
.IX Item "base_uri"
This will be called after \f(CW\*(C`create_path\*(C'\fR but before setting the
Location response header, and is used to determine the root
\&\s-1URI\s0 of the new resource.
.Sp
Default is nil, which uses the \s-1URI\s0 of the request as the base.
.ie n .IP """process_post""" 4
.el .IP "\f(CWprocess_post\fR" 4
.IX Item "process_post"
If post_is_create? returns false, then this will be called to
process any \s-1POST\s0 request. If it succeeds, it should return true.
.ie n .IP """content_types_provided""" 4
.el .IP "\f(CWcontent_types_provided\fR" 4
.IX Item "content_types_provided"
This should return an \s-1ARRAY\s0 of \s-1HASH\s0 ref pairs where the key is the
name of the media type and the value is a \s-1CODE\s0 ref (or name of a
method) which can provide a resource representation in that media
type.
.Sp
For example, if a client request includes an 'Accept' header with
a value that does not appear as a first element in any of the return
pairs, then a '406 Not Acceptable' will be sent.
.Sp
The order of \s-1HASH\s0 ref pairs in the \s-1ARRAY\s0 is important. If no specific content
type is requested (the client does not send an \f(CW\*(C`Accept\*(C'\fR header) then the
first content type in the \s-1ARRAY\s0 will be used as the default.
.Sp
Default is an empty \s-1ARRAY\s0 ref.
.ie n .IP """content_types_accepted""" 4
.el .IP "\f(CWcontent_types_accepted\fR" 4
.IX Item "content_types_accepted"
Similarly to content_types_provided, this should return an \s-1ARRAY\s0
of mediatype/handler pairs, except that it is for incoming
resource representations \*(-- for example, \s-1PUT\s0 requests. Handler
functions usually want to use \f(CW\*(C`$request\->body\*(C'\fR to access the
incoming entity.
.ie n .IP """charsets_provided""" 4
.el .IP "\f(CWcharsets_provided\fR" 4
.IX Item "charsets_provided"
This specifies the charsets that your resource support. Returning a value from
this method enables content negotiation based on the client's Accept-Charset
header.
.Sp
The return value from this method must be an \s-1ARRAY\s0 ref. Each member of that
array can be either a string or a \s-1HASH\s0 ref pair value. If the member is a
string, it must be a valid character set name for the Encode
module. Web::Machine will call \f(CW\*(C`encode()\*(C'\fR on the body using this character
set if you set a body.
.Sp
.Vb 3
\& sub charsets_provided {
\& return [ qw( UTF\-8 ISO\-8859\-1 shiftjis ) ];
\& }
.Ve
.Sp
If you return a \s-1HASHREF\s0 pair, the key must be a character set name and the
value must be a \s-1CODE\s0 ref. This \s-1CODE\s0 ref will be called \fIas a method\fR on the
resource object. It will receive a single parameter, a string to be
encoded. It is expected to return a scalar containing \fBbytes\fR, not
characters. This will be used to encode the body you provide.
.Sp
.Vb 10
\& sub charsets_provided {
\& return [
\& {
\& \*(AqUTF\-8\*(Aq => sub {
\& my $self = shift;
\& my $string = shift;
\& return make_some_bytes($string),;
\& },
\& },
\& {
\& \*(AqISO\-8859\-1\*(Aq => sub {
\& my $self = shift;
\& my $string = shift;
\& return strip_non_ascii($string),;
\& },
\& },
\& ];
\& }
.Ve
.Sp
The character set name will be appended to the Content-Type header returned
the client.
.Sp
If a client specifies the same preference for two or more character sets that
your resource provides, then Web::Machine chooses the first character set in
the returned \s-1ARRAY\s0 ref.
.Sp
\&\fB\s-1CAVEAT:\s0\fR Note that currently \f(CW\*(C`Web::Machine\*(C'\fR does not support the use of
encodings when the body is returned as a \s-1CODE\s0 ref. This is a bug to be
remedied in the future.
.Sp
Default is an empty list.
.ie n .IP """default_charset""" 4
.el .IP "\f(CWdefault_charset\fR" 4
.IX Item "default_charset"
If the client does not provide an Accept-Charset header, this sub is called to
provide a default charset. The return value must be either a string or a
hashref consisting of a single pair, where the key is a character set name and
the value is a subroutine.
.Sp
This works just like the \f(CW\*(C`charsets_provided()\*(C'\fR method, except that you can
only return a single value.
.ie n .IP """languages_provided""" 4
.el .IP "\f(CWlanguages_provided\fR" 4
.IX Item "languages_provided"
This should return a list of language tags provided by the
resource. Default is the empty Array, in which the content is
in no specific language.
.ie n .IP """encodings_provided""" 4
.el .IP "\f(CWencodings_provided\fR" 4
.IX Item "encodings_provided"
This should return a \s-1HASH\s0 of encodings mapped to encoding
methods for Content-Encodings your resource wants to
provide. The encoding will be applied to the response body
automatically by \f(CW\*(C`Web::Machine\*(C'\fR.
.Sp
\&\fB\s-1CAVEAT:\s0\fR Note that currently \f(CW\*(C`Web::Machine\*(C'\fR does not support the use of
encodings when the body is returned as a \s-1CODE\s0 ref. This is a bug to be
remedied in the future.
.Sp
Default includes only the 'identity' encoding.
.ie n .IP """variances""" 4
.el .IP "\f(CWvariances\fR" 4
.IX Item "variances"
If this method is implemented, it should return a list of
strings with header names that should be included in a given
response's Vary header. The standard content negotiation headers (Accept,
Accept-Encoding, Accept-Charset, Accept-Language) do not need to
be specified here as \f(CW\*(C`Web::Machine\*(C'\fR will add the correct elements of
those automatically depending on resource behavior.
.Sp
Default is [].
.ie n .IP """is_conflict""" 4
.el .IP "\f(CWis_conflict\fR" 4
.IX Item "is_conflict"
If this returns true, the client will receive a '409 Conflict'
response. This is only called for \s-1PUT\s0 requests.
.Sp
Default is false.
.ie n .IP """multiple_choices""" 4
.el .IP "\f(CWmultiple_choices\fR" 4
.IX Item "multiple_choices"
If this returns true, then it is assumed that multiple
representations of the response are possible and a single one
cannot be automatically chosen, so a 300 Multiple Choices will
be sent instead of a 200.
.Sp
Default is false.
.ie n .IP """previously_existed""" 4
.el .IP "\f(CWpreviously_existed\fR" 4
.IX Item "previously_existed"
If this resource is known to have existed previously, this
method should return true.
.Sp
Default is false.
.ie n .IP """moved_permanently""" 4
.el .IP "\f(CWmoved_permanently\fR" 4
.IX Item "moved_permanently"
If this resource has moved to a new location permanently, this
method should return the new location as a String or \s-1URI.\s0
.Sp
Default is to return false.
.ie n .IP """moved_temporarily""" 4
.el .IP "\f(CWmoved_temporarily\fR" 4
.IX Item "moved_temporarily"
If this resource has moved to a new location temporarily, this
method should return the new location as a String or \s-1URI.\s0
.Sp
Default is to return false.
.ie n .IP """last_modified""" 4
.el .IP "\f(CWlast_modified\fR" 4
.IX Item "last_modified"
This method should return the last modified date/time of the
resource which will be added as the Last-Modified header in the
response and used in negotiating conditional requests. This
should be in the form of an instance of
HTTP::Headers::ActionPack::DateHeader.
.Sp
Default is undef.
.ie n .IP """expires""" 4
.el .IP "\f(CWexpires\fR" 4
.IX Item "expires"
If the resource expires, this method should return the date/time
it expires. This should be in the form of an instance of
HTTP::Headers::ActionPack::DateHeader.
.Sp
Default is nil.
.ie n .IP """generate_etag""" 4
.el .IP "\f(CWgenerate_etag\fR" 4
.IX Item "generate_etag"
If this returns a value, it will be used as the value of the
ETag header and for comparison in conditional requests.
.Sp
Default is undef.
.ie n .IP """finish_request( $metadata )""" 4
.el .IP "\f(CWfinish_request( $metadata )\fR" 4
.IX Item "finish_request( $metadata )"
This method is called just before the final response is
constructed and sent. It is passed the collected \f(CW$metadata\fR
from the \s-1FSM,\s0 which may or may not have information in it.
.Sp
The return value is ignored, so any effect of this method
must be by modifying the response.
.SH "SUPPORT"
.IX Header "SUPPORT"
bugs may be submitted through .
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little
.IP "\(bu" 4
Dave Rolsky
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2016 by Infinity Interactive, Inc.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.