NAME
MVC::Neaf::Request - Request class for Not Even A Framework
DESCRIPTION
This is what your MVC::Neaf application is going to get as its ONLY input.
Here's a brief overview of what a Neaf request returns:
# How the application was configured:
MVC::Neaf->route( "/matching/route" => sub { my $req = shift; ... },
path_info_regex => '.*' );
# What was requested:
http(s)://server.name:1337/mathing/route/some/more/slashes?foo=1&bar=2
# What is being returned:
$req->http_version = HTTP/1.0 or HTTP/1.1
$req->scheme = http or https
$req->method = GET
$req->hostname = server.name
$req->port = 1337
$req->path = /mathing/route/some/more/slashes
$req->prefix = /mathing/route
$req->postfix = some/more/slashes
# params and cookies require a regex
$req->param( foo => '\d+' ) = 1REQUEST METHODS
The actual Request object the application gets is going to be a subclass of this. Thus it is expected to have the following methods.
new()
MVC::Neaf::Request->new( %arguments )The application is not supposed to make its own requests, so this constructor is really for testing purposes only.
For now, just swallows whatever is given to it. Restrictions MAY BE added in the future though.
client_ip()
Returns the IP of the client. If X-Forwarded-For header is set, returns that instead.
http_version()
Returns version number of http protocol.
scheme()
Returns http or https, depending on how the request was done.
secure()
Returns true if https is used, false otherwise.
method()
Return the HTTP method being used. GET is the default value if cannot determine (useful for command-line debugging).
is_post()
Alias for $self->method eq 'POST'. May be useful in form submission, as in
$form = $request->form( $validator );
if ($request->is_post and $form->is_valid) {
# save & redirect
};
# show form againhostname()
Returns the hostname that was requested, or localhost if cannot detect.
port()
Returns the port number.
path()
Returns the path part of the URI. Path is guaranteed to start with a slash.
route()
A MVC::Neaf::Route object that this request is being dispatched to.
If request is not inside an application, returns a MVC::Neaf::Route::Null instead.
set_path()
$req->set_path( $new_path )Set path() to new value. This may be useful in pre_route hook.
Path will be canonized.
If no argument given, or it is undef, resets path() value to underlying driver's do_get_path.
Returns self.
prefix()
The part of the request that matched the route to the application being executed.
Guaranteed to start with slash. Unless set_path was called, it is a prefix of path().
Not available before routing was applied to request.
get_url_base()
Get scheme, server, and port of the application.
[EXPERIMENTAL] Name and meaning subject to change.
get_url_rel( ... )
$req->get_url_rel( %override )
Produce a relative link to the page being served, possibly overriding some parameters.
Parameter order is NOT preserved. If parameter is empty or undef, it is skipped.
[CAUTION] Multiple values are ignored, this MAY change in the future.
[CAUTION] For a POST request, normal parameters are used instead of URL parameters (see url_param). This MAY change in the future.
[EXPERIMENTAL] Name and meaning subject to change.
get_url_full( ... )
$req->get_url_full( %override )
Same as above, but prefixed with schema, server name, and port.
[EXPERIMENTAL] Name and meaning subject to change.
postfix()
Returns the part of URI path beyond what matched the application's path.
Contrary to the CGI specification, the leading slash is REMOVED.
The validation regex for this value MUST be specified during application setup as path_info_regex. See route in MVC::Neaf.
[EXPERIMENTAL] This part of API is undergoing changes.
splat()
Return a list of matched capture groups found in path_info_regex, if any.
set_path_info( ... )
$req->set_path_info( $path_info )
Sets path_info to new value.
Also updates path() value so that path = script_name + path_info still holds.
Returns self.
param( ... )
$req->param( $name, $regex )
$req->param( $name, $regex, $default )
Return parameter, if it passes regex check, default value or undef otherwise.
The regular expression is applied to the WHOLE string, from beginning to end, not just the middle. Use '.*' if you really trust the data.
Dies if regular expression didn't match and the route has the strict flag.
[EXPERIMENTAL] If param_regex hash was given during route definition, $regex MAY be omitted for params that were listed there. This feature is not stable yet, though. Use with care.
If method other than GET/HEAD is being used, whatever is in the address line after ? is IGNORED. Use url_param (see below) if you intend to mix GET/POST parameters.
[NOTE] param() ALWAYS returns a single value, even in list context. Use multi_param() (see below) if you really want a list.
[NOTE] param() has nothing to do with getting parameter list from request. Instead, use form with wildcards:
neaf form => "my_form" => [ [ 'guest\d+' => '.*'], [ 'arrival\d+' => '.*' ] ],
engine => 'Wildcard';
# later in controller
my $guests = $req->form("my_form");
$guests->fields; # has guest1 & arrival1, guest2 & arrival2 etc
$guests->error; # hash with values that didn't match regexSee MVC::Neaf::X::Form::Wildcard.
url_param( ... )
$req->url_param( name => qr/regex/ )
If method is GET or HEAD, identical to param.
Otherwise would return the parameter from query string, AS IF it was a GET request.
Dies if regular expression didn't match and the route has the strict flag.
Multiple values are deliberately ignored.
See CGI.
multi_param( ... )
$req->multi_param( name => qr/regex/ )
Get a multiple value GET/POST parameter as a @list. The name generally follows that of newer CGI (4.08+).
ALL values must match the regex, or an empty list is returned. Dies if strict mode if enabled for route and there is a mismatch.
[EXPERIMENTAL] If param_regex hash was given during route definition, $regex MAY be omitted for params that were listed there. This feature is not stable yet, though. Use with care.
[EXPERIMENTAL] This method's behavior MAY change in the future. Please be careful when upgrading.
set_param( ... )
$req->set_param( name => $value )
Override form parameter. Returns self.
form( ... )
$req->form( $validator )
Apply validator to raw params and return whatever it returns.
A validator MUST be an object with validate method, or a coderef, or a symbolic name registered earlier via neaf form ....
Neaf's own validators, MVC::Neaf::X::Form and MVC::Neaf::X::Form::LIVR, will return a MVC::Neaf::X::Form::Data object with the following methods:
is_valid - tells whether data passed validation
error - hash of errors, can also be modified if needed:
$result->error( myfield => "Correct, but not found in database" );data - hash of valid, cleaned data
raw - hash of data entered initially, may be useful to display input form again.
You are encouraged to use this return format from your own validation class or propose improvements.
get_form_as_list( ... )
$req->get_form_as_list( qr/.../, qw(name1 name2 ...) )
get_form_as_list( ... )
$req->get_form_as_list( [ qr/.../, "default" ], qw(name1 name2 ...) )
Return a group of uniform parameters as a list, in that order. Values that fail validation are returned as undef, unless default given.
[EXPERIMENTAL] The name MAY be changed in the future.
body()
See "body_raw" below.
body_text()
Returns request body for PUT/POST requests as unicode text.
WARNING Encodings other than UTF-8 are not supported as of yet.
body_json()
Get decoded request body in JSON format. In case of errors, error 422 is thrown.
body_raw()
Returns request body for PUT/POST requests as binary data. Decoding and validation is left up to the user.
upload_utf8( ... )
upload_raw( ... )
$req->upload_utf8( "name" )Returns an MVC::Neaf::Upload object corresponding to an uploaded file, if such uploaded file is present.
All data read from such upload will be converted to unicode, raising an exception if decoding ever fails.
An upload object has at least
handleandcontentmethods to work with data:my $upload = $req->upload("user_file"); if ($upload) { my $untrusted_filename = $upload->filename; my $fd = $upload->handle; while (<$fd>) { ... }; }or just
if ($upload) { while ($upload->content =~ /(...)/g) { do_something($1); }; };$req->upload_raw( "name" )Like above, but no decoding whatsoever is performed.
get_cookie( ... )
$req->get_cookie( "name" => qr/regex/ [, "default" ] )
Fetch client cookie. The cookie MUST be sanitized by regular expression.
The regular expression is applied to the WHOLE string, from beginning to end, not just the middle. Use '.*' if you really need none.
Dies if regular expression didn't match and the route has the strict flag.
set_cookie( ... )
$req->set_cookie( name => "value", %options )
Set HTTP cookie. %options may include:
regex- regular expression to check outgoing valuettl- time to live in seconds. 0 means nottl. Use negativettland empty value to delete cookie.expire- UNIX time stamp when the cookie expires (overridden byttl).expires- [DEPRECATED] - use 'expire' instead (without trailing "s")domainpathhttponly- flagsecure- flag
Returns self.
delete_cookie( ... )
$req->delete_cookie( "name" )
Remove cookie by setting value to an empty string, and expiration in the past. [NOTE] It is up to the user agent to actually remove cookie.
Returns self.
format_cookies
Converts stored cookies into an arrayref of scalars ready to be put into Set-Cookie header.
error( ... )
$req->error( status )
Report error to the CORE.
This throws an MVC::Neaf::Exception object.
If you're planning calling $req->error within eval block, consider using neaf_err function to let it propagate:
use MVC::Neaf::Exception qw(neaf_err);
eval {
$req->error(422)
if ($foo);
$req->redirect( "http://google.com" )
if ($bar);
};
if ($@) {
neaf_err($@);
# The rest of the catch block
};redirect( ... )
$req->redirect( $location )
Redirect to a new location.
This throws an MVC::Neaf::Exception object. See error() discussion above.
header_in( ... )
header_in()- return headers as-is$req->header_in( "header_name", qr/.../ )
Fetch HTTP header sent by client. Header names are canonized, so Http-Header, HTTP_HEADER and http_header are all the same.
Without argument, returns a HTTP::Headers::Fast object.
With a name, returns all values for that header in list context, or ", " - joined value as one scalar in scalar context. An empty string is returned if no such header is present.
If regex fails to match any of the header values, error 422 is thrown.
This call still works without regex, but such behavior is deprecated.
referer
Get/set HTTP referrer - i.e. where the request pretends to come from.
[NOTE] Avoid using this for anything serious/secure - too easy to forge.
user_agent
Get/set user_agent.
[NOTE] Avoid using user_agent for anything serious - too easy to forge.
content_type
Returns Content-Type request header, if present, or an empty string.
The usage of Content-Type in GET/HEAD requests is discouraged. See also body.
dump ()
Dump whatever came in the request. Useful for debugging.
SESSION MANAGEMENT
session()
Get reference to session data. This reference is guaranteed to be the same throughout the request lifetime.
If MVC::Neaf->set_session_handler() was called during application setup, this data will be initialized by that handler; otherwise initializes with an empty hash (or whatever session engine generates).
If session engine was not provided, dies instead.
See MVC::Neaf::X::Session for details about session engine internal API.
load_session
Like above, but don't create session - just fetch from cookies & storage.
Never tries to load anything if session already loaded or created.
save_session( ... )
$req->save_session( [$replace] )
Save whatever is in session data reference.
If argument is given, replace session (if any) altogether with that one before saving.
delete_session()
Remove session.
REPLY METHODS
Typically, a Neaf user only needs to return a hashref with the whole reply to client.
However, sometimes more fine-grained control is required.
In this case, a number of methods help stashing your data (headers, cookies etc) in the request object until the response is sent.
Also some lengthly actions (e.g. writing request statistics or sending confirmation e-mail) may be postponed until the request is served.
header_out( ... )
$req->header_out( [$header_name] )
Without parameters returns a HTTP::Headers::Fast-compatible object containing all headers to be returned to client.
With one parameter returns this header.
Returned values are just proxied HTTP::Headers::Fast returns. It is generally advised to use them in list context as multiple headers may return trash in scalar context.
E.g.
my @old_value = $req->header_out( foobar => set => [ "XX", "XY" ] );or
my $old_value = [ $req->header_out( foobar => delete => 1 ) ];[NOTE] This format may change in the future.
set_header( ... )
push_header( ... )
remove_header( ... )
$req->set_header( $name, $value || [] )$req->push_header( $name, $value || [] )$req->remove_header( $name )
Set, append, and delete values in the header_out object. See HTTP::Headers::Fast.
Arrayrefs are fine and will set multiple values for a given header.
reply
Returns reply hashref that was returned by controller, if any. Returns undef unless the controller was actually called. This may be useful in postponed actions or hooks.
This is killed by a clear() call.
stash( ... )
Stash (ah, the naming...) is a temporary set of data that only lives throughtout request's lifetime and never gets to the client.
This may be useful to maintain shared data across hooks and callbacks. Usage is as follows:
$req->stash()- get the whole stash as hash.$req->stash( "name" )- get a single value$req->stash( %save_data )- set multiple values, old data is overridden rather than replaced.
As a rule of thumb,
use
sessionif you intend to share data between requests;use
replyif you intend to render the data for the user;use
stashas a last resort for temporary, private data.
Stash is not killed by clear() function so that cleanup hooks aren't botched accidentally.
postpone( ... )
$req->postpone( CODEREF->($request) )$req->postpone( [ CODEREF->($request), ... ] )
Execute a function (or several) right after the request is served.
Can be called multiple times.
[CAVEAT] If CODEREF contains reference to the request, the request will never be destroyed due to circular reference. Thus CODEREF may not be executed.
Don't pass request to CODEREF, use my $req = shift instead.
Returns self.
write( ... )
$req->write( $data )
Write data to client inside -continue callback, unless close was called.
Returns self.
close()
Stop writing to client in -continue callback.
By default, does nothing, as the socket will probably be closed anyway when the request finishes.
clear()
Remove all data that belongs to reply. This is called when a handler bails out to avoid e.g. setting cookies in a failed request.
DEVELOPER METHODS
id()
Fetch unique request id. If none has been set yet (see "set_id"), use "make_id" method to create one.
The request id is present in both log messages from Neaf and default error pages, making it easier to establish link between the two.
Custom ids can be provided, see "make_id" below.
set_id( ... )
$req->set_id( $new_value )
Set the id above to a user-supplied value.
If a false value given, just generate a new one next time id is requested.
Symbols outside ascii, as well as whitespace and " and C"\", are prohibited.
Returns the request object.
log_error( ... )
$req->log_error( $message )
Log an error message, annotated with request id and the route being processed.
Currently works via warn, but this may change in the future.
[EXPERIMENTAL] This feature is still under development.
One can count on log_error to be available in the future and do some king of logging.
execute_postponed()
NOT TO BE CALLED BY USER.
Execute postponed functions. This is called in DESTROY by default, but request driver may decide it knows better.
Flushes postponed queue. Ignores exceptions in functions being executed.
Returns self.
METHODS THAT CAN BE OVERRIDDEN
Generally Neaf allows to define custom Request methods restricted to certain path & method combinations.
The following methods are available by default, but can be overridden via the helper mechanism.
For instance,
use MVC::Neaf;
my $id;
neaf helper => make_id => sub { $$ . "_" . ++$id };
neaf helper => make_id => \&unique_secure_base64, path => '/admin';make_id
Create unique request id, e.g. for logging context. This is called by "id" if the id has not yet been set.
By default, generates MD5 checksum based on time, hostname, process id, and a sequential number and encodes as URL-friendly base64.
[CAUTION] This should be unique, but may not be secure. Use MVC::Neaf::X::Session if you need something to rely upon.
log_message
$req->log_message( $level => $message );By default would print uppercased level, $request->id, route, and the message itself.
Levels are not restricted whatsoever. Suggested values are "fatal", "error", "warn", "debug".
DRIVER METHODS
The following methods MUST be implemented in every Request subclass to create a working Neaf backend.
They SHOULD NOT be called directly inside the application.
do_get_client_ip()
do_get_http_version()
do_get_method()
do_get_scheme()
do_get_hostname()
do_get_port()
do_get_path()
do_get_params()
do_get_param_as_array() - get single GET/POST parameter in list context
do_get_upload()
do_get_body()
do_get_header_in() - returns a HTTP::Headers-compatible object.
do_reply( $status, $content ) - write reply to client
do_reply( $status ) - only send headers to client
do_write( $data )
do_close()
DEPRECATED METHODS
Some methods become obsolete during Neaf development. Anything that is considered deprecated will continue to be supported for at least three minor versions after official deprecation and a corresponding warning being added.
Please keep an eye on Changes though.
Here are these methods, for the sake of completeness.
script_name
See "prefix"
path_info
See "postfix".
path_info_split
See "prefix"
These three will start warning in 0.30 and will be removed in 0.40
header_in_keys ()
Return all keys in header_in object as a list.
[DEPRECATED] Use $req->header_in->header_field_names instead.
endpoint_origin
Returns file:line where controller was defined.
[DEPRECATED] This function was added prematurely and shall not be used.
get_form_as_hash( ... )
$req->get_form_as_hash( name => qr/.../, name2 => qr/..../, ... )
[DEPRECATED] and dies. Use MVC::Neaf::X::Form instead.
set_default( ... )
$req->set_default( key => $value, ... )
As of v.0.20 this dies.
Use path-based defaults, or stash().
get_default()
As of v.0.20 this dies.
Use path-based defaults, or stash().
LICENSE AND COPYRIGHT
This module is part of MVC::Neaf suite.
Copyright 2016-2023 Konstantin S. Uvarin khedin@cpan.org.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.