Web::Machine::Manual - Learn how to use Web::Machine
version 0.16
The basic idea behind Web::Machine is that the handling of a web request is implemented as a state machine. If you're not familiar with state machines, think of a flowchart. We look at the request and the resource we provide and ask questions about them. Is our service available? Is this a GET, POST, PUT, etc.? Does the request ask for a content type our resource provides?
Web::Machine
The result of each question leads us to the next state (or flowchart box). Eventually we reach a point where we have a response for the client. Since this is all built on top of Plack and PSGI, the response consists of a status code, some headers, and an optional body.
The best way to understand the full request/response cycle is to look at the original Erlang webmachine state diagram. Each diamond in that diagram corresponds to a method that your Web::Machine::Resource subclass can implement. The return value from your method determines what method to call next.
However, unlike on that diagram, we often support return values beyond simple true/false values for methods. The Web::Machine::Resource documentation describes what each method can return.
Web::Machine is built on top of Plack and follows the PSGI spec. You can mix Web::Machine applications with other Plack applications using standard Plack tools like Plack::Builder.
Since Web::Machine implements the complete request and response cycle, some Plack middleware is not really needed with Web::Machine. For example, it wouldn't make sense to use something like Plack::Middleware::XSLT with Web::Machine. Web::Machine implements the full content negotiation process, so if you want to handle requests for text/html it probably makes more sense to do this in your resources. The benefit of doing so is that with Web::Machine you can easily ensure that you return a proper 406 Not Acceptable status for content types you can't handle.
Plack::Middleware::XSLT
text/html
406 Not Acceptable
There are still many pieces of Plack middleware that are useful with Web::Machine, such as logging middleware, debugging/linting middleware, etc.
That all said, Web::Machine won't break if you use an inappropriate middleware; you'll just lose some of the benefits you get from implementing things the Web::Machine way.
The PSGI spec requires that the body you return contain bytes, not Perl characters. In other words, strings you return must be passed through Encode::encode so that Perl interprets their contents as bytes.
Encode::encode
If your data is not binary or ASCII, your resource should make sure to provide charset_provided() and default_charset() methods. This will make sure that Web::Machine knows how to turn your response bodies into bytes.
charset_provided()
default_charset()
CAVEAT: Note that currently Web::Machine does not provide full charset or encoding support when the body is returned as a CODE ref. This is a bug to be remedied in the future, but currently you are responsible for making sure this code ref returns bytes.
Stevan Little <stevan@cpan.org>
Dave Rolsky <autarch@urth.org>
Andreas Marienborg <andreas.marienborg@gmail.com>
Andrew Nelson <anelson@cpan.org>
Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
Carlos Fernando Avila Gratz <cafe@q1software.com>
Fayland Lam <fayland@gmail.com>
George Hartzell <hartzell@alerce.com>
Gregory Oschwald <goschwald@maxmind.com>
Jesse Luehrs <doy@tozt.net>
John SJ Anderson <genehack@genehack.org>
Mike Raynham <enquiries@mikeraynham.co.uk>
Mike Raynham <mike.raynham@spareroom.co.uk>
Nathan Cutler <ncutler@suse.cz>
Olaf Alders <olaf@wundersolutions.com>
Thomas Sibley <tsibley@cpan.org>
This software is copyright (c) 2015 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Web::Machine, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Web::Machine
CPAN shell
perl -MCPAN -e shell install Web::Machine
For more information on module installation, please visit the detailed CPAN module installation guide.