=encoding utf8

=head1 NAME

Mojolicious::Guides::FAQ - Frequently Asked Questions

=head1 OVERVIEW

This document contains answers for the most frequently asked questions about

L<Mojolicious>.

=head1 QUESTIONS

=head2 How does Mojolicious compare to other Perl web frameworks?

The short answer is "it doesn't", because we interpret the words

"web framework" much more literally than others. With the emergence of the

C<real-time web> and new technologies such as C<WebSockets>, we are facing new

challenges that go way beyond what commonly used modules like L<LWP> were

designed for. Because of this, L<Mojolicious> contains a whole new HTTP

client/server stack called L<Mojo>, which was heavily inspired by the original

C<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 actually defines a whole new category and could even be the

foundation for more advanced ones in the future.

=head2 Why doesn't Mojolicious have any dependencies?

We are optimizing L<Mojolicious> for user-friendliness and development speed,

without compromises. While there are no rules in

L<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 L<EV>, L<IO::Socket::IP>, L<IO::Socket::SSL> and L<Plack> to

provide advanced functionality if they are installed.

=head2 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.

=head2 What about backwards compatibility?

In conformance with L<Mojolicious::Guides::Contributing>, we will always

deprecate a feature 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 L<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.

=head2 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.

=head2 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. This limit is

around C<10MB> by default, you can use the MOJO_MAX_MESSAGE_SIZE environment

variable to change this value.

=head2 What does the error "Maximum 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

any C<\x0d\x0a> terminated part of a HTTP message, such as request line,

status line and headers. This limit is around C<10KB> by default, you can use

the MOJO_MAX_LINE_SIZE environment variable to change this value.

=head2 What does the error "Maximum buffer size exceeded" mean?

This protection mechanism is very similar to those mentioned in the two

previous answers. It limits how much content the HTTP parser is allowed to

buffer when parsing chunked, compressed and multipart messages. This limit is

around C<256KB> by default, you can use the MOJO_MAX_BUFFER_SIZE environment

variable to change this value.

=head2 What does the error "EV does not work with ithreads" mean?

The L<Mojolicious> user agent and web servers are based on an event loop that

supports multiple reactor backends. One of these backends is L<EV>, it is very

fast and will be automatically used if installed. On Windows however, the

C<ithreads> based C<fork()> emulation can interfere with it, and you may have

to use the MOJO_REACTOR environment variable to enforce a more portable one.

  MOJO_REACTOR=Mojo::Reactor::Poll

=head2 What does "Your secret passphrase needs to be changed" mean?

L<Mojolicious> uses a secret passphrase for security features such as signed

cookies. It defaults to the moniker of your application, which is not very

secure, so we added this log message as a reminder. You can change the

passphrase with the attribute L<Mojolicious/"secret">.

  app->secret('My very secret passphrase.');

=head2 What does "Nothing has been rendered, expecting delayed response" mean?

L<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.

=head2 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 C<20> seconds for the user

agent and C<15> seconds for all built-in web servers, and is commonly referred

to as C<inactivity_timeout>. This timeout always applies, so you might have to

tweak it for applications that take a long time to process a request.

=head2 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.

=head2 What does "Worker 31842 has no heartbeat, restarting" mean?

As long as they are accepting new connections, Hypnotoad worker processes 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 (or active connections after a worker has stopped accepting

new connections) can prevent this, and will force the affected worker to be

restarted after a timeout. This C<heartbeat_timeout> defaults to C<20> seconds

and can be extended if your application requires it.

=head1 MORE

You can continue with L<Mojolicious::Guides> now or take a look at the

L<Mojolicious wiki|http://github.com/kraih/mojo/wiki>, which contains a lot

more documentation and examples by many different authors.

=head1 SUPPORT

If you have any questions the documentation might not yet answer, don't

hesitate to ask on the

L<mailing-list|http://groups.google.com/group/mojolicious> or the official IRC

channel C<#mojo> on C<irc.perl.org>.

=cut