Lemonldap::NG::Common::PSGI(3pm)

1Lemonldap::NG::Common::UPsSeGrI(C3o)ntributed Perl DocumLeenmtoantlidoanp::NG::Common::PSGI(3)
2
3
4

NAME

6       Lemonldap::NG::Common::PSGI - Base library for PSGI modules of
7       Lemonldap::NG.  Use Lemonldap::NG::Common::PSGI::Router for REST API.
8

SYNOPSIS

10         package My::PSGI;
11
12         use base Lemonldap::NG::Common::PSGI;
13
14         sub init {
15           my ($self,$args) = @_;
16           # Will be called 1 time during startup
17
18           # Store debug level
19           $self->logLevel('info');
20           # It is possible to use syslog for user actions
21           $self->syslog('daemon');
22
23           # Return a boolean. If false, then error message has to be stored in
24           # $self->error
25           return 1;
26         }
27
28         sub handler {
29           my ( $self, $req ) = @_;
30           # Do something and return a PSGI response
31           # NB: $req is a Lemonldap::NG::Common::PSGI::Request object
32
33           return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Body lines' ] ];
34         }
35
36       This package could then be called as a CGI, using FastCGI,...
37
38         #!/usr/bin/env perl
39
40         use My::PSGI;
41         use Plack::Handler::FCGI; # or Plack::Handler::CGI
42
43         Plack::Handler::FCGI->new->run( My::PSGI->run() );
44

DESCRIPTION

46       This package provides base class for Lemonldap::NG web interfaces but
47       could be used regardless.
48

METHODS

50   Running methods
51       run ( $args )
52
53       Main method that will manage requests. It can be called using class or
54       already created object:
55
56       Class->run($args):
57           launch new($args), init(), then manage requests (using private
58           _run() method
59
60       $object->run():
61           manage directly requests. Initialization must have be done earlier.
62
63   Logging
64       lmLog ( $msg, $level)
65
66       Print on STDERR messages if level > $self->{logLevel}. Defined log
67       levels are: debug, info, notice, warn, error.
68
69       userLog ($msg, $level)
70
71       Alias for $self->userLogger->$level($msg). Prefer to use this form
72       (required for Auth/Combination)
73
74       userError() userNotice() userInfo()
75
76       Alias for userLog(level). Note that you must use
77       $self->userLogger->$level instead
78
79   Content sending
80       Note that $req, the first argument of these functions, is a
81       Lemonldap::NG::Common::PSGI::Request. See the corresponding
82       documentation.
83
84       sendHtml ( $req, $template )
85
86       This method build HTML response using HTML::Template and the template
87       $template.  $template file must be in $self->templateDir directory.
88       HTML template will receive 5 variables:
89
90       SCRIPT_NAME: the path to the (F)CGI
91       STATIC_PREFIX: content of $self->staticPrefix
92       AVAILABLE_LANGUAGES: content of $self->languages
93       LINKS: JSON stringification of $self->links
94       VERSION: Lemonldap::NG version
95
96       The response is always send with a 200 code.
97
98       sendJSONresponse ( $req, $json, %args )
99
100       Stringify $json object and send it to the client. $req is the
101       Lemonldap::NG::Common::PSGI::Request object; %args can define the HTTP
102       error code (200 by default) or headers to add.
103
104       If client is not json compatible (`Accept` header), response is send in
105       XML.
106
107       Examples:
108
109         $self->sendJSONresponse ( $req, { result => 0 }, code => 400 );
110
111         $self->sendJSONresponse ( $req, { result => 1 } );
112
113         $self->sendJSONresponse ( $req, { result => 1 }, headers => [ X => Z ] );
114
115       sendError ( $req, $msg, $code )
116
117       Call sendJSONresponse with `{ error => $msg }` and code (default to
118       500) and call lmLog() to duplicate error in logs
119
120       abort ( $msg )
121
122       When an error is detected during startup (init() sub), you must not
123       call sendError() but call abort(). Each request received later will
124       receive the error (abort uses sendError() behind the scene).
125
126   Accessors
127       error
128
129       String error. Used if init() fails or if sendError is called without
130       argument.
131
132       languages
133
134       String containing list of languages (ie "fr, en'). Used by sendHtml().
135
136       logLevel
137
138       See lmLog().
139
140       staticPrefix
141
142       String indicating the path of static content (js, css,...). Used by
143       sendHtml().
144
145       templateDir
146
147       Directory containing template files.
148
149       links
150
151       Array of links to display by sendHtml(). Each element has the form:
152
153        { target => 'http://target', title => 'string to display' }
154
155       syslog
156
157       Syslog facility. If empty, STDERR will be used for logging
158

AUTHORS

166       LemonLDAP::NG team <http://lemonldap-ng.org/team>
167

BUG REPORT

169       Use OW2 system to report bug or ask for features:
170       <https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>
171

DOWNLOAD

173       Lemonldap::NG is available at <https://lemonldap-ng.org/download>
174

COPYRIGHT AND LICENSE

176       See COPYING file for details.
177
178       This library is free software; you can redistribute it and/or modify it
179       under the terms of the GNU General Public License as published by the
180       Free Software Foundation; either version 2, or (at your option) any
181       later version.
182
183       This program is distributed in the hope that it will be useful, but
184       WITHOUT ANY WARRANTY; without even the implied warranty of
185       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
186       General Public License for more details.
187
188       You should have received a copy of the GNU General Public License along
189       with this program.  If not, see <http://www.gnu.org/licenses/>.
190
191
192
193perl v5.36.1                      2023-11-14    Lemonldap::NG::Common::PSGI(3)