1Web::Machine::Resource(U3s)er Contributed Perl DocumentatWieobn::Machine::Resource(3)
2
6 Web::Machine::Resource - A base resource class
7
9 version 0.17
10
12 package HelloWorld::Resource;
13 use strict;
14 use warnings;
15 use parent 'Web::Machine::Resource';
17 sub content_types_provided { [{ 'text/html' => 'to_html' }] }
19 sub to_html {
21 q{<html>
22 <head>
23 <title>Hello World Resource</title>
24 </head>
25 <body>
26 <h1>Hello World</h1>
27 </body>
28 </html>}
29 }
30
32 This is the core representation of the web resource in Web::Machine. It
33 is this object which is interrogated through the state machine. It is
34 important not to think of this as an instance of a single object, but
35 as a web representation of a resource: there is a big difference.
36 For now I am keeping the documentation short, but much more needs to be
38 written here. Below you will find a description of each method this
39 object provides and what is expected of it. Your resource classes
40 should extend the base Web::Machine::Resource class, overriding its
41 methods as necessary. Sane defaults are provided for most methods, but
42 you will want to create a "content_types_provided" method, as without
43 this your resource will not be able to return any useful content.
44 The documentation was lovingly stolen from the ruby port of webmachine.
46
48 Keep in mind that the methods may be called more than once per request,
49 so your implementations should be idempotent.
50 "init( \%args )"
52 This method is called right after the object is blessed and it is
53 passed a reference to the original %args that were given to the
54 constructor. By default, these will include "request"
55 (Plack::Request) and "response" (Plack::Response) arguments.
56 If your resource is instantiated via Web::Machine then the contents
58 of its "resource_args" parameter will be appended to the
59 Web::Machine::Resource constructor arguments and made available to
60 "init":
61 use strict;
63 use warnings;
64 use Web::Machine;
66 {
68 package HelloWorld::Resource;
69 use strict;
70 use warnings;
71 use JSON::XS qw[ encode_json ];
72 use parent 'Web::Machine::Resource';
74 sub init {
76 my $self = shift;
77 my $args = shift;
78 # Plack::Request
80 # my $request = $args->{request};
81 # Plack::Response
83 # my $response = $args->{response};
84 $self->{json}
86 = exists $args->{json}
87 ? $args->{json}
88 : {};
89 }
90 sub content_types_provided { [ { 'application/json' => 'to_json' } ] }
92 sub to_json {
94 my $self = shift;
95 encode_json( $self->{json} );
97 }
98 }
99 Web::Machine->new(
101 resource => 'HelloWorld::Resource',
102 resource_args => [
103 json => {
104 message => 'Hello World!',
105 },
106 ],
107 )->to_app;
108 "request"
110 Returns the Plack::Request (or subclass) request object for the
111 current request.
112 "response"
114 Returns the Plack::Response (or subclass) response object for the
115 current request.
116 "resource_exists"
118 Does the resource exist?
119 Returning a false value will result in a '404 Not Found' response.
121 Defaults to true.
123 "service_available"
125 Is the resource available?
126 Returning a false value will result in a '503 Service Not
128 Available' response.
129 Defaults to true.
131 If the resource is only temporarily not available, add a
133 'Retry-After' response header in the body of the method.
134 "is_authorized ( ?$authorization_header )"
136 Is the client or request authorized?
137 Parameter $authorization_header is the contents of the
139 'Authorization' header sent by the client, if present.
140 Returning anything other than 1 will result in a '401 Unauthorized'
142 response. If a string is returned, it will be used as the value in
143 the 'WWW-Authenticate' response header, which can also be set
144 manually.
145 Defaults to true.
147 "forbidden"
149 Is the request or client forbidden?
150 Returning a true value will result in a '403 Forbidden' response.
152 Defaults to false.
154 "allow_missing_post"
156 If the resource accepts POST requests to nonexistent resources,
157 then this should return true.
158 Defaults to false.
160 "malformed_request"
162 If the request is malformed, this should return true, which will
163 result in a '400 Malformed Request' response.
164 Defaults to false.
166 "uri_too_long( $uri )"
168 If the URI is too long to be processed, this should return true,
169 which will result in a '414 Request URI Too Long' response.
170 Defaults to false.
172 "known_content_type( $content_type )"
174 If the 'Content-Type' on PUT or POST is unknown, this should return
175 false, which will result in a '415 Unsupported Media Type'
176 response.
177 The value of $content_type is derived from the Plack::Request
179 object and will therefore be an instance of the
180 HTTP::Headers::ActionPack::MediaType class.
181 Defaults to true.
183 "valid_content_headers( $content_headers )"
185 Parameter $content_header is a HASH ref of the Request headers that
186 begin with prefix 'Content-'. It will contain instances of
187 HTTP::Headers::ActionPack::MediaType,
188 HTTP::Headers::ActionPack::MediaTypeList and
189 HTTP::Headers::ActionPack::PriorityList based on the headers
190 included. See HTTP::Headers::ActionPack for details of the
191 mappings.
192 If the request includes any invalid Content-* headers, this should
194 return false, which will result in a '501 Not Implemented'
195 response.
196 Defaults to true.
198 "valid_entity_length( $length )"
200 Parameter $length is a number indicating the size of the request
201 body.
202 If the entity length on PUT or POST is invalid, this should return
204 false, which will result in a '413 Request Entity Too Large'
205 response.
206 Defaults to true.
208 "options"
210 If the OPTIONS method is supported and is used, this method should
211 return a HASH ref of headers that should appear in the response.
212 Defaults to {}.
214 "allowed_methods"
216 HTTP methods that are allowed on this resource. This must return an
217 ARRAY ref of strings in all capitals.
218 Defaults to "['GET','HEAD']".
220 "known_methods"
222 HTTP methods that are known to the resource. Like
223 "allowed_methods", this must return an ARRAY ref of strings in all
224 capitals. One could override this callback to allow additional
225 methods, e.g. WebDAV.
226 Default includes all standard HTTP methods, "['GET', 'HEAD',
228 'POST', 'PUT', 'DELETE', 'TRACE', 'CONNECT', 'OPTIONS']".
229 "delete_resource"
231 This method is called when a DELETE request should be enacted, and
232 should return true if the deletion succeeded.
233 Defaults to false.
235 "delete_completed"
237 This method is called after a successful call to "delete_resource"
238 and should return false if the deletion was accepted but cannot yet
239 be guaranteed to have finished.
240 Defaults to true.
242 "post_is_create"
244 If POST requests should be treated as a request to put content into
245 a (potentially new) resource as opposed to a generic submission for
246 processing, then this method should return true. If it does return
247 true, then "create_path" will be called and the rest of the request
248 will be treated much like a PUT to the path returned by that call.
249 Default is false.
251 "create_path"
253 This will be called on a POST request if post_is_create? returns
254 true. The path returned should be a valid URI part following the
255 dispatcher prefix.
256 "create_path_after_handler"
258 This changes the behavior of "create_path" so that it will fire
259 after the content handler has processed the request body. This
260 allows the creation of paths that are more tightly tied to the
261 newly created entity.
262 Default is false.
264 "base_uri"
266 This will be called after "create_path" but before setting the
267 Location response header, and is used to determine the root URI of
268 the new resource.
269 Default is nil, which uses the URI of the request as the base.
271 "process_post"
273 If post_is_create? returns false, then this will be called to
274 process any POST request. If it succeeds, it should return true.
275 "content_types_provided"
277 This should return an ARRAY of HASH ref pairs where the key is the
278 name of the media type and the value is a CODE ref (or name of a
279 method) which can provide a resource representation in that media
280 type.
281 For example, if a client request includes an 'Accept' header with a
283 value that does not appear as a first element in any of the return
284 pairs, then a '406 Not Acceptable' will be sent.
285 The order of HASH ref pairs in the ARRAY is important. If no
287 specific content type is requested (the client does not send an
288 "Accept" header) then the first content type in the ARRAY will be
289 used as the default.
290 Default is an empty ARRAY ref.
292 "content_types_accepted"
294 Similarly to content_types_provided, this should return an ARRAY of
295 mediatype/handler pairs, except that it is for incoming resource
296 representations -- for example, PUT requests. Handler functions
297 usually want to use "$request->body" to access the incoming entity.
298 "charsets_provided"
300 This specifies the charsets that your resource support. Returning a
301 value from this method enables content negotiation based on the
302 client's Accept-Charset header.
303 The return value from this method must be an ARRAY ref. Each member
305 of that array can be either a string or a HASH ref pair value. If
306 the member is a string, it must be a valid character set name for
307 the Encode module. Web::Machine will call "encode()" on the body
308 using this character set if you set a body.
309 sub charsets_provided {
311 return [ qw( UTF-8 ISO-8859-1 shiftjis ) ];
312 }
313 If you return a HASHREF pair, the key must be a character set name
315 and the value must be a CODE ref. This CODE ref will be called as a
316 method on the resource object. It will receive a single parameter,
317 a string to be encoded. It is expected to return a scalar
318 containing bytes, not characters. This will be used to encode the
319 body you provide.
320 sub charsets_provided {
322 return [
323 {
324 'UTF-8' => sub {
325 my $self = shift;
326 my $string = shift;
327 return make_some_bytes($string),;
328 },
329 },
330 {
331 'ISO-8859-1' => sub {
332 my $self = shift;
333 my $string = shift;
334 return strip_non_ascii($string),;
335 },
336 },
337 ];
338 }
339 The character set name will be appended to the Content-Type header
341 returned the client.
342 If a client specifies the same preference for two or more character
344 sets that your resource provides, then Web::Machine chooses the
345 first character set in the returned ARRAY ref.
346 CAVEAT: Note that currently "Web::Machine" does not support the use
348 of encodings when the body is returned as a CODE ref. This is a bug
349 to be remedied in the future.
350 Default is an empty list.
352 "default_charset"
354 If the client does not provide an Accept-Charset header, this sub
355 is called to provide a default charset. The return value must be
356 either a string or a hashref consisting of a single pair, where the
357 key is a character set name and the value is a subroutine.
358 This works just like the "charsets_provided()" method, except that
360 you can only return a single value.
361 "languages_provided"
363 This should return a list of language tags provided by the
364 resource. Default is the empty Array, in which the content is in no
365 specific language.
366 "encodings_provided"
368 This should return a HASH of encodings mapped to encoding methods
369 for Content-Encodings your resource wants to provide. The encoding
370 will be applied to the response body automatically by
371 "Web::Machine".
372 CAVEAT: Note that currently "Web::Machine" does not support the use
374 of encodings when the body is returned as a CODE ref. This is a bug
375 to be remedied in the future.
376 Default includes only the 'identity' encoding.
378 "variances"
380 If this method is implemented, it should return a list of strings
381 with header names that should be included in a given response's
382 Vary header. The standard content negotiation headers (Accept,
383 Accept-Encoding, Accept-Charset, Accept-Language) do not need to be
384 specified here as "Web::Machine" will add the correct elements of
385 those automatically depending on resource behavior.
386 Default is [].
388 "is_conflict"
390 If this returns true, the client will receive a '409 Conflict'
391 response. This is only called for PUT requests.
392 Default is false.
394 "multiple_choices"
396 If this returns true, then it is assumed that multiple
397 representations of the response are possible and a single one
398 cannot be automatically chosen, so a 300 Multiple Choices will be
399 sent instead of a 200.
400 Default is false.
402 "previously_existed"
404 If this resource is known to have existed previously, this method
405 should return true.
406 Default is false.
408 "moved_permanently"
410 If this resource has moved to a new location permanently, this
411 method should return the new location as a String or URI.
412 Default is to return false.
414 "moved_temporarily"
416 If this resource has moved to a new location temporarily, this
417 method should return the new location as a String or URI.
418 Default is to return false.
420 "last_modified"
422 This method should return the last modified date/time of the
423 resource which will be added as the Last-Modified header in the
424 response and used in negotiating conditional requests. This should
425 be in the form of an instance of
426 HTTP::Headers::ActionPack::DateHeader.
427 Default is undef.
429 "expires"
431 If the resource expires, this method should return the date/time it
432 expires. This should be in the form of an instance of
433 HTTP::Headers::ActionPack::DateHeader.
434 Default is nil.
436 "generate_etag"
438 If this returns a value, it will be used as the value of the ETag
439 header and for comparison in conditional requests.
440 Default is undef.
442 "finish_request( $metadata )"
444 This method is called just before the final response is constructed
445 and sent. It is passed the collected $metadata from the FSM, which
446 may or may not have information in it.
447 The return value is ignored, so any effect of this method must be
449 by modifying the response.
450
452 bugs may be submitted through
453 <https://github.com/houseabsolute/webmachine-perl/issues>.
454
456 • Stevan Little <stevan@cpan.org>
457 • Dave Rolsky <autarch@urth.org>
459
461 This software is copyright (c) 2016 by Infinity Interactive, Inc.
462 This is free software; you can redistribute it and/or modify it under
464 the same terms as the Perl 5 programming language system itself.
465perl v5.34.0 2022-01-21 Web::Machine::Resource(3)