1Mojolicious::Guides::FAUQs(e3r)Contributed Perl DocumentMaotjioolnicious::Guides::FAQ(3)
2
3
4

NAME

6       Mojolicious::Guides::FAQ - Frequently Asked Questions
7

OVERVIEW

9       This document contains answers for the most frequently asked questions
10       about Mojolicious.
11

QUESTIONS

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

MORE

274       You can continue with Mojolicious::Guides now or take a look at the
275       Mojolicious wiki <https://github.com/mojolicious/mojo/wiki>, which
276       contains a lot more documentation and examples by many different
277       authors.
278

SUPPORT

280       If you have any questions the documentation might not yet answer, don't
281       hesitate to ask in the Forum <https://forum.mojolicious.org>, on Matrix
282       <https://matrix.to/#/#mojo:matrix.org>, or IRC
283       <https://web.libera.chat/#mojo>.
284
285
286
287perl v5.36.0                      2022-07-22       Mojolicious::Guides::FAQ(3)
Impressum