Server/API.pm untested

filter: Statementstmt 0.0% 0 / 66 Branchbran 0.0% 0 / 26 Conditioncond 0.0% 0 / 24 MC/DCmcdc 0.0% 0 / 7 Subroutinesub 0.0% 0 / 11 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 137 CC 14 SCAR 41.7
CC
14
Cov
0%
api
132.0
is_connected
20.0
check
2.0
CRAP 64.6
1 package WWW::Suffit::Server::API;
2 use strict;
3 use utf8;
4  
5 =encoding utf8
6  
7 =head1 NAME
8  
9 WWW::Suffit::Server::API - The Suffit API controller
10  
11 =head1 SYNOPSIS
12  
13 use WWW::Suffit::Server::API;
14  
15 =head1 DESCRIPTION
16  
17 The Suffit API controller
18  
19 =head1 METHODS
20  
21 List of internal methods
22  
23 =head2 api
24  
25 See L</"GET /api">
26  
27 =head2 check
28  
29 See L</"GET /api/check">
30  
31 =head2 is_connected
32  
33 This method connects to the authorization database and returns the connection status
34  
35 my $r = $app->routes->under('/')
36 ->to('API#is_connected')
37 ->name('__authdb');
38  
39 =head1 API METHODS
40  
41 List of API methods
42  
43 =head2 GET /api
44  
45 This method returns general statistics of the API server, available only after authorization
46  
47 # curl -v -H "Authorization: Bearer eyJh...s5aM" \
48 https://localhost:8695/api
49  
50 > GET /api HTTP/1.1
51 > Host: localhost:8695
52 > User-Agent: curl/7.68.0
53 > Accept: */*
54 > Authorization: Bearer eyJh...s5aM
55 >
56 < HTTP/1.1 200 OK
57 < Content-Length: 3188
58 < Content-Type: application/json;charset=UTF-8
59 < Date: Wed, 14 Aug 2024 08:05:01 GMT
60 < Server: OWL/1.11
61 < Vary: Accept-Encoding
62 <
63 {
64 "algorithms": [ "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512" ],
65 "api_version": "1.02",
66 "authdb": {
67 "ds": "mysql://localhost/authdb?mysql_auto_reconnect=1&mysql_enable_utf8=1",
68 "error": "",
69 "schver": "1.01",
70 "status": true
71 },
72 "base_url": "https://localhost:8695",
73 "code": "E0000",
74 "csrf": "...",
75 "datetime": "2024-08-14T08:05:01Z",
76 "elapsed": 0.000289,
77 "entities": {
78 "Default": [ "Allow", "Deny" ],
79 "Env": [
80 "LANG", "LOGNAME", "MOJO_MODE", "USER", "USERNAME",
81 "USR1", "USR2", "USR3"
82 ],
83 "Header": [
84 "Accept", "Host", "User-Agent", "X-Token", "X-Auth",
85 "X-Usr1", "X-Usr2", "X-Usr3" ],
86 "Host": [ "Host", "IP" ],
87 "User/Group": [ "User", "Group", "Valid-User" ]
88 },
89 "files": {
90 "datadir": "/tmp/data",
91 "documentroot": "/tmp/public",
92 "home": "/tmp/www",
93 "homedir": "/tmp/www",
94 "logfile": null,
95 "render_paths": [
96 "/tmp/templates", "/tmp/public", "/tmp/www"
97 ],
98 "static_paths": [ "/tmp/public", "/tmp/www" ],
99 "tempdir": "/tmp"
100 },
101 "generated": 1723622701,
102 "is_authorized": true,
103 "message": "Ok",
104 "methods": [
105 "CONNECT", "OPTIONS", "HEAD", "GET", "POST", "PUT",
106 "PATCH", "DELETE", "TRACE", "ANY", "MULTI"
107 ],
108 "namespaces": [
109 "WWW::OWL::Server::Controller",
110 "WWW::OWL::Server",
111 "WWW::Suffit::Server"
112 ],
113 "operators": [
114 { "name": "eq", "operator": "==", "title": "equal to" },
115 { "name": "ne", "operator": "!=", "title": "not equal" },
116 { "name": "gt", "operator": ">", "title": "greater than" },
117 { "name": "lt", "operator": "<", "title": "less than" },
118 { "name": "ge", "operator": ">=", "title": "greater than or equal to" },
119 { "name": "le", "operator": "<=", "title": "less than or equal to" },
120 { "name": "re", "operator": "=~", "title": "regexp match" },
121 { "name": "rn", "operator": "!~", "title": "regexp not match" }
122 ],
123 "project": "XXX",
124 "providers": [ "Default", "User/Group", "Host", "Env", "Header" ],
125 "public_key": "-----BEGIN RSA PUBLIC KEY-----...",
126 "remote_addr": "127.0.0.1",
127 "requestid": "MsojYEwbL8Nx",
128 "route": "api-data",
129 "status": true,
130 "token": "eyJh...BQIM",
131 "trustedproxies": [ "127.0.0.1", "10.0.0.0/8" ],
132 "user": {
133 "attributes": "",
134 "cachekey": null,
135 "comment": "Test user for internal testing only",
136 "email": "test@owl.localhost",
137 "email_md5": "163e50783979333ebae6fd63b2d96d16",
138 "expiration": 1723708629,
139 "expires": 1723622701,
140 "flags": 31,
141 "groups": [ "user" ],
142 "id": 2,
143 "name": "Test User",
144 "public_key": "-----BEGIN RSA PUBLIC KEY-----...",
145 "role": "Test user",
146 "username": "test"
147 },
148 "version": "1.11",
149 "year": "2024"
150 }
151  
152 =head2 GET /api/check
153  
154 This method simply checks the readiness state of the Suffit API server to interaction
155  
156 B<NOTE!> The method does not require authorization
157  
158 # curl -v https://localhost:8695/api/check
159  
160 > GET /api/check HTTP/1.1
161 > Host: localhost:8695
162 > User-Agent: curl/7.68.0
163 > Accept: */*
164 >
165 < HTTP/1.1 200 OK
166 < Content-Length: 241
167 < Content-Type: application/json;charset=UTF-8
168 < Date: Wed, 14 Aug 2024 07:31:08 GMT
169 < Server: OWL/1.11
170 <
171 {
172 "api_version": "1.02",
173 "base_url": "https://localhost:8695",
174 "code": "E0000",
175 "datetime": "2024-08-14T07:31:08Z",
176 "message": "Ok",
177 "project": "OWL",
178 "remote_addr": "127.0.0.1",
179 "requestid": "l6TPHQ2TX4vl",
180 "status": true,
181 "time": 1723620668,
182 "version": "1.11"
183 }
184  
185 =head2 GET /api/status
186  
187 This method returns extended status information about the Suffit API server state
188  
189 B<NOTE!> The method does not require authorization
190  
191 # curl -v https://localhost:8695/api/status
192  
193 > GET /api/status HTTP/1.1
194 > Host: localhost:8695
195 > User-Agent: curl/7.68.0
196 > Accept: */*
197 >
198 < HTTP/1.1 200 OK
199 < Content-Length: 606
200 < Content-Type: application/json;charset=UTF-8
201 < Date: Wed, 14 Aug 2024 07:44:31 GMT
202 < Server: OWL/1.11
203 <
204 {
205 "api_version": "1.02",
206 "authdb": {
207 "ds": "",
208 "error": "",
209 "schver": "1.01",
210 "status": true
211 },
212 "base_url": "https://localhost:8695",
213 "code": "E0000",
214 "csrf": "...",
215 "datetime": "2024-08-14T07:44:31Z",
216 "elapsed": 0.00079,
217 "generated": 1723621471,
218 "is_authorized": false,
219 "message": "Ok",
220 "project": "OWL",
221 "public_key": "-----BEGIN RSA PUBLIC KEY-----...",
222 "remote_addr": "127.0.0.1",
223 "requestid": "6vJjylIPm0mY",
224 "route": "api-status",
225 "status": true,
226 "token": "",
227 "version": "1.11",
228 "year": "2024"
229 }
230  
231 =head1 ERROR CODES
232  
233 The list of public Suffit API error codes
234  
235 API | HTTP | DESCRIPTION
236 -------+-------+-------------------------------------------------
237 E1030 [---] Reserved
238 ...
239 E1059 [---] Reserved
240  
241 B<*> -- this code will be defined later on the interface side
242  
243 See also list of common Suffit API error codes in L<WWW::Suffit::API/"ERROR CODES">
244  
245 =head1 HISTORY
246  
247 See C<Changes> file
248  
249 =head1 TO DO
250  
251 See C<TODO> file
252  
253 =head1 SEE ALSO
254  
255 L<Mojolicious>, L<WWW::Suffit>, L<WWW::Suffit::Server>, L<WWW::Suffit::API>
256  
257 =head1 AUTHOR
258  
259 Serż Minus (Sergey Lepenkov) L<https://www.serzik.com> E<lt>abalama@cpan.orgE<gt>
260  
261 =head1 COPYRIGHT
262  
263 Copyright (C) 1998-2026 D&D Corporation
264  
265 =head1 LICENSE
266  
267 This program is distributed under the terms of the Artistic License Version 2.0
268  
269 See the C<LICENSE> file or L<https://opensource.org/license/artistic-2-0> for details
270  
271 =cut
272  
273 use Mojo::Base 'Mojolicious::Controller';
274  
275 use POSIX qw/ strftime /;
276  
277 use Mojo::JSON qw/ true false /;
278 use Mojo::Date;
279  
280 use WWW::Suffit::API;
281 use WWW::Suffit::Const qw/ :dicts DIGEST_ALGORITHMS /;
282  
283 sub is_connected {
284 my $self = shift; # Controller
285  
286 # Get authdb instance
287 my $authdb = $self->authdb;
288 unless ($authdb) {
289 $self->reply->json_error(500 => "E1005" => "The authorization database is not ready");
290 return;
291 }
292  
293 # Connect to AuthDB
294 $authdb->connect;
295 if ($authdb->error) {
296 $self->reply->json_error($authdb->code, $authdb->error);
297 return;
298 } elsif (!$authdb->initialized) {
299 $self->reply->json_error(500 => "E1307" => "The authorization database is not initialized");
300 return;
301 }
302  
303 # Ok
304 return 1;
305 }
306 sub api {
307 my $self = shift;
308 $self->timing->begin('suffit_api'); # stuff
309 my $now = time;
310 my $status = 1;
311 my $code = "E0000";
312 my $message = "Ok";
313 my $username = $self->stash('username'); # from Auth::is_authorized
314 my $cachekey = $self->stash('cachekey'); # from Auth::is_authorized
315 my $authdb = $self->authdb;
316  
317 # AuthDB (Database info)
318 my %authdb_info = (
319 status => $authdb->error ? false : $authdb->is_connected ? true : false,
320 error => $authdb->error // '',
321 ds => '',
322 schver => '0.00',
323 );
324 unless ($authdb->error) {
325 my %vd = $authdb->model->meta_get("schema.version");
326 $authdb_info{schver} = $vd{value} || '0.00';
327 }
328  
329 # Extended data of user
330 my $is_authorized = 0;
331 my $user = undef;
332 if ($username) {
333 $user = $authdb->user($username, $cachekey);
334 if ($authdb->error) { # Error
335 $self->log->error(sprintf("[%s] %s", $authdb->code, $authdb->error));
336 $authdb_info{error} = $authdb->error;
337 } else { # Ok
338 $is_authorized = $user->uid && ($user->username eq $username) && $self->stash('is_authorized');
339 if ($is_authorized) {
340 $authdb_info{ds} = $authdb->ds ? Mojo::URL->new($authdb->ds)->to_string : '';
341 }
342 }
343 }
344 return $self->render(json => {
345 status => $status ? true : false,
346 code => $code,
347 message => $message,
348 project => $self->app->project_name,
349 version => $self->app->project_version,
350 api_version => WWW::Suffit::API->VERSION,
351 generated => $now,
352 datetime => Mojo::Date->new($now)->to_datetime, # RFC 3339
353 requestid => $self->req->request_id,
354 remote_addr => $self->remote_ip($self->app->trustedproxies),
355 base_url => $self->base_url,
356 token => $self->token,
357 public_key => $self->app->public_key,
358 year => strftime('%Y', localtime $now),
359 route => $self->current_route // 'root',
360 elapsed => $self->timing->elapsed('suffit_api') // 0,
361 csrf => $self->csrf_token,
362 is_authorized => $is_authorized ? true : false,
363 authdb => { %authdb_info },
364  
365 # Authorized only
366 $is_authorized ? (
367 algorithms => DIGEST_ALGORITHMS,
368 methods => HTTP_METHODS,
369 providers => AUTHZ_PROVIDERS,
370 entities => AUTHZ_ENTITIES,
371 operators => AUTHZ_OPERATOTS,
372 trustedproxies => $self->app->trustedproxies,
373 namespaces => $self->app->routes->namespaces,
374  
375 # User information
376 user => {
377 id => $user->id || 0,
378 username => $username,
379 cachekey => $cachekey,
380 name => $self->stash('name'),
381 email => $self->stash('email'),
382 email_md5 => $self->stash('email_md5'),
383 role => $self->stash('role'),
384 groups => $self->stash('groups'),
385 expiration => $self->stash('expiration'), # Session TOKEN expiration time (no user data!)
386 expires => $self->stash('expires'), # Cache expiration time
387 # Extended fields
388 attributes => $user->attributes // '',
389 flags => $user->flags || 0,
390 public_key => $user->public_key // '',
391 comment => $user->comment // '',
392 },
393  
394 # Fies & Directories
395 files => {
396 home => $self->app->home->to_string,
397 homedir => $self->app->homedir,
398 datadir => $self->app->datadir,
399 documentroot=> $self->app->documentroot,
400 tempdir => $self->app->tempdir,
401 logfile => $self->app->logfile,
402 static_paths=> $self->app->static->paths,
403 render_paths=> $self->app->renderer->paths,
404 },
405 ) : (),
406 });
407 }
408 sub check {
409 my $self = shift;
410 my $now = time;
411 return $self->reply->json_ok({
412 message => "Ok",
413 project => $self->app->project_name,
414 version => $self->app->project_version,
415 api_version => WWW::Suffit::API->VERSION,
416 time => $now,
417 datetime => Mojo::Date->new($now)->to_datetime, # RFC 3339
418 requestid => $self->req->request_id,
419 remote_addr => $self->remote_ip($self->app->trustedproxies),
420 base_url => $self->base_url,
421 });
422 }
423  
424 1;
425  
426 __END__