bug 8215: (followup) make sure C4::CourseReserves doesn't export anything
[koha.git] / C4 / Service.pm
1 package C4::Service;
2 #
3 # Copyright 2008 LibLime
4 #
5 # This file is part of Koha.
6 #
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 2 of the License, or (at your option) any later
10 # version.
11 #
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
15 #
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19
20 =head1 NAME
21
22 C4::Service - functions for JSON webservices.
23
24 =head1 SYNOPSIS
25
26 my ( $query, $response) = C4::Service->init( { circulate => 1 } );
27 my ( $borrowernumber) = C4::Service->require_params( 'borrowernumber' );
28
29 C4::Service->return_error( 'internal', 'Frobnication failed', frobnicator => 'foo' );
30
31 $response->param( frobnicated => 'You' );
32
33 C4::Service->return_success( $response );
34
35 =head1 DESCRIPTION
36
37 This module packages several useful functions for JSON webservices.
38
39 =cut
40
41 use strict;
42 use warnings;
43
44 use CGI;
45 use C4::Auth qw( check_api_auth );
46 use C4::Output qw( :ajax );
47 use C4::Output::JSONStream;
48 use JSON;
49
50 our $debug;
51
52 BEGIN {
53     $debug = $ENV{DEBUG} || 0;
54 }
55
56 our ( $query, $cookie );
57
58 =head1 METHODS
59
60 =head2 init
61
62    our ( $query, $response ) = C4::Service->init( %needed_flags );
63
64 Initialize the service and check for the permissions in C<%needed_flags>.
65
66 Also, check that the user is authorized and has a current session, and return an
67 'auth' error if not.
68
69 init() returns a C<CGI> object and a C<C4::Output::JSONStream>. The latter can
70 be used for both flat scripts and those that use dispatch(), and should be
71 passed to C<return_success()>.
72
73 =cut
74
75 sub init {
76     my ( $class, %needed_flags ) = @_;
77
78     our $query = new CGI;
79
80     my ( $status, $cookie_, $sessionID ) = check_api_auth( $query, \%needed_flags );
81
82     our $cookie = $cookie_; # I have no desire to offend the Perl scoping gods
83
84     $class->return_error( 'auth', $status ) if ( $status ne 'ok' );
85
86     return ( $query, new C4::Output::JSONStream );
87 }
88
89 =head2 return_error
90
91     C4::Service->return_error( $type, $error, %flags );
92
93 Exit the script with HTTP status 400, and return a JSON error object.
94
95 C<$type> should be a short, lower case code for the generic type of error (such
96 as 'auth' or 'input').
97
98 C<$error> should be a more specific code giving information on the error. If
99 multiple errors of the same type occurred, they should be joined by '|'; i.e.,
100 'expired|different_ip'. Information in C<$error> does not need to be
101 human-readable, as its formatting should be handled by the client.
102
103 Any additional information to be given in the response should be passed as
104 param => value pairs.
105
106 =cut
107
108 sub return_error {
109     my ( $class, $type, $error, %flags ) = @_;
110
111     my $response = new C4::Output::JSONStream;
112
113     $response->param( message => $error ) if ( $error );
114     $response->param( type => $type, %flags );
115
116     output_with_http_headers $query, $cookie, $response->output, 'json', '400 Bad Request';
117     exit;
118 }
119
120 =head2 return_multi
121
122     C4::Service->return_multi( \@responses, %flags );
123
124 return_multi is similar to return_success or return_error, but allows you to
125 return different statuses for several requests sent at once (using HTTP status
126 "207 Multi-Status", much like WebDAV). The toplevel hashref (turned into the
127 JSON response) looks something like this:
128
129     { multi => JSON::true, responses => \@responses, %flags }
130
131 Each element of @responses should be either a plain hashref or an arrayref. If
132 it is a hashref, it is sent to the browser as-is. If it is an arrayref, it is
133 assumed to be in the same form as the arguments to return_error, and is turned
134 into an error structure.
135
136 All key-value pairs %flags are, as stated above, put into the returned JSON
137 structure verbatim.
138
139 =cut
140
141 sub return_multi {
142     my ( $class, $responses, @flags ) = @_;
143
144     my $response = new C4::Output::JSONStream;
145
146     if ( !@$responses ) {
147         $class->return_success( $response );
148     } else {
149         my @responses_formatted;
150
151         foreach my $response ( @$responses ) {
152             if ( ref( $response ) eq 'ARRAY' ) {
153                 my ($type, $error, @error_flags) = @$response;
154
155                 push @responses_formatted, { is_error => JSON::true, type => $type, message => $error, @error_flags };
156             } else {
157                 push @responses_formatted, $response;
158             }
159         }
160
161         $response->param( 'multi' => JSON::true, responses => \@responses_formatted, @flags );
162         output_with_http_headers $query, $cookie, $response->output, 'json', '207 Multi-Status';
163     }
164
165     exit;
166 }
167
168 =head2 return_success
169
170     C4::Service->return_success( $response );
171
172 Print out the information in the C<C4::Output::JSONStream> C<$response>, then
173 exit with HTTP status 200.
174
175 =cut
176
177 sub return_success {
178     my ( $class, $response ) = @_;
179
180     output_with_http_headers $query, $cookie, $response->output, 'json';
181 }
182
183 =head2 require_params
184
185     my @values = C4::Service->require_params( @params );
186
187 Check that each of of the parameters specified in @params was sent in the
188 request, then return their values in that order.
189
190 If a required parameter is not found, send a 'param' error to the browser.
191
192 =cut
193
194 sub require_params {
195     my ( $class, @params ) = @_;
196
197     my @values;
198
199     for my $param ( @params ) {
200         $class->return_error( 'params', "Missing '$param'" ) if ( !defined( $query->param( $param ) ) );
201         push @values, $query->param( $param );
202     }
203
204     return @values;
205 }
206
207 =head2 dispatch
208
209     C4::Service->dispatch(
210         [ $path_regex, \@required_params, \&handler ],
211         ...
212     );
213
214 dispatch takes several array-refs, each one describing a 'route', to use the
215 Rails terminology.
216
217 $path_regex should be a string in regex-form, describing which methods and
218 paths this route handles. Each route is tested in order, from the top down, so
219 put more specific handlers first. Also, the regex is tested on the request
220 method, plus the path. For instance, you might use the route [ 'POST /', ... ]
221 to handle POST requests to your service.
222
223 Each named parameter in @required_params is tested for to make sure the route
224 matches, but does not raise an error if one is missing; it simply tests the next
225 route. If you would prefer to raise an error, instead use
226 C<C4::Service->require_params> inside your handler.
227
228 \&handler is called with each matched group in $path_regex in its arguments. For
229 example, if your service is accessed at the path /blah/123, and you call
230 C<dispatch> with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called
231 with the argument '123'.
232
233 =cut
234
235 sub dispatch {
236     my $class = shift;
237
238     my $path_info = $query->path_info || '/';
239
240     ROUTE: foreach my $route ( @_ ) {
241         my ( $path, $params, $handler ) = @$route;
242
243         next unless ( my @match = ( ($query->request_method . ' ' . $path_info)   =~ m,^$path$, ) );
244
245         for my $param ( @$params ) {
246             next ROUTE if ( !defined( $query->param ( $param ) ) );
247         }
248
249         $debug and warn "Using $path";
250         $handler->( @match );
251         return;
252     }
253
254     $class->return_error( 'no_handler', '' );
255 }
256
257 1;
258
259 __END__
260
261 =head1 AUTHORS
262
263 Koha Development Team
264
265 Jesse Weaver <jesse.weaver@liblime.com>