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 EV, IO::Socket::Socks, IO::Socket::SSL,
       Net::DNS::Native and Plack 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.

   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.

   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.22.x
       and 5.20.x.  Mojolicious follows this model and fully supports these two release series.  In addition we
       will also keep the distribution installable up to a certain legacy version that we deem worthy of
       supporting, but not specifically optimize for it, this is currently 5.10.1.

   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_*". 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.

   What is the difference between blocking and non-blocking operations?
       A blocking operation is a subroutine that blocks the execution of the calling subroutine until the
       subroutine is finished.

         sub foo {
           my $result = blocking_subroutine();
           ...
         }

       A non-blocking operation on the other hand lets the calling subroutine continue execution even though the
       subroutine is not yet finished. Instead of waiting, the calling subroutine passes along a callback to be
       executed once the subroutine is finished, this is called continuation-passing style.

         sub foo {
           non_blocking_subroutine(sub {
             my $result = shift;
             ...
           });
           ...
         }

   Will my code magically become non-blocking with Mojolicious?
       No, it is not possible to magically make Perl code non-blocking. While Mojolicious has been designed from
       the ground up for non-blocking I/O and event loops, taking advantage of this requires specialized code
       available through modules like Mojo::IOLoop and Mojo::UserAgent, or third-party event loops. In the
       documentation we often refer to this as real-time web, for more information see also "REAL-TIME WEB" in
       Mojolicious::Guides::Cookbook.

   What is an event loop?
       An event loop is basically a loop that continually tests for external events and executes the appropriate
       callbacks to handle them, it is often the main loop in a program. Non-blocking tests for
       readability/writability of file descriptors and timers are commonly used events for highly scalable
       network servers, because they allow a single process to handle thousands of client connections
       concurrently.

         while (1) {
           my @readable = test_fds_for_readability();
           handle_readable_fds(@readable);

           my @writable = test_fds_for_writability();
           handle_writable_fds(@writable);

           my @expired = test_timers();
           handle_timers(@expired);
         }

       In Mojolicious this event loop is Mojo::IOLoop.

   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.

   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 16MB by default, you can use the attribute "max_message_size" in Mojo::Message or
       "MOJO_MAX_MESSAGE_SIZE" environment variable to change this value.

   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 8KB 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 8KB 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 256KB 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 the error "EV does not work with ithreads" mean?
       The Mojolicious user agent and web servers are based on an event loop that supports multiple reactor
       backends. One of these backends is EV, it is very fast and will be automatically used if possible. On
       Windows however, the "ithreads" based "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

   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.

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

   What does "Worker 31842 has no heartbeat, restarting" mean?
       As long as they are accepting new connections, worker processes of all built-in preforking 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 20 seconds and can be
       extended with the attribute "heartbeat_timeout" in Mojo::Server::Prefork if your application requires it.

MORE

       You can continue with Mojolicious::Guides now or take a look at the Mojolicious wiki
       <http://github.com/kraih/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.perl.org".

perl v5.22.1                                       2015-12-28                      Mojolicious::Guides::FAQ(3pm)