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