.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "Mojolicious::Guides::FAQ 3"
.TH Mojolicious::Guides::FAQ 3 "2022-06-14" "perl v5.26.3" "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"
Mojolicious::Guides::FAQ \- Frequently Asked Questions
.SH "OVERVIEW"
.IX Header "OVERVIEW"
This document contains answers for the most frequently asked questions about Mojolicious.
.SH "QUESTIONS"
.IX Header "QUESTIONS"
We hope these answers are to your satisfaction.
.SS "How does Mojolicious compare to other Perl web frameworks?"
.IX Subsection "How does Mojolicious compare to other Perl web frameworks?"
The short answer is \*(L"it doesn't\*(R", because we interpret the term \*(L"web framework\*(R" much more literally than others. With
the emergence of the real-time web and new technologies such as WebSockets, we are facing new challenges that go way
beyond what commonly used modules like \s-1LWP\s0 were designed for. Because of this, Mojolicious contains a whole new
\&\s-1HTTP\s0 client/server stack called Mojo, which was heavily inspired by the original LWPng effort and carefully designed
with these new requirements in mind. So while some of the higher abstraction layers might look similar to other web
frameworks, it is more of a web toolkit and can even be used as the foundation for more advanced web frameworks.
.SS "Why doesn't Mojolicious have any dependencies?"
.IX Subsection "Why doesn't Mojolicious have any dependencies?"
We are optimizing Mojolicious for user-friendliness and development speed, without compromises. While there are no
rules in Mojolicious::Guides::Contributing that forbid dependencies, we do currently discourage adding non-optional
ones in favor of a faster and more painless installation process. And we do in fact already use several optional \s-1CPAN\s0
modules such as Cpanel::JSON::XS, \s-1EV\s0, IO::Socket::Socks, IO::Socket::SSL, Net::DNS::Native, Plack and
Role::Tiny to provide advanced functionality if possible.
.SS "Why reinvent wheels?"
.IX Subsection "Why reinvent wheels?"
Because we can make them rounder. Components specifically designed for user-friendliness and development speed are not
easy to come by. We are strong believers of the Perl mantra \*(L"There is more than one way to do it\*(R", and our quest is to
develop the best possible solutions for these two criteria.
.SS "What about backwards compatibility?"
.IX Subsection "What about backwards compatibility?"
In conformance with Mojolicious::Guides::Contributing, we will always deprecate a feature for 3 months, before
removing or changing it in incompatible ways between major releases. New features can however be marked as experimental
to explicitly exclude them from these rules. This gives us the necessary freedom to ensure a healthy future for
Mojolicious. So, as long as you are not using anything marked experimental, untested or undocumented, you can always
count on backwards compatibility, everything else would be considered a bug. However, to completely avoid any risk of
accidental breakage, we do recommend following current best practices for version pinning with Carton for production
setups.
.SS "Why not split up Mojolicious into many smaller distributions?"
.IX Subsection "Why not split up Mojolicious into many smaller distributions?"
Because there are no advantages, it drastically increases maintenance costs and installation times without giving us
anything in return. It would only make sense if we wanted to pass ownership of a module to a new maintainer, which we
already have done in the past.
.SS "Where can I discuss my patches for Mojolicious?"
.IX Subsection "Where can I discuss my patches for Mojolicious?"
We'd love to discuss your contributions to Mojolicious on Matrix <https://matrix.to/#/#mojo:matrix.org> or
\&\s-1IRC\s0 <https://web.libera.chat/#mojo>.
.SS "Which versions of Perl are supported by Mojolicious?"
.IX Subsection "Which versions of Perl are supported by Mojolicious?"
First of all, you need to be aware that according to the perlpolicy, only the two most recent stable release series
of Perl are supported by the community and receive bug fixes, which are currently 5.32.x and 5.30.x. Mojolicious
follows this model and fully supports these two release series. In addition we will also keep the distribution
installable (and that means passing all tests) up to a certain legacy version that the core team deems worthy of
supporting, but not specifically optimize for it, this is currently 5.16.0.
.SS "How well is Windows supported by Mojolicious?"
.IX Subsection "How well is Windows supported by Mojolicious?"
Windows is not officially supported by Mojolicious, even though we try to keep the distribution installable. There
may be serious security and/or reliability issues. Some of the more advanced features, such as
subprocesses and the Hypnotoad web server, will also require
the use of the Windows Subsystem for Linux <https://msdn.microsoft.com/commandline/wsl/>.
.SS "Is Perl's taint mode supported by Mojolicious?"
.IX Subsection "Is Perl's taint mode supported by Mojolicious?"
No. There is no benefit at all to using taint mode. Modern Perl applications are much too complex to benefit from such a
naive mechanism in any meaningful way. At best it would give you a false sense of security.
.SS "Do I need to clean my environment before testing Mojolicious?"
.IX Subsection "Do I need to clean my environment before testing Mojolicious?"
Mojolicious uses many environment variables both internally and externally, notably (but not exclusively) those
starting with the prefix \f(CW\*(C`MOJO_*\*(C'\fR and \f(CW\*(C`PLACK_ENV\*(C'\fR. The test suite expects a clean environment; testing with a
non-standard environment is unsupported and is unlikely to succeed. Therefore when installing or upgrading
Mojolicious and when running its tests, we highly recommend using an environment which does not set these variables.
.SS "Where did my file extension go?"
.IX Subsection "Where did my file extension go?"
Standard route placeholders will not match the \f(CW\*(C`.\*(C'\fR character, however Mojolicious routes automatically take file
extensions like \f(CW\*(C`.html\*(C'\fR, remove the leading \f(CW\*(C`.\*(C'\fR, and store the result in the \f(CW\*(C`format\*(C'\fR stash value. This can be
useful for URL-based content negotiation, such as automatically rendering different templates based on the file
extension. See \*(L"Formats\*(R" in Mojolicious::Guides::Routing for information on customizing format detection, or consider
using relaxed placeholders to allow matching of the \f(CW\*(C`.\*(C'\fR
character.
.SS "Can I configure Hypnotoad from the command line?"
.IX Subsection "Can I configure Hypnotoad from the command line?"
No, you can't, Hypnotoad is a bit special in this regard. Because when you initiate a zero
downtime software upgrade (hot deployment), you are only really sending a \f(CW\*(C`USR2\*(C'\fR signal to the already running server,
and no other information can be passed along. What you can do instead, is to use a Mojolicious::Plugin::Config,
Mojolicious::Plugin::JSONConfig or Mojolicious::Plugin::NotYAMLConfig configuration file.
.PP
.Vb 7
\&  # myapp.conf
\&  {
\&    hypnotoad => {
\&      listen  => [\*(Aqhttp://*:8080\*(Aq],
\&      workers => 10
\&    }
\&  };
.Ve
.PP
Or if you don't actually need zero downtime software upgrades, just use Mojolicious::Command::prefork instead, which
is otherwise almost identical to Hypnotoad.
.PP
.Vb 1
\&  $ ./myapp.pl prefork \-m production \-l http://*:8080 \-w 10
.Ve
.ie n .SS "What does the error ""...certificate verify failed"" mean?"
.el .SS "What does the error ``...certificate verify failed'' mean?"
.IX Subsection "What does the error ...certificate verify failed mean?"
There are many variations of this error, but most of them mean that \s-1TLS\s0 certificate verification in Mojo::UserAgent
failed. This usually happens for two reasons. The most common one is that the peer certificate is simply invalid. If
that's the case and you are certain that no \s-1MITM\s0 attack is being attempted, you can use the attribute
\&\*(L"insecure\*(R" in Mojo::UserAgent or \f(CW\*(C`MOJO_INSECURE\*(C'\fR environment variable to disable certificate verification. And if
that's not the case you might be missing the Mozilla::CA module, which is often required by IO::Socket::SSL to be
able to verify certificates.
.ie n .SS "What does the error ""Maximum message size exceeded"" mean?"
.el .SS "What does the error ``Maximum message size exceeded'' mean?"
.IX Subsection "What does the error Maximum message size exceeded mean?"
To protect your applications from excessively large requests and responses, our \s-1HTTP\s0 parser has a cap after which it
will automatically stop accepting new data, and in most cases force the connection to be closed. The limit is 16MiB for
requests, and 2GiB for responses by default. You can use the attributes \*(L"max_request_size\*(R" in Mojolicious and
\&\*(L"max_response_size\*(R" in Mojo::UserAgent to change these values.
.ie n .SS "What does the error ""Maximum start-line size exceeded"" mean?"
.el .SS "What does the error ``Maximum start-line size exceeded'' mean?"
.IX Subsection "What does the error Maximum start-line size exceeded mean?"
This is a very similar protection mechanism to the one described in the previous answer, but a little more specific. It
limits the maximum length of the start-line for \s-1HTTP\s0 requests and responses. The limit is 8KiB by default, you can use
the attribute \*(L"max_line_size\*(R" in Mojo::Message or \f(CW\*(C`MOJO_MAX_LINE_SIZE\*(C'\fR environment variable to change this value.
.ie n .SS "What does the error ""Maximum header size exceeded"" mean?"
.el .SS "What does the error ``Maximum header size exceeded'' mean?"
.IX Subsection "What does the error Maximum header size exceeded mean?"
Almost the same as the previous answer, but this protection mechanism limits the number and maximum length of \s-1HTTP\s0
request and response headers. The limits are 100 headers with 8KiB each by default, you can use the attributes
\&\*(L"max_lines\*(R" in Mojo::Headers and \*(L"max_line_size\*(R" in Mojo::Headers or the \f(CW\*(C`MOJO_MAX_LINES\*(C'\fR and \f(CW\*(C`MOJO_MAX_LINE_SIZE\*(C'\fR
environment variables to change these values.
.ie n .SS "What does the error ""Maximum buffer size exceeded"" mean?"
.el .SS "What does the error ``Maximum buffer size exceeded'' mean?"
.IX Subsection "What does the error Maximum buffer size exceeded mean?"
This protection mechanism limits how much content the \s-1HTTP\s0 parser is allowed to buffer when parsing chunked, compressed
and multipart messages. The limit is around 256KiB by default, you can use the attribute
\&\*(L"max_buffer_size\*(R" in Mojo::Content or \f(CW\*(C`MOJO_MAX_BUFFER_SIZE\*(C'\fR environment variable to change this value.
.ie n .SS "What does ""Your secret passphrase needs to be changed"" mean?"
.el .SS "What does ``Your secret passphrase needs to be changed'' mean?"
.IX Subsection "What does Your secret passphrase needs to be changed mean?"
Mojolicious uses secret passphrases for security features such as signed cookies. It defaults to using
\&\*(L"moniker\*(R" in Mojolicious, which is not very secure, so we added this log message as a reminder. You can change the
passphrase with the attribute \*(L"secrets\*(R" in Mojolicious. Since some plugins also depend on it, you should try changing
it as early as possible in your application.
.PP
.Vb 1
\&  $app\->secrets([\*(AqMy very secret passphrase.\*(Aq]);
.Ve
.ie n .SS "What does ""Nothing has been rendered, expecting delayed response"" mean?"
.el .SS "What does ``Nothing has been rendered, expecting delayed response'' mean?"
.IX Subsection "What does Nothing has been rendered, expecting delayed response mean?"
Mojolicious has been designed from the ground up for non-blocking I/O and event loops. So when a new request comes
in and no response is generated right away, it will assume that this was intentional and return control to the web
server, which can then handle other requests while waiting for events such as timers to finally generate a response.
.ie n .SS "What does ""Inactivity timeout"" mean?"
.el .SS "What does ``Inactivity timeout'' mean?"
.IX Subsection "What does Inactivity timeout mean?"
To protect your applications from denial-of-service attacks, all connections have an inactivity timeout which limits
how long a connection may be inactive before being closed automatically. It defaults to \f(CW40\fR seconds for the user
agent and \f(CW30\fR seconds for all built-in web servers, and can be changed with the attributes
\&\*(L"inactivity_timeout\*(R" in Mojo::UserAgent and \*(L"inactivity_timeout\*(R" in Mojo::Server::Daemon or the
\&\f(CW\*(C`MOJO_INACTIVITY_TIMEOUT\*(C'\fR environment variable. In Mojolicious applications you can also use the helper
\&\*(L"inactivity_timeout\*(R" in Mojolicious::Plugin::DefaultHelpers to change it on demand for each connection individually.
This timeout always applies, so you might have to tweak it for applications that take a long time to process a request.
.ie n .SS "What does ""Premature connection close"" mean?"
.el .SS "What does ``Premature connection close'' mean?"
.IX Subsection "What does Premature connection close mean?"
This error message is often related to the one above, and means that the web server closed the connection before the
user agent could receive the whole response or that the user agent got destroyed, which forces all connections to be
closed immediately.
.PP
.Vb 7
\&  # The variable $ua goes out of scope and gets destroyed too early
\&  Mojo::IOLoop\->timer(5 => sub {
\&    my $ua = Mojo::UserAgent\->new;
\&    $ua\->get(\*(Aqhttps://mojolicious.org\*(Aq => sub ($ua, $tx) {
\&      say $tx\->result\->dom\->at(\*(Aqtitle\*(Aq)\->text;
\&    });
\&  });
.Ve
.ie n .SS "What does ""Worker 31842 has no heartbeat (50 seconds), restarting"" mean?"
.el .SS "What does ``Worker 31842 has no heartbeat (50 seconds), restarting'' mean?"
.IX Subsection "What does Worker 31842 has no heartbeat (50 seconds), restarting mean?"
As long as they are accepting new connections, worker processes of all built-in pre-forking web servers send heartbeat
messages to the manager process at regular intervals, to signal that they are still responsive. A blocking operation
such as an infinite loop in your application can prevent this, and will force the affected worker to be restarted after
a timeout. This timeout defaults to \f(CW50\fR seconds and can be extended with the attribute
\&\*(L"heartbeat_timeout\*(R" in Mojo::Server::Prefork if your application requires it.
.ie n .SS "What does ""Transaction already destroyed"" mean?"
.el .SS "What does ``Transaction already destroyed'' mean?"
.IX Subsection "What does Transaction already destroyed mean?"
This error message usually appears after waiting for the results of a non-blocking operation for longer periods of
time, because the underlying connection has been closed in the meantime and the value of the attribute
\&\*(L"tx\*(R" in Mojolicious::Controller is no longer available. While there might not be a way to prevent the connection from
getting closed, you can try to avoid this error message by keeping a reference to the transaction object that is not
weakened.
.PP
.Vb 8
\&  # Keep a strong reference to the transaction object
\&  my $tx = $c\->render_later\->tx;
\&  $c\->ua\->get_p(\*(Aqhttps://mojolicious.org\*(Aq)\->then(sub {
\&    $c\->render(text => \*(AqVisited mojolicious.org\*(Aq);
\&  })\->catch(sub ($err) {
\&    $tx;
\&    $c\->reply\->exception($err);
\&  });
.Ve
.ie n .SS "What does ""Illegal character in prototype"" mean?"
.el .SS "What does ``Illegal character in prototype'' mean?"
.IX Subsection "What does Illegal character in prototype mean?"
Mojolicious assumes subroutine signatures are enabled in documentation examples. If
the signatures feature has not been enabled in that scope, they are interpreted as prototypes,
an unrelated parser feature. Mojolicious does not require signatures; if you don't want to or cannot use signatures
(which require Perl 5.20+), you can translate most signatures into a standard subroutine parameter assignment.
.PP
.Vb 6
\&  # With signatures feature
\&  get \*(Aq/title\*(Aq => sub ($c) {
\&    $c\->ua\->get(\*(Aqmojolicious.org\*(Aq => sub ($ua, $tx) {
\&      $c\->render(data => $tx\->result\->dom\->at(\*(Aqtitle\*(Aq)\->text);
\&    });
\&  };
\&
\&  # Without signatures feature
\&  get \*(Aq/title\*(Aq => sub {
\&    my ($c) = @_;
\&    $c\->ua\->get(\*(Aqmojolicious.org\*(Aq => sub {
\&      my ($ua, $tx) = @_;
\&      $c\->render(data => $tx\->result\->dom\->at(\*(Aqtitle\*(Aq)\->text);
\&    });
\&  };
.Ve
.SH "MORE"
.IX Header "MORE"
You can continue with Mojolicious::Guides now or take a look at the Mojolicious
wiki <https://github.com/mojolicious/mojo/wiki>, which contains a lot more documentation and examples by many different
authors.
.SH "SUPPORT"
.IX Header "SUPPORT"
If you have any questions the documentation might not yet answer, don't hesitate to ask in the
Forum <https://forum.mojolicious.org>, on Matrix <https://matrix.to/#/#mojo:matrix.org>, or
\&\s-1IRC\s0 <https://web.libera.chat/#mojo>.