
=head1 NAME

Mojolicious::Guides::FAQ - Frequently Asked Questions

=head1 OVERVIEW

This document contains the most frequently asked questions about
L<Mojolicious> together with the right answers.

=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::CodingGuidelines> 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>,
L<Net::Rendezvous::Publish> 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::CodingGuidelines>, we will always
deprecate a feature for at least one major release before removing or
changing it in incompatible ways. 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 dropped. This limit is
around C<5MB> by default, you can use the C<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<\r\n> 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
C<MOJO_MAX_LINE_SIZE> environment variable to change this value.

=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 name 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 "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 dropped 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 I think i have found a bug, what should i do now?

First make sure you are using the latest version of L<Mojolicious>, it is
quite likely that the bug has already been fixed. If that doesn't help,
prepare a test case demonstrating the bug, you are not expected to fix it
yourself, but you'll have to make sure the developers can replicate your
problem. Sending in your whole application generally does more harm than
good, the C<t> directory of this distribution has many good examples for how
to do it right. Writing a test is usually the hardest part of fixing a bug,
so the better your test case the faster it can be fixed. ;)

Once that's done you can contact the developers via via GitHub
(L<https://github.com/kraih/mojo/issues>), mailing list
(L<http://groups.google.com/group/mojolicious>) or IRC
(C<#mojo> on C<irc.perl.org>).

If you decide to fix the bug yourself make sure to also take a look at
L<Mojolicious::Guides::CodingGuidelines>.

=head2 Which namespace should i use for Mojolicious plugins?

For all new plugins that you might want to release to CPAN, we suggest using
the "Mojolicious::Plugin" namespace. While "MojoX" has been used a lot in the
past, it is now deprecated.

=head1 MORE

You can continue with L<Mojolicious::Guides> now or take a look at the
Mojolicious wiki L<http://github.com/kraih/mojo/wiki>, which contains a lot
more documentation and examples by many different authors.

=cut
