| 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__ |