README.md
1# NAME
2
3Web::Machine - A Perl port of Webmachine
4
5# VERSION
6
7version 0.17
8
9# SYNOPSIS
10
11 use strict;
12 use warnings;
13
14 use Web::Machine;
15
16 {
17 package HelloWorld::Resource;
18 use strict;
19 use warnings;
20
21 use parent 'Web::Machine::Resource';
22
23 sub content_types_provided { [{ 'text/html' => 'to_html' }] }
24
25 sub to_html {
26 q{<html>
27 <head>
28 <title>Hello World Resource</title>
29 </head>
30 <body>
31 <h1>Hello World</h1>
32 </body>
33 </html>}
34 }
35 }
36
37 Web::Machine->new( resource => 'HelloWorld::Resource' )->to_app;
38
39# DESCRIPTION
40
41`Web::Machine` provides a RESTful web framework modeled as a state
42machine. You define one or more resource classes. Each resource represents a
43single RESTful URI end point, such as a user, an email, etc. The resource
44class can also be the target for `POST` requests to create a new user, email,
45etc.
46
47Each resource is a state machine, and each request for a resource is handled
48by running the request through that state machine.
49
50`Web::Machine` is built on top of [Plack](https://metacpan.org/pod/Plack), but it handles the full request
51and response cycle.
52
53See [Web::Machine::Manual](https://metacpan.org/pod/Web::Machine::Manual) for more details on using `Web::Machine` in
54general, and how `Web::Machine` and [Plack](https://metacpan.org/pod/Plack) interact.
55
56This is a port of [Webmachine](https://github.com/basho/webmachine), actually
57it is much closer to [the Ruby
58version](https://github.com/seancribbs/webmachine-ruby), with a little bit of
59[the JavaScript version](https://github.com/tautologistics/nodemachine) and
60even some of [the Python version](https://github.com/benoitc/pywebmachine)
61thrown in for good measure.
62
63You can learn a bit about Web::Machine's history from the slides for my [2012
64YAPC::NA talk](https://speakerdeck.com/stevan_little/rest-from-the-trenches).
65
66To learn more about Webmachine, take a look at the links in the SEE ALSO
67section.
68
69# METHODS
70
71NOTE: This module is a [Plack::Component](https://metacpan.org/pod/Plack::Component) subclass and so follows the interface
72set forward by that module.
73
74- `new( resource => $resource_classname, ?resource_args => $arg_list, ?tracing => 1|0, ?streaming => 1|0, ?request_class => $request_class )`
75
76 The constructor expects to get a `$resource_classname`, which it will use to
77 load and create an instance of the resource class. If that class requires any
78 additional arguments, they can be specified with the `resource_args`
79 parameter. The contents of the `resource_args` parameter will be made
80 available to the `init()` method of `Web::Machine::Resource`.
81
82 The `new` method can also take an optional `tracing` parameter which it will
83 pass on to [Web::Machine::FSM](https://metacpan.org/pod/Web::Machine::FSM) and an optional `streaming` parameter, which
84 if true will run the request in a [PSGI](http://plackperl.org/) streaming
85 response. This can be useful if you need to run your content generation
86 asynchronously.
87
88 The optional `request_class` parameter accepts the name of a module that will
89 be used as the request object. The module must be a class that inherits from
90 [Plack::Request](https://metacpan.org/pod/Plack::Request). Use this if you have a subclass of [Plack::Request](https://metacpan.org/pod/Plack::Request) that
91 you would like to use in your [Web::Machine::Resource](https://metacpan.org/pod/Web::Machine::Resource).
92
93- `inflate_request( $env )`
94
95 This takes a raw PSGI `$env` and inflates it into a [Plack::Request](https://metacpan.org/pod/Plack::Request) instance.
96 By default this also uses [HTTP::Headers::ActionPack](https://metacpan.org/pod/HTTP::Headers::ActionPack) to inflate the headers
97 of the request to be complex objects.
98
99- `create_fsm`
100
101 This will create the [Web::Machine::FSM](https://metacpan.org/pod/Web::Machine::FSM) object to run. It will get passed
102 the value of the `tracing` constructor parameter.
103
104- `create_resource( $request )`
105
106 This will create the [Web::Machine::Resource](https://metacpan.org/pod/Web::Machine::Resource) instance using the class specified
107 in the `resource` constructor parameter. It will pass in the `$request` object
108 and call `new_response` on the `$request` object to get a [Plack::Response](https://metacpan.org/pod/Plack::Response)
109 instance.
110
111- `finalize_response( $response )`
112
113 Given a `$response` which is a [Plack::Response](https://metacpan.org/pod/Plack::Response) object, this will finalize
114 it and return a raw PSGI response.
115
116- `call( $env )`
117
118 This is the `call` method overridden from the [Plack::Component](https://metacpan.org/pod/Plack::Component) superclass.
119
120# DEBUGGING
121
122If you set the `WM_DEBUG` environment variable to `1` we will print
123out information about the path taken through the state machine to STDERR.
124
125If you set `WM_DEBUG` to `diag` then debugging information will be printed
126using [Test::More](https://metacpan.org/pod/Test::More)'s `diag()` sub instead.
127
128# SEE ALSO
129
130- The diagram - [https://github.com/Webmachine/webmachine/wiki/Diagram](https://github.com/Webmachine/webmachine/wiki/Diagram)
131- Original Erlang - [https://github.com/basho/webmachine](https://github.com/basho/webmachine)
132- Ruby port - [https://github.com/seancribbs/webmachine-ruby](https://github.com/seancribbs/webmachine-ruby)
133- Node JS port - [https://github.com/tautologistics/nodemachine](https://github.com/tautologistics/nodemachine)
134- Python port - [https://github.com/benoitc/pywebmachine](https://github.com/benoitc/pywebmachine)
135- 2012 YAPC::NA slides - [https://speakerdeck.com/stevan\_little/rest-from-the-trenches](https://speakerdeck.com/stevan_little/rest-from-the-trenches)
136- an elaborate machine is indispensable: a blog post by Justin Sheehy - [http://blog.therestfulway.com/2008/09/webmachine-is-resource-server-for-web.html](http://blog.therestfulway.com/2008/09/webmachine-is-resource-server-for-web.html)
137- Resources, For Real This Time (with Webmachine): a video by Sean Cribbs - [http://www.youtube.com/watch?v=odRrLK87s\_Y](http://www.youtube.com/watch?v=odRrLK87s_Y)
138
139# SUPPORT
140
141bugs may be submitted through [https://github.com/houseabsolute/webmachine-perl/issues](https://github.com/houseabsolute/webmachine-perl/issues).
142
143# AUTHORS
144
145- Stevan Little <stevan@cpan.org>
146- Dave Rolsky <autarch@urth.org>
147
148# CONTRIBUTORS
149
150- Andreas Marienborg <andreas.marienborg@gmail.com>
151- Andrew Nelson <anelson@cpan.org>
152- Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
153- Carlos Fernando Avila Gratz <cafe@q1software.com>
154- Fayland Lam <fayland@gmail.com>
155- George Hartzell <hartzell@alerce.com>
156- Gregory Oschwald <goschwald@maxmind.com>
157- Jesse Luehrs <doy@tozt.net>
158- John SJ Anderson <genehack@genehack.org>
159- Mike Raynham <enquiries@mikeraynham.co.uk>
160- Nathan Cutler <ncutler@suse.cz>
161- Olaf Alders <olaf@wundersolutions.com>
162- Stevan Little <stevan.little@gmail.com>
163- Thomas Sibley <tsibley@cpan.org>
164
165# COPYRIGHT AND LICENCE
166
167This software is copyright (c) 2016 by Infinity Interactive, Inc.
168
169This is free software; you can redistribute it and/or modify it under
170the same terms as the Perl 5 programming language system itself.
171