1 2=encoding utf8 3 4=head1 NAME 5 6Mojolicious::Guides::FAQ - Frequently Asked Questions 7 8=head1 OVERVIEW 9 10This document contains answers for the most frequently asked questions about L<Mojolicious>. 11 12=head1 QUESTIONS 13 14We hope these answers are to your satisfaction. 15 16=head2 How does Mojolicious compare to other Perl web frameworks? 17 18The short answer is "it doesn't", because we interpret the term "web framework" much more literally than others. With 19the emergence of the real-time web and new technologies such as WebSockets, we are facing new challenges that go way 20beyond what commonly used modules like L<LWP> were designed for. Because of this, L<Mojolicious> contains a whole new 21HTTP client/server stack called L<Mojo>, which was heavily inspired by the original LWPng effort and carefully designed 22with these new requirements in mind. So while some of the higher abstraction layers might look similar to other web 23frameworks, it is more of a web toolkit and can even be used as the foundation for more advanced web frameworks. 24 25=head2 Why doesn't Mojolicious have any dependencies? 26 27We are optimizing L<Mojolicious> for user-friendliness and development speed, without compromises. While there are no 28rules in L<Mojolicious::Guides::Contributing> that forbid dependencies, we do currently discourage adding non-optional 29ones in favor of a faster and more painless installation process. And we do in fact already use several optional CPAN 30modules such as L<Cpanel::JSON::XS>, L<EV>, L<IO::Socket::Socks>, L<IO::Socket::SSL>, L<Net::DNS::Native>, L<Plack> and 31L<Role::Tiny> to provide advanced functionality if possible. 32 33=head2 Why reinvent wheels? 34 35Because we can make them rounder. Components specifically designed for user-friendliness and development speed are not 36easy 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 37develop the best possible solutions for these two criteria. 38 39=head2 What about backwards compatibility? 40 41In conformance with L<Mojolicious::Guides::Contributing>, we will always deprecate a feature for 3 months, before 42removing or changing it in incompatible ways between major releases. New features can however be marked as experimental 43to explicitly exclude them from these rules. This gives us the necessary freedom to ensure a healthy future for 44L<Mojolicious>. So, as long as you are not using anything marked experimental, untested or undocumented, you can always 45count on backwards compatibility, everything else would be considered a bug. However, to completely avoid any risk of 46accidental breakage, we do recommend following current best practices for version pinning with L<Carton> for production 47setups. 48 49=head2 Why not split up Mojolicious into many smaller distributions? 50 51Because there are no advantages, it drastically increases maintenance costs and installation times without giving us 52anything in return. It would only make sense if we wanted to pass ownership of a module to a new maintainer, which we 53already have done in the past. 54 55=head2 Where can I discuss my patches for Mojolicious? 56 57We'd love to discuss your contributions to L<Mojolicious> on our official IRC channel C<#mojo> on C<irc.libera.chat> 58(L<chat now!|https://web.libera.chat/#mojo>). 59 60=head2 Which versions of Perl are supported by Mojolicious? 61 62First of all, you need to be aware that according to the L<perlpolicy>, only the two most recent stable release series 63of Perl are supported by the community and receive bug fixes, which are currently 5.32.x and 5.30.x. L<Mojolicious> 64follows this model and fully supports these two release series. In addition we will also keep the distribution 65installable (and that means passing all tests) up to a certain legacy version that the core team deems worthy of 66supporting, but not specifically optimize for it, this is currently 5.16.0. 67 68=head2 How well is Windows supported by Mojolicious? 69 70Windows is not officially supported by L<Mojolicious>, even though we try to keep the distribution installable. There 71may be serious security and/or reliability issues. Some of the more advanced features, such as 72L<subprocesses|Mojo::IOLoop/"subprocess"> and the L<Hypnotoad|Mojo::Server::Hypnotoad> web server, will also require 73the use of the L<Windows Subsystem for Linux|https://msdn.microsoft.com/commandline/wsl/>. 74 75=head2 Is Perl's taint mode supported by Mojolicious? 76 77No. There is no benefit at all to using taint mode. Modern Perl applications are much too complex to benefit from such a 78naive mechanism in any meaningful way. At best it would give you a false sense of security. 79 80=head2 Do I need to clean my environment before testing Mojolicious? 81 82L<Mojolicious> uses many environment variables both internally and externally, notably (but not exclusively) those 83starting with the prefix C<MOJO_*> and C<PLACK_ENV>. The test suite expects a clean environment; testing with a 84non-standard environment is unsupported and is unlikely to succeed. Therefore when installing or upgrading 85L<Mojolicious> and when running its tests, we highly recommend using an environment which does not set these variables. 86 87=head2 Where did my file extension go? 88 89Standard route placeholders will not match the C<.> character, however L<Mojolicious> routes automatically take file 90extensions like C<.html>, remove the leading C<.>, and store the result in the C<format> stash value. This can be 91useful for URL-based content negotiation, such as automatically rendering different templates based on the file 92extension. See L<Mojolicious::Guides::Routing/"Formats"> for information on customizing format detection, or consider 93using L<relaxed placeholders|Mojolicious::Guides::Routing/"Relaxed placeholders"> to allow matching of the C<.> 94character. 95 96=head2 Can I configure Hypnotoad from the command line? 97 98No, you can't, L<Hypnotoad|Mojo::Server::Hypnotoad> is a bit special in this regard. Because when you initiate a zero 99downtime software upgrade (hot deployment), you are only really sending a C<USR2> signal to the already running server, 100and no other information can be passed along. What you can do instead, is to use a L<Mojolicious::Plugin::Config>, 101L<Mojolicious::Plugin::JSONConfig> or L<Mojolicious::Plugin::NotYAMLConfig> configuration file. 102 103 # myapp.conf 104 { 105 hypnotoad => { 106 listen => ['http://*:8080'], 107 workers => 10 108 } 109 }; 110 111Or if you don't actually need zero downtime software upgrades, just use L<Mojolicious::Command::prefork> instead, which 112is otherwise almost identical to Hypnotoad. 113 114 $ ./myapp.pl prefork -m production -l http://*:8080 -w 10 115 116=head2 What does the error "...certificate verify failed" mean? 117 118There are many variations of this error, but most of them mean that TLS certificate verification in L<Mojo::UserAgent> 119failed. This usually happens for two reasons. The most common one is that the peer certificate is simply invalid. If 120that's the case and you are certain that no MITM attack is being attempted, you can use the attribute 121L<Mojo::UserAgent/"insecure"> or C<MOJO_INSECURE> environment variable to disable certificate verification. And if 122that's not the case you might be missing the L<Mozilla::CA> module, which is often required by L<IO::Socket::SSL> to be 123able to verify certificates. 124 125=head2 What does the error "Maximum message size exceeded" mean? 126 127To protect your applications from excessively large requests and responses, our HTTP parser has a cap after which it 128will automatically stop accepting new data, and in most cases force the connection to be closed. The limit is 16MiB for 129requests, and 2GiB for responses by default. You can use the attributes L<Mojolicious/"max_request_size"> and 130L<Mojo::UserAgent/"max_response_size"> to change these values. 131 132=head2 What does the error "Maximum start-line size exceeded" mean? 133 134This is a very similar protection mechanism to the one described in the previous answer, but a little more specific. It 135limits the maximum length of the start-line for HTTP requests and responses. The limit is 8KiB by default, you can use 136the attribute L<Mojo::Message/"max_line_size"> or C<MOJO_MAX_LINE_SIZE> environment variable to change this value. 137 138=head2 What does the error "Maximum header size exceeded" mean? 139 140Almost the same as the previous answer, but this protection mechanism limits the number and maximum length of HTTP 141request and response headers. The limits are 100 headers with 8KiB each by default, you can use the attributes 142L<Mojo::Headers/"max_lines"> and L<Mojo::Headers/"max_line_size"> or the C<MOJO_MAX_LINES> and C<MOJO_MAX_LINE_SIZE> 143environment variables to change these values. 144 145=head2 What does the error "Maximum buffer size exceeded" mean? 146 147This protection mechanism limits how much content the HTTP parser is allowed to buffer when parsing chunked, compressed 148and multipart messages. The limit is around 256KiB by default, you can use the attribute 149L<Mojo::Content/"max_buffer_size"> or C<MOJO_MAX_BUFFER_SIZE> environment variable to change this value. 150 151=head2 What does "Your secret passphrase needs to be changed" mean? 152 153L<Mojolicious> uses secret passphrases for security features such as signed cookies. It defaults to using 154L<Mojolicious/"moniker">, which is not very secure, so we added this log message as a reminder. You can change the 155passphrase with the attribute L<Mojolicious/"secrets">. Since some plugins also depend on it, you should try changing 156it as early as possible in your application. 157 158 $app->secrets(['My very secret passphrase.']); 159 160=head2 What does "Nothing has been rendered, expecting delayed response" mean? 161 162L<Mojolicious> has been designed from the ground up for non-blocking I/O and event loops. So when a new request comes 163in and no response is generated right away, it will assume that this was intentional and return control to the web 164server, which can then handle other requests while waiting for events such as timers to finally generate a response. 165 166=head2 What does "Inactivity timeout" mean? 167 168To protect your applications from denial-of-service attacks, all connections have an inactivity timeout which limits 169how long a connection may be inactive before being closed automatically. It defaults to C<40> seconds for the user 170agent and C<30> seconds for all built-in web servers, and can be changed with the attributes 171L<Mojo::UserAgent/"inactivity_timeout"> and L<Mojo::Server::Daemon/"inactivity_timeout"> or the 172C<MOJO_INACTIVITY_TIMEOUT> environment variable. In L<Mojolicious> applications you can also use the helper 173L<Mojolicious::Plugin::DefaultHelpers/"inactivity_timeout"> to change it on demand for each connection individually. 174This timeout always applies, so you might have to tweak it for applications that take a long time to process a request. 175 176=head2 What does "Premature connection close" mean? 177 178This error message is often related to the one above, and means that the web server closed the connection before the 179user agent could receive the whole response or that the user agent got destroyed, which forces all connections to be 180closed immediately. 181 182 # The variable $ua goes out of scope and gets destroyed too early 183 Mojo::IOLoop->timer(5 => sub { 184 my $ua = Mojo::UserAgent->new; 185 $ua->get('https://mojolicious.org' => sub ($ua, $tx) { 186 say $tx->result->dom->at('title')->text; 187 }); 188 }); 189 190=head2 What does "Worker 31842 has no heartbeat (50 seconds), restarting" mean? 191 192As long as they are accepting new connections, worker processes of all built-in pre-forking web servers send heartbeat 193messages to the manager process at regular intervals, to signal that they are still responsive. A blocking operation 194such as an infinite loop in your application can prevent this, and will force the affected worker to be restarted after 195a timeout. This timeout defaults to C<50> seconds and can be extended with the attribute 196L<Mojo::Server::Prefork/"heartbeat_timeout"> if your application requires it. 197 198=head2 What does "Transaction already destroyed" mean? 199 200This error message usually appears after waiting for the results of a non-blocking operation for longer periods of 201time, because the underlying connection has been closed in the meantime and the value of the attribute 202L<Mojolicious::Controller/"tx"> is no longer available. While there might not be a way to prevent the connection from 203getting closed, you can try to avoid this error message by keeping a reference to the transaction object that is not 204weakened. 205 206 # Keep a strong reference to the transaction object 207 my $tx = $c->render_later->tx; 208 $c->ua->get_p('https://mojolicious.org')->then(sub { 209 $c->render(text => 'Visited mojolicious.org'); 210 })->catch(sub ($err) { 211 $tx; 212 $c->reply->exception($err); 213 }); 214 215=head2 What does "Illegal character in prototype" mean? 216 217Mojolicious assumes L<subroutine signatures|Mojolicious::Guides/"Signatures"> are enabled in documentation examples. If 218the signatures feature has not been enabled in that scope, they are interpreted as L<prototypes|perlsub/"Prototypes">, 219an unrelated parser feature. Mojolicious does not require signatures; if you don't want to or cannot use signatures 220(which require Perl 5.20+), you can translate most signatures into a standard subroutine parameter assignment. 221 222 # With signatures feature 223 get '/title' => sub ($c) { 224 $c->ua->get('mojolicious.org' => sub ($ua, $tx) { 225 $c->render(data => $tx->result->dom->at('title')->text); 226 }); 227 }; 228 229 # Without signatures feature 230 get '/title' => sub { 231 my ($c) = @_; 232 $c->ua->get('mojolicious.org' => sub { 233 my ($ua, $tx) = @_; 234 $c->render(data => $tx->result->dom->at('title')->text); 235 }); 236 }; 237 238=head1 MORE 239 240You can continue with L<Mojolicious::Guides> now or take a look at the L<Mojolicious 241wiki|https://github.com/mojolicious/mojo/wiki>, which contains a lot more documentation and examples by many different 242authors. 243 244=head1 SUPPORT 245 246If you have any questions the documentation might not yet answer, don't hesitate to ask in the 247L<Forum|https://forum.mojolicious.org> or the official IRC channel C<#mojo> on C<irc.libera.chat> 248(L<chat now!|https://web.libera.chat/#mojo>). 249 250=cut 251