VERSION
version 0.16Web::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 <http://plackperl.org/>, 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 <https://github.com/basho/webmachine/wiki/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 <http://plackperl.org/> 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 <[email protected]>
- Dave Rolsky <[email protected]>
CONTRIBUTORS
- Andreas Marienborg <[email protected]>
- Andrew Nelson <[email protected]>
- Arthur Axel 'fREW' Schmidt <[email protected]>
- Carlos Fernando Avila Gratz <[email protected]>
- Fayland Lam <[email protected]>
- George Hartzell <[email protected]>
- Gregory Oschwald <[email protected]>
- Jesse Luehrs <[email protected]>
- John SJ Anderson <[email protected]>
- Mike Raynham <[email protected]>
- Mike Raynham <[email protected]>
- Nathan Cutler <[email protected]>
- Olaf Alders <[email protected]>
- Thomas Sibley <[email protected]>
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.