1Web::Machine::Manual(3)User Contributed Perl DocumentatioWneb::Machine::Manual(3)
2
6 Web::Machine::Manual - Learn how to use Web::Machine
7
9 version 0.17
10
12 The basic idea behind "Web::Machine" is that the handling of a web
13 request is implemented as a state machine. If you're not familiar with
14 state machines, think of a flowchart. We look at the request and the
15 resource we provide and ask questions about them. Is our service
16 available? Is this a GET, POST, PUT, etc.? Does the request ask for a
17 content type our resource provides?
18 The result of each question leads us to the next state (or flowchart
20 box). Eventually we reach a point where we have a response for the
21 client. Since this is all built on top of Plack and PSGI
22 <http://plackperl.org/>, the response consists of a status code, some
23 headers, and an optional body.
24 The best way to understand the full request/response cycle is to look
26 at the original Erlang webmachine state diagram
27 <https://github.com/basho/webmachine/wiki/Diagram>. Each diamond in
28 that diagram corresponds to a method that your Web::Machine::Resource
29 subclass can implement. The return value from your method determines
30 what method to call next.
31 However, unlike on that diagram, we often support return values beyond
33 simple true/false values for methods. The Web::Machine::Resource
34 documentation describes what each method can return.
35
37 "Web::Machine" is built on top of Plack and follows the PSGI
38 <http://plackperl.org/> spec. You can mix "Web::Machine" applications
39 with other Plack applications using standard Plack tools like
40 Plack::Builder.
41 Web::Machine and Plack Middleware
43 Since "Web::Machine" implements the complete request and response
44 cycle, some Plack middleware is not really needed with "Web::Machine".
45 For example, it wouldn't make sense to use something like
46 "Plack::Middleware::XSLT" with "Web::Machine". "Web::Machine"
47 implements the full content negotiation process, so if you want to
48 handle requests for "text/html" it probably makes more sense to do this
49 in your resources. The benefit of doing so is that with "Web::Machine"
50 you can easily ensure that you return a proper "406 Not Acceptable"
51 status for content types you can't handle.
52 There are still many pieces of Plack middleware that are useful with
54 "Web::Machine", such as logging middleware, debugging/linting
55 middleware, etc.
56 That all said, "Web::Machine" won't break if you use an inappropriate
58 middleware; you'll just lose some of the benefits you get from
59 implementing things the "Web::Machine" way.
60 Bodies Must be Bytes
62 The PSGI spec requires that the body you return contain bytes, not Perl
63 characters. In other words, strings you return must be passed through
64 "Encode::encode" so that Perl interprets their contents as bytes.
65 If your data is not binary or ASCII, your resource should make sure to
67 provide "charset_provided()" and "default_charset()" methods. This will
68 make sure that "Web::Machine" knows how to turn your response bodies
69 into bytes.
70 CAVEAT: Note that currently "Web::Machine" does not provide full
72 charset or encoding support when the body is returned as a CODE ref.
73 This is a bug to be remedied in the future, but currently you are
74 responsible for making sure this code ref returns bytes.
75
77 bugs may be submitted through
78 <https://github.com/houseabsolute/webmachine-perl/issues>.
79
81 • Stevan Little <stevan@cpan.org>
82 • Dave Rolsky <autarch@urth.org>
84
86 This software is copyright (c) 2016 by Infinity Interactive, Inc.
87 This is free software; you can redistribute it and/or modify it under
89 the same terms as the Perl 5 programming language system itself.
90perl v5.36.0 2022-07-22 Web::Machine::Manual(3)