Mojolicious::Guides::FAQ
Section: User Contributed Perl Documentation (3)
Updated: 2018-10-22
Page Index
NAME
Mojolicious::Guides::FAQ - Frequently Asked Questions
OVERVIEW
This document contains answers for the most frequently asked questions about
Mojolicious.
QUESTIONS
We hope these answers are to your satisfaction.
How does Mojolicious compare to other Perl web frameworks?
The short answer is ``it doesn't'', because we interpret the term ``web framework''
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
LWP were designed for. Because of
this, Mojolicious contains a whole new
HTTP 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.
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
CPAN
modules such as Cpanel::JSON::XS,
EV, IO::Socket::Socks,
IO::Socket::SSL, Net::DNS::Native, Plack and Role::Tiny to provide
advanced functionality if possible.
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 ``There is more than one way to do it'', and our
quest is to develop the best possible solutions for these two criteria.
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.
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.
Where can i discuss my patches for Mojolicious?
We'd love to discuss your contributions to Mojolicious on our official
IRC
channel
"#mojo" on
"irc.freenode.net" (chat
now! <
https://kiwiirc.com/nextclient/#irc://irc.freenode.net/mojo?nick=guest-?>).
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.28.x and 5.26.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.10.1.
Note that Perl versions 5.10.x and 5.12.x are known to work very poorly with
Mojolicious, and we strongly suggest you do not use them, to avoid stability
and security issues. If it wasn't for a very vocal minority within the community
we would not support these versions at all.
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/>.
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
"MOJO_*" and
"PLACK_ENV". 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.
Where did my file extension go?
Standard route placeholders will not match the
"." character, however
Mojolicious routes automatically take file extensions like
".html", remove
the leading
".", and store the result in the
"format" stash value. This can
be useful for URL-based content negotiation, such as automatically rendering
different templates based on the file extension. See
``Formats'' in Mojolicious::Guides::Routing for information on customizing format
detection, or consider using
relaxed placeholders to
allow matching of the
"." character.
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
"USR2" 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 or Mojolicious::Plugin::JSONConfig
configuration file.
# myapp.conf
{
hypnotoad => {
listen => ['http://*:8080'],
workers => 10
}
};
Or if you don't actually need zero downtime software upgrades, just use
Mojolicious::Command::prefork instead, which is otherwise almost identical to
Hypnotoad.
$ ./myapp.pl prefork -m production -l http://*:8080 -w 10
What does the error ...certificate verify failed mean?
There are many variations of this error, but most of them mean that
TLS
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
MITM attack is being attempted,
you can use the attribute ``insecure'' in Mojo::UserAgent or
"MOJO_INSECURE"
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.
What does the error Maximum message size exceeded mean?
To protect your applications from excessively large requests and responses, our
HTTP 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
``max_request_size'' in Mojolicious and ``max_response_size'' in Mojo::UserAgent to
change these values.
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
HTTP requests and responses. The limit is 8KiB by default,
you can use the attribute ``max_line_size'' in Mojo::Message or
"MOJO_MAX_LINE_SIZE" environment variable to change this value.
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
HTTP request and response headers. The limits
are 100 headers with 8KiB each by default, you can use the attributes
``max_lines'' in Mojo::Headers and ``max_line_size'' in Mojo::Headers or the
"MOJO_MAX_LINES" and
"MOJO_MAX_LINE_SIZE" environment variables to change
these values.
What does the error Maximum buffer size exceeded mean?
This protection mechanism limits how much content the
HTTP parser is allowed to
buffer when parsing chunked, compressed and multipart messages. The limit is
around 256KiB by default, you can use the attribute
``max_buffer_size'' in Mojo::Content or
"MOJO_MAX_BUFFER_SIZE" environment
variable to change this value.
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 ``moniker'' in Mojolicious, which is not very
secure, so we added this log message as a reminder. You can change the
passphrase with the attribute ``secrets'' in Mojolicious. Since some plugins also
depend on it, you should try changing it as early as possible in your
application.
$app->secrets(['My very secret passphrase.']);
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.
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
20 seconds for the user
agent and
15 seconds for all built-in web servers, and can be changed with
the attributes ``inactivity_timeout'' in Mojo::UserAgent and
``inactivity_timeout'' in Mojo::Server::Daemon or the
"MOJO_INACTIVITY_TIMEOUT"
environment variable. In Mojolicious applications you can also use the helper
``inactivity_timeout'' 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.
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.
# The variable $ua goes out of scope and gets destroyed too early
Mojo::IOLoop->timer(5 => sub {
my $ua = Mojo::UserAgent->new;
$ua->get('https://mojolicious.org' => sub {
my ($ua, $tx) = @_;
say $tx->result->dom->at('title')->text;
});
});
What does Worker 31842 has no heartbeat (30 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
30 seconds and can be extended with the attribute
``heartbeat_timeout'' in Mojo::Server::Prefork if your application requires it.
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
``tx'' 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.
# Keep a strong reference to the transaction object
my $tx = $c->render_later->tx;
$c->ua->get_p('https://mojolicious.org')->then(sub {
$c->render(text => 'Visited mojolicious.org');
})->catch(sub {
my $err = shift;
$tx;
$c->reply->exception($err);
});
MORE
You can continue with Mojolicious::Guides now or take a look at the
Mojolicious wiki <
http://github.com/mojolicious/mojo/wiki>, which contains a lot more
documentation and examples by many different authors.
SUPPORT
If you have any questions the documentation might not yet answer, don't
hesitate to ask on the
mailing list <
http://groups.google.com/group/mojolicious> or the official
IRC
channel
"#mojo" on
"irc.freenode.net" (chat
now! <
https://kiwiirc.com/nextclient/#irc://irc.freenode.net/mojo?nick=guest-?>).