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