/ 
Web-Machine-0.16
River stage one • 3 direct dependents • 5 total dependents
/ Web::Machine::Manual

NAME

Web::Machine::Manual - Learn how to use Web::Machine

VERSION

version 0.16

Web::Machine IN A NUTSHELL

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?

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 and Plack

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.

Web::Machine and Plack Middleware

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.

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.

Bodies Must be Bytes

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.

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.

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.

AUTHORS

  • Stevan Little <stevan@cpan.org>

  • Dave Rolsky <autarch@urth.org>

CONTRIBUTORS

  • 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>

COPYRIGHT AND LICENSE

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.