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 ($result) {
31 ...
32 });
33 ...
34 }
35 While Mojolicious has been designed from the ground up for non-blocking
37 I/O and event loops, it is not possible to magically make Perl code
38 non-blocking. You have to use specialized non-blocking code available
39 through modules like Mojo::IOLoop and Mojo::UserAgent, or third-party
40 event loops. You can wrap your blocking code in subprocesses though to
41 prevent it from interfering with your non-blocking code.
42 Event loops
44 An event loop is basically a loop that continually tests for external
45 events and executes the appropriate callbacks to handle them, it is
46 often the main loop in a program. Non-blocking tests for
47 readability/writability of file descriptors and timers are commonly
48 used events for highly scalable network servers, because they allow a
49 single process to handle thousands of client connections concurrently.
50 while (1) {
52 my @readable = test_fds_for_readability();
53 handle_readable_fds(@readable);
54 my @writable = test_fds_for_writability();
56 handle_writable_fds(@writable);
57 my @expired = test_timers();
59 handle_timers(@expired);
60 }
61 In Mojolicious this event loop is Mojo::IOLoop.
63 Reverse proxy
65 A reverse proxy architecture is a deployment technique used in many
66 production environments, where a reverse proxy server is put in front
67 of your application to act as the endpoint accessible by external
68 clients. It can provide a lot of benefits, like terminating SSL
69 connections from the outside, limiting the number of concurrent open
70 sockets towards the Mojolicious application (or even using Unix
71 sockets), balancing load across multiple instances, or supporting
72 several applications through the same IP/port.
73 ..........................................
75 : :
76 +--------+ : +-----------+ +---------------+ :
77 | |-------->| | | | :
78 | client | : | reverse |----->| Mojolicious | :
79 | |<--------| proxy | | application | :
80 +--------+ : | |<-----| | :
81 : +-----------+ +---------------+ :
82 : :
83 .. system boundary (e.g. same host) ......
84 This setup introduces some problems, though: the application will
86 receive requests from the reverse proxy instead of the original client;
87 the address/hostname where your application lives internally will be
88 different from the one visible from the outside; and if terminating
89 SSL, the reverse proxy exposes services via HTTPS while using HTTP
90 towards the Mojolicious application.
91 As an example, compare a sample request from the client and what the
93 Mojolicious application receives:
94 client reverse proxy Mojolicious app
96 __|__ _______________|______________ ____|____
97 / \ / \ / \
98 1.2.3.4 --HTTPS--> api.example.com 10.20.30.39 --HTTP--> 10.20.30.40
99 GET /foo/1 HTTP/1.1 | GET /foo/1 HTTP/1.1
101 Host: api.example.com | Host: 10.20.30.40
102 User-Agent: Firefox | User-Agent: ShinyProxy/1.2
103 ... | ...
104 However, now the client address is no longer available (which might be
106 useful for analytics, or Geo-IP) and URLs generated via "url_for" in
107 Mojolicious::Controller will look like this:
108 http://10.20.30.40/bar/2
110 instead of something meaningful for the client, like this:
112 https://api.example.com/bar/2
114 To solve these problems, you can configure your reverse proxy to send
116 the missing data (see "Nginx" and "Apache/mod_proxy") and tell your
117 application about it by setting the environment variable
118 "MOJO_REVERSE_PROXY". In more complex situations, usually involving
119 multiple proxies or proxies that live outside your network, it can be
120 necessary to tell the application from which ip addresses to expect
121 proxy requests by setting "MOJO_TRUSTED_PROXIES" to a list of comma
122 separated addresses or CIDR networks. For even finer control,
123 "Rewriting" includes examples of how the changes could be implemented
124 manually.
125
127 Getting Mojolicious and Mojolicious::Lite applications running on
128 different platforms. Note that many real-time web features are based on
129 the Mojo::IOLoop event loop, and therefore require one of the built-in
130 web servers to be able to use them to their full potential.
131 Built-in web server
133 Mojolicious contains a very portable non-blocking I/O HTTP and
134 WebSocket server with Mojo::Server::Daemon. It is usually used during
135 development and in the construction of more advanced web servers, but
136 is solid and fast enough for small to mid sized applications.
137 $ ./script/my_app daemon
139 Web application available at http://127.0.0.1:3000
140 It is available to every application through the command
142 Mojolicious::Command::daemon, which has many configuration options and
143 is known to work on every platform Perl works on with its single-
144 process architecture.
145 $ ./script/my_app daemon -h
147 ...List of available options...
148 Another huge advantage is that it supports TLS and WebSockets out of
150 the box, a development certificate for testing purposes is built right
151 in, so it just works, but you can specify all listen locations
152 supported by "listen" in Mojo::Server::Daemon.
153 $ ./script/my_app daemon -l https://[::]:3000
155 Web application available at https://[::]:3000
156 To manage the web server with systemd, you can use a unit configuration
158 file like this.
159 [Unit]
161 Description=My Mojolicious application
162 After=network.target
163 [Service]
165 Type=simple
166 ExecStart=/home/sri/myapp/script/my_app daemon -m production -l http://*:8080
167 [Install]
169 WantedBy=multi-user.target
170 Pre-forking
172 For bigger applications Mojolicious contains the UNIX optimized pre-
173 forking web server Mojo::Server::Prefork, which can take advantage of
174 multiple CPU cores and copy-on-write memory management to scale up to
175 thousands of concurrent client connections.
176 Mojo::Server::Prefork
178 |- Mojo::Server::Daemon [1]
179 |- Mojo::Server::Daemon [2]
180 |- Mojo::Server::Daemon [3]
181 +- Mojo::Server::Daemon [4]
182 It is based on Mojo::Server::Daemon and available to every application
184 through the command Mojolicious::Command::prefork.
185 $ ./script/my_app prefork
187 Web application available at http://127.0.0.1:3000
188 Since all built-in web servers are based on the Mojo::IOLoop event
190 loop, they scale best with non-blocking operations. But if your
191 application for some reason needs to perform many blocking operations,
192 you can improve performance by increasing the number of worker
193 processes and decreasing the number of concurrent connections each
194 worker is allowed to handle (often as low as 1).
195 $ ./script/my_app prefork -m production -w 10 -c 1
197 Web application available at http://127.0.0.1:3000
198 During startup your application is preloaded in the manager process,
200 which does not run an event loop, so you can use "next_tick" in
201 Mojo::IOLoop to run code whenever a new worker process has been forked
202 and its event loop gets started.
203 use Mojolicious::Lite;
205 Mojo::IOLoop->next_tick(sub ($ioloop) {
207 app->log->info("Worker $$ star...ALL GLORY TO THE HYPNOTOAD!");
208 });
209 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
211 app->start;
213 And to manage the pre-forking web server with systemd, you can use a
215 unit configuration file like this.
216 [Unit]
218 Description=My Mojolicious application
219 After=network.target
220 [Service]
222 Type=simple
223 ExecStart=/home/sri/myapp/script/my_app prefork -m production -l http://*:8080
224 [Install]
226 WantedBy=multi-user.target
227 Morbo
229 After reading the Mojolicious::Guides::Tutorial, you should already be
230 familiar with Mojo::Server::Morbo.
231 Mojo::Server::Morbo
233 +- Mojo::Server::Daemon
234 It is basically a restarter that forks a new Mojo::Server::Daemon web
236 server whenever a file in your project changes, and should therefore
237 only be used during development. To start applications with it you can
238 use the morbo script.
239 $ morbo ./script/my_app
241 Web application available at http://127.0.0.1:3000
242 Containers
244 There are many ways to go cloud-native with Mojolicious. To get you
245 started with containerizing your web applications we will explore one
246 of them in this recipe. First, you will need to declare the CPAN
247 dependencies of your application, for example in a "Makefile.PL" file.
248 This should always include at the very least Mojolicious itself.
249 use strict;
251 use warnings;
252 use ExtUtils::MakeMaker;
254 WriteMakefile(
256 VERSION => '0.01',
257 PREREQ_PM => {
258 'Mojolicious' => '8.65',
259 'Mojolicious::Plugin::Status' => '1.12'
260 },
261 test => {TESTS => 't/*.t'}
262 );
263 The helper command Mojolicious::Command::Author::generate::makefile can
265 also generate a minimal "Makefile.PL" for you.
266 $ ./myapp.pl generate makefile
268 ...
269 And then we are going to need a "Dockerfile" describing the container.
271 A very simple one will do for now.
272 FROM perl
274 WORKDIR /opt/myapp
275 COPY . .
276 RUN cpanm --installdeps -n .
277 EXPOSE 3000
278 CMD ./myapp.pl prefork
279 It uses the latest Perl container <https://hub.docker.com/_/perl> from
281 Docker Hub, copies all the contents of your application directory into
282 the container, installs CPAN dependencies with App::cpanminus, and then
283 starts the application on port 3000 with the pre-forking web server.
284 With Mojolicious::Command::generate::dockerfile there is also a helper
285 command to generate a minimal "Dockerfile" for you.
286 $ ./myapp.pl generate dockerfile
288 ...
289 To build and deploy our container there are also many options
291 available, here we will simply use Docker.
292 $ docker build -t myapp_image .
294 ...
295 $ docker run -d -p 3000:3000 --name myapp_container myapp_image
296 ...
297 And now your web application should be deployed as a container under
299 "http://127.0.0.1:3000". For more information and many more container
300 deployment options we recommend the Docker <https://docs.docker.com/>
301 and Kubernetes <https://kubernetes.io/docs/> documentation.
302 Hypnotoad
304 Hypnotoad is based on the Mojo::Server::Prefork web server, and adds
305 some features especially optimized for high availability non-
306 containerized production environments. To start applications with it
307 you can use the hypnotoad script, which listens on port 8080,
308 automatically daemonizes the server process and defaults to
309 "production" mode for Mojolicious and Mojolicious::Lite applications.
310 $ hypnotoad ./script/my_app
312 Many configuration settings can be tweaked right from within your
314 application with "config" in Mojolicious, for a full list see
315 "SETTINGS" in Mojo::Server::Hypnotoad.
316 use Mojolicious::Lite;
318 app->config(hypnotoad => {listen => ['http://*:80']});
320 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
322 app->start;
324 Or just add a "hypnotoad" section to your Mojolicious::Plugin::Config,
326 Mojolicious::Plugin::JSONConfig or Mojolicious::Plugin::NotYAMLConfig
327 configuration file.
328 # myapp.conf
330 {
331 hypnotoad => {
332 listen => ['https://*:443?cert=/etc/server.crt&key=/etc/server.key'],
333 workers => 10
334 }
335 };
336 But one of its biggest advantages is the support for effortless zero
338 downtime software upgrades (hot deployment). That means you can upgrade
339 Mojolicious, Perl or even system libraries at runtime without ever
340 stopping the server or losing a single incoming connection, just by
341 running the command above again.
342 $ hypnotoad ./script/my_app
344 Starting hot deployment for Hypnotoad server 31841.
345 You might also want to enable proxy support if you're using Hypnotoad
347 behind a reverse proxy. This allows Mojolicious to automatically pick
348 up the "X-Forwarded-For" and "X-Forwarded-Proto" headers.
349 # myapp.conf
351 {hypnotoad => {proxy => 1}};
352 To manage Hypnotoad with systemd, you can use a unit configuration file
354 like this.
355 [Unit]
357 Description=My Mojolicious application
358 After=network.target
359 [Service]
361 Type=forking
362 PIDFile=/home/sri/myapp/script/hypnotoad.pid
363 ExecStart=/path/to/hypnotoad /home/sri/myapp/script/my_app
364 ExecReload=/path/to/hypnotoad /home/sri/myapp/script/my_app
365 KillMode=process
366 [Install]
368 WantedBy=multi-user.target
369 Zero downtime software upgrades
371 Hypnotoad makes zero downtime software upgrades (hot deployment) very
372 simple, as you can see above, but on modern operating systems that
373 support the "SO_REUSEPORT" socket option, there is also another method
374 available that works with all built-in web servers.
375 $ ./script/my_app prefork -P /tmp/first.pid -l http://*:8080?reuse=1
377 Web application available at http://127.0.0.1:8080
378 All you have to do, is to start a second web server listening to the
380 same port, and stop the first web server gracefully afterwards.
381 $ ./script/my_app prefork -P /tmp/second.pid -l http://*:8080?reuse=1
383 Web application available at http://127.0.0.1:8080
384 $ kill -s TERM `cat /tmp/first.pid`
385 Just remember that both web servers need to be started with the "reuse"
387 parameter.
388 Nginx
390 One of the most popular setups these days is Hypnotoad behind an Nginx
391 <https://nginx.org> reverse proxy, which even supports WebSockets in
392 newer versions.
393 upstream myapp {
395 server 127.0.0.1:8080;
396 }
397 server {
398 listen 80;
399 server_name localhost;
400 location / {
401 proxy_pass http://myapp;
402 proxy_http_version 1.1;
403 proxy_set_header Upgrade $http_upgrade;
404 proxy_set_header Connection "upgrade";
405 proxy_set_header Host $host;
406 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
407 proxy_set_header X-Forwarded-Proto $scheme;
408 }
409 }
410 Apache/mod_proxy
412 Another good reverse proxy is Apache <https://httpd.apache.org> with
413 "mod_proxy", the configuration looks quite similar to the Nginx one
414 above. And if you need WebSocket support, newer versions come with
415 "mod_proxy_wstunnel".
416 <VirtualHost *:80>
418 ServerName localhost
419 <Proxy *>
420 Require all granted
421 </Proxy>
422 ProxyRequests Off
423 ProxyPreserveHost On
424 ProxyPass /echo ws://localhost:8080/echo
425 ProxyPass / http://localhost:8080/ keepalive=On
426 ProxyPassReverse / http://localhost:8080/
427 RequestHeader set X-Forwarded-Proto "http"
428 </VirtualHost>
429 Apache/CGI
431 "CGI" is supported out of the box and your Mojolicious application will
432 automatically detect that it is executed as a "CGI" script. Its use in
433 production environments is discouraged though, because as a result of
434 how "CGI" works, it is very slow and many web servers are making it
435 exceptionally hard to configure properly. Additionally, many real-time
436 web features, such as WebSockets, are not available.
437 ScriptAlias / /home/sri/my_app/script/my_app/
439 Envoy
441 Mojolicious applications can be deployed on cloud-native environments
442 that use Envoy <https://www.envoyproxy.io>, such as with this reverse
443 proxy configuration similar to the Apache and Nginx ones above.
444 static_resources:
446 listeners:
447 - name: listener_0
448 address:
449 socket_address: { address: 0.0.0.0, port_value: 80 }
450 filter_chains:
451 - filters:
452 - name: envoy.filters.network.http_connection_manager
453 typed_config:
454 "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
455 codec_type: auto
456 stat_prefix: index_http
457 route_config:
458 name: local_route
459 virtual_hosts:
460 - name: service
461 domains: ["*"]
462 routes:
463 - match:
464 prefix: "/"
465 route:
466 cluster: local_service
467 upgrade_configs:
468 - upgrade_type: websocket
469 http_filters:
470 - name: envoy.filters.http.router
471 typed_config:
472 clusters:
473 - name: local_service
474 connect_timeout: 0.25s
475 type: strict_dns
476 lb_policy: round_robin
477 load_assignment:
478 cluster_name: local_service
479 endpoints:
480 - lb_endpoints:
481 - endpoint:
482 address:
483 socket_address: { address: mojo, port_value: 8080 }
484 While this configuration works for simple applications, Envoy's typical
486 use case is for implementing proxies of applications as a "service
487 mesh" providing advanced filtering, load balancing, and observability
488 features, such as seen in Istio
489 <https://istio.io/latest/docs/ops/deployment/architecture/>. For more
490 examples, visit the Envoy documentation
491 <https://www.envoyproxy.io/docs/envoy/latest/start/start>.
492 PSGI/Plack
494 PSGI is an interface between Perl web frameworks and web servers, and
495 Plack is a Perl module and toolkit that contains PSGI middleware,
496 helpers and adapters to web servers. PSGI and Plack are inspired by
497 Python's WSGI and Ruby's Rack. Mojolicious applications are
498 ridiculously simple to deploy with Plack, but be aware that many real-
499 time web features, such as WebSockets, are not available.
500 $ plackup ./script/my_app
502 Plack provides many server and protocol adapters for you to choose
504 from, such as "FCGI", "uWSGI" and "mod_perl".
505 $ plackup ./script/my_app -s FCGI -l /tmp/myapp.sock
507 The "MOJO_REVERSE_PROXY" environment variable can be used to enable
509 proxy support, this allows Mojolicious to automatically pick up the
510 "X-Forwarded-For" and "X-Forwarded-Proto" headers.
511 $ MOJO_REVERSE_PROXY=1 plackup ./script/my_app
513 If an older server adapter is unable to correctly detect the
515 application home directory, you can simply use the "MOJO_HOME"
516 environment variable.
517 $ MOJO_HOME=/home/sri/my_app plackup ./script/my_app
519 There is no need for a ".psgi" file, just point the server adapter at
521 your application script, it will automatically act like one if it
522 detects the presence of a "PLACK_ENV" environment variable.
523 Plack middleware
525 Wrapper scripts like "myapp.fcgi" are a great way to separate
526 deployment and application logic.
527 #!/usr/bin/env plackup -s FCGI
529 use Plack::Builder;
530 builder {
532 enable 'Deflater';
533 require './script/my_app';
534 };
535 Mojo::Server::PSGI can be used directly to load and customize
537 applications in the wrapper script.
538 #!/usr/bin/env plackup -s FCGI
540 use Mojo::Server::PSGI;
541 use Plack::Builder;
542 builder {
544 enable 'Deflater';
545 my $server = Mojo::Server::PSGI->new;
546 $server->load_app('./script/my_app');
547 $server->app->config(foo => 'bar');
548 $server->to_psgi_app;
549 };
550 But you could even use middleware right in your application.
552 use Mojolicious::Lite -signatures;
554 use Plack::Builder;
555 get '/welcome' => sub ($c) {
557 $c->render(text => 'Hello Mojo!');
558 };
559 builder {
561 enable 'Deflater';
562 app->start;
563 };
564 Rewriting
566 Sometimes you might have to deploy your application in a blackbox
567 environment where you can't just change the server configuration or
568 behind a reverse proxy that passes along additional information with
569 "X-Forwarded-*" headers. In such cases you can use the hook
570 "before_dispatch" in Mojolicious to rewrite incoming requests.
571 # Change scheme if "X-Forwarded-HTTPS" header is set
573 $app->hook(before_dispatch => sub ($c) {
574 $c->req->url->base->scheme('https')
575 if $c->req->headers->header('X-Forwarded-HTTPS');
576 });
577 Since reverse proxies generally don't pass along information about path
579 prefixes your application might be deployed under, rewriting the base
580 path of incoming requests is also quite common. This allows "url_for"
581 in Mojolicious::Controller for example, to generate portable URLs based
582 on the current environment.
583 # Move first part and slash from path to base path in production mode
585 $app->hook(before_dispatch => sub ($c) {
586 push @{$c->req->url->base->path->trailing_slash(1)},
587 shift @{$c->req->url->path->leading_slash(0)};
588 }) if $app->mode eq 'production';
589 Mojo::URL objects are very easy to manipulate, just make sure that the
591 URL ("foo/bar?baz=yada"), which represents the routing destination, is
592 always relative to the base URL ("http://example.com/myapp/"), which
593 represents the deployment location of your application.
594 Application embedding
596 From time to time you might want to reuse parts of Mojolicious
597 applications like configuration files, database connection or helpers
598 for other scripts, with this little Mojo::Server based mock server you
599 can just embed them.
600 use Mojo::Server;
602 # Load application with mock server
604 my $server = Mojo::Server->new;
605 my $app = $server->load_app('./myapp.pl');
606 # Access fully initialized application
608 say for @{$app->static->paths};
609 say $app->config->{secret_identity};
610 say $app->dumper({just => 'a helper test'});
611 say $app->build_controller->render_to_string(template => 'foo');
612 The plugin Mojolicious::Plugin::Mount uses this functionality to allow
614 you to combine multiple applications into one and deploy them together.
615 use Mojolicious::Lite;
617 app->config(hypnotoad => {listen => ['http://*:80']});
619 plugin Mount => {'test1.example.com' => '/home/sri/myapp1.pl'};
621 plugin Mount => {'test2.example.com' => '/home/sri/myapp2.pl'};
622 app->start;
624 Web server embedding
626 You can also use "one_tick" in Mojo::IOLoop to embed the built-in web
627 server Mojo::Server::Daemon into alien environments like foreign event
628 loops that for some reason can't just be integrated with a new reactor
629 backend.
630 use Mojolicious::Lite;
632 use Mojo::IOLoop;
633 use Mojo::Server::Daemon;
634 # Normal action
636 get '/' => {text => 'Hello World!'};
637 # Connect application with web server and start accepting connections
639 my $daemon = Mojo::Server::Daemon->new(app => app, listen => ['http://*:8080']);
640 $daemon->start;
641 # Call "one_tick" repeatedly from the alien environment
643 Mojo::IOLoop->one_tick while 1;
644
646 The real-time web is a collection of technologies that include Comet
647 (long polling), EventSource and WebSockets, which allow content to be
648 pushed to consumers with long-lived connections as soon as it is
649 generated, instead of relying on the more traditional pull model. All
650 built-in web servers use non-blocking I/O and are based on the
651 Mojo::IOLoop event loop, which provides many very powerful features
652 that allow real-time web applications to scale up to thousands of
653 concurrent client connections.
654 Backend web services
656 Since Mojo::UserAgent is also based on the Mojo::IOLoop event loop, it
657 won't block the built-in web servers when used non-blocking, even for
658 high latency backend web services.
659 use Mojolicious::Lite -signatures;
661 # Search MetaCPAN for "mojolicious"
663 get '/' => sub ($c) {
664 $c->ua->get('fastapi.metacpan.org/v1/module/_search?q=mojolicious' => sub ($ua, $tx) {
665 $c->render('metacpan', hits => $tx->result->json->{hits}{hits});
666 });
667 };
668 app->start;
670 __DATA__
671 @@ metacpan.html.ep
673 <!DOCTYPE html>
674 <html>
675 <head><title>MetaCPAN results for "mojolicious"</title></head>
676 <body>
677 % for my $hit (@$hits) {
678 <p><%= $hit->{_source}{release} %></p>
679 % }
680 </body>
681 </html>
682 The callback passed to "get" in Mojo::UserAgent will be executed once
684 the request to the backend web service has been finished, this is
685 called continuation-passing style.
686 Synchronizing non-blocking operations
688 Multiple non-blocking operations, such as concurrent requests, can be
689 easily synchronized with promises and "all" in Mojo::Promise. You
690 create Mojo::Promise objects manually or use methods like "get_p" in
691 Mojo::UserAgent that create them for you.
692 use Mojolicious::Lite -signatures;
694 use Mojo::Promise;
695 use Mojo::URL;
696 # Search MetaCPAN for "mojo" and "minion"
698 get '/' => sub ($c) {
699 # Create two promises
701 my $url = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
702 my $mojo = $c->ua->get_p($url->clone->query({q => 'mojo'}));
703 my $minion = $c->ua->get_p($url->clone->query({q => 'minion'}));
704 # Render a response once both promises have been resolved
706 Mojo::Promise->all($mojo, $minion)->then(sub ($mojo, $minion) {
707 $c->render(json => {
708 mojo => $mojo->[0]->result->json('/hits/hits/0/_source/release'),
709 minion => $minion->[0]->result->json('/hits/hits/0/_source/release')
710 });
711 })->catch(sub ($err) {
712 $c->reply->exception($err);
713 })->wait;
714 };
715 app->start;
717 To create promises manually you just wrap your continuation-passing
719 style APIs in functions that return promises. Here's an example for
720 how "get_p" in Mojo::UserAgent works internally.
721 use Mojo::UserAgent;
723 use Mojo::Promise;
724 # Wrap a user agent method with a promise
726 my $ua = Mojo::UserAgent->new;
727 sub get_p {
728 my $promise = Mojo::Promise->new;
729 $ua->get(@_ => sub ($ua, $tx) {
730 my $err = $tx->error;
731 $promise->resolve($tx) if !$err || $err->{code};
732 $promise->reject($err->{message});
733 });
734 return $promise;
735 }
736 # Use our new promise generating function
738 get_p('https://mojolicious.org')->then(sub ($tx) {
739 say $tx->result->dom->at('title')->text;
740 })->wait;
741 Promises have three states, they start out as "pending" and you call
743 "resolve" in Mojo::Promise to transition them to "fulfilled", or
744 "reject" in Mojo::Promise to transition them to "rejected".
745 async/await
747 And if you have Future::AsyncAwait installed you can make using
748 promises even easier. The "async" and "await" keywords are enabled with
749 the "-async_await" flag of Mojo::Base, and make the use of closures
750 with promises completely optional.
751 use Mojo::Base -strict, -async_await;
753 The "async" keyword is placed before the "sub" keyword, and means that
755 this function always returns a promise. Returned values that are not
756 Mojo::Promise objects will be wrapped in a resolved promise
757 automatically. And if an exception gets thrown in the function it will
758 result in a rejected promise.
759 use Mojo::Base -strict, -async_await;
761 async sub hello_p {
763 return 'Hello Mojo!';
764 }
765 hello_p()->then(sub { say @_ })->wait;
767 The "await" keyword on the other hand makes Perl wait for the promise
769 to be settled. It then returns the fulfillment values or throws an
770 exception with the rejection reason. While waiting, the event loop is
771 free to perform other tasks however, so no resources are wasted.
772 use Mojo::Base -strict, -signatures, -async_await;
774 use Mojo::UserAgent;
775 use Mojo::URL;
776 my $ua = Mojo::UserAgent->new;
778 # Search MetaCPAN non-blocking for multiple terms sequentially
780 async sub search_cpan_p ($terms) {
781 my $cpan = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
782 my @urls = map { $cpan->clone->query(q => $_) } @$terms;
783 for my $url (@urls) {
785 my $tx = await $ua->get_p($url);
786 say $tx->result->json('/hits/hits/0/_source/release');
787 }
788 }
789 search_cpan_p(['mojo', 'minion'])->wait;
791 The loop above performs all requests sequentially, awaiting a result
793 before sending the next request. But you can also perform those
794 requests concurrently instead, by using methods like "all" in
795 Mojo::Promise to combine multiple promises before awaiting the results.
796 use Mojo::Base -strict, -signatures, -async_await;
798 use Mojo::Promise;
799 use Mojo::UserAgent;
800 use Mojo::URL;
801 my $ua = Mojo::UserAgent->new;
803 # Search MetaCPAN non-blocking for multiple terms concurrently
805 async sub search_cpan_p ($terms) {
806 my $cpan = Mojo::URL->new('http://fastapi.metacpan.org/v1/module/_search');
807 my @urls = map { $cpan->clone->query(q => $_) } @$terms;
808 my @promises = map { $ua->get_p($_) } @urls;
810 my @results = await Mojo::Promise->all(@promises);
811 for my $result (@results) {
812 say $result->[0]->result->json('/hits/hits/0/_source/release');
813 }
814 }
815 search_cpan_p(['mojo', 'minion'])->wait;
817 All of this also means that you can use normal Perl exception handling
819 again. Even many 3rd party exception handling modules from CPAN work
820 just fine.
821 use Mojo::Base -strict, -async_await;
823 use Mojo::Promise;
824 # Catch a non-blocking exception
826 async sub hello_p {
827 eval { await Mojo::Promise->reject('This is an exception') };
828 if (my $err = $@) { warn "Error: $err" }
829 }
830 hello_p()->wait;
832 And it works just the same in Mojolicious and Mojolicious::Lite
834 applications. Just declare your actions with the "async" keyword and
835 use "await" to wait for promises to be "fulfilled" or "rejected".
836 use Mojolicious::Lite -signatures, -async_await;
838 # Request HTML titles from two sites non-blocking
840 get '/' => async sub ($c) {
841 my $mojo_tx = await $c->ua->get_p('https://mojolicious.org');
842 my $mojo_title = $mojo_tx->result->dom->at('title')->text;
843 my $cpan_tx = await $c->ua->get_p('https://metacpan.org');
844 my $cpan_title = $cpan_tx->result->dom->at('title')->text;
845 $c->render(json => {mojo => $mojo_title, cpan => $cpan_title});
847 };
848 app->start;
850 Promises returned by actions will automatically get the default
852 Mojolicious exception handler attached. Making it much harder to ever
853 miss a non-blocking exception again, even if you forgot to handle it
854 yourself.
855 Timers
857 Timers, another primary feature of the event loop, are created with
858 "timer" in Mojo::IOLoop and can, for example, be used to delay
859 rendering of a response, and unlike "sleep", won't block any other
860 requests that might be processed concurrently.
861 use Mojolicious::Lite -signatures;
863 use Mojo::IOLoop;
864 # Wait 3 seconds before rendering a response
866 get '/' => sub ($c) {
867 Mojo::IOLoop->timer(3 => sub ($ioloop) {
868 $c->render(text => 'Delayed by 3 seconds!');
869 });
870 };
871 app->start;
873 Recurring timers created with "recurring" in Mojo::IOLoop are slightly
875 more powerful, but need to be stopped manually, or they would just keep
876 getting emitted.
877 use Mojolicious::Lite -signatures;
879 use Mojo::IOLoop;
880 # Count to 5 in 1 second steps
882 get '/' => sub ($c) {
883 # Start recurring timer
885 my $i = 1;
886 my $id = Mojo::IOLoop->recurring(1 => sub ($ioloop) {
887 $c->write_chunk($i);
888 $c->finish if $i++ == 5;
889 });
890 # Stop recurring timer
892 $c->on(finish => sub ($ioloop) { $ioloop->remove($id) });
893 };
894 app->start;
896 Timers are not tied to a specific request or connection, and can even
898 be created at startup time.
899 use Mojolicious::Lite -signatures;
901 use Mojo::IOLoop;
902 # Check title in the background every 10 seconds
904 my $title = 'Got no title yet.';
905 Mojo::IOLoop->recurring(10 => sub ($ioloop) {
906 app->ua->get('https://mojolicious.org' => sub ($ua, $tx) {
907 $title = $tx->result->dom->at('title')->text;
908 });
909 });
910 # Show current title
912 get '/' => sub ($c) {
913 $c->render(json => {title => $title});
914 };
915 app->start;
917 Just remember that all these non-blocking operations are processed
919 cooperatively, so your callbacks shouldn't block for too long.
920 Subprocesses
922 You can also use subprocesses, created with "subprocess" in
923 Mojo::IOLoop, to perform computationally expensive operations without
924 blocking the event loop.
925 use Mojolicious::Lite -signatures;
927 use Mojo::IOLoop;
928 # Operation that would block the event loop for 5 seconds
930 get '/' => sub ($c) {
931 Mojo::IOLoop->subprocess->run_p(sub {
932 sleep 5;
933 return '♥', 'Mojolicious';
934 })->then(sub (@results) {
935 $c->render(text => "I $results[0] $results[1]!");
936 })->catch(sub ($err) {
937 $c->reply->exception($err);
938 });
939 };
940 app->start;
942 The callback passed to "run_p" in Mojo::IOLoop::Subprocess will be
944 executed in a child process, without blocking the event loop of the
945 parent process. The results of the callback will then be shared between
946 both processes, and the promise fulfilled or rejected in the parent
947 process.
948 Exceptions in non-blocking operations
950 Since timers and other non-blocking operations are running solely in
951 the event loop, outside of the application, exceptions that get thrown
952 in callbacks can't get caught and handled automatically. But you can
953 handle them manually by subscribing to the event "error" in
954 Mojo::Reactor or catching them inside the callback.
955 use Mojolicious::Lite -signatures;
957 use Mojo::IOLoop;
958 # Forward error messages to the application log
960 Mojo::IOLoop->singleton->reactor->on(error => sub ($reactor, $err) {
961 app->log->error($err);
962 });
963 # Exception only gets logged (and connection times out)
965 get '/connection_times_out' => sub ($c) {
966 Mojo::IOLoop->timer(2 => sub ($ioloop) {
967 die 'This request will not be getting a response';
968 });
969 };
970 # Exception gets caught and handled
972 get '/catch_exception' => sub ($c) {
973 Mojo::IOLoop->timer(2 => sub ($ioloop) {
974 eval { die 'This request will be getting a response' };
975 $c->reply->exception($@) if $@;
976 });
977 };
978 app->start;
980 A default subscriber that turns all errors into warnings will usually
982 be added by Mojo::IOLoop as a fallback.
983 Mojo::IOLoop->singleton->reactor->unsubscribe('error');
985 During development or for applications where crashing is simply
987 preferable, you can also make every exception that gets thrown in a
988 callback fatal by removing all of its subscribers.
989 WebSocket web service
991 The WebSocket protocol offers full bi-directional low-latency
992 communication channels between clients and servers. Receive messages
993 just by subscribing to events such as "message" in
994 Mojo::Transaction::WebSocket with "on" in Mojolicious::Controller and
995 return them with "send" in Mojolicious::Controller.
996 use Mojolicious::Lite -signatures;
998 # Template with browser-side code
1000 get '/' => 'index';
1001 # WebSocket echo service
1003 websocket '/echo' => sub ($c) {
1004 # Opened
1006 $c->app->log->debug('WebSocket opened');
1007 # Increase inactivity timeout for connection a bit
1009 $c->inactivity_timeout(300);
1010 # Incoming message
1012 $c->on(message => sub ($c, $msg) {
1013 $c->send("echo: $msg");
1014 });
1015 # Closed
1017 $c->on(finish => sub ($c, $code, $reason = undef) {
1018 $c->app->log->debug("WebSocket closed with status $code");
1019 });
1020 };
1021 app->start;
1023 __DATA__
1024 @@ index.html.ep
1026 <!DOCTYPE html>
1027 <html>
1028 <head><title>Echo</title></head>
1029 <body>
1030 <script>
1031 var ws = new WebSocket('<%= url_for('echo')->to_abs %>');
1032 // Incoming messages
1034 ws.onmessage = function (event) {
1035 document.body.innerHTML += event.data + '<br/>';
1036 };
1037 // Outgoing messages
1039 ws.onopen = function (event) {
1040 window.setInterval(function () { ws.send('Hello Mojo!') }, 1000);
1041 };
1042 </script>
1043 </body>
1044 </html>
1045 The event "finish" in Mojo::Transaction::WebSocket will be emitted
1047 right after the WebSocket connection has been closed.
1048 $c->tx->with_compression;
1050 You can activate "permessage-deflate" compression with
1052 "with_compression" in Mojo::Transaction::WebSocket, this can result in
1053 much better performance, but also increases memory usage by up to
1054 300KiB per connection.
1055 my $proto = $c->tx->with_protocols('v2.proto', 'v1.proto');
1057 You can also use "with_protocols" in Mojo::Transaction::WebSocket to
1059 negotiate a subprotocol.
1060 EventSource web service
1062 EventSource is a special form of long polling where you can use "write"
1063 in Mojolicious::Controller to directly send DOM events from servers to
1064 clients. It is uni-directional, that means you will have to use Ajax
1065 requests for sending data from clients to servers, the advantage
1066 however is low infrastructure requirements, since it reuses the HTTP
1067 protocol for transport.
1068 use Mojolicious::Lite -signatures;
1070 # Template with browser-side code
1072 get '/' => 'index';
1073 # EventSource for log messages
1075 get '/events' => sub ($c) {
1076 # Increase inactivity timeout for connection a bit
1078 $c->inactivity_timeout(300);
1079 # Change content type and finalize response headers
1081 $c->res->headers->content_type('text/event-stream');
1082 $c->write;
1083 # Subscribe to "message" event and forward "log" events to browser
1085 my $cb = $c->app->log->on(message => sub ($log, $level, @lines) {
1086 $c->write("event:log\ndata: [$level] @lines\n\n");
1087 });
1088 # Unsubscribe from "message" event again once we are done
1090 $c->on(finish => sub ($c) {
1091 $c->app->log->unsubscribe(message => $cb);
1092 });
1093 };
1094 app->start;
1096 __DATA__
1097 @@ index.html.ep
1099 <!DOCTYPE html>
1100 <html>
1101 <head><title>LiveLog</title></head>
1102 <body>
1103 <script>
1104 var events = new EventSource('<%= url_for 'events' %>');
1105 // Subscribe to "log" event
1107 events.addEventListener('log', function (event) {
1108 document.body.innerHTML += event.data + '<br/>';
1109 }, false);
1110 </script>
1111 </body>
1112 </html>
1113 The event "message" in Mojo::Log will be emitted for every new log
1115 message and the event "finish" in Mojo::Transaction right after the
1116 transaction has been finished.
1117 Streaming multipart uploads
1119 Mojolicious contains a very sophisticated event system based on
1120 Mojo::EventEmitter, with ready-to-use events on almost all layers, and
1121 which can be combined to solve some of the hardest problems in web
1122 development.
1123 use Mojolicious::Lite -signatures;
1125 use Scalar::Util qw(weaken);
1126 # Intercept multipart uploads and log each chunk received
1128 hook after_build_tx => sub ($tx) {
1129 # Subscribe to "upgrade" event to identify multipart uploads
1131 weaken $tx;
1132 $tx->req->content->on(upgrade => sub ($single, $multi) {
1133 return unless $tx->req->url->path->contains('/upload');
1134 # Subscribe to "part" event to find the right one
1136 $multi->on(part => sub ($multi, $single) {
1137 # Subscribe to "body" event of part to make sure we have all headers
1139 $single->on(body => sub ($single) {
1140 # Make sure we have the right part and replace "read" event
1142 return unless $single->headers->content_disposition =~ /example/;
1143 $single->unsubscribe('read')->on(read => sub ($single, $bytes) {
1144 # Log size of every chunk we receive
1146 app->log->debug(length($bytes) . ' bytes uploaded');
1147 });
1148 });
1149 });
1150 });
1151 };
1152 # Upload form in DATA section
1154 get '/' => 'index';
1155 # Streaming multipart upload
1157 post '/upload' => {text => 'Upload was successful.'};
1158 app->start;
1160 __DATA__
1161 @@ index.html.ep
1163 <!DOCTYPE html>
1164 <html>
1165 <head><title>Streaming multipart upload</title></head>
1166 <body>
1167 %= form_for upload => (enctype => 'multipart/form-data') => begin
1168 %= file_field 'example'
1169 %= submit_button 'Upload'
1170 % end
1171 </body>
1172 </html>
1173 More event loops
1175 Internally, the Mojo::IOLoop event loop can use multiple reactor
1176 backends, EV for example, will be automatically used if possible. Which
1177 in turn allows other event loops like AnyEvent to just work.
1178 use Mojolicious::Lite -signatures;
1180 use EV;
1181 use AnyEvent;
1182 # Wait 3 seconds before rendering a response
1184 get '/' => sub ($c) {
1185 my $w;
1186 $w = AE::timer 3, 0, sub {
1187 $c->render(text => 'Delayed by 3 seconds!');
1188 undef $w;
1189 };
1190 };
1191 app->start;
1193
1195 When we say Mojolicious is a web framework we actually mean it, with
1196 Mojo::UserAgent there's a full featured HTTP and WebSocket user agent
1197 built right in.
1198 REST web services
1200 Requests can be performed very comfortably with methods like "get" in
1201 Mojo::UserAgent, and always result in a Mojo::Transaction::HTTP object,
1202 which has many useful attributes and methods. You can check for
1203 connection errors with "result" in Mojo::Transaction, or access HTTP
1204 request and response information directly through "req" in
1205 Mojo::Transaction and "res" in Mojo::Transaction.
1206 use Mojo::UserAgent;
1208 # Request a resource and make sure there were no connection errors
1210 my $ua = Mojo::UserAgent->new;
1211 my $tx = $ua->get('https://docs.mojolicious.org/Mojo' => {Accept => 'text/plain'});
1212 my $res = $tx->result;
1213 # Decide what to do with its representation
1215 if ($res->is_success) { say $res->body }
1216 elsif ($res->is_error) { say $res->message }
1217 elsif ($res->code == 301) { say $res->headers->location }
1218 else { say 'Whatever...' }
1219 While methods like "is_success" in Mojo::Message::Response and
1221 "is_error" in Mojo::Message::Response serve as building blocks for more
1222 sophisticated REST clients.
1223 Web scraping
1225 Scraping information from websites has never been this much fun before.
1226 The built-in HTML/XML parser Mojo::DOM is accessible through "dom" in
1227 Mojo::Message and supports all CSS selectors that make sense for a
1228 standalone parser, it can be a very powerful tool especially for
1229 testing web application.
1230 use Mojo::UserAgent;
1232 # Fetch website
1234 my $ua = Mojo::UserAgent->new;
1235 my $res = $ua->get('https://docs.mojolicious.org')->result;
1236 # Extract title
1238 say 'Title: ', $res->dom->at('head > title')->text;
1239 # Extract headings
1241 $res->dom('h1, h2, h3')->each(sub ($dom, $i) {
1242 say 'Heading: ', $dom->all_text;
1243 });
1244 # Visit all nodes recursively to extract more than just text
1246 for my $n ($res->dom->descendant_nodes->each) {
1247 # Text or CDATA node
1249 print $n->content if $n->type eq 'text' || $n->type eq 'cdata';
1250 # Also include alternate text for images
1252 print $n->{alt} if $n->type eq 'tag' && $n->tag eq 'img';
1253 }
1254 For a full list of available CSS selectors see "SELECTORS" in
1256 Mojo::DOM::CSS.
1257 JSON web services
1259 Most web services these days are based on the JSON data-interchange
1260 format. That's why Mojolicious comes with the possibly fastest pure-
1261 Perl implementation Mojo::JSON built right in, which is accessible
1262 through "json" in Mojo::Message.
1263 use Mojo::UserAgent;
1265 use Mojo::URL;
1266 # Fresh user agent
1268 my $ua = Mojo::UserAgent->new;
1269 # Search MetaCPAN for "mojolicious" and list latest releases
1271 my $url = Mojo::URL->new('http://fastapi.metacpan.org/v1/release/_search');
1272 $url->query({q => 'mojolicious', sort => 'date:desc'});
1273 for my $hit (@{$ua->get($url)->result->json->{hits}{hits}}) {
1274 say "$hit->{_source}{name} ($hit->{_source}{author})";
1275 }
1276 Basic authentication
1278 You can just add username and password to the URL, an "Authorization"
1279 header will be automatically generated.
1280 use Mojo::UserAgent;
1282 my $ua = Mojo::UserAgent->new;
1284 say $ua->get('https://sri:secret@example.com/hideout')->result->body;
1285 If you're using Mojo::URL to build the URL, be aware that the userinfo
1287 part will not be included if the object is stringified. You'll have to
1288 pass the object itself to Mojo::UserAgent or use "to_unsafe_string" in
1289 Mojo::URL.
1290 use Mojo::UserAgent;
1292 use Mojo::URL;
1293 my $ua = Mojo::UserAgent->new;
1295 my $url = Mojo::URL->new('https://example.com/hideout')->userinfo('sri:secret');
1296 say $ua->get($url)->result->body;
1297 Decorating follow-up requests
1299 Mojo::UserAgent can automatically follow redirects, the event "start"
1300 in Mojo::UserAgent allows you direct access to each transaction right
1301 after they have been initialized and before a connection gets
1302 associated with them.
1303 use Mojo::UserAgent;
1305 # User agent following up to 10 redirects
1307 my $ua = Mojo::UserAgent->new(max_redirects => 10);
1308 # Add a witty header to every request
1310 $ua->on(start => sub ($ua, $tx) {
1311 $tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
1312 say 'Request: ', $tx->req->url->clone->to_abs;
1313 });
1314 # Request that will most likely get redirected
1316 say 'Title: ', $ua->get('google.com')->result->dom->at('head > title')->text;
1317 This even works for proxy "CONNECT" requests.
1319 Content generators
1321 Content generators can be registered with "add_generator" in
1322 Mojo::UserAgent::Transactor to generate the same type of content
1323 repeatedly for multiple requests.
1324 use Mojo::UserAgent;
1326 use Mojo::Asset::File;
1327 # Add "stream" generator
1329 my $ua = Mojo::UserAgent->new;
1330 $ua->transactor->add_generator(stream => sub ($transactor, $tx, $path) {
1331 $tx->req->content->asset(Mojo::Asset::File->new(path => $path));
1332 });
1333 # Send multiple files streaming via PUT and POST
1335 $ua->put('http://example.com/upload' => stream => '/home/sri/mojo.png');
1336 $ua->post('http://example.com/upload' => stream => '/home/sri/minion.png');
1337 The "json", "form" and "multipart" content generators are always
1339 available.
1340 use Mojo::UserAgent;
1342 # Send "application/json" content via PATCH
1344 my $ua = Mojo::UserAgent->new;
1345 my $tx = $ua->patch('http://api.example.com' => json => {foo => 'bar'});
1346 # Send query parameters via GET
1348 my $tx2 = $ua->get('search.example.com' => form => {q => 'test'});
1349 # Send "application/x-www-form-urlencoded" content via POST
1351 my $tx3 = $ua->post('http://search.example.com' => form => {q => 'test'});
1352 # Send "multipart/form-data" content via PUT
1354 my $tx4 = $ua->put('upload.example.com' => form => {test => {content => 'Hello World!'}});
1355 # Send custom multipart content via PUT
1357 my $tx5 = $ua->put('api.example.com' => multipart => ['Hello', 'World!']);
1358 For more information about available content generators see also "tx"
1360 in Mojo::UserAgent::Transactor.
1361 Large file downloads
1363 When downloading large files with Mojo::UserAgent you don't have to
1364 worry about memory usage at all, because it will automatically stream
1365 everything above 250KiB into a temporary file, which can then be moved
1366 into a permanent file with "save_to" in Mojo::Message.
1367 use Mojo::UserAgent;
1369 # Fetch the latest Mojolicious tarball
1371 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1372 my $tx = $ua->get('https://www.github.com/mojolicious/mojo/tarball/master');
1373 $tx->result->save_to('mojo.tar.gz');
1374 To protect you from excessively large files there is also a limit of
1376 2GiB by default, which you can tweak with the attribute
1377 "max_response_size" in Mojo::UserAgent.
1378 # Increase limit to 10GiB
1380 $ua->max_response_size(10737418240);
1381 Large file upload
1383 Uploading a large file is even easier.
1384 use Mojo::UserAgent;
1386 # Upload file via POST and "multipart/form-data"
1388 my $ua = Mojo::UserAgent->new;
1389 $ua->post('example.com/upload' => form => {image => {file => '/home/sri/hello.png'}});
1390 And once again you don't have to worry about memory usage, all data
1392 will be streamed directly from the file.
1393 Streaming response
1395 Receiving a streaming response can be really tricky in most HTTP
1396 clients, but Mojo::UserAgent makes it actually easy.
1397 use Mojo::UserAgent;
1399 # Accept responses of indefinite size
1401 my $ua = Mojo::UserAgent->new(max_response_size => 0);
1402 # Build a normal transaction
1404 my $tx = $ua->build_tx(GET => 'http://example.com');
1405 # Replace "read" events to disable default content parser
1407 $tx->res->content->unsubscribe('read')->on(read => sub ($content, $bytes) {
1408 say "Streaming: $bytes";
1409 });
1410 # Process transaction
1412 $tx = $ua->start($tx);
1413 The event "read" in Mojo::Content will be emitted for every chunk of
1415 data that is received, even chunked transfer encoding and gzip content
1416 encoding will be handled transparently if necessary.
1417 Streaming request
1419 Sending a streaming request is almost just as easy.
1420 use Mojo::UserAgent;
1422 # Build a normal transaction
1424 my $ua = Mojo::UserAgent->new;
1425 my $tx = $ua->build_tx(GET => 'http://example.com');
1426 # Prepare body
1428 my $body = 'Hello World!';
1429 $tx->req->headers->content_length(length $body);
1430 # Start writing directly with a drain callback
1432 my $drain = sub ($content) {
1433 my $chunk = substr $body, 0, 1, '';
1434 $content->write($chunk, length $body ? __SUB__ : undef);
1435 };
1436 $tx->req->content->$drain;
1437 # Process transaction
1439 $tx = $ua->start($tx);
1440 The drain callback passed to "write" in Mojo::Content will be executed
1442 whenever the entire previous chunk of data has actually been written.
1443 Non-blocking
1445 Mojo::UserAgent has been designed from the ground up to be non-
1446 blocking, the whole blocking API is just a simple convenience wrapper.
1447 Especially for high latency tasks like web crawling this can be
1448 extremely useful, because you can keep many concurrent connections
1449 active at the same time.
1450 use Mojo::UserAgent;
1452 use Mojo::IOLoop;
1453 # Concurrent non-blocking requests
1455 my $ua = Mojo::UserAgent->new;
1456 $ua->get('https://metacpan.org/search?q=mojo' => sub ($ua, $mojo) {
1457 say $mojo->result->dom->at('title')->text;
1458 });
1459 $ua->get('https://metacpan.org/search?q=minion' => sub ($ua, $minion) {
1460 say $minion->result->dom->at('title')->text;
1461 });
1462 # Start event loop if necessary
1464 Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
1465 But don't try to open too many connections to one server at the same
1467 time, it might get overwhelmed. Better use a queue to process requests
1468 in smaller batches.
1469 use Mojo::Promise;
1471 use Mojo::UserAgent;
1472 my @urls = (
1474 'https://docs.mojolicious.org/Mojo/DOM', 'https://docs.mojolicious.org/Mojo',
1475 'https://docs.mojolicious.org/Mojo/File', 'https://docs.mojolicious.org/Mojo/URL'
1476 );
1477 # User agent with a custom name, following up to 5 redirects
1479 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1480 $ua->transactor->name('MyParallelCrawler 1.0');
1481 # Use a promise to keep the event loop running until we are done
1483 my $promise = Mojo::Promise->new;
1484 my $count = 0;
1485 my $fetch = sub {
1486 # Stop if there are no more URLs
1488 return unless my $url = shift @urls;
1489 # Fetch the next title
1491 $ua->get($url => sub ($ua, $tx) {
1492 say "$url: ", $tx->result->dom->at('title')->text;
1493 # Next request
1495 __SUB__->();
1496 $promise->resolve if --$count == 0;
1497 });
1498 $count++;
1499 };
1500 # Process two requests at a time
1502 $fetch->() for 1 .. 2;
1503 $promise->wait;
1504 It is also strongly recommended to respect every sites "robots.txt"
1506 file as well as terms of service, and to wait a little before reopening
1507 connections to the same host, or the operators might be forced to block
1508 your access.
1509 Concurrent blocking requests
1511 You might have seen "wait" in Mojo::Promise already in some examples
1512 above. It is used to make non-blocking operations portable, allowing
1513 them to work inside an already running event loop or start one on
1514 demand.
1515 use Mojo::UserAgent;
1517 use Mojo::Promise;
1518 # Synchronize non-blocking requests with promises
1520 my $ua = Mojo::UserAgent->new;
1521 my $mojo_promise = $ua->get_p('https://metacpan.org/search?q=mojo');
1522 my $minion_promise = $ua->get_p('https://metacpan.org/search?q=minion');
1523 Mojo::Promise->all($mojo_promise, $minion_promise)->then(sub ($mojo, $minion) {
1524 say $mojo->[0]->result->dom->at('title')->text;
1525 say $minion->[0]->result->dom->at('title')->text;
1526 })->wait;
1527 WebSockets
1529 WebSockets are not just for the server-side, you can use "websocket_p"
1530 in Mojo::UserAgent to open new connections, which are always non-
1531 blocking. The WebSocket handshake uses HTTP, and is a normal "GET"
1532 request with a few additional headers. It can even contain cookies, and
1533 is followed by a 101 response from the server, notifying our user agent
1534 that the connection has been established and it can start using the bi-
1535 directional WebSocket protocol.
1536 use Mojo::UserAgent;
1538 use Mojo::Promise;
1539 # Open WebSocket to echo service
1541 my $ua = Mojo::UserAgent->new;
1542 $ua->websocket_p('ws://echo.websocket.org')->then(sub ($tx) {
1543 # Prepare a followup promise so we can wait for messages
1545 my $promise = Mojo::Promise->new;
1546 # Wait for WebSocket to be closed
1548 $tx->on(finish => sub ($tx, $code, $reason) {
1549 say "WebSocket closed with status $code.";
1550 $promise->resolve;
1551 });
1552 # Close WebSocket after receiving one message
1554 $tx->on(message => sub ($tx, $msg) {
1555 say "WebSocket message: $msg";
1556 $tx->finish;
1557 });
1558 # Send a message to the server
1560 $tx->send('Hi!');
1561 # Insert a new promise into the promise chain
1563 return $promise;
1564 })->catch(sub ($err) {
1565 # Handle failed WebSocket handshakes and other exceptions
1567 warn "WebSocket error: $err";
1568 })->wait;
1569 UNIX domain sockets
1571 Not just TCP/IP sockets are supported, but also UNIX domain sockets,
1572 which can have significant security and performance benefits when used
1573 for inter-process communication. Instead of "http://" and "ws://" you
1574 can use the "http+unix://" and "ws+unix://" schemes, and pass along a
1575 percent encoded path ("/" becomes %2F) instead of a hostname.
1576 use Mojo::UserAgent;
1578 use Mojo::Promise;
1579 # GET request via UNIX domain socket "/tmp/foo.sock"
1581 my $ua = Mojo::UserAgent->new;
1582 say $ua->get('http+unix://%2Ftmp%2Ffoo.sock/index.html')->result->body;
1583 # GET request with HOST header via UNIX domain socket "/tmp/bar.sock"
1585 my $tx = $ua->get('http+unix://%2Ftmp%2Fbar.sock' => {Host => 'example.com'});
1586 say $tx->result->body;
1587 # WebSocket connection via UNIX domain socket "/tmp/baz.sock"
1589 $ua->websocket_p('ws+unix://%2Ftmp%2Fbaz.sock/echo')->then(sub ($tx) {
1590 my $promise = Mojo::Promise->new;
1592 $tx->on(finish => sub ($tx) { $promise->resolve });
1593 $tx->on(message => sub ($tx, $msg) {
1595 say "WebSocket message: $msg";
1596 $tx->finish;
1597 });
1598 $tx->send('Hi!');
1599 return $promise;
1601 })->catch(sub ($err) {
1602 warn "WebSocket error: $err";
1603 })->wait;
1604 You can set the "Host" header manually to pass along a hostname.
1606 Command line
1608 Don't you hate checking huge HTML files from the command line? Thanks
1609 to the command Mojolicious::Command::get that is about to change. You
1610 can just pick the parts that actually matter with the CSS selectors
1611 from Mojo::DOM and JSON Pointers from Mojo::JSON::Pointer.
1612 $ mojo get https://mojolicious.org 'head > title'
1614 How about a list of all id attributes?
1616 $ mojo get https://mojolicious.org '*' attr id
1618 Or the text content of all heading tags?
1620 $ mojo get https://mojolicious.org 'h1, h2, h3' text
1622 Maybe just the text of the third heading?
1624 $ mojo get https://mojolicious.org 'h1, h2, h3' 3 text
1626 You can also extract all text from nested child elements.
1628 $ mojo get https://mojolicious.org '#mojobar' all
1630 The request can be customized as well.
1632 $ mojo get -M POST -H 'X-Bender: Bite my shiny metal ass!' http://google.com
1634 Store response data by redirecting "STDOUT".
1636 $ mojo get mojolicious.org > example.html
1638 Pass request data by redirecting "STDIN".
1640 $ mojo get -M PUT mojolicious.org < example.html
1642 Or use the output of another program.
1644 $ echo 'Hello World' | mojo get -M PUT https://mojolicious.org
1646 Submit forms as "application/x-www-form-urlencoded" content.
1648 $ mojo get -M POST -f 'q=Mojo' -f 'size=5' https://metacpan.org/search
1650 And upload files as "multipart/form-data" content.
1652 $ mojo get -M POST -f 'upload=@example.html' mojolicious.org
1654 You can follow redirects and view the headers for all messages.
1656 $ mojo get -r -v http://google.com 'head > title'
1658 Extract just the information you really need from JSON data structures.
1660 $ mojo get https://fastapi.metacpan.org/v1/author/SRI /name
1662 This can be an invaluable tool for testing your applications.
1664 $ ./myapp.pl get /welcome 'head > title'
1666 One-liners
1668 For quick hacks and especially testing, ojo one-liners are also a great
1669 choice.
1670 $ perl -Mojo -E 'say g("mojolicious.org")->dom->at("title")->text'
1672
1674 Fun Mojolicious application hacks for all occasions.
1675 Basic authentication
1677 Basic authentication data will be automatically extracted from the
1678 "Authorization" header.
1679 use Mojolicious::Lite -signatures;
1681 use Mojo::Util qw(secure_compare);
1682 get '/' => sub ($c) {
1684 # Check for username "Bender" and password "rocks"
1686 return $c->render(text => 'Hello Bender!') if secure_compare $c->req->url->to_abs->userinfo, 'Bender:rocks';
1687 # Require authentication
1689 $c->res->headers->www_authenticate('Basic');
1690 $c->render(text => 'Authentication required!', status => 401);
1691 };
1692 app->start;
1694 This can be combined with TLS for a secure authentication mechanism.
1696 $ ./myapp.pl daemon -l 'https://*:3000?cert=./server.crt&key=./server.key'
1698 Adding a configuration file
1700 Adding a configuration file to your application is as easy as adding a
1701 file to its home directory and loading the plugin
1702 Mojolicious::Plugin::Config. The default name is based on the value of
1703 "moniker" in Mojolicious ("myapp"), appended with a ".conf" extension
1704 ("myapp.conf").
1705 $ mkdir myapp
1707 $ cd myapp
1708 $ touch myapp.pl
1709 $ chmod 744 myapp.pl
1710 $ echo '{name => "my Mojolicious application"};' > myapp.conf
1711 Configuration files themselves are just Perl scripts that return a hash
1713 reference with configuration settings of your choice. All those
1714 settings are then available through the method "config" in Mojolicious
1715 and the helper "config" in Mojolicious::Plugin::DefaultHelpers.
1716 use Mojolicious::Lite;
1718 plugin 'Config';
1720 my $name = app->config('name');
1722 app->log->debug("Welcome to $name");
1723 get '/' => 'with_config';
1725 app->start;
1727 __DATA__
1728 @@ with_config.html.ep
1729 <!DOCTYPE html>
1730 <html>
1731 <head><title><%= config 'name' %></title></head>
1732 <body>Welcome to <%= config 'name' %></body>
1733 </html>
1734 Alternatively you can also use configuration files in the JSON format
1736 with Mojolicious::Plugin::JSONConfig.
1737 Adding a plugin to your application
1739 To organize your code better and to prevent helpers from cluttering
1740 your application, you can use application specific plugins.
1741 $ mkdir -p lib/MyApp/Plugin
1743 $ touch lib/MyApp/Plugin/MyHelpers.pm
1744 They work just like normal plugins and are also subclasses of
1746 Mojolicious::Plugin. Nested helpers with a prefix based on the plugin
1747 name are an easy way to avoid conflicts.
1748 package MyApp::Plugin::MyHelpers;
1750 use Mojo::Base 'Mojolicious::Plugin', -signatures;
1751 sub register ($self, $app, $conf) {
1753 $app->helper('my_helpers.render_with_header' => sub ($c, @args) {
1754 $c->res->headers->header('X-Mojo' => 'I <3 Mojolicious!');
1755 $c->render(@args);
1756 });
1757 }
1758 1;
1760 You can have as many application specific plugins as you like, the only
1762 difference to normal plugins is that you load them using their full
1763 class name.
1764 use Mojolicious::Lite -signatures;
1766 use lib qw(lib);
1768 plugin 'MyApp::Plugin::MyHelpers';
1770 get '/' => sub ($c) {
1772 $c->my_helpers->render_with_header(text => 'I ♥ Mojolicious!');
1773 };
1774 app->start;
1776 Of course these plugins can contain more than just helpers, take a look
1778 at "PLUGINS" in Mojolicious::Plugins for a few ideas.
1779 Adding commands to Mojolicious
1781 By now you've probably used many of the built-in commands described in
1782 Mojolicious::Commands, but did you know that you can just add new ones
1783 and that they will be picked up automatically by the command line
1784 interface if they are placed in a directory from @INC?
1785 package Mojolicious::Command::spy;
1787 use Mojo::Base 'Mojolicious::Command', -signatures;
1788 has description => 'Spy on application';
1790 has usage => "Usage: APPLICATION spy [TARGET]\n";
1791 sub run ($self, @args) {
1793 # Leak secret passphrases
1795 if ($args[0] eq 'secrets') { say for @{$self->app->secrets} }
1796 # Leak mode
1798 elsif ($args[0] eq 'mode') { say $self->app->mode }
1799 }
1800 1;
1802 Command line arguments are passed right through and there are many
1804 useful attributes and methods in Mojolicious::Command that you can use
1805 or overload.
1806 $ mojo spy secrets
1808 HelloWorld
1809 $ ./script/myapp spy secrets
1811 secr3t
1812 And to make your commands application specific, just add a custom
1814 namespace to "namespaces" in Mojolicious::Commands and use a class name
1815 like "MyApp::Command::spy" instead of "Mojolicious::Command::spy".
1816 # Application
1818 package MyApp;
1819 use Mojo::Base 'Mojolicious', -signatures;
1820 sub startup ($self) {
1822 # Add another namespace to load commands from
1824 push @{$self->commands->namespaces}, 'MyApp::Command';
1825 }
1826 1;
1828 The options "-h"/"--help", "--home" and "-m"/"--mode" are handled
1830 automatically by Mojolicious::Commands and are shared by all commands.
1831 $ ./script/myapp spy -m production mode
1833 production
1834 For a full list of shared options see "SYNOPSIS" in
1836 Mojolicious::Commands.
1837 Running code against your application
1839 Ever thought about running a quick one-liner against your Mojolicious
1840 application to test something? Thanks to the command
1841 Mojolicious::Command::eval you can do just that, the application object
1842 itself can be accessed via "app".
1843 $ mojo generate lite-app myapp.pl
1845 $ ./myapp.pl eval 'say for @{app->static->paths}'
1846 $ ./myapp.pl eval 'say for sort keys %{app->renderer->helpers}'
1847 The "verbose" options will automatically print the return value or
1849 returned data structure to "STDOUT".
1850 $ ./myapp.pl eval -v 'app->static->paths->[0]'
1852 $ ./myapp.pl eval -V 'app->static->paths'
1853 Making your application installable
1855 Ever thought about releasing your Mojolicious application to CPAN? It's
1856 actually much easier than you might think.
1857 $ mojo generate app MyApp
1859 $ cd my_app
1860 $ mv public lib/MyApp/
1861 $ mv templates lib/MyApp/
1862 The trick is to move the "public" and "templates" directories so they
1864 can get automatically installed with the modules. Additionally author
1865 commands from the "Mojolicious::Command::Author" namespace are not
1866 usually wanted by an installed application so they can be excluded.
1867 # Application
1869 package MyApp;
1870 use Mojo::Base 'Mojolicious', -signatures;
1871 use Mojo::File qw(curfile);
1873 use Mojo::Home;
1874 # Every CPAN module needs a version
1876 our $VERSION = '1.0';
1877 sub startup ($self) {
1879 # Switch to installable home directory
1881 $self->home(Mojo::Home->new(curfile->sibling('MyApp')));
1882 # Switch to installable "public" directory
1884 $self->static->paths->[0] = $self->home->child('public');
1885 # Switch to installable "templates" directory
1887 $self->renderer->paths->[0] = $self->home->child('templates');
1888 # Exclude author commands
1890 $self->commands->namespaces(['Mojolicious::Commands']);
1891 my $r = $self->routes;
1893 $r->get('/welcome')->to('example#welcome');
1894 }
1895 1;
1897 Finally there is just one small change to be made to the application
1899 script. The shebang line becomes the recommended "#!perl", which the
1900 toolchain can rewrite to the proper shebang during installation.
1901 #!perl
1903 use strict;
1905 use warnings;
1906 use Mojo::File qw(curfile);
1908 use lib curfile->dirname->sibling('lib')->to_string;
1909 use Mojolicious::Commands;
1910 # Start command line interface for application
1912 Mojolicious::Commands->start_app('MyApp');
1913 That's really everything, now you can package your application like any
1915 other CPAN module.
1916 $ ./script/my_app generate makefile
1918 $ perl Makefile.PL
1919 $ make test
1920 $ make manifest
1921 $ make dist
1922 And if you have a PAUSE account (which can be requested at
1924 <http://pause.perl.org>) even upload it.
1925 $ mojo cpanify -u USER -p PASS MyApp-0.01.tar.gz
1927 Hello World
1929 If every byte matters this is the smallest "Hello World" application
1930 you can write with Mojolicious::Lite.
1931 use Mojolicious::Lite;
1933 any {text => 'Hello World!'};
1934 app->start;
1935 It works because all routes without a pattern default to "/" and
1937 automatic rendering kicks in even if no actual code gets executed by
1938 the router. The renderer just picks up the "text" value from the stash
1939 and generates a response.
1940 Hello World one-liners
1942 The "Hello World" example above can get even a little bit shorter in an
1943 ojo one-liner.
1944 $ perl -Mojo -E 'a({text => "Hello World!"})->start' daemon
1946 And you can use all the commands from Mojolicious::Commands.
1948 $ perl -Mojo -E 'a({text => "Hello World!"})->start' get -v /
1950
1952 You can continue with Mojolicious::Guides now or take a look at the
1953 Mojolicious wiki <https://github.com/mojolicious/mojo/wiki>, which
1954 contains a lot more documentation and examples by many different
1955 authors.
1956
1958 If you have any questions the documentation might not yet answer, don't
1959 hesitate to ask in the Forum <https://forum.mojolicious.org> or the
1960 official IRC channel "#mojo" on "chat.freenode.net" (chat now!
1961 <https://webchat.freenode.net/#mojo>).
1962perl v5.32.1 2021-02-07 Mojolicious::Guides::Cookbook(3)