CGI-Tiny
view release on metacpan or search on metacpan
CGI::Tiny only loads code or processes information once it is needed,
so simple requests can be handled without unnecessary overhead.
* Restrained
CGI::Tiny is designed for the CGI protocol which executes the program
again for every request. It is not suitable for persistent protocols
like FastCGI or PSGI.
* Flexible
CGI::Tiny can be used with other modules to handle tasks like routing
and templating, and doesn't impose unnecessary constraints to reading
input or rendering output.
Most applications are better written in a PSGI-compatible framework
(e.g. Dancer2 or Mojolicious) and deployed in a persistent application
server so that the application does not have to start up again every
time it receives a request. CGI::Tiny, and the CGI protocol in general,
is only suited for restricted deployment environments that can only run
CGI scripts, or applications that don't need to scale.
See "COMPARISON TO CGI.PM".
USAGE
CGI::Tiny's interface is the cgi block.
use CGI::Tiny;
cgi {
my $cgi = $_;
# set up error handling on $cgi
# inspect request data via $cgi
# set response headers if needed via $cgi
# render response with $cgi->render or $cgi->render_chunk
};
The block is immediately run with $_ set to a CGI::Tiny object, which
"METHODS" can be called on to read request information and render a
response.
If an exception is thrown within the block, or the block does not
render a response, it will run the handler set by "set_error_handler"
if any, or by default emit the error as a warning and (if nothing has
been rendered yet) render a 500 Internal Server Error.
The default server error will also be rendered if the process ends
abnormally between importing from CGI::Tiny and the start of the cgi
block. To load CGI::Tiny without triggering this cleanup mechanism or
making the cgi block available (such as to use convenience "FUNCTIONS"
in non-CGI code), load the module with use CGI::Tiny (); or require
CGI::Tiny;.
NOTE: The cgi block's current implementation as a regular exported
subroutine is an implementation detail, and future implementations
reserve the right to provide it as an XSUB or keyword for performance
reasons. Don't call it as CGI::Tiny::cgi, don't rely on @_ being set,
and don't use return to exit the block; use exit to end a CGI script
early after rendering a response.
See CGI::Tiny::Cookbook for advanced usage examples.
DATA SAFETY
CGI::Tiny does not provide any special affordances for taint mode as it
is overeager, imprecise, and can significantly impact performance. Web
developers should instead proactively take care not to use any request
data (including request headers, form fields, or other request content)
directly in an unsafe manner, as it can make the program vulnerable to
injections that cause undesired or dangerous behavior. The most common
risks to watch out for include:
* System commands
Do not interpolate arbitrary data into a shell command, such as with
system or backticks. Data can be safely passed as command arguments
using methods that bypass the shell, such as the list form of system,
or modules like IPC::System::Simple, IPC::ReadpipeX, and IPC::Run3.
If shell features are needed, data can be escaped for bourne-style
shells with String::ShellQuote.
* Database queries
Do not interpolate arbitrary data into database queries. Data can be
safely passed to database queries using placeholders
<https://metacpan.org/pod/DBI#Placeholders-and-Bind-Values>.
* Regex
Do not interpolate arbitrary data into regular expressions, such as
the m// or s/// operators, or the first argument to split. Data can
be safely included in a regex to match it as an exact string by
escaping it with the quotemeta function or equivalent \Q escape
sequence.
* HTML
Do not interpolate arbitrary data into HTML. Data can be safely
included in HTML by escaping it with "escape_html", or passing it to
an HTML template engine with an auto-escape feature; see "Templating"
in CGI::Tiny::Cookbook.
METHODS
The following methods can be called on the CGI::Tiny object provided to
the cgi block.
Setup
set_error_handler
$cgi = $cgi->set_error_handler(sub {
my ($cgi, $error, $rendered) = @_;
...
});
Sets an error handler to run in the event of an exception or if the
script ends without rendering a response. The handler will be called
with the CGI::Tiny object, the error value, and a boolean indicating
whether response headers have been rendered yet.
The error value can be any exception thrown by Perl or user code. It
should generally not be included in any response rendered to the
client, but instead warned or logged.
Exceptions may occur before or after response headers have been
rendered. If response headers have not been rendered, error handlers
may inspect "response_status_code" and/or render some error response.
The response status code will be set to 500 when this handler is called
if it has not been set to a specific 400- or 500-level error status.
If the error handler itself throws an exception, that error and the
original error will be emitted as a warning. If no response has been
rendered after the error handler completes or dies, a default error
response will be rendered.
NOTE: The error handler is only meant for logging and customization of
the final error response in a failed request dispatch; to handle
exceptions within standard application flow without causing an error
response, use an exception handling mechanism such as
Syntax::Keyword::Try or Feature::Compat::Try (which will use the new
try feature if available).
set_request_body_buffer
$cgi = $cgi->set_request_body_buffer(256*1024);
Sets the buffer size (number of bytes to read at once) for reading the
request body. Defaults to the value of the CGI_TINY_REQUEST_BODY_BUFFER
environment variable or 262144 (256 KiB). A value of 0 will use the
default value.
set_request_body_limit
$cgi = $cgi->set_request_body_limit(16*1024*1024);
Sets the limit in bytes for the request body. Defaults to the value of
the CGI_TINY_REQUEST_BODY_LIMIT environment variable or 16777216 (16
MiB). A value of 0 will remove the limit (not recommended unless you
have other safeguards on memory usage).
<https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>
and will have the standard human-readable message appended.
No effect after response headers have been rendered.
The CGI protocol assumes a status of 200 OK if no response status is
set.
set_response_disposition
$cgi = $cgi->set_response_disposition('attachment');
$cgi = $cgi->set_response_disposition(attachment => $filename);
$cgi = $cgi->set_response_disposition('inline'); # default behavior
$cgi = $cgi->set_response_disposition(inline => $filename);
Sets the response Content-Disposition header to indicate how the client
should present the response, with an optional filename specified in
Unicode characters. attachment suggests to download the content as a
file, and inline suggests to display the content inline (the default
behavior). No effect after response headers have been rendered.
set_response_type
$cgi = $cgi->set_response_type('application/xml');
Sets the response Content-Type header, to override autodetection in
"render" or "render_chunk". undef will remove the override. No effect
after response headers have been rendered.
set_response_charset
$cgi = $cgi->set_response_charset('UTF-8');
Set charset to use when rendering text, html, or xml response content,
defaults to UTF-8.
add_response_header
$cgi = $cgi->add_response_header('Content-Language' => 'en');
Adds a custom response header. No effect after response headers have
been rendered.
NOTE: Header names are case insensitive and CGI::Tiny does not attempt
to deduplicate or munge headers that have been added manually. Headers
are printed in the response in the same order added, and adding the
same header multiple times will result in multiple instances of that
response header.
add_response_cookie
$cgi = $cgi->add_response_cookie($name => $value,
Expires => 'Sun, 06 Nov 1994 08:49:37 GMT',
HttpOnly => 1,
'Max-Age' => 3600,
Path => '/foo',
SameSite => 'Strict',
Secure => 1,
);
Adds a Set-Cookie response header. No effect after response headers
have been rendered.
Cookie values should consist only of simple ASCII text; see "Cookies"
in CGI::Tiny::Cookbook for methods of storing more complex strings and
data structures.
Optional cookie attributes are specified in key-value pairs after the
cookie name and value. Cookie attribute names are case-insensitive.
Domain
Domain for which cookie is valid. Defaults to the host of the current
document URL, not including subdomains.
Expires
Expiration date string for cookie. Defaults to persisting for the
current browser session. "epoch_to_date" can be used to generate the
appropriate date string format.
HttpOnly
If set to a true value, the cookie will be restricted from
client-side scripts.
Max-Age
Max age of cookie before it expires, in seconds, as an alternative to
specifying Expires.
Path
URL path for which cookie is valid.
SameSite
Strict to restrict the cookie to requests from the same site, Lax to
allow it additionally in certain cross-site requests. This attribute
is currently part of a draft specification so its handling may
change, but it is supported by most browsers.
Secure
If set to a true value, the cookie will be restricted to HTTPS
requests.
reset_response_headers
$cgi = $cgi->reset_response_headers;
Remove any pending response headers set by "add_response_header" or
"add_response_cookie". No effect after response headers have been
rendered.
response_status_code
my $code = $cgi->response_status_code;
Numerical response HTTP status code that will be sent when headers are
rendered, as set by "set_response_status" or an error occurring.
Defaults to 200.
render
$cgi = $cgi->render; # default Content-Type:
$cgi = $cgi->render(text => $text); # text/plain;charset=$charset
$cgi = $cgi->render(html => $html); # text/html;charset=$charset
$cgi = $cgi->render(xml => $xml); # application/xml;charset=$charset
The Date response header will be set to the current time as an HTTP
date string if not set manually.
If the "request_method" is HEAD, any provided response content will be
ignored.
text, html, or xml data is expected to be decoded Unicode characters,
and will be encoded according to "set_response_charset" (UTF-8 by
default). Unicode::UTF8 will be used for efficient UTF-8 encoding if
available.
json data structures will be encoded to JSON and UTF-8.
data, file, or handle will render bytes from a string, local file path,
or open filehandle respectively. A handle will have binmode applied to
remove any translation layers, and its contents will be streamed until
EOF.
redirect responses must be rendered with "render".
FUNCTIONS
The following convenience functions are provided but not exported.
epoch_to_date
my $date = CGI::Tiny::epoch_to_date $epoch;
Convert a Unix epoch timestamp, such as returned by time, to a RFC 1123
HTTP date string suitable for use in HTTP headers such as Date and
Expires.
date_to_epoch
my $epoch = CGI::Tiny::date_to_epoch $date;
Parse a RFC 1123 HTTP date string to a Unix epoch timestamp. For
compatibility as required by RFC 7231
<https://tools.ietf.org/html/rfc7231#section-7.1.1.1>, legacy RFC 850
and ANSI C asctime date formats are also recognized. Returns undef if
the string does not parse as any of these formats.
# RFC 1123
my $epoch = CGI::Tiny::date_to_epoch 'Sun, 06 Nov 1994 08:49:37 GMT';
# RFC 850
my $epoch = CGI::Tiny::date_to_epoch 'Sunday, 06-Nov-94 08:49:37 GMT';
# asctime
my $epoch = CGI::Tiny::date_to_epoch 'Sun Nov 6 08:49:37 1994';
escape_html
my $escaped = CGI::Tiny::escape_html $text;
Escapes characters that are unsafe for embedding in HTML text. The
characters &<>"' will each be replaced with the corresponding HTML
character reference (HTML entity).
This functionality is built into most HTML template engines; see
"Templating" in CGI::Tiny::Cookbook. For more general HTML entity
escaping and unescaping use HTML::Entities.
ENVIRONMENT
CGI::Tiny recognizes the following environment variables, in addition
to the standard CGI environment variables.
CGI_TINY_REQUEST_BODY_BUFFER
Default value for "set_request_body_buffer".
CGI_TINY_REQUEST_BODY_LIMIT
Default value for "set_request_body_limit".
CGI_TINY_RESPONSE_BODY_BUFFER
Default value for "set_response_body_buffer".
DEBUGGING COMMANDS
CGI::Tiny scripts can be executed from the commandline for debugging
purposes. A command can be passed as the first argument to help set up
the CGI environment.
These commands are considered a development interface and come with no
stability guarantee.
$ ./script.cgi get '/?foo=bar'
$ ./script.cgi head
$ ./script.cgi post '/form' -C 'one=value' -C 'two=value' --content='foo=bar+baz'
-H 'Content-Type: application/x-www-form-urlencoded'
$ ./script.cgi put -H "Content-Length: $(stat --printf='%s' foo.dat)"
-H "Content-Type: $(file -bi foo.dat)" <foo.dat
$ ./script.cgi delete -v '/item/42'
The get, head, post, put, and delete commands will emulate a request of
the specified "request_method". A following URL parameter will be
passed as the "path_info" and "query_string" if present.
Request content may be provided through STDIN but the Content-Length
request header must be set to the size of the input as required by the
CGI spec.
The response will be printed to STDOUT as normal. You may wish to
redirect the output of the command to a file or hexdump program if the
response is expected not to be printable text in the character encoding
of your terminal.
Options may follow the command:
--content=<string>, -c <string>
Passes the string value as request body content and sets the
Content-Length request header to its size.
--cookie=<string>, -C <string>
String values of the form name=value will be passed as request
cookies. Can appear multiple times.
Traditionally, the CGI module (referred to as CGI.pm to differentiate
it from the CGI protocol) has been used to write Perl CGI scripts. This
module fills a similar need but has a number of interface differences
to be aware of.
* There is no CGI::Tiny object constructor; the object is accessible
within the cgi block, only reads request data from the environment
once it is accessed, and ensures that a valid response is rendered to
avoid gateway errors even in the event of an exception or premature
exit.
* Instead of global variables like $CGI::POST_MAX, global behavior
settings are applied to the CGI::Tiny object inside the cgi block.
* Exceptions within the cgi block are handled by default by rendering
a server error response and emitting the error as a warning. This can
be customized with "set_error_handler".
* Request parameter accessors in CGI::Tiny are not context sensitive,
as context sensitivity can lead to surprising behavior and
vulnerabilities
<https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-1572>.
"param", "query_param", "body_param", and "upload" always return a
single value; "param_array", "query_param_array", "body_param_array",
and "upload_array" must be used to retrieve multi-value parameters.
* CGI::Tiny's "param" accessor is also not method-sensitive; it
accesses either query or body request parameters with the same
behavior regardless of request method, and query and body request
parameters can be accessed separately with "query_param" and
"body_param" respectively.
* CGI::Tiny's "param" accessor only retrieves text parameters;
uploaded files and their metadata are accessed with "upload" and
related methods.
* CGI::Tiny decodes request parameters to Unicode characters
automatically, and "render"/"render_chunk" provide methods to encode
response content from Unicode characters to UTF-8 by default.
* In CGI.pm, response headers must be printed manually before any
response content is printed to avoid malformed responses. In
CGI::Tiny, the "render" or "render_chunk" methods are used to print
response content, and automatically print response headers when first
called. redirect responses are also handled by "render".
* In CGI::Tiny, a custom response status is set by calling
"set_response_status" before the first "render" or "render_chunk",
which only requires the status code and will add the appropriate
human-readable status message itself.
* Response setters are distinct methods from request accessors in
CGI::Tiny. "content_type", "header", and "cookie" are used to access
request data, and "set_response_type", "add_response_header", and
"add_response_cookie" are used to set response headers for the
pending response before the first call to "render" or "render_chunk".
* CGI::Tiny does not provide any HTML generation helpers, as this
functionality is much better implemented by other robust
implementations on CPAN; see "Templating" in CGI::Tiny::Cookbook.
* CGI::Tiny does not do any implicit encoding of cookie values or the
Expires header or cookie attribute. See "Cookies" in
CGI::Tiny::Cookbook for examples of encoding and decoding cookie
values. The "epoch_to_date" convenience function is provided to
render appropriate Expires date values.
There are a number of alternatives to CGI.pm but they do not
sufficiently address the design issues; primarily, none of them
gracefully handle exceptions or failure to render a response, and
several of them have no features for rendering responses.
* CGI::Simple shares all of the interface design problems of CGI.pm,
though it does not reimplement the HTML generation helpers.
* CGI::Thin is ancient and only implements parsing of request query
or body parameters, without decoding them to Unicode characters.
* CGI::Minimal has context-sensitive parameter accessors, and only
implements parsing of request query/body parameters (without decoding
them to Unicode characters) and uploads.
* CGI::Lite has context-sensitive parameter accessors, and only
implements parsing of request query/body parameters (without decoding
them to Unicode characters), uploads, and cookies.
* CGI::Easy has a robust interface, but pre-parses all request
information.
CAVEATS
CGI is an extremely simplistic protocol and relies particularly on the
global state of environment variables and the STDIN and STDOUT standard
filehandles. CGI::Tiny does not prevent you from messing with these
interfaces directly, but it may result in confusion.
CGI::Tiny eschews certain sanity checking for performance reasons. For
example, Content-Type and other header values set for the response
should only contain ASCII text with no control characters, but
CGI::Tiny does not verify this (though it does verify they do not
contain newline characters to protect against HTTP response splitting).
Field names and filenames in multipart/form-data requests do not have a
well-defined escape mechanism for special characters, so CGI::Tiny will
not attempt to decode these names from however the client passes them
aside from "set_multipart_form_charset". For best compatibility, form
field names should be ASCII without double quotes or semicolons.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2021 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
( run in 1.222 second using v1.01-cache-2.11-cpan-39bf76dae61 )