1Perlbal::Plugin::CgilikUes(e3r)Contributed Perl DocumentPaetrilobnal::Plugin::Cgilike(3)
2
3
4

NAME

6       Perlbal::Plugin::Cgilike - Handle Perlbal requests with a Perl
7       subroutine
8

DESCRIPTION

10       This module allows responses to be handled with a simple API that's
11       similar in principle to CGI, mod_perl response handlers, etc.
12
13       It does not, however, come anywhere close to conforming to the CGI
14       "standard". It's actually more like mod_perl in usage, though there are
15       several differences.  Most notably, Perlbal is single-process and
16       single-threaded, and handlers run inside the Perlbal process and must
17       therefore return quickly and not do any blocking operations.
18
19       As it currently stands, this is very bare-bones and has only really
20       been used with basic GET requests. It lacks a nice API for handling the
21       body of a POST or PUT request.
22
23       It is not recommended to use this for extensive applications. Perlbal
24       is first and foremost a load balancer, so if you're doing something at
25       all complicated you're probably better off using something like Apache
26       mod_perl and then putting Perlbal in front if it if necessary.
27       However, this plugin may prove useful for simple handlers or perhaps
28       embedding a simple HTTP service into another application that uses
29       "Danga::Socket".
30

SYNOPSIS

32       This module provides a Perlbal plugin which can be loaded and used as
33       follows.
34
35               LOAD cgilike
36               PERLREQUIRE = MyPackage
37
38               CREATE SERVICE cgilike
39                       SET role   = web_server
40                       SET listen = 127.0.0.1:80
41                       SET plugins = cgilike
42                       PERLHANDLER = MyPackage::handler
43               ENABLE cgilike
44
45       With this plugin loaded into a particular service, the plugin will then
46       be called for all requests for that service.
47
48       Set cgilike.handler to the name of a subroutine that will handle
49       requests. This subroutine will receive an object which allows
50       interaction with the Perlbal service.
51
52               package MyPackage
53               sub handler {
54                   my ($r) = @_;
55                       if ($r->uri eq '/') {
56                               print "<p>Hello, world</p>";
57                               return Perlbal::Plugin::Cgilike::HANDLED;
58                       }
59                       else {
60                               return 404;
61                       }
62               }
63
64       Return "Perlbal::Plugin::Cgilike::HANDLED" to indicate that the request
65       has been handled, or return some HTTP error code to produce a
66       predefined error message.  You may also return
67       "Perlbal::Plugin::Cgilike::DECLINED" if you do not wish to handle the
68       request, in which case Perlbal will be allowed to handle the request in
69       whatever way it would have done without Cgilike loaded.
70
71       If your handler returns any non-success value, it MUST NOT produce any
72       output. If you produce output before returning such a value, the
73       response to the client is likely to be utter nonsense.
74
75       You may also return "Perlbal::Plugin::Cgilike::POSTPONE_RESPONSE",
76       which is equivalent to returning zero except that the HTTP connection
77       will be left open once you return. It is your responsibility to later
78       call "$r->end_response()" when you have completed the response. This
79       style is necessary when you need to perform some long operation before
80       you can return a response; you'll need to use some appropriate method
81       to set a callback to run when the operation completes and then do your
82       response in the callback. Once you've called "end_response", you must
83       not call any further methods on $r; it's probably safest to just return
84       immediately afterwards to avoid any mishaps.
85

API DOCUMENTATION

87       TODO: Write this
88

TODO

90       Currently there is no API for dealing with the body of a POST or PUT
91       request. Ideally it'd be able to do automatic decoding of
92       application/x-www-form-urlencoded data, too.
93
94       The POSTPONE_RESPONSE functionality has not been tested extensively and
95       is probably buggy.
96

98       Copyright 2007 Martin Atkins <mart@degeneration.co.uk> and Six Apart
99       Ltd.
100
101       This module is part of the Perlbal distribution, and as such can be
102       distributed under the same licence terms as the rest of Perlbal.
103
104
105
106perl v5.30.0                      2019-07-24       Perlbal::Plugin::Cgilike(3)
Impressum