1Mojolicious::Guides::CoUoskebrooCko(n3t)ributed Perl DocMuomjeonltiactiioouns::Guides::Cookbook(3)
2
6 Mojolicious::Guides::Cookbook - Cooking with Mojolicious
7
9 This document contains many fun recipes for cooking with Mojolicious.
10
12 Essentials every Mojolicious developer should know.
13 Blocking and non-blocking operations
15 A blocking operation is a subroutine that blocks the execution of the
16 calling subroutine until the subroutine is finished.
17 sub foo {
19 my $result = blocking_subroutine();
20 ...
21 }
22 A non-blocking operation on the other hand lets the calling subroutine
24 continue execution even though the subroutine is not yet finished.
25 Instead of waiting, the calling subroutine passes along a callback to
26 be executed once the subroutine is finished, this is called
27 continuation-passing style.
28 sub foo {
30 non_blocking_subroutine(sub {
31 my $result = shift;
32 ...
33 });
34 ...
35 }
36 While Mojolicious has been designed from the ground up for non-blocking
38 I/O and event loops, it is not possible to magically make Perl code
39 non-blocking. You have to use specialized non-blocking code available
40 through modules like Mojo::IOLoop and Mojo::UserAgent, or third-party
41 event loops. You can wrap your blocking code in subprocesses though to
42 prevent it from interfering with your non-blocking code.
43 Event loops
45 An event loop is basically a loop that continually tests for external
46 events and executes the appropriate callbacks to handle them, it is
47 often the main loop in a program. Non-blocking tests for
48 readability/writability of file descriptors and timers are commonly
49 used events for highly scalable network servers, because they allow a
50 single process to handle thousands of client connections concurrently.
51 while (1) {
53 my @readable = test_fds_for_readability();
54 handle_readable_fds(@readable);
55 my @writable = test_fds_for_writability();
57 handle_writable_fds(@writable);
58 my @expired = test_timers();
60 handle_timers(@expired);
61 }
62 In Mojolicious this event loop is Mojo::IOLoop.
64 Reverse proxy
66 A reverse proxy architecture is a deployment technique used in many
67 production environments, where a reverse proxy server is put in front
68 of your application to act as the endpoint accessible by external
69 clients. It can provide a lot of benefits, like terminating SSL
70 connections from the outside, limiting the number of concurrent open
71 sockets towards the Mojolicious application (or even using Unix
72 sockets), balancing load across multiple instances, or supporting
73 several applications through the same IP/port.
74 ..........................................
76 : :
77 +--------+ : +-----------+ +---------------+ :
78 | |-------->| | | | :
79 | client | : | reverse |----->| Mojolicious | :
80 | |<--------| proxy | | application | :
81 +--------+ : | |<-----| | :
82 : +-----------+ +---------------+ :
83 : :
84 .. system boundary (e.g. same host) ......
85 This setup introduces some problems, though: the application will
87 receive requests from the reverse proxy instead of the original client;
88 the address/hostname where your application lives internally will be
89 different from the one visible from the outside; and if terminating
90 SSL, the reverse proxy exposes services via HTTPS while using HTTP
91 towards the Mojolicious application.
92 As an example, compare a sample request from the client and what the
94 Mojolicious application receives:
95 client reverse proxy Mojolicious app
97 __|__ _______________|______________ ____|____
98 / \ / \ / \
99 1.2.3.4 --HTTPS--> api.example.com 10.20.30.39 --HTTP--> 10.20.30.40
100 GET /foo/1 HTTP/1.1 | GET /foo/1 HTTP/1.1
102 Host: api.example.com | Host: 10.20.30.40
103 User-Agent: Firefox | User-Agent: ShinyProxy/1.2
104 ... | ...
105 However, now the client address is no longer available (which might be
107 useful for analytics, or Geo-IP) and URLs generated via "url_for" in
108 Mojolicious::Controller will look like this:
109 http://10.20.30.40/bar/2
111 instead of something meaningful for the client, like this:
113 https://api.example.com/bar/2
115 To solve these problems, you can configure your reverse proxy to send
117 the missing data (see "Nginx" and "Apache/mod_proxy") and tell your
118 application about it by setting the environment variable
119 "MOJO_REVERSE_PROXY". For finer control, "Rewriting" includes examples
120 of how the changes could be implemented manually.
121
123 Getting Mojolicious and Mojolicious::Lite applications running on
124 different platforms. Note that many real-time web features are based on
125 the Mojo::IOLoop event loop, and therefore require one of the built-in
126 web servers to be able to use them to their full potential.
127 Built-in web server
129 Mojolicious contains a very portable non-blocking I/O HTTP and
130 WebSocket server with Mojo::Server::Daemon. It is usually used during
131 development and in the construction of more advanced web servers, but
132 is solid and fast enough for small to mid sized applications.
133 $ ./script/my_app daemon
135 Server available at http://127.0.0.1:3000
136 It is available to every application through the command
138 Mojolicious::Command::daemon, which has many configuration options and
139 is known to work on every platform Perl works on with its single-
140 process architecture.
141 $ ./script/my_app daemon -h
143 ...List of available options...
144 Another huge advantage is that it supports TLS and WebSockets out of
146 the box, a development certificate for testing purposes is built right
147 in, so it just works, but you can specify all listen locations
148 supported by "listen" in Mojo::Server::Daemon.
149 $ ./script/my_app daemon -l https://[::]:3000
151 Server available at https://[::]:3000
152 To manage the web server with systemd, you can use a unit configuration
154 file like this.
155 [Unit]
157 Description=My Mojolicious application
158 After=network.target
159 [Service]
161 Type=simple
162 ExecStart=/home/sri/myapp/script/my_app daemon -m production -l http://*:8080
163 [Install]
165 WantedBy=multi-user.target
166 Pre-forking
168 On UNIX platforms you can also add pre-forking to the built-in web
169 server and switch to a multi-process architecture with
170 Mojolicious::Command::prefork, to take advantage of multiple CPU cores
171 and copy-on-write memory management.
172 $ ./script/my_app prefork
174 Server available at http://127.0.0.1:3000
175 Since all built-in web servers are based on the Mojo::IOLoop event
177 loop, they scale best with non-blocking operations. But if your
178 application for some reason needs to perform many blocking operations,
179 you can improve performance by increasing the number of worker
180 processes and decreasing the number of concurrent connections each
181 worker is allowed to handle (often as low as 1).
182 $ ./script/my_app prefork -m production -w 10 -c 1
184 Server available at http://127.0.0.1:3000
185 During startup your application is preloaded in the manager process,
187 which does not run an event loop, so you can use "next_tick" in
188 Mojo::IOLoop to run code whenever a new worker process has been forked
189 and its event loop gets started.
190 use Mojolicious::Lite;
192 Mojo::IOLoop->next_tick(sub {
194 app->log->info("Worker $$ star...ALL GLORY TO THE HYPNOTOAD!");
195 });
196 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
198 app->start;
200 And to manage the pre-forking web server with systemd, you can use a
202 unit configuration file like this.
203 [Unit]
205 Description=My Mojolicious application
206 After=network.target
207 [Service]
209 Type=simple
210 ExecStart=/home/sri/myapp/script/my_app prefork -m production -l http://*:8080
211 [Install]
213 WantedBy=multi-user.target
214 Morbo
216 After reading the Mojolicious::Guides::Tutorial, you should already be
217 familiar with Mojo::Server::Morbo.
218 Mojo::Server::Morbo
220 +- Mojo::Server::Daemon
221 It is basically a restarter that forks a new Mojo::Server::Daemon web
223 server whenever a file in your project changes, and should therefore
224 only be used during development. To start applications with it you can
225 use the morbo script.
226 $ morbo ./script/my_app
228 Server available at http://127.0.0.1:3000
229 Hypnotoad
231 For bigger applications Mojolicious contains the UNIX optimized pre-
232 forking web server Hypnotoad, which can take advantage of multiple CPU
233 cores and copy-on-write memory management to scale up to thousands of
234 concurrent client connections.
235 Mojo::Server::Hypnotoad
237 |- Mojo::Server::Daemon [1]
238 |- Mojo::Server::Daemon [2]
239 |- Mojo::Server::Daemon [3]
240 +- Mojo::Server::Daemon [4]
241 It is based on the Mojo::Server::Prefork web server, which adds pre-
243 forking to Mojo::Server::Daemon, but optimized specifically for
244 production environments out of the box. To start applications with it
245 you can use the hypnotoad script, which listens on port 8080,
246 automatically daemonizes the server process and defaults to
247 "production" mode for Mojolicious and Mojolicious::Lite applications.
248 $ hypnotoad ./script/my_app
250 Many configuration settings can be tweaked right from within your
252 application with "config" in Mojolicious, for a full list see
253 "SETTINGS" in Mojo::Server::Hypnotoad.
254 use Mojolicious::Lite;
256 app->config(hypnotoad => {listen => ['http://*:80']});
258 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
260 app->start;
262 Or just add a "hypnotoad" section to your Mojolicious::Plugin::Config
264 or Mojolicious::Plugin::JSONConfig configuration file.
265 # myapp.conf
267 {
268 hypnotoad => {
269 listen => ['https://*:443?cert=/etc/server.crt&key=/etc/server.key'],
270 workers => 10
271 }
272 };
273 But one of its biggest advantages is the support for effortless zero
275 downtime software upgrades (hot deployment). That means you can upgrade
276 Mojolicious, Perl or even system libraries at runtime without ever
277 stopping the server or losing a single incoming connection, just by
278 running the command above again.
279 $ hypnotoad ./script/my_app
281 Starting hot deployment for Hypnotoad server 31841.
282 You might also want to enable proxy support if you're using Hypnotoad
284 behind a reverse proxy. This allows Mojolicious to automatically pick
285 up the "X-Forwarded-For" and "X-Forwarded-Proto" headers.
286 # myapp.conf
288 {hypnotoad => {proxy => 1}};
289 To manage Hypnotoad with systemd, you can use a unit configuration file
291 like this.
292 [Unit]
294 Description=My Mojolicious application
295 After=network.target
296 [Service]
298 Type=forking
299 PIDFile=/home/sri/myapp/script/hypnotoad.pid
300 ExecStart=/path/to/hypnotoad /home/sri/myapp/script/my_app
301 ExecReload=/path/to/hypnotoad /home/sri/myapp/script/my_app
302 KillMode=process
303 [Install]
305 WantedBy=multi-user.target
306 Zero downtime software upgrades
308 Hypnotoad makes zero downtime software upgrades (hot deployment) very
309 simple, as you can see above, but on modern operating systems that
310 support the "SO_REUSEPORT" socket option, there is also another method
311 available that works with all built-in web servers.
312 $ ./script/my_app prefork -P /tmp/first.pid -l http://*:8080?reuse=1
314 Server available at http://127.0.0.1:8080
315 All you have to do, is to start a second web server listening to the
317 same port, and stop the first web server gracefully afterwards.
318 $ ./script/my_app prefork -P /tmp/second.pid -l http://*:8080?reuse=1
320 Server available at http://127.0.0.1:8080
321 $ kill -s TERM `cat /tmp/first.pid`
322 Just remember that both web servers need to be started with the "reuse"
324 parameter.
325 Nginx
327 One of the most popular setups these days is Hypnotoad behind an Nginx
328 <http://nginx.org> reverse proxy, which even supports WebSockets in
329 newer versions.
330 upstream myapp {
332 server 127.0.0.1:8080;
333 }
334 server {
335 listen 80;
336 server_name localhost;
337 location / {
338 proxy_pass http://myapp;
339 proxy_http_version 1.1;
340 proxy_set_header Upgrade $http_upgrade;
341 proxy_set_header Connection "upgrade";
342 proxy_set_header Host $host;
343 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
344 proxy_set_header X-Forwarded-Proto $scheme;
345 }
346 }
347 Apache/mod_proxy
349 Another good reverse proxy is Apache <http://httpd.apache.org> with
350 "mod_proxy", the configuration looks quite similar to the Nginx one
351 above. And if you need WebSocket support, newer versions come with
352 "mod_proxy_wstunnel".
353 <VirtualHost *:80>
355 ServerName localhost
356 <Proxy *>
357 Require all granted
358 </Proxy>
359 ProxyRequests Off
360 ProxyPreserveHost On
361 ProxyPass /echo ws://localhost:8080/echo
362 ProxyPass / http://localhost:8080/ keepalive=On
363 ProxyPassReverse / http://localhost:8080/
364 RequestHeader set X-Forwarded-Proto "http"
365 </VirtualHost>
366 Apache/CGI
368 "CGI" is supported out of the box and your Mojolicious application will
369 automatically detect that it is executed as a "CGI" script. Its use in
370 production environments is discouraged though, because as a result of
371 how "CGI" works, it is very slow and many web servers are making it
372 exceptionally hard to configure properly. Additionally, many real-time
373 web features, such as WebSockets, are not available.
374 ScriptAlias / /home/sri/my_app/script/my_app/
376 PSGI/Plack
378 PSGI is an interface between Perl web frameworks and web servers, and
379 Plack is a Perl module and toolkit that contains PSGI middleware,
380 helpers and adapters to web servers. PSGI and Plack are inspired by
381 Python's WSGI and Ruby's Rack. Mojolicious applications are
382 ridiculously simple to deploy with Plack, but be aware that many real-
383 time web features, such as WebSockets, are not available.
384 $ plackup ./script/my_app
386 Plack provides many server and protocol adapters for you to choose
388 from, such as "FCGI", "uWSGI" and "mod_perl".
389 $ plackup ./script/my_app -s FCGI -l /tmp/myapp.sock
391 The "MOJO_REVERSE_PROXY" environment variable can be used to enable
393 proxy support, this allows Mojolicious to automatically pick up the
394 "X-Forwarded-For" and "X-Forwarded-Proto" headers.
395 $ MOJO_REVERSE_PROXY=1 plackup ./script/my_app
397 If an older server adapter is unable to correctly detect the
399 application home directory, you can simply use the "MOJO_HOME"
400 environment variable.
401 $ MOJO_HOME=/home/sri/my_app plackup ./script/my_app
403 There is no need for a ".psgi" file, just point the server adapter at
405 your application script, it will automatically act like one if it
406 detects the presence of a "PLACK_ENV" environment variable.
407 Plack middleware
409 Wrapper scripts like "myapp.fcgi" are a great way to separate
410 deployment and application logic.
411 #!/usr/bin/env plackup -s FCGI
413 use Plack::Builder;
414 builder {
416 enable 'Deflater';
417 require './script/my_app';
418 };
419 Mojo::Server::PSGI can be used directly to load and customize
421 applications in the wrapper script.
422 #!/usr/bin/env plackup -s FCGI
424 use Mojo::Server::PSGI;
425 use Plack::Builder;
426 builder {
428 enable 'Deflater';
429 my $server = Mojo::Server::PSGI->new;
430 $server->load_app('./script/my_app');
431 $server->app->config(foo => 'bar');
432 $server->to_psgi_app;
433 };
434 But you could even use middleware right in your application.
436 use Mojolicious::Lite;
438 use Plack::Builder;
439 get '/welcome' => sub {
441 my $c = shift;
442 $c->render(text => 'Hello Mojo!');
443 };
444 builder {
446 enable 'Deflater';
447 app->start;
448 };
449 Rewriting
451 Sometimes you might have to deploy your application in a blackbox
452 environment where you can't just change the server configuration or
453 behind a reverse proxy that passes along additional information with
454 "X-Forwarded-*" headers. In such cases you can use the hook
455 "before_dispatch" in Mojolicious to rewrite incoming requests.
456 # Change scheme if "X-Forwarded-HTTPS" header is set
458 $app->hook(before_dispatch => sub {
459 my $c = shift;
460 $c->req->url->base->scheme('https')
461 if $c->req->headers->header('X-Forwarded-HTTPS');
462 });
463 Since reverse proxies generally don't pass along information about path
465 prefixes your application might be deployed under, rewriting the base
466 path of incoming requests is also quite common. This allows "url_for"
467 in Mojolicious::Controller for example, to generate portable URLs based
468 on the current environment.
469 # Move first part and slash from path to base path in production mode
471 $app->hook(before_dispatch => sub {
472 my $c = shift;
473 push @{$c->req->url->base->path->trailing_slash(1)},
474 shift @{$c->req->url->path->leading_slash(0)};
475 }) if $app->mode eq 'production';
476 Mojo::URL objects are very easy to manipulate, just make sure that the
478 URL ("foo/bar?baz=yada"), which represents the routing destination, is
479 always relative to the base URL ("http://example.com/myapp/"), which
480 represents the deployment location of your application.
481 Application embedding
483 From time to time you might want to reuse parts of Mojolicious
484 applications like configuration files, database connection or helpers
485 for other scripts, with this little Mojo::Server based mock server you
486 can just embed them.
487 use Mojo::Server;
489 # Load application with mock server
491 my $server = Mojo::Server->new;
492 my $app = $server->load_app('./myapp.pl');
493 # Access fully initialized application
495 say for @{$app->static->paths};
496 say $app->config->{secret_identity};
497 say $app->dumper({just => 'a helper test'});
498 say $app->build_controller->render_to_string(template => 'foo');
499 The plugin Mojolicious::Plugin::Mount uses this functionality to allow
501 you to combine multiple applications into one and deploy them together.
502 use Mojolicious::Lite;
504 app->config(hypnotoad => {listen => ['http://*:80']});
506 plugin Mount => {'test1.example.com' => '/home/sri/myapp1.pl'};
508 plugin Mount => {'test2.example.com' => '/home/sri/myapp2.pl'};
509 app->start;
511 Web server embedding
513 You can also use "one_tick" in Mojo::IOLoop to embed the built-in web
514 server Mojo::Server::Daemon into alien environments like foreign event
515 loops that for some reason can't just be integrated with a new reactor
516 backend.
517 use Mojolicious::Lite;
519 use Mojo::IOLoop;
520 use Mojo::Server::Daemon;
521 # Normal action
523 get '/' => {text => 'Hello World!'};
524 # Connect application with web server and start accepting connections
526 my $daemon
527 = Mojo::Server::Daemon->new(app => app, listen => ['http://*:8080']);
528 $daemon->start;
529 # Call "one_tick" repeatedly from the alien environment
531 Mojo::IOLoop->one_tick while 1;
532
534 The real-time web is a collection of technologies that include Comet
535 (long polling), EventSource and WebSockets, which allow content to be
536 pushed to consumers with long-lived connections as soon as it is
537 generated, instead of relying on the more traditional pull model. All
538 built-in web servers use non-blocking I/O and are based on the
539 Mojo::IOLoop event loop, which provides many very powerful features
540 that allow real-time web applications to scale up to thousands of
541 concurrent client connections.
542 Backend web services
544 Since Mojo::UserAgent is also based on the Mojo::IOLoop event loop, it
545 won't block the built-in web servers when used non-blocking, even for
546 high latency backend web services.
547 use Mojolicious::Lite;
549 # Search MetaCPAN for "mojolicious"
551 get '/' => sub {
552 my $c = shift;
553 $c->ua->get('fastapi.metacpan.org/v1/module/_search?q=mojolicious' => sub {
554 my ($ua, $tx) = @_;
555 $c->render('metacpan', hits => $tx->result->json->{hits}{hits});
556 });
557 };
558 app->start;
560 __DATA__
561 @@ metacpan.html.ep
563 <!DOCTYPE html>
564 <html>
565 <head><title>MetaCPAN results for "mojolicious"</title></head>
566 <body>
567 % for my $hit (@$hits) {
568 <p><%= $hit->{_source}{release} %></p>
569 % }
570 </body>
571 </html>
572 The callback passed to "get" in Mojo::UserAgent will be executed once
574 the request to the backend web service has been finished, this is
575 called continuation-passing style.
576 Synchronizing non-blocking operations
578 Multiple non-blocking operations, such as concurrent requests, can be
579 easily synchronized with promises and "all" in Mojo::Promise. You
580 create Mojo::Promise objects manually or use methods like "get_p" in
581 Mojo::UserAgent that create them for you.
582 use Mojolicious::Lite;
584 use Mojo::Promise;
585 use Mojo::URL;
586 # Search MetaCPAN for "mojo" and "minion"
588 get '/' => sub {
589 my $c = shift;
590 # Create two promises
592 my $url = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
593 my $mojo = $c->ua->get_p($url->clone->query({q => 'mojo'}));
594 my $minion = $c->ua->get_p($url->clone->query({q => 'minion'}));
595 # Render a response once both promises have been resolved
597 Mojo::Promise->all($mojo, $minion)->then(sub {
598 my ($mojo, $minion) = @_;
599 $c->render(json => {
600 mojo => $mojo->[0]->result->json('/hits/hits/0/_source/release'),
601 minion => $minion->[0]->result->json('/hits/hits/0/_source/release')
602 });
603 })->catch(sub {
604 my $err = shift;
605 $c->reply->exception($err);
606 })->wait;
607 };
608 app->start;
610 To create promises manually you just wrap your continuation-passing
612 style APIs in functions that return promises. Here's an example for how
613 "get_p" in Mojo::UserAgent works internally.
614 use Mojo::UserAgent;
616 use Mojo::Promise;
617 # Wrap a user agent method with a promise
619 my $ua = Mojo::UserAgent->new;
620 sub get_p {
621 my $promise = Mojo::Promise->new;
622 $ua->get(@_ => sub {
623 my ($ua, $tx) = @_;
624 my $err = $tx->error;
625 $promise->resolve($tx) if !$err || $err->{code};
626 $promise->reject($err->{message});
627 });
628 return $promise;
629 }
630 # Use our new promise generating function
632 get_p('https://mojolicious.org')->then(sub {
633 my $tx = shift;
634 say $tx->result->dom->at('title')->text;
635 })->wait;
636 Promises have three states, they start out as "pending" and you call
638 "resolve" in Mojo::Promise to transition them to "fulfilled", or
639 "reject" in Mojo::Promise to transition them to "rejected".
640 async/await
642 And if you have Future::AsyncAwait installed you can make using
643 promises even easier. The "async" and "await" keywords are enabled with
644 the "-async_await" flag of Mojo::Base, and make the use of closures
645 with promises completely optional.
646 use Mojo::Base -strict, -async_await;
648 The "async" keyword is placed before the "sub" keyword, and means that
650 this function always returns a promise. Returned values that are not
651 Mojo::Promise objects will be wrapped in a resolved promise
652 automatically. And if an exception gets thrown in the function it will
653 result in a rejected promise.
654 use Mojo::Base -strict, -async_await;
656 async sub hello_p {
658 return 'Hello Mojo!';
659 }
660 hello_p()->then(sub { say @_ })->wait;
662 The "await" keyword on the other hand makes Perl wait for the promise
664 to be settled. It then returns the fulfillment values or throws an
665 exception with the rejection reason. While waiting, the event loop is
666 free to perform other tasks however, so no resources are wasted.
667 use Mojo::Base -strict, -signatures, -async_await;
669 use Mojo::UserAgent;
670 use Mojo::URL;
671 my $ua = Mojo::UserAgent->new;
673 # Search MetaCPAN non-blocking for multiple terms sequentially
675 async sub search_cpan_p ($terms) {
676 my $cpan = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
677 my @urls = map { $cpan->clone->query(q => $_) } @$terms;
678 for my $url (@urls) {
680 my $tx = await $ua->get_p($url);
681 say $tx->result->json('/hits/hits/0/_source/release');
682 }
683 }
684 search_cpan_p(['mojo', 'minion'])->wait;
686 The loop above performs all requests sequentially, awaiting a result
688 before sending the next request. But you can also perform those
689 requests concurrently instead, by using methods like "all" in
690 Mojo::Promise to combine multiple promises before awaiting the results.
691 use Mojo::Base -strict, -signatures, -async_await;
693 use Mojo::Promise;
694 use Mojo::UserAgent;
695 use Mojo::URL;
696 my $ua = Mojo::UserAgent->new;
698 # Search MetaCPAN non-blocking for multiple terms concurrently
700 async sub search_cpan_p ($terms) {
701 my $cpan = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
702 my @urls = map { $cpan->clone->query(q => $_) } @$terms;
703 my @promises = map { $ua->get_p($_) } @urls;
705 my @results = await Mojo::Promise->all(@promises);
706 for my $result (@results) {
707 say $result->[0]->result->json('/hits/hits/0/_source/release');
708 }
709 }
710 search_cpan_p(['mojo', 'minion'])->wait;
712 All of this also means that you can use normal Perl exception handling
714 again. Even many 3rd party exception handling modules from CPAN work
715 just fine.
716 use Mojo::Base -strict, -async_await;
718 use Mojo::Promise;
719 # Catch a non-blocking exception
721 async sub hello_p {
722 eval { await Mojo::Promise->reject('This is an exception') };
723 if (my $err = $@) { warn "Error: $err" }
724 }
725 hello_p()->wait;
727 And it works just the same in Mojolicious and Mojolicious::Lite
729 applications. Just declare your actions with the "async" keyword and
730 use "await" to wait for promises to be "fulfilled" or "rejected".
731 use Mojolicious::Lite -signatures, -async_await;
733 # Request HTML titles from two sites non-blocking
735 get '/' => async sub ($c) {
736 my $mojo_tx = await $c->ua->get_p('https://mojolicious.org');
737 my $mojo_title = $mojo_tx->result->dom->at('title')->text;
738 my $cpan_tx = await $c->ua->get_p('https://metacpan.org');
739 my $cpan_title = $cpan_tx->result->dom->at('title')->text;
740 $c->render(json => {mojo => $mojo_title, cpan => $cpan_title});
742 };
743 app->start;
745 Promises returned by actions will automatically get the default
747 Mojolicious exception handler attached. Making it much harder to ever
748 miss a non-blocking exception again, even if you forgot to handle it
749 yourself.
750 Timers
752 Timers, another primary feature of the event loop, are created with
753 "timer" in Mojo::IOLoop and can, for example, be used to delay
754 rendering of a response, and unlike "sleep", won't block any other
755 requests that might be processed concurrently.
756 use Mojolicious::Lite;
758 use Mojo::IOLoop;
759 # Wait 3 seconds before rendering a response
761 get '/' => sub {
762 my $c = shift;
763 Mojo::IOLoop->timer(3 => sub {
764 $c->render(text => 'Delayed by 3 seconds!');
765 });
766 };
767 app->start;
769 Recurring timers created with "recurring" in Mojo::IOLoop are slightly
771 more powerful, but need to be stopped manually, or they would just keep
772 getting emitted.
773 use Mojolicious::Lite;
775 use Mojo::IOLoop;
776 # Count to 5 in 1 second steps
778 get '/' => sub {
779 my $c = shift;
780 # Start recurring timer
782 my $i = 1;
783 my $id = Mojo::IOLoop->recurring(1 => sub {
784 $c->write_chunk($i);
785 $c->finish if $i++ == 5;
786 });
787 # Stop recurring timer
789 $c->on(finish => sub { Mojo::IOLoop->remove($id) });
790 };
791 app->start;
793 Timers are not tied to a specific request or connection, and can even
795 be created at startup time.
796 use Mojolicious::Lite;
798 use Mojo::IOLoop;
799 # Check title in the background every 10 seconds
801 my $title = 'Got no title yet.';
802 Mojo::IOLoop->recurring(10 => sub {
803 app->ua->get('https://mojolicious.org' => sub {
804 my ($ua, $tx) = @_;
805 $title = $tx->result->dom->at('title')->text;
806 });
807 });
808 # Show current title
810 get '/' => sub {
811 my $c = shift;
812 $c->render(json => {title => $title});
813 };
814 app->start;
816 Just remember that all these non-blocking operations are processed
818 cooperatively, so your callbacks shouldn't block for too long.
819 Subprocesses
821 You can also use subprocesses, created with "subprocess" in
822 Mojo::IOLoop, to perform computationally expensive operations without
823 blocking the event loop.
824 use Mojolicious::Lite;
826 use Mojo::IOLoop;
827 # Operation that would block the event loop for 5 seconds
829 get '/' => sub {
830 my $c = shift;
831 Mojo::IOLoop->subprocess(
832 sub {
833 my $subprocess = shift;
834 sleep 5;
835 return '♥', 'Mojolicious';
836 },
837 sub {
838 my ($subprocess, $err, @results) = @_;
839 $c->reply->exception($err) and return if $err;
840 $c->render(text => "I $results[0] $results[1]!");
841 }
842 );
843 };
844 app->start;
846 The first callback will be executed in a child process, without
848 blocking the event loop of the parent process. The results of the first
849 callback will then be shared between both processes, and the second
850 callback executed in the parent process.
851 Exceptions in non-blocking operations
853 Since timers and other non-blocking operations are running solely in
854 the event loop, outside of the application, exceptions that get thrown
855 in callbacks can't get caught and handled automatically. But you can
856 handle them manually by subscribing to the event "error" in
857 Mojo::Reactor or catching them inside the callback.
858 use Mojolicious::Lite;
860 use Mojo::IOLoop;
861 # Forward error messages to the application log
863 Mojo::IOLoop->singleton->reactor->on(error => sub {
864 my ($reactor, $err) = @_;
865 app->log->error($err);
866 });
867 # Exception only gets logged (and connection times out)
869 get '/connection_times_out' => sub {
870 my $c = shift;
871 Mojo::IOLoop->timer(2 => sub {
872 die 'This request will not be getting a response';
873 });
874 };
875 # Exception gets caught and handled
877 get '/catch_exception' => sub {
878 my $c = shift;
879 Mojo::IOLoop->timer(2 => sub {
880 eval { die 'This request will be getting a response' };
881 $c->reply->exception($@) if $@;
882 });
883 };
884 app->start;
886 A default subscriber that turns all errors into warnings will usually
888 be added by Mojo::IOLoop as a fallback.
889 Mojo::IOLoop->singleton->reactor->unsubscribe('error');
891 During development or for applications where crashing is simply
893 preferable, you can also make every exception that gets thrown in a
894 callback fatal by removing all of its subscribers.
895 WebSocket web service
897 The WebSocket protocol offers full bi-directional low-latency
898 communication channels between clients and servers. Receive messages
899 just by subscribing to events such as "message" in
900 Mojo::Transaction::WebSocket with "on" in Mojolicious::Controller and
901 return them with "send" in Mojolicious::Controller.
902 use Mojolicious::Lite;
904 # Template with browser-side code
906 get '/' => 'index';
907 # WebSocket echo service
909 websocket '/echo' => sub {
910 my $c = shift;
911 # Opened
913 $c->app->log->debug('WebSocket opened');
914 # Increase inactivity timeout for connection a bit
916 $c->inactivity_timeout(300);
917 # Incoming message
919 $c->on(message => sub {
920 my ($c, $msg) = @_;
921 $c->send("echo: $msg");
922 });
923 # Closed
925 $c->on(finish => sub {
926 my ($c, $code, $reason) = @_;
927 $c->app->log->debug("WebSocket closed with status $code");
928 });
929 };
930 app->start;
932 __DATA__
933 @@ index.html.ep
935 <!DOCTYPE html>
936 <html>
937 <head><title>Echo</title></head>
938 <body>
939 <script>
940 var ws = new WebSocket('<%= url_for('echo')->to_abs %>');
941 // Incoming messages
943 ws.onmessage = function (event) {
944 document.body.innerHTML += event.data + '<br/>';
945 };
946 // Outgoing messages
948 ws.onopen = function (event) {
949 window.setInterval(function () { ws.send('Hello Mojo!') }, 1000);
950 };
951 </script>
952 </body>
953 </html>
954 The event "finish" in Mojo::Transaction::WebSocket will be emitted
956 right after the WebSocket connection has been closed.
957 $c->tx->with_compression;
959 You can activate "permessage-deflate" compression with
961 "with_compression" in Mojo::Transaction::WebSocket, this can result in
962 much better performance, but also increases memory usage by up to
963 300KiB per connection.
964 my $proto = $c->tx->with_protocols('v2.proto', 'v1.proto');
966 You can also use "with_protocols" in Mojo::Transaction::WebSocket to
968 negotiate a subprotocol.
969 EventSource web service
971 EventSource is a special form of long polling where you can use "write"
972 in Mojolicious::Controller to directly send DOM events from servers to
973 clients. It is uni-directional, that means you will have to use Ajax
974 requests for sending data from clients to servers, the advantage
975 however is low infrastructure requirements, since it reuses the HTTP
976 protocol for transport.
977 use Mojolicious::Lite;
979 # Template with browser-side code
981 get '/' => 'index';
982 # EventSource for log messages
984 get '/events' => sub {
985 my $c = shift;
986 # Increase inactivity timeout for connection a bit
988 $c->inactivity_timeout(300);
989 # Change content type and finalize response headers
991 $c->res->headers->content_type('text/event-stream');
992 $c->write;
993 # Subscribe to "message" event and forward "log" events to browser
995 my $cb = $c->app->log->on(message => sub {
996 my ($log, $level, @lines) = @_;
997 $c->write("event:log\ndata: [$level] @lines\n\n");
998 });
999 # Unsubscribe from "message" event again once we are done
1001 $c->on(finish => sub {
1002 my $c = shift;
1003 $c->app->log->unsubscribe(message => $cb);
1004 });
1005 };
1006 app->start;
1008 __DATA__
1009 @@ index.html.ep
1011 <!DOCTYPE html>
1012 <html>
1013 <head><title>LiveLog</title></head>
1014 <body>
1015 <script>
1016 var events = new EventSource('<%= url_for 'events' %>');
1017 // Subscribe to "log" event
1019 events.addEventListener('log', function (event) {
1020 document.body.innerHTML += event.data + '<br/>';
1021 }, false);
1022 </script>
1023 </body>
1024 </html>
1025 The event "message" in Mojo::Log will be emitted for every new log
1027 message and the event "finish" in Mojo::Transaction right after the
1028 transaction has been finished.
1029 Streaming multipart uploads
1031 Mojolicious contains a very sophisticated event system based on
1032 Mojo::EventEmitter, with ready-to-use events on almost all layers, and
1033 which can be combined to solve some of the hardest problems in web
1034 development.
1035 use Mojolicious::Lite;
1037 use Scalar::Util 'weaken';
1038 # Intercept multipart uploads and log each chunk received
1040 hook after_build_tx => sub {
1041 my $tx = shift;
1042 # Subscribe to "upgrade" event to identify multipart uploads
1044 weaken $tx;
1045 $tx->req->content->on(upgrade => sub {
1046 my ($single, $multi) = @_;
1047 return unless $tx->req->url->path->contains('/upload');
1048 # Subscribe to "part" event to find the right one
1050 $multi->on(part => sub {
1051 my ($multi, $single) = @_;
1052 # Subscribe to "body" event of part to make sure we have all headers
1054 $single->on(body => sub {
1055 my $single = shift;
1056 # Make sure we have the right part and replace "read" event
1058 return unless $single->headers->content_disposition =~ /example/;
1059 $single->unsubscribe('read')->on(read => sub {
1060 my ($single, $bytes) = @_;
1061 # Log size of every chunk we receive
1063 app->log->debug(length($bytes) . ' bytes uploaded');
1064 });
1065 });
1066 });
1067 });
1068 };
1069 # Upload form in DATA section
1071 get '/' => 'index';
1072 # Streaming multipart upload
1074 post '/upload' => {text => 'Upload was successful.'};
1075 app->start;
1077 __DATA__
1078 @@ index.html.ep
1080 <!DOCTYPE html>
1081 <html>
1082 <head><title>Streaming multipart upload</title></head>
1083 <body>
1084 %= form_for upload => (enctype => 'multipart/form-data') => begin
1085 %= file_field 'example'
1086 %= submit_button 'Upload'
1087 % end
1088 </body>
1089 </html>
1090 More event loops
1092 Internally, the Mojo::IOLoop event loop can use multiple reactor
1093 backends, EV for example, will be automatically used if possible. Which
1094 in turn allows other event loops like AnyEvent to just work.
1095 use Mojolicious::Lite;
1097 use EV;
1098 use AnyEvent;
1099 # Wait 3 seconds before rendering a response
1101 get '/' => sub {
1102 my $c = shift;
1103 my $w;
1104 $w = AE::timer 3, 0, sub {
1105 $c->render(text => 'Delayed by 3 seconds!');
1106 undef $w;
1107 };
1108 };
1109 app->start;
1111
1113 When we say Mojolicious is a web framework we actually mean it, with
1114 Mojo::UserAgent there's a full featured HTTP and WebSocket user agent
1115 built right in.
1116 REST web services
1118 Requests can be performed very comfortably with methods like "get" in
1119 Mojo::UserAgent, and always result in a Mojo::Transaction::HTTP object,
1120 which has many useful attributes and methods. You can check for
1121 connection errors with "result" in Mojo::Transaction, or access HTTP
1122 request and response information directly through "req" in
1123 Mojo::Transaction and "res" in Mojo::Transaction.
1124 use Mojo::UserAgent;
1126 # Request a resource and make sure there were no connection errors
1128 my $ua = Mojo::UserAgent->new;
1129 my $tx = $ua->get('mojolicious.org/perldoc/Mojo' => {Accept => 'text/plain'});
1130 my $res = $tx->result;
1131 # Decide what to do with its representation
1133 if ($res->is_success) { say $res->body }
1134 elsif ($res->is_error) { say $res->message }
1135 elsif ($res->code == 301) { say $res->headers->location }
1136 else { say 'Whatever...' }
1137 While methods like "is_success" in Mojo::Message::Response and
1139 "is_error" in Mojo::Message::Response serve as building blocks for more
1140 sophisticated REST clients.
1141 Web scraping
1143 Scraping information from websites has never been this much fun before.
1144 The built-in HTML/XML parser Mojo::DOM is accessible through "dom" in
1145 Mojo::Message and supports all CSS selectors that make sense for a
1146 standalone parser, it can be a very powerful tool especially for
1147 testing web application.
1148 use Mojo::UserAgent;
1150 # Fetch website
1152 my $ua = Mojo::UserAgent->new;
1153 my $res = $ua->get('mojolicious.org/perldoc')->result;
1154 # Extract title
1156 say 'Title: ', $res->dom->at('head > title')->text;
1157 # Extract headings
1159 $res->dom('h1, h2, h3')->each(sub { say 'Heading: ', shift->all_text });
1160 # Visit all nodes recursively to extract more than just text
1162 for my $n ($res->dom->descendant_nodes->each) {
1163 # Text or CDATA node
1165 print $n->content if $n->type eq 'text' || $n->type eq 'cdata';
1166 # Also include alternate text for images
1168 print $n->{alt} if $n->type eq 'tag' && $n->tag eq 'img';
1169 }
1170 For a full list of available CSS selectors see "SELECTORS" in
1172 Mojo::DOM::CSS.
1173 JSON web services
1175 Most web services these days are based on the JSON data-interchange
1176 format. That's why Mojolicious comes with the possibly fastest pure-
1177 Perl implementation Mojo::JSON built right in, which is accessible
1178 through "json" in Mojo::Message.
1179 use Mojo::UserAgent;
1181 use Mojo::URL;
1182 # Fresh user agent
1184 my $ua = Mojo::UserAgent->new;
1185 # Search MetaCPAN for "mojolicious" and list latest releases
1187 my $url = Mojo::URL->new('http://fastapi.metacpan.org/v1/release/_search');
1188 $url->query({q => 'mojolicious', sort => 'date:desc'});
1189 for my $hit (@{$ua->get($url)->result->json->{hits}{hits}}) {
1190 say "$hit->{_source}{name} ($hit->{_source}{author})";
1191 }
1192 Basic authentication
1194 You can just add username and password to the URL, an "Authorization"
1195 header will be automatically generated.
1196 use Mojo::UserAgent;
1198 my $ua = Mojo::UserAgent->new;
1200 say $ua->get('https://sri:secret@example.com/hideout')->result->body;
1201 Decorating follow-up requests
1203 Mojo::UserAgent can automatically follow redirects, the event "start"
1204 in Mojo::UserAgent allows you direct access to each transaction right
1205 after they have been initialized and before a connection gets
1206 associated with them.
1207 use Mojo::UserAgent;
1209 # User agent following up to 10 redirects
1211 my $ua = Mojo::UserAgent->new(max_redirects => 10);
1212 # Add a witty header to every request
1214 $ua->on(start => sub {
1215 my ($ua, $tx) = @_;
1216 $tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
1217 say 'Request: ', $tx->req->url->clone->to_abs;
1218 });
1219 # Request that will most likely get redirected
1221 say 'Title: ', $ua->get('google.com')->result->dom->at('head > title')->text;
1222 This even works for proxy "CONNECT" requests.
1224 Content generators
1226 Content generators can be registered with "add_generator" in
1227 Mojo::UserAgent::Transactor to generate the same type of content
1228 repeatedly for multiple requests.
1229 use Mojo::UserAgent;
1231 use Mojo::Asset::File;
1232 # Add "stream" generator
1234 my $ua = Mojo::UserAgent->new;
1235 $ua->transactor->add_generator(stream => sub {
1236 my ($transactor, $tx, $path) = @_;
1237 $tx->req->content->asset(Mojo::Asset::File->new(path => $path));
1238 });
1239 # Send multiple files streaming via PUT and POST
1241 $ua->put('http://example.com/upload' => stream => '/home/sri/mojo.png');
1242 $ua->post('http://example.com/upload' => stream => '/home/sri/minion.png');
1243 The "json", "form" and "multipart" content generators are always
1245 available.
1246 use Mojo::UserAgent;
1248 # Send "application/json" content via PATCH
1250 my $ua = Mojo::UserAgent->new;
1251 my $tx = $ua->patch('http://api.example.com' => json => {foo => 'bar'});
1252 # Send query parameters via GET
1254 my $tx2 = $ua->get('search.example.com' => form => {q => 'test'});
1255 # Send "application/x-www-form-urlencoded" content via POST
1257 my $tx3 = $ua->post('http://search.example.com' => form => {q => 'test'});
1258 # Send "multipart/form-data" content via PUT
1260 my $tx4 = $ua->put(
1261 'upload.example.com' => form => {test => {content => 'Hello World!'}});
1262 # Send custom multipart content via PUT
1264 my $tx5 = $ua->put('api.example.com' => multipart => ['Hello', 'World!']);
1265 For more information about available content generators see also "tx"
1267 in Mojo::UserAgent::Transactor.
1268 Large file downloads
1270 When downloading large files with Mojo::UserAgent you don't have to
1271 worry about memory usage at all, because it will automatically stream
1272 everything above 250KiB into a temporary file, which can then be moved
1273 into a permanent file with "save_to" in Mojo::Message.
1274 use Mojo::UserAgent;
1276 # Fetch the latest Mojolicious tarball
1278 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1279 my $tx = $ua->get('https://www.github.com/mojolicious/mojo/tarball/master');
1280 $tx->result->save_to('mojo.tar.gz');
1281 To protect you from excessively large files there is also a limit of
1283 2GiB by default, which you can tweak with the attribute
1284 "max_response_size" in Mojo::UserAgent.
1285 # Increase limit to 10GiB
1287 $ua->max_response_size(10737418240);
1288 Large file upload
1290 Uploading a large file is even easier.
1291 use Mojo::UserAgent;
1293 # Upload file via POST and "multipart/form-data"
1295 my $ua = Mojo::UserAgent->new;
1296 $ua->post('example.com/upload' =>
1297 form => {image => {file => '/home/sri/hello.png'}});
1298 And once again you don't have to worry about memory usage, all data
1300 will be streamed directly from the file.
1301 Streaming response
1303 Receiving a streaming response can be really tricky in most HTTP
1304 clients, but Mojo::UserAgent makes it actually easy.
1305 use Mojo::UserAgent;
1307 # Accept responses of indefinite size
1309 my $ua = Mojo::UserAgent->new(max_response_size => 0);
1310 # Build a normal transaction
1312 my $tx = $ua->build_tx(GET => 'http://example.com');
1313 # Replace "read" events to disable default content parser
1315 $tx->res->content->unsubscribe('read')->on(read => sub {
1316 my ($content, $bytes) = @_;
1317 say "Streaming: $bytes";
1318 });
1319 # Process transaction
1321 $tx = $ua->start($tx);
1322 The event "read" in Mojo::Content will be emitted for every chunk of
1324 data that is received, even chunked transfer encoding and gzip content
1325 encoding will be handled transparently if necessary.
1326 Streaming request
1328 Sending a streaming request is almost just as easy.
1329 use Mojo::UserAgent;
1331 # Build a normal transaction
1333 my $ua = Mojo::UserAgent->new;
1334 my $tx = $ua->build_tx(GET => 'http://example.com');
1335 # Prepare body
1337 my $body = 'Hello World!';
1338 $tx->req->headers->content_length(length $body);
1339 # Start writing directly with a drain callback
1341 my $drain;
1342 $drain = sub {
1343 my $content = shift;
1344 my $chunk = substr $body, 0, 1, '';
1345 $drain = undef unless length $body;
1346 $content->write($chunk, $drain);
1347 };
1348 $tx->req->content->$drain;
1349 # Process transaction
1351 $tx = $ua->start($tx);
1352 The drain callback passed to "write" in Mojo::Content will be executed
1354 whenever the entire previous chunk of data has actually been written.
1355 Non-blocking
1357 Mojo::UserAgent has been designed from the ground up to be non-
1358 blocking, the whole blocking API is just a simple convenience wrapper.
1359 Especially for high latency tasks like web crawling this can be
1360 extremely useful, because you can keep many concurrent connections
1361 active at the same time.
1362 use Mojo::UserAgent;
1364 use Mojo::IOLoop;
1365 # Concurrent non-blocking requests
1367 my $ua = Mojo::UserAgent->new;
1368 $ua->get('https://metacpan.org/search?q=mojo' => sub {
1369 my ($ua, $mojo) = @_;
1370 say $mojo->result->dom->at('title')->text;
1371 });
1372 $ua->get('https://metacpan.org/search?q=minion' => sub {
1373 my ($ua, $minion) = @_;
1374 say $minion->result->dom->at('title')->text;
1375 });
1376 # Start event loop if necessary
1378 Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
1379 But don't try to open too many connections to one server at the same
1381 time, it might get overwhelmed. Better use a queue to process requests
1382 in smaller batches.
1383 use Mojo::UserAgent;
1385 use Mojo::IOLoop;
1386 my @urls = (
1388 'mojolicious.org/perldoc/Mojo/DOM', 'mojolicious.org/perldoc/Mojo',
1389 'mojolicious.org/perldoc/Mojo/File', 'mojolicious.org/perldoc/Mojo/URL'
1390 );
1391 # User agent with a custom name, following up to 5 redirects
1393 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1394 $ua->transactor->name('MyParallelCrawler 1.0');
1395 # Use a delay to keep the event loop running until we are done
1397 my $delay = Mojo::IOLoop->delay;
1398 my $fetch;
1399 $fetch = sub {
1400 # Stop if there are no more URLs
1402 return unless my $url = shift @urls;
1403 # Fetch the next title
1405 my $end = $delay->begin;
1406 $ua->get($url => sub {
1407 my ($ua, $tx) = @_;
1408 say "$url: ", $tx->result->dom->at('title')->text;
1409 # Next request
1411 $fetch->();
1412 $end->();
1413 });
1414 };
1415 # Process two requests at a time
1417 $fetch->() for 1 .. 2;
1418 $delay->wait;
1419 It is also strongly recommended to respect every sites "robots.txt"
1421 file as well as terms of service, and to wait a little before reopening
1422 connections to the same host, or the operators might be forced to block
1423 your access.
1424 Concurrent blocking requests
1426 You might have seen "wait" in Mojo::Promise already in some examples
1427 above. It is used to make non-blocking operations portable, allowing
1428 them to work inside an already running event loop or start one on
1429 demand.
1430 use Mojo::UserAgent;
1432 use Mojo::Promise;
1433 # Synchronize non-blocking requests with promises
1435 my $ua = Mojo::UserAgent->new;
1436 my $mojo = $ua->get_p('https://metacpan.org/search?q=mojo');
1437 my $minion = $ua->get_p('https://metacpan.org/search?q=minion');
1438 Mojo::Promise->all($mojo, $minion)->then(sub {
1439 my ($mojo, $minion) = @_;
1440 say $mojo->[0]->result->dom->at('title')->text;
1441 say $minion->[0]->result->dom->at('title')->text;
1442 })->wait;
1443 WebSockets
1445 WebSockets are not just for the server-side, you can use "websocket_p"
1446 in Mojo::UserAgent to open new connections, which are always non-
1447 blocking. The WebSocket handshake uses HTTP, and is a normal "GET"
1448 request with a few additional headers. It can even contain cookies, and
1449 is followed by a 101 response from the server, notifying our user agent
1450 that the connection has been established and it can start using the bi-
1451 directional WebSocket protocol.
1452 use Mojo::UserAgent;
1454 use Mojo::Promise;
1455 # Open WebSocket to echo service
1457 my $ua = Mojo::UserAgent->new;
1458 $ua->websocket_p('ws://echo.websocket.org')->then(sub {
1459 my $tx = shift;
1460 # Prepare a followup promise so we can wait for messages
1462 my $promise = Mojo::Promise->new;
1463 # Wait for WebSocket to be closed
1465 $tx->on(finish => sub {
1466 my ($tx, $code, $reason) = @_;
1467 say "WebSocket closed with status $code.";
1468 $promise->resolve;
1469 });
1470 # Close WebSocket after receiving one message
1472 $tx->on(message => sub {
1473 my ($tx, $msg) = @_;
1474 say "WebSocket message: $msg";
1475 $tx->finish;
1476 });
1477 # Send a message to the server
1479 $tx->send('Hi!');
1480 # Insert a new promise into the promise chain
1482 return $promise;
1483 })->catch(sub {
1484 my $err = shift;
1485 # Handle failed WebSocket handshakes and other exceptions
1487 warn "WebSocket error: $err";
1488 })->wait;
1489 UNIX domain sockets
1491 Not just TCP/IP sockets are supported, but also UNIX domain sockets,
1492 which can have significant security and performance benefits when used
1493 for inter-process communication. Instead of "http://" and "ws://" you
1494 can use the "http+unix://" and "ws+unix://" schemes, and pass along a
1495 percent encoded path ("/" becomes %2F) instead of a hostname.
1496 use Mojo::UserAgent;
1498 use Mojo::Promise;
1499 # GET request via UNIX domain socket "/tmp/foo.sock"
1501 my $ua = Mojo::UserAgent->new;
1502 say $ua->get('http+unix://%2Ftmp%2Ffoo.sock/index.html')->result->body;
1503 # GET request with HOST header via UNIX domain socket "/tmp/bar.sock"
1505 my $tx = $ua->get('http+unix://%2Ftmp%2Fbar.sock' => {Host => 'example.com'});
1506 say $tx->result->body;
1507 # WebSocket connection via UNIX domain socket "/tmp/baz.sock"
1509 $ua->websocket_p('ws+unix://%2Ftmp%2Fbaz.sock/echo')->then(sub {
1510 my $tx = shift;
1511 my $promise = Mojo::Promise->new;
1513 $tx->on(finish => sub { $promise->resolve });
1514 $tx->on(message => sub {
1516 my ($tx, $msg) = @_;
1517 say "WebSocket message: $msg";
1518 $tx->finish;
1519 });
1520 $tx->send('Hi!');
1521 return $promise;
1523 })->catch(sub {
1524 my $err = shift;
1525 warn "WebSocket error: $err";
1526 })->wait;
1527 You can set the "Host" header manually to pass along a hostname.
1529 Command line
1531 Don't you hate checking huge HTML files from the command line? Thanks
1532 to the command Mojolicious::Command::get that is about to change. You
1533 can just pick the parts that actually matter with the CSS selectors
1534 from Mojo::DOM and JSON Pointers from Mojo::JSON::Pointer.
1535 $ mojo get https://mojolicious.org 'head > title'
1537 How about a list of all id attributes?
1539 $ mojo get https://mojolicious.org '*' attr id
1541 Or the text content of all heading tags?
1543 $ mojo get https://mojolicious.org 'h1, h2, h3' text
1545 Maybe just the text of the third heading?
1547 $ mojo get https://mojolicious.org 'h1, h2, h3' 3 text
1549 You can also extract all text from nested child elements.
1551 $ mojo get https://mojolicious.org '#mojobar' all
1553 The request can be customized as well.
1555 $ mojo get -M POST -H 'X-Bender: Bite my shiny metal ass!' http://google.com
1557 Store response data by redirecting "STDOUT".
1559 $ mojo get mojolicious.org > example.html
1561 Pass request data by redirecting "STDIN".
1563 $ mojo get -M PUT mojolicious.org < example.html
1565 Or use the output of another program.
1567 $ echo 'Hello World' | mojo get -M PUT https://mojolicious.org
1569 Submit forms as "application/x-www-form-urlencoded" content.
1571 $ mojo get -M POST -f 'q=Mojo' -f 'size=5' https://metacpan.org/search
1573 And upload files as "multipart/form-data" content.
1575 $ mojo get -M POST -f 'upload=@example.html' mojolicious.org
1577 You can follow redirects and view the headers for all messages.
1579 $ mojo get -r -v http://google.com 'head > title'
1581 Extract just the information you really need from JSON data structures.
1583 $ mojo get https://fastapi.metacpan.org/v1/author/SRI /name
1585 This can be an invaluable tool for testing your applications.
1587 $ ./myapp.pl get /welcome 'head > title'
1589 One-liners
1591 For quick hacks and especially testing, ojo one-liners are also a great
1592 choice.
1593 $ perl -Mojo -E 'say g("mojolicious.org")->dom->at("title")->text'
1595
1597 Fun Mojolicious application hacks for all occasions.
1598 Basic authentication
1600 Basic authentication data will be automatically extracted from the
1601 "Authorization" header.
1602 use Mojolicious::Lite;
1604 use Mojo::Util 'secure_compare';
1605 get '/' => sub {
1607 my $c = shift;
1608 # Check for username "Bender" and password "rocks"
1610 return $c->render(text => 'Hello Bender!')
1611 if secure_compare $c->req->url->to_abs->userinfo, 'Bender:rocks';
1612 # Require authentication
1614 $c->res->headers->www_authenticate('Basic');
1615 $c->render(text => 'Authentication required!', status => 401);
1616 };
1617 app->start;
1619 This can be combined with TLS for a secure authentication mechanism.
1621 $ ./myapp.pl daemon -l 'https://*:3000?cert=./server.crt&key=./server.key'
1623 Adding a configuration file
1625 Adding a configuration file to your application is as easy as adding a
1626 file to its home directory and loading the plugin
1627 Mojolicious::Plugin::Config. The default name is based on the value of
1628 "moniker" in Mojolicious ("myapp"), appended with a ".conf" extension
1629 ("myapp.conf").
1630 $ mkdir myapp
1632 $ cd myapp
1633 $ touch myapp.pl
1634 $ chmod 744 myapp.pl
1635 $ echo '{name => "my Mojolicious application"};' > myapp.conf
1636 Configuration files themselves are just Perl scripts that return a hash
1638 reference with configuration settings of your choice. All those
1639 settings are then available through the method "config" in Mojolicious
1640 and the helper "config" in Mojolicious::Plugin::DefaultHelpers.
1641 use Mojolicious::Lite;
1643 plugin 'Config';
1645 my $name = app->config('name');
1647 app->log->debug("Welcome to $name");
1648 get '/' => 'with_config';
1650 app->start;
1652 __DATA__
1653 @@ with_config.html.ep
1654 <!DOCTYPE html>
1655 <html>
1656 <head><title><%= config 'name' %></title></head>
1657 <body>Welcome to <%= config 'name' %></body>
1658 </html>
1659 Alternatively you can also use configuration files in the JSON format
1661 with Mojolicious::Plugin::JSONConfig.
1662 Adding a plugin to your application
1664 To organize your code better and to prevent helpers from cluttering
1665 your application, you can use application specific plugins.
1666 $ mkdir -p lib/MyApp/Plugin
1668 $ touch lib/MyApp/Plugin/MyHelpers.pm
1669 They work just like normal plugins and are also subclasses of
1671 Mojolicious::Plugin. Nested helpers with a prefix based on the plugin
1672 name are an easy way to avoid conflicts.
1673 package MyApp::Plugin::MyHelpers;
1675 use Mojo::Base 'Mojolicious::Plugin';
1676 sub register {
1678 my ($self, $app) = @_;
1679 $app->helper('my_helpers.render_with_header' => sub {
1680 my ($c, @args) = @_;
1681 $c->res->headers->header('X-Mojo' => 'I <3 Mojolicious!');
1682 $c->render(@args);
1683 });
1684 }
1685 1;
1687 You can have as many application specific plugins as you like, the only
1689 difference to normal plugins is that you load them using their full
1690 class name.
1691 use Mojolicious::Lite;
1693 use lib 'lib';
1695 plugin 'MyApp::Plugin::MyHelpers';
1697 get '/' => sub {
1699 my $c = shift;
1700 $c->my_helpers->render_with_header(text => 'I ♥ Mojolicious!');
1701 };
1702 app->start;
1704 Of course these plugins can contain more than just helpers, take a look
1706 at "PLUGINS" in Mojolicious::Plugins for a few ideas.
1707 Adding commands to Mojolicious
1709 By now you've probably used many of the built-in commands described in
1710 Mojolicious::Commands, but did you know that you can just add new ones
1711 and that they will be picked up automatically by the command line
1712 interface if they are placed in a directory from @INC?
1713 package Mojolicious::Command::spy;
1715 use Mojo::Base 'Mojolicious::Command';
1716 has description => 'Spy on application';
1718 has usage => "Usage: APPLICATION spy [TARGET]\n";
1719 sub run {
1721 my ($self, @args) = @_;
1722 # Leak secret passphrases
1724 if ($args[0] eq 'secrets') { say for @{$self->app->secrets} }
1725 # Leak mode
1727 elsif ($args[0] eq 'mode') { say $self->app->mode }
1728 }
1729 1;
1731 Command line arguments are passed right through and there are many
1733 useful attributes and methods in Mojolicious::Command that you can use
1734 or overload.
1735 $ mojo spy secrets
1737 HelloWorld
1738 $ ./script/myapp spy secrets
1740 secr3t
1741 And to make your commands application specific, just add a custom
1743 namespace to "namespaces" in Mojolicious::Commands and use a class name
1744 like "MyApp::Command::spy" instead of "Mojolicious::Command::spy".
1745 # Application
1747 package MyApp;
1748 use Mojo::Base 'Mojolicious';
1749 sub startup {
1751 my $self = shift;
1752 # Add another namespace to load commands from
1754 push @{$self->commands->namespaces}, 'MyApp::Command';
1755 }
1756 1;
1758 The options "-h"/"--help", "--home" and "-m"/"--mode" are handled
1760 automatically by Mojolicious::Commands and are shared by all commands.
1761 $ ./script/myapp spy -m production mode
1763 production
1764 For a full list of shared options see "SYNOPSIS" in
1766 Mojolicious::Commands.
1767 Running code against your application
1769 Ever thought about running a quick one-liner against your Mojolicious
1770 application to test something? Thanks to the command
1771 Mojolicious::Command::eval you can do just that, the application object
1772 itself can be accessed via "app".
1773 $ mojo generate lite_app myapp.pl
1775 $ ./myapp.pl eval 'say for @{app->static->paths}'
1776 $ ./myapp.pl eval 'say for sort keys %{app->renderer->helpers}'
1777 The "verbose" options will automatically print the return value or
1779 returned data structure to "STDOUT".
1780 $ ./myapp.pl eval -v 'app->static->paths->[0]'
1782 $ ./myapp.pl eval -V 'app->static->paths'
1783 Making your application installable
1785 Ever thought about releasing your Mojolicious application to CPAN? It's
1786 actually much easier than you might think.
1787 $ mojo generate app MyApp
1789 $ cd my_app
1790 $ mv public lib/MyApp/
1791 $ mv templates lib/MyApp/
1792 The trick is to move the "public" and "templates" directories so they
1794 can get automatically installed with the modules. Additionally author
1795 commands from the "Mojolicious::Command::Author" namespace are not
1796 usually wanted by an installed application so they can be excluded.
1797 # Application
1799 package MyApp;
1800 use Mojo::Base 'Mojolicious';
1801 use Mojo::File 'curfile';
1803 use Mojo::Home;
1804 # Every CPAN module needs a version
1806 our $VERSION = '1.0';
1807 sub startup {
1809 my $self = shift;
1810 # Switch to installable home directory
1812 $self->home(Mojo::Home->new(curfile->sibling('MyApp')));
1813 # Switch to installable "public" directory
1815 $self->static->paths->[0] = $self->home->child('public');
1816 # Switch to installable "templates" directory
1818 $self->renderer->paths->[0] = $self->home->child('templates');
1819 # Exclude author commands
1821 $self->commands->namespaces(['Mojolicious::Commands']);
1822 my $r = $self->routes;
1824 $r->get('/welcome')->to('example#welcome');
1825 }
1826 1;
1828 Finally there is just one small change to be made to the application
1830 script. The shebang line becomes the recommended "#!perl", which the
1831 toolchain can rewrite to the proper shebang during installation.
1832 #!perl
1834 use strict;
1836 use warnings;
1837 use Mojo::File 'curfile';
1839 use lib curfile->dirname->sibling('lib')->to_string;
1840 use Mojolicious::Commands;
1841 # Start command line interface for application
1843 Mojolicious::Commands->start_app('MyApp');
1844 That's really everything, now you can package your application like any
1846 other CPAN module.
1847 $ ./script/my_app generate makefile
1849 $ perl Makefile.PL
1850 $ make test
1851 $ make manifest
1852 $ make dist
1853 And if you have a PAUSE account (which can be requested at
1855 <http://pause.perl.org>) even upload it.
1856 $ mojo cpanify -u USER -p PASS MyApp-0.01.tar.gz
1858 Hello World
1860 If every byte matters this is the smallest "Hello World" application
1861 you can write with Mojolicious::Lite.
1862 use Mojolicious::Lite;
1864 any {text => 'Hello World!'};
1865 app->start;
1866 It works because all routes without a pattern default to "/" and
1868 automatic rendering kicks in even if no actual code gets executed by
1869 the router. The renderer just picks up the "text" value from the stash
1870 and generates a response.
1871 Hello World one-liners
1873 The "Hello World" example above can get even a little bit shorter in an
1874 ojo one-liner.
1875 $ perl -Mojo -E 'a({text => "Hello World!"})->start' daemon
1877 And you can use all the commands from Mojolicious::Commands.
1879 $ perl -Mojo -E 'a({text => "Hello World!"})->start' get -v /
1881
1883 You can continue with Mojolicious::Guides now or take a look at the
1884 Mojolicious wiki <http://github.com/mojolicious/mojo/wiki>, which
1885 contains a lot more documentation and examples by many different
1886 authors.
1887
1889 If you have any questions the documentation might not yet answer, don't
1890 hesitate to ask on the mailing list
1891 <http://groups.google.com/group/mojolicious> or the official IRC
1892 channel "#mojo" on "irc.freenode.net" (chat now!
1893 <https://kiwiirc.com/nextclient/#irc://irc.freenode.net/mojo?nick=guest-?>).
1894perl v5.30.1 2020-01-30 Mojolicious::Guides::Cookbook(3)