1Mojolicious::Guides::FAUQs(e3r)Contributed Perl DocumentMaotjioolnicious::Guides::FAQ(3)
2
6 Mojolicious::Guides::FAQ - Frequently Asked Questions
7
9 This document contains answers for the most frequently asked questions
10 about Mojolicious.
11
13 We hope these answers are to your satisfaction.
14 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 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 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 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 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 Where can i discuss my patches for Mojolicious?
65 We'd love to discuss your contributions to Mojolicious on our official
66 IRC channel "#mojo" on "irc.freenode.net" (chat now!
67 <https://webchat.freenode.net/#mojo>).
68 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.30.x and
73 5.28.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 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 Do I need to clean my environment before testing Mojolicious?
88 Mojolicious uses many environment variables both internally and
89 externally, notably (but not exclusively) those starting with the
90 prefix "MOJO_*" and "PLACK_ENV". The test suite expects a clean
91 environment; testing with a non-standard environment is unsupported and
92 is unlikely to succeed. Therefore when installing or upgrading
93 Mojolicious and when running its tests, we highly recommend using an
94 environment which does not set these variables.
95 Where did my file extension go?
97 Standard route placeholders will not match the "." character, however
98 Mojolicious routes automatically take file extensions like ".html",
99 remove the leading ".", and store the result in the "format" stash
100 value. This can be useful for URL-based content negotiation, such as
101 automatically rendering different templates based on the file
102 extension. See "Formats" in Mojolicious::Guides::Routing for
103 information on customizing format detection, or consider using relaxed
104 placeholders to allow matching of the "." character.
105 Can I configure Hypnotoad from the command line?
107 No, you can't, Hypnotoad is a bit special in this regard. Because when
108 you initiate a zero downtime software upgrade (hot deployment), you are
109 only really sending a "USR2" signal to the already running server, and
110 no other information can be passed along. What you can do instead, is
111 to use a Mojolicious::Plugin::Config, Mojolicious::Plugin::JSONConfig
112 or Mojolicious::Plugin::NotYAMLConfig configuration file.
113 # myapp.conf
115 {
116 hypnotoad => {
117 listen => ['http://*:8080'],
118 workers => 10
119 }
120 };
121 Or if you don't actually need zero downtime software upgrades, just use
123 Mojolicious::Command::prefork instead, which is otherwise almost
124 identical to Hypnotoad.
125 $ ./myapp.pl prefork -m production -l http://*:8080 -w 10
127 What does the error "...certificate verify failed" mean?
129 There are many variations of this error, but most of them mean that TLS
130 certificate verification in Mojo::UserAgent failed. This usually
131 happens for two reasons. The most common one is that the peer
132 certificate is simply invalid. If that's the case and you are certain
133 that no MITM attack is being attempted, you can use the attribute
134 "insecure" in Mojo::UserAgent or "MOJO_INSECURE" environment variable
135 to disable certificate verification. And if that's not the case you
136 might be missing the Mozilla::CA module, which is often required by
137 IO::Socket::SSL to be able to verify certificates.
138 What does the error "Maximum message size exceeded" mean?
140 To protect your applications from excessively large requests and
141 responses, our HTTP parser has a cap after which it will automatically
142 stop accepting new data, and in most cases force the connection to be
143 closed. The limit is 16MiB for requests, and 2GiB for responses by
144 default. You can use the attributes "max_request_size" in Mojolicious
145 and "max_response_size" in Mojo::UserAgent to change these values.
146 What does the error "Maximum start-line size exceeded" mean?
148 This is a very similar protection mechanism to the one described in the
149 previous answer, but a little more specific. It limits the maximum
150 length of the start-line for HTTP requests and responses. The limit is
151 8KiB by default, you can use the attribute "max_line_size" in
152 Mojo::Message or "MOJO_MAX_LINE_SIZE" environment variable to change
153 this value.
154 What does the error "Maximum header size exceeded" mean?
156 Almost the same as the previous answer, but this protection mechanism
157 limits the number and maximum length of HTTP request and response
158 headers. The limits are 100 headers with 8KiB each by default, you can
159 use the attributes "max_lines" in Mojo::Headers and "max_line_size" in
160 Mojo::Headers or the "MOJO_MAX_LINES" and "MOJO_MAX_LINE_SIZE"
161 environment variables to change these values.
162 What does the error "Maximum buffer size exceeded" mean?
164 This protection mechanism limits how much content the HTTP parser is
165 allowed to buffer when parsing chunked, compressed and multipart
166 messages. The limit is around 256KiB by default, you can use the
167 attribute "max_buffer_size" in Mojo::Content or "MOJO_MAX_BUFFER_SIZE"
168 environment variable to change this value.
169 What does "Your secret passphrase needs to be changed" mean?
171 Mojolicious uses secret passphrases for security features such as
172 signed cookies. It defaults to using "moniker" in Mojolicious, which is
173 not very secure, so we added this log message as a reminder. You can
174 change the passphrase with the attribute "secrets" in Mojolicious.
175 Since some plugins also depend on it, you should try changing it as
176 early as possible in your application.
177 $app->secrets(['My very secret passphrase.']);
179 What does "Nothing has been rendered, expecting delayed response" mean?
181 Mojolicious has been designed from the ground up for non-blocking I/O
182 and event loops. So when a new request comes in and no response is
183 generated right away, it will assume that this was intentional and
184 return control to the web server, which can then handle other requests
185 while waiting for events such as timers to finally generate a response.
186 What does "Inactivity timeout" mean?
188 To protect your applications from denial-of-service attacks, all
189 connections have an inactivity timeout which limits how long a
190 connection may be inactive before being closed automatically. It
191 defaults to 40 seconds for the user agent and 30 seconds for all built-
192 in web servers, and can be changed with the attributes
193 "inactivity_timeout" in Mojo::UserAgent and "inactivity_timeout" in
194 Mojo::Server::Daemon or the "MOJO_INACTIVITY_TIMEOUT" environment
195 variable. In Mojolicious applications you can also use the helper
196 "inactivity_timeout" in Mojolicious::Plugin::DefaultHelpers to change
197 it on demand for each connection individually. This timeout always
198 applies, so you might have to tweak it for applications that take a
199 long time to process a request.
200 What does "Premature connection close" mean?
202 This error message is often related to the one above, and means that
203 the web server closed the connection before the user agent could
204 receive the whole response or that the user agent got destroyed, which
205 forces all connections to be closed immediately.
206 # The variable $ua goes out of scope and gets destroyed too early
208 Mojo::IOLoop->timer(5 => sub {
209 my $ua = Mojo::UserAgent->new;
210 $ua->get('https://mojolicious.org' => sub {
211 my ($ua, $tx) = @_;
212 say $tx->result->dom->at('title')->text;
213 });
214 });
215 What does "Worker 31842 has no heartbeat (50 seconds), restarting" mean?
217 As long as they are accepting new connections, worker processes of all
218 built-in pre-forking web servers send heartbeat messages to the manager
219 process at regular intervals, to signal that they are still responsive.
220 A blocking operation such as an infinite loop in your application can
221 prevent this, and will force the affected worker to be restarted after
222 a timeout. This timeout defaults to 50 seconds and can be extended with
223 the attribute "heartbeat_timeout" in Mojo::Server::Prefork if your
224 application requires it.
225 What does "Transaction already destroyed" mean?
227 This error message usually appears after waiting for the results of a
228 non-blocking operation for longer periods of time, because the
229 underlying connection has been closed in the meantime and the value of
230 the attribute "tx" in Mojolicious::Controller is no longer available.
231 While there might not be a way to prevent the connection from getting
232 closed, you can try to avoid this error message by keeping a reference
233 to the transaction object that is not weakened.
234 # Keep a strong reference to the transaction object
236 my $tx = $c->render_later->tx;
237 $c->ua->get_p('https://mojolicious.org')->then(sub {
238 $c->render(text => 'Visited mojolicious.org');
239 })->catch(sub {
240 my $err = shift;
241 $tx;
242 $c->reply->exception($err);
243 });
244
246 You can continue with Mojolicious::Guides now or take a look at the
247 Mojolicious wiki <http://github.com/mojolicious/mojo/wiki>, which
248 contains a lot more documentation and examples by many different
249 authors.
250
252 If you have any questions the documentation might not yet answer, don't
253 hesitate to ask on the mailing list
254 <http://groups.google.com/group/mojolicious> or the official IRC
255 channel "#mojo" on "irc.freenode.net" (chat now!
256 <https://webchat.freenode.net/#mojo>).
257perl v5.32.0 2020-07-28 Mojolicious::Guides::FAQ(3)