File Coverage

blib/lib/Message/Passing/PSGI.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package Message::Passing::PSGI;
2 1     1   812 use strict;
  1         3  
  1         49  
3 1     1   7 use warnings;
  1         1  
  1         86  
4              
5             our $VERSION = '0.001';
6             $VERSION = eval $VERSION;
7              
8             1;
9              
10             =head1 NAME
11              
12             Message::Passing::PSGI - ALPHA QUALITY PSGI adaptor for Message::Passing
13              
14             =head1 SYNOPSIS
15              
16             # Run the server - note that the -e has to all be on one line!
17             plackup -E production -s Twiggy -MPlack::App::Message::Passing -e'Plack::App::Message::Passing->new(return_address => "tcp://127.0.0.1:5555", send_address => "tcp://127.0.0.1:5556")->to_app'
18              
19             # Run your app with the handler
20             plackup -E production -s Message::Passing testapp.psgi --host 127.0.0.1 --port 5556
21              
22             # Browse to:
23             http://localhost:5000/
24              
25             =head1 DESCRIPTION
26              
27             B<ALPHA QUALITY EXPERIMENT - YOU HAVE BEEN WARNED!>
28              
29             This module implements a mongrel2 like strategy for web handlers, using
30             L<Message::Passing::ZeroMQ>.
31              
32             =head1 WHY
33              
34             Because I could! It's a useful experiment to prove that L<Message::Passing>
35             can be used for things entirely unlike my initial goals.
36              
37             =head2 NO, REALLY?
38              
39             B<Theoretically>, this is quite an interesting model - as you've totally split
40             the front end connection acceptance and the back end request handling,
41             you can do things which are harder in other server environments trivially.
42              
43             Examples of things that 'just work' include:
44              
45             =over
46              
47             =item Adding more handler processes
48              
49             Totally dynamic, run as many as you want
50              
51             =item Adding handler processes on other servers
52              
53             As long as your send/return sockets are bound to a host that's network
54             accessible, you can spin up handlers wherever you want.
55              
56             =item Upgrade the application in production
57              
58             You can spin up a new version, verify it appears to be working correctly
59             etc before shutting down the old version
60              
61             =item Profile the application in production
62              
63             Just run a handler with NYTProf..
64              
65             =back
66              
67             B<NOTE:> The properties above _do not_ exist in the current code - you
68             B<will> drop requests in-flight if you shut handlers down!! (Patches to fix
69             this should not be that hard, and would be welcome if anyone is interested)
70              
71             If you're actually interested in using this in production, I'd recommend
72             you look at the real mongrel2, and L<Plack::Handler::Mongrel2>.
73              
74             =head1 BUGS
75              
76             Many, and varied. Please do not try to run this in production ;_)
77              
78             Issues include:
79              
80             =over
81              
82             =item Large responses will use SEVERAL times the response length in RAM
83              
84             =item Requests never timeout
85              
86             =item App Handler crashes / restarts will lost in-flight requests.
87              
88             =item Quite probably leaks RAM.
89              
90             This has not been tested, which means I quite probably got it wrong somewhere ;)
91              
92             =back
93              
94             =head1 SEE ALSO
95              
96             =over
97              
98             =item L<Plack::App::Message::Passing>.
99              
100             =item L<Plack::Handler::Message::Passing>.
101              
102             =item mongrel2
103              
104             =item L<Message::Passing>
105              
106             =item L<Message::Passing::ZeroMQ>.
107              
108             =back
109              
110             =head1 AUTHOR
111              
112             Tomas Doran (t0m) C<< <bobtfish@bobtfish.net> >>
113              
114             =head1 COPYRIGHT
115              
116             Copyright the above author.
117              
118             =head1 LICENSE
119              
120             GNU Affero General Public License, Version 3
121              
122             If you feel this is too restrictive to be able to use this software,
123             please talk to us as we'd be willing to consider re-licensing under
124             less restrictive terms.
125              
126             =cut
127              
128             1;
129