NAME

WWW::Suffit::AuthDB - Suffit Authorization Database

SYNOPSIS

use WWW::Suffit::AuthDB;

my $authdb = WWW::Suffit::AuthDB->new(
    ds => "sqlite:///tmp/auth.db?sqlite_unicode=1"
);

DESCRIPTION

Suffit Authorization Database

ATTRIBUTES

This class implements the following attributes

cached

cached => 1
cached => 'yes'
cached => 'on'
cached => 'enable'

This attribute performs enabling caching while establishing of connection with database

$authdb = $authdb->cached("On");
my $cached = $authdb->cached;

Default: false (no caching connection)

initialized

initialized => 1
initialized => 'yes'
initialized => 'on'
initialized => 'enable'

This attribute marks the schema as initialized or performs read this status

code

code => undef

Read only attribute to get the HTTP code

my $code = $authdb->code; # 200

data

data => undef

Read only attribute to get the current data pool

my $data = $authdb->data;

ds, dsuri

ds => "sqlite:///tmp/auth.db?sqlite_unicode=1"

Data source URI. See WWW::Suffit::AuthDB::Model

$authdb = $authdb->ds("sqlite:///tmp/auth.db?sqlite_unicode=1");
my $ds = $authdb->ds;

Default: 'sponge://'

error

error => undef

Read only attribute to get the error message

my $error = $authdb->error;

expiration

expiration => 300

The expiration time

$authdb = $authdb->expiration(60*5);
my $expiration = $authdb->expiration;

NOTE! This attribute MUST be defined before first calling the cache method

Default: 300 (5 min)

max_keys

max_keys => 1024

The maximum keys number in cache

$authdb = $authdb->max_keys(1024*10);
my $max_keys = $authdb->max_keys;

NOTE! This attribute MUST be defined before first calling the cache method

Default: 1024*1024 (1`048`576 keys max)

sourcefile

sourcefile => '/tmp/authdb.json'

Path to the source file in JSON format

$authdb = $authdb->sourcefile("/tmp/authdb.json");
my $sourcefile = $authdb->sourcefile;

Default: none

METHODS

This class inherits all methods from Mojo::Base and implements the following new ones

new

my $authdb = WWW::Suffit::AuthDB->new(
        ds => "sqlite:///tmp/auth.db?sqlite_unicode=1",
        sourcefile => "/tmp/authdb.json"
    );
die $authdb->error if $authdb->error;

Create new AuthDB object

cache

my $cache = $authdb->cache;

Get cache instance

cached_group

my $group = $authdb->cached_group("manager");
my $group = $authdb->cached_group("manager", 'd1b919c1');

This method returns cached data of specified groupname as WWW::Suffit::AuthDB::Group object by cachekey

cached_realm

my $realm = $authdb->cached_realm("default");
my $realm = $authdb->cached_realm("default", 'd1b919c1');

This method returns cached data of specified realm name as WWW::Suffit::AuthDB::Realm object by cachekey s

cached_routes

my $routes = $authdb->cached_routes("http://localhost/");
my $routes = $authdb->cached_routes("http://localhost/", 'd1b919c1');

Returns cached hash of routes by base URL and cachekey optionaly

cached_user

my $user = $authdb->cached_user("alice");
my $user = $authdb->cached_user("alice", 'd1b919c1');

This method returns cached data of specified username as WWW::Suffit::AuthDB::User object by cachekey

checksum

my $digest = $authdb->checksum("string", "algorithm");

This method generates checksum for string. Supported algorithms: MD5 (unsafe), SHA1 (unsafe), SHA224, SHA256, SHA384, SHA512 Default algorithm: SHA256

clean

$authdb->clean;

Cleans state vars on the AuthDB object and returns it

connect

$authdb->connect;
$authdb->connect('yes'); # cached connection

This method performs regular or cached connection with database. See also "cached" attribute

dump

print $authdb->dump;

Returns JSON dump of loaded authentication database

group

my $group = $authdb->group("manager");

This method returns data of specified groupname as WWW::Suffit::AuthDB::Group object

is_connected

$authdb->connect unless $authdb->is_connected

This method checks connection status

load

$authdb->load("/tmp/authdb.json");
die $authdb->error if $authdb->error;

$authdb->load(); # from `sourcefile`
die $authdb->error if $authdb->error;

This method performs loading file to data pool

model

my $model = $authdb->model;

Get model WWW::Suffit::AuthDB::Model instance

raise

return $authdb->raise("Error string");
return $authdb->raise("Error %s", "string");
return $authdb->raise(200 => "Error string");
return $authdb->raise(200 => "Error %s", "string");

Sets error string and returns false status (undef). Also this method can performs sets the HTTP status code

realm

my $realm = $authdb->realm("default");

This method returns data of specified realm name as WWW::Suffit::AuthDB::Realm object

save

$authdb->save(); # to `sourcefile`
die $authdb->error if $authdb->error;

Performs flush database to file that was specified in constructor

$authdb->save("/tmp/new-authdb.json");
die $authdb->error if $authdb->error;

Performs flush database to file that specified directly

user

my $user = $authdb->user("alice");

This method returns data of specified username as WWW::Suffit::AuthDB::User object

META KEYS

Meta keys define the AuthDB setting parameters

schema.version

Version of the current schema

ERROR CODES

List of AuthDB Suffit API error codes

 API   | HTTP  | DESCRIPTION
-------+-------+-------------------------------------------------
 E1300   [500]   Can't load file. File not found
 E1301   [500]   Can't load data pool from file
 E1302   [500]   File did not return a JSON object
 E1303   [500]   Can't serialize data pool to JSON
 E1304   [500]   Can't save data pool to file
 E1305   [500]   Can't connect to database (model)
 E1306   [500]   Connection failed
 E1307   [500]   The authorization database is not initialized
 E1308   [---]   Reserved
 E1309   [---]   Reserved
 E1310   [ * ]   User not found
 E1311   [ * ]   Incorrect username stored
 E1312   [ * ]   Incorrect password stored
 E1313   [ * ]   The user data is expired
 E1314   [ * ]   Group not found
 E1315   [ * ]   Incorrect groupname stored
 E1316   [ * ]   The group data is expired
 E1317   [403]   External requests is blocked
 E1318   [403]   Internal requests is blocked
 E1319   [403]   Access denied
 E1320   [400]   No username specified
 E1321   [413]   The username is too long (1-256 chars required)
 E1322   [400]   No password specified
 E1323   [413]   The password is too long (1-256 chars required)
 E1324   [403]   Account frozen for 5 min
 E1325   [501]   Incorrect digest algorithm
 E1326   [401]   Incorrect username or password
 E1327   [403]   User is disabled
 E1328   [---]   Reserved
 E1329   [500]   Database request error (meta_get)
 E1330   [400]   No key specified
 E1331   [500]   Database request error (meta_set)
 E1332   [400]   Incorrect digest algorithm
 E1333   [500]   Database request error (user_get)
 E1334   [400]   User already exists
 E1335   [500]   Database request error (user_add)
 E1336   [400]   User not found
 E1337   [500]   Database request error (user_edit)
 E1338   [500]   Database request error (user_getall)
 E1339   [500]   Database request error (meta_del)
 E1340   [500]   Database request error (user_del)
 E1341   [500]   Database request error (grpusr_del)
 E1342   [500]   Database request error (user_search)
 E1343   [500]   Database request error (user_groups)
 E1344   [400]   No password specified
 E1345   [500]   Database request error (user_passwd)
 E1346   [500]   Database request error (user_setkeys)
 E1347   [500]   Database request error (user_tokens)
 E1348   [500]   Database request error (group_get)
 E1349   [400]   Group already exists
 E1350   [500]   Database request error (group_add)
 E1351   [500]   Database request error (user_set)
 E1352   [500]   Database request error (grpusr_add)
 E1353   [500]   Database request error (group_set)
 E1354   [---]   Reserved
 E1355   [500]   Database request error (group_getall)
 E1356   [500]   Database request error (group_del)
 E1357   [500]   Database request error (grpusr_get)
 E1358   [500]   Database request error (group_members)
 E1359   [500]   Database request error (realm_get)
 E1360   [400]   Realm already exists
 E1361   [500]   Database request error (realm_add)
 E1362   [500]   Database request error (route_release)
 E1363   [500]   Database request error (route_assign)
 E1364   [500]   Database request error (realm_requirement_del)
 E1365   [500]   Database request error (realm_requirement_add)
 E1366   [500]   Database request error (realm_set)
 E1367   [500]   Database request error (realm_getall)
 E1368   [500]   Database request error (realm_del)
 E1369   [500]   Database request error (token_add)
 E1370   [500]   Database request error (route_add)
 E1371   [500]   Database request error (realm_requirements)
 E1372   [500]   Database request error (realm_routes)
 E1373   [500]   Database request error (route_get)
 E1374   [400]   Route already exists
 E1375   [500]   Database request error (route_set)
 E1376   [500]   Database request error (route_getall)
 E1377   [500]   Database request error (route_del)
 E1378   [500]   Database request error (route_search)
 E1379   [500]   Database request error (token_del)
 E1380   [500]   Database request error (token_get)
 E1381   [500]   Database request error (token_get_cond)
 E1382   [500]   Database request error (token_set)
 E1383   [500]   Database request error (token_getall)
 E1384   [500]   Database request error (stat_get)
 E1385   [500]   Database request error (stat_set)

* -- this code will be defined later on the interface side

See also list of common Suffit API error codes in "ERROR CODES" in WWW::Suffit::API

EXAMPLE

Example of default authdb.json

See src/authdb.json

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

WWW::Suffit, Mojolicious

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2025 D&D Corporation. All Rights Reserved

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See LICENSE file and https://dev.perl.org/licenses/