The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WWW-Suffit-Server-1.11
River stage zero No dependents
/ WWW::Suffit::Server

NAME

WWW::Suffit::Server - The Suffit API web-server class

SYNOPSIS

    use Mojo::File qw/ path /;

    my $root = path()->child('test')->to_string;
    my $app = MyApp->new(
        project_name => 'MyApp',
        project_version => '0.01',
        moniker => 'myapp',
        debugmode => 1,
        loglevel => 'debug',
        max_history_size => 25,

        # System
        uid => 1000,
        gid => 1000,

        # Dirs and files
        homedir => path($root)->child('share')->make_path->to_string,
        datadir => path($root)->child('var')->make_path->to_string,
        tempdir => path($root)->child('tmp')->make_path->to_string,
        documentroot => path($root)->child('www')->make_path->to_string,
        logfile => path($root)->child('log')->make_path->child('myapp.log')->to_string,
        pidfile => path($root)->child('run')->make_path->child('myapp.pid')->to_string,

        # Server
        server_addr => '*',
        server_port => 8080,
        server_url => 'http://127.0.0.1:8080',
        trustedproxies => ['127.0.0.1'],
        accepts => 10000,
        clients => 1000,
        requests => 100,
        workers => 4,
        spare => 2,
        reload_sig => 'USR2',
        no_daemonize => 1,

        # Security
        mysecret => 'Eph9Ce$quo.p2@oW3',
        rsa_keysize => 2048,
        private_key => undef, # Auto
        public_key => undef, # Auto

        # Initialization options
        all_features    => 'no',
        config_opts     => {
            file => path($root)->child('etc')->make_path->child('myapp.conf')->to_string,
            defaults => {foo => 'bar'},
        },
    );

    # Run preforked application
    $app->preforked_run( 'start' );

    1;

    package MyApp;

    use Mojo::Base 'WWW::Suffit::Server';

    sub init { shift->routes->any('/' => {text => 'Hello World!'}) }

    1;

DESCRIPTION

This module provides API web-server functionality

OPTIONS

    sub startup {
        my $self = shift->SUPER::startup( OPTION_NAME => VALUE, ... );

        # ...
    }

Options passed as arguments to the startup function allow you to customize the initialization of plugins at the level of your descendant class, and options are considered to have higher priority than attributes of the same name.

List of allowed options (pairs of name-value):

admin_routes_opts

    admin_routes_opts => {
        prefix_path => "/admin",
        prefix_name => "admin",
    }
prefix_name
    prefix_name => "admin"

This option defines prefix of admin api route name

Default: 'admin'

prefix_path
    prefix_path => "/admin"

This option defines prefix of admin api route

Default: '/admin'

all_features

    all_features => 'on'

This option enables all of the init_* options, which are described bellow

Default: off

api_routes_opts

    api_routes_opts => {
        prefix_path => "/api",
        prefix_name => "api",
    }
prefix_name
    prefix_name => "api"

This option defines prefix of api route name

Default: 'api'

prefix_path
    prefix_path => "/api"

This option defines prefix of api route

Default: '/api'

authdb_opts

    authdb_opts => {
        uri => "sqlite://<PATH_TO_DB_FILE>?sqlite_unicode=1",
        cachedconnection => 'on',
        cacheexpiration => 300,
        cachemaxkeys => 1024*1024,
        sourcefile => '/tmp/authdb.json',
    }
uri, url
    uri => "sqlite:///tmp/auth.db?sqlite_unicode=1",

Default: See config AuthDBURL or AuthDBURI directive

cachedconnection
    cachedconnection => 'on',

Default: See config AuthDBCachedConnection directive. Default: on

cacheexpire, cacheexpiration
    cacheexpiration => 300,

Default: See config AuthDBCacheExpire or AuthDBCacheExpiration directive. Default: 300

cachemaxkeys
    cachemaxkeys => 1024*1024,

Default: See config AuthDBCacheMaxKeys directive. Default: 1024*1024

sourcefile
    sourcefile => '/tmp/authdb.json',

Default: See config AuthDBSourceFile directive

config_opts

    config_opts => { ... }

This option sets Mojolicious::Plugin::ConfigGeneral plugin options

Default:

    `noload => 1` if $self->configobj exists
    `defaults => $self->config` if $self->config is not void

init_admin_routes

    init_admin_routes => 'on'

This option enables Admin Suffit API routes

Default: off

init_authdb

    init_authdb => 'on'

This option enables AuthDB initialize

Default: off

init_api_routes

    init_api_routes => 'on'

This option enables Suffit API routes

Default: off

init_rsa_keys

    init_rsa_keys => 'on'

This option enables RSA keys initialize

Default: off

init_user_routes

    init_user_routes => 'on'

This option enables User Suffit API routes

Default: off

syslog_opts

    syslog_opts => { ... }

This option sets WWW::Suffit::Plugin::Syslog plugin options

Default:

    `enable => 1` if the `Log` config directive is "syslog"

user_routes_opts

    user_routes_opts => {
        prefix_path => "/user",
        prefix_name => "user",
    }
prefix_name
    prefix_name => "user"

This option defines prefix of user api route name

Default: 'user'

prefix_path
    prefix_path => "/user"

This option defines prefix of user api route

Default: '/user'

ATTRIBUTES

This class implements the following attributes

accepts

    accepts => 0,

Maximum number of connections a worker is allowed to accept, before stopping gracefully and then getting replaced with a newly started worker, passed along to "max_accepts" in Mojo::IOLoop

Default: 10000

See "accepts" in Mojo::Server::Prefork

cache

The WWW::Suffit::Cache object

clients

    clients => 0,

Maximum number of accepted connections this server is allowed to handle concurrently, before stopping to accept new incoming connections, passed along to "max_connections" in Mojo::IOLoop

Default: 1000

See "max_clients" in Mojo::Server::Daemon

configobj

The Config::General object or undef

acruxconfig

The Acrux::Config object or undef

datadir

    datadir => '/var/lib/myapp',

The sharedstate data directory (data dir)

Default: /var/lib/<MONIKER>

debugmode

    debugmode => 0,

If this attribute is enabled then this server is no daemonize performs

documentroot

    documentroot => '/var/www/myapp',

Document root directory

Default: /var/www/<MONIKER>

gid

    gid => 1000,
    gid => getgrnam( 'anonymous' ),

This attribute pass GID to set the real group identifier and the effective group identifier for this process

homedir

    homedir => '/usr/share/myapp',

The Project home directory

Default: /usr/share/<MONIKER>

logfile

    logfile => '/var/log/myapp.log',

The log file

Default: /var/log/<MONIKER>.log

loglevel

    loglevel => 'warn',

This attribute performs set the log level

Default: warn

max_history_size

    max_history_size => 25,

Maximum number of logged messages to store in "history"

Default: 25

moniker

    moniker => 'myapp',

Project name in lowercase notation, project nickname, moniker. This value often used as default filename for configuration files and the like

Default: decamelizing the application class

See "moniker" in Mojolicious

mysecret

    mysecret => 'dgdfg',

Default secret string

Default: <DEFAULT_SECRET>

no_daemonize

    no_daemonize => 1,

This attribute disables the daemonize process

Default: 0

pidfile

    pidfile => '/var/run/myapp.pid',

The pid file

Default: /tmp/prefork.pid

See "pid_file" in Mojo::Server::Prefork

project_name

    project_name => 'MyApp',

The project name. For example: MyApp

Default: current class name

private_key

    private_key => '...'

Private RSA key

project_version

    project_version => '0.01'

The project version. For example: 1.00

NOTE! This is required attribute!

public_key

    public_key => '...',

Public RSA key

requests

    requests => 0,

Maximum number of keep-alive requests per connection

Default: 100

See "max_requests" in Mojo::Server::Daemon

reload_sig

    reload_sig => 'USR2',
    reload_sig => 'HUP',

The signal name that will be used to receive reload commands from the system

Default: USR2

rsa_keysize

    rsa_keysize => 2048

RSA key size

See RSA_KeySize configuration directive

Default: 2048

server_addr

    server_addr => '*',

Main listener address (host)

Default: * (::0, 0:0:0:0)

server_port

    server_port => 8080,

Main listener port

Default: 8080

server_url

    server_url => 'http://127.0.0.1:8080',

Main real listener URL

See ListenAddr and ListenPort configuration directives

Default: http://127.0.0.1:8080

spare

    spare => 0,

Temporarily spawn up to this number of additional workers if there is a need.

Default: 2

See "spare" in Mojo::Server::Prefork

tempdir

    tempdir => '/tmp/myapp',

The temp directory

Default: /tmp/<MONIKER>

trustedproxies

List of trusted proxies

Default: none

uid

    uid => 1000,
    uid => getpwnam( 'anonymous' ),

This attribute pass UID to set the real user identifier and the effective user identifier for this process

workers

    workers => 0,

Number of worker processes

Default: 4

See "workers" in Mojo::Server::Prefork

METHODS

This class inherits all methods from Mojolicious and implements the following new ones

init

    $app->init;

This is your main hook into the Suffit application, it will be called at application startup immediately after calling the Mojolicious startup hook. Meant to be overloaded in a your subclass

listeners

This method returns server listeners as list of URLs

    $prefork->listen( $app->listeners );

preforked_run

    $app->preforked_run( COMMAND );
    $app->preforked_run( COMMAND, ...OPTIONS... );
    $app->preforked_run( COMMAND, { ...OPTIONS... } );
    $app->preforked_run( 'start' );
    $app->preforked_run( 'start', prerun => sub { ... } );
    $app->preforked_run( 'stop' );
    $app->preforked_run( 'restart', prerun => sub { ... } );
    $app->preforked_run( 'status' );
    $app->preforked_run( 'reload' );

This method runs your application using a command that is passed as the first argument

Options:

prerun
    prerun => sub {
        my ($app, $prefork) = @_;

        $prefork->on(finish => sub { # Finish
            my $this = shift; # Prefork object
            my $graceful = shift;
            $this->app->log->debug($graceful
                ? 'Graceful server shutdown'
                : 'Server shutdown'
            );
        });
    }

This option defines callback function that performs operations with prefork instance Mojo::Server::Prefork befor demonize and server running

raise

    $app->raise("Mask %s", "val");
    $app->raise("val");

Prints error message to STDERR and exit with errorlevel = 1

NOTE! For internal use only

reload

The reload hook

startup

Main "startup" in Mojolicious hook

HELPERS

This class implements the following helpers

authdb

This is access method to the AuthDB object (state object)

clientid

    my $clientid = $app->clientid;

This helper returns client ID that calculates from User-Agent and Remote-Address headers:

    md5(User-Agent . Remote-Address)

gen_cachekey

    my $cachekey = $app->gen_cachekey;
    my $cachekey = $app->gen_cachekey(16);

This helper helps generate the new CacheKey for caching user data that was got from authorization database

gen_rsakeys

    my %keysdata = $app->gen_rsakeys;
    my %keysdata = $app->gen_rsakeys( 2048 );

This helper generates RSA keys pair and returns structure as hash:

    private_key => '...',
    public_key  => '...',
    key_size    => 2048,
    error       => '...',

jwt

This helper makes JWT object with RSA keys and returns it

token

This helper performs get of current token from HTTP Request headers

CONFIGURATION

This class supports the following configuration directives

GENERAL DIRECTIVES

Log
    Log         Syslog
    Log         File

This directive defines the log provider. Supported providers: File, Syslog

Default: File

LogFile
    LogFile     /var/log/myapp.log

This directive sets the path to logfile

Default: /var/log/<MONIKER>.log

LogLevel
    LogLevel    warn

This directive defines log level.

Available log levels are trace, debug, info, warn, error and fatal, in that order.

Default: warn

SERVER DIRECTIVES

ListenURL
    ListenURL http://127.0.0.1:8008
    ListenURL http://127.0.0.1:8009
    ListenURL 'https://*:3000?cert=/x/server.crt&key=/y/server.key&ca=/z/ca.crt'

Directives that specify additional listening addresses in URL form

NOTE! This is a multiple directive

Default: none

ListenAddr
    ListenAddr  *
    ListenAddr  0.0.0.0
    ListenAddr  127.0.0.1

This directive sets the master listen address

Default: * (0.0.0.0)

ListenPort
    ListenPort  8080
    ListenPort  80
    ListenPort  443

This directive sets the master listen port

Default: 8080

Accepts
    Accepts     0

Maximum number of connections a worker is allowed to accept, before stopping gracefully and then getting replaced with a newly started worker, defaults to the value of "accepts" in Mojo::Server::Prefork. Setting the value to 0 will allow workers to accept new connections indefinitely

Default: 0

Clients
    Clients     1000

Maximum number of accepted connections each worker process is allowed to handle concurrently, before stopping to accept new incoming connections, defaults to 100. Note that high concurrency works best with applications that perform mostly non-blocking operations, to optimize for blocking operations you can decrease this value and increase "workers" instead for better performance

Default: 1000

Requests
    Requests    100

Maximum number of keep-alive requests per connection

Default: 100

Spare
    Spare       2

Temporarily spawn up to this number of additional workers if there is a need, defaults to 2. This allows for new workers to be started while old ones are still shutting down gracefully, drastically reducing the performance cost of worker restarts

Default: 2

Workers
    Workers     4

Number of worker processes, defaults to 4. A good rule of thumb is two worker processes per CPU core for applications that perform mostly non-blocking operations, blocking operations often require more and benefit from decreasing concurrency with "clients" (often as low as 1)

Default: 4

TrustedProxy
    TrustedProxy  127.0.0.1
    TrustedProxy  10.0.0.0/8
    TrustedProxy  172.16.0.0/12
    TrustedProxy  192.168.0.0/16
    TrustedProxy  fc00::/7

Trusted reverse proxies, addresses or networks in CIDR form. The real IP address takes from X-Forwarded-For header

NOTE! This is a multiple directive

Default: All reverse proxies will be passed

Reload_Sig
    Reload_Sig  USR2
    Reload_Sig  HUP

This directive sets the dafault signal name that will be used to receive reload commands from the system

Default: USR2

SSL/TLS SERVER DIRECTIVES

TLS
    TLS         enabled

This directive enables or disables the TLS (https) listening

Default: disabled

TLS_CA, TLS_Cert, TLS_Key
    TLS_CA      certs/ca.crt
    TLS_Cert    certs/server.crt
    TLS_Key     certs/server.key

Paths to TLS files. Absolute or relative paths (started from /etc/<MONIKER>)

TLS_CA - Path to TLS certificate authority file used to verify the peer certificate. TLS_Cert - Path to the TLS cert file, defaults to a built-in test certificate. TLS_Key - Path to the TLS key file, defaults to a built-in test key

Default: none

TLS_Ciphers, TLS_Verify, TLS_Version
    TLS_Version     TLSv1_2
    TLS_Ciphers     AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH
    TLS_Verify      0x00

Directives for setting TLS extra data

TLS cipher specification string. For more information about the format see https://www.openssl.org/docs/manmaster/man1/ciphers.html/CIPHER-STRINGS. TLS_Verify - TLS verification mode. TLS_Version - TLS protocol version.

Default: none

TLS_FD, TLS_Reuse, TLS_Single_Accept

TLS_FD - File descriptor with an already prepared listen socket. TLS_Reuse - Allow multiple servers to use the same port with the SO_REUSEPORT socket option. TLS_Single_Accept - Only accept one connection at a time.

SECURITY DIRECTIVES

PrivateKeyFile, PublicKeyFile
    PrivateKeyFile /var/lib/myapp/rsa-private.key
    PublicKeyFile  /var/lib/myapp/rsa-public.key

Private and Public RSA key files If not possible to read files by the specified paths, they will be created automatically

Defaults:

    PrivateKeyFile /var/lib/E<lt>MONIKERE<gt>/rsa-private.key
    PublicKeyFile  /var/lib/E<lt>MONIKERE<gt>/rsa-public.key
RSA_KeySize
    RSA_KeySize     2048

RSA Key size. This is size (length) of the RSA Key. Allowed key sizes in bits: 512, 1024, 2048, 3072, 4096

Default: 2048

Secret
    Secret      "My$ecretPhr@se!"

HMAC secret passphrase

Default: md5(rsa_private_file)

ATHORIZATION DIRECTIVES

AuthDBURL, AuthDBURI
    AuthDBURI "mysql://user:pass@mysql.example.com/authdb \
           ?mysql_auto_reconnect=1&mysql_enable_utf8=1"
    AuthDBURI "sqlite:///var/lib/myapp/auth.db?sqlite_unicode=1"

Authorization database connect string (Data Source URI) This directive written in the URI form

Default: "sqlite:///var/lib/<MONIKER>/auth.db?sqlite_unicode=1"

AuthDBCachedConnection
    AuthDBCachedConnection  1
    AuthDBCachedConnection  Yes
    AuthDBCachedConnection  On
    AuthDBCachedConnection  Enable

This directive defines status of caching while establishing of connection to database

See "cached" in WWW::Suffit::AuthDB

Default: false (no caching connection)

AuthDBCacheExpire, AuthDBCacheExpiration
    AuthDBCacheExpiration    300

The expiration time

See "expiration" in WWW::Suffit::AuthDB

Default: 300 (5 min)

AuthDBCacheMaxKeys
    AuthDBCacheMaxKeys  1024

The maximum keys number in cache

See "max_keys" in WWW::Suffit::AuthDB

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

AuthDBSourceFile
    AuthDBSourceFile /var/lib/myapp/authdb.json

Authorization database source file path. This is simple JSON file that contains three blocks: users, groups and realms.

Default: /var/lib/<MONIKER>/authdb.json

Token
    Token   ed23...3c0a

Development token directive This development directive allows authorization without getting real Authorization header from the client request

Default: none

EXAMPLE

Example of well-structured simplified web application

    # mkdir lib
    # touch lib/MyApp.pm
    # chmod 644 lib/MyApp.pm

We will start by MyApp.pm that contains main application class and controller class

    package MyApp;

    use Mojo::Base 'WWW::Suffit::Server';

    our $VERSION = '1.00';

    sub init {
        my $self = shift;
        my $r = $self->routes;
        $r->any('/' => {text => 'Your test server is working!'})->name('index');
        $r->get('/test')->to('example#test')->name('test');
    }

    1;

    package MyApp::Controller::Example;

    use Mojo::Base 'Mojolicious::Controller';

    sub test {
        my $self = shift;
        $self->render(text => 'Hello World!');
    }

    1;

The init method gets called right after instantiation and is the place where the whole your application gets set up

    # mkdir bin
    # touch bin/myapp.pl
    # chmod 644 bin/myapp.pl

myapp.pl itself can now be created as simplified application script to allow running tests.

    #!/usr/bin/perl -w
    use strict;
    use warnings;

    use Mojo::File qw/ curfile path /;

    use lib curfile->dirname->sibling('lib')->to_string;

    use Mojo::Server;

    my $root = curfile->dirname->child('test')->to_string;

    Mojo::Server->new->build_app('MyApp',
        debugmode => 1,
        loglevel => 'debug',
        homedir => path($root)->child('www')->make_path->to_string,
        datadir => path($root)->child('var')->make_path->to_string,
        tempdir => path($root)->child('tmp')->make_path->to_string,
        config_opts     => {
            noload => 1, # force disable loading config from file
            defaults => {
                foo => 'bar',
            },
        },
    )->start();

Now try to run it

    # perl bin/myapp.pl daemon -l http://*:8080

Now let's get to simplified testing

    # mkdir t
    # touch t/myapp.t
    # chmod 644 t/myapp.t

Full Mojolicious applications are easy to test, so t/myapp.t can be containts:

    use strict;
    use warnings;

    use Test::More;
    use Test::Mojo;

    use Mojo::File qw/ path /;

    use MyApp;

    my $root = path()->child('test')->to_string;

    my $t = Test::Mojo->new(MyApp->new(
        homedir => path($root)->child('www')->make_path->to_string,
        datadir => path($root)->child('var')->make_path->to_string,
        tempdir => path($root)->child('tmp')->make_path->to_string,
        config_opts     => {
            noload => 1, # force disable loading config from file
            defaults => {
                foo => 'bar',
            },
        },
    ));

    subtest 'Test workflow' => sub {

        $t->get_ok('/')
          ->status_is(200)
          ->content_like(qr/working!/, 'right content by GET /');

        $t->post_ok('/' => form => {'_' => time})
          ->status_is(200)
          ->content_like(qr/working!/, 'right content by POST /');

        $t->get_ok('/test')
          ->status_is(200)
          ->content_like(qr/World/, 'right content by GET /test');

    };

    done_testing();

Now try to test

    # prove -lv t/myapp.t

And our final directory structure should be looking like this

    MyApp
    +- bin
    |  +- myapp.pl
    +- lib
    |  +- MyApp.pm
    +- t
    |  +- myapp.t
    +- test
       +- tmp
       +- var
       +- www

Test-driven development takes a little getting used to, but can be a very powerful tool

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

Mojolicious, WWW::Suffit, WWW::Suffit::RSA, WWW::Suffit::JWT, WWW::Suffit::API, WWW::Suffit::AuthDB

AUTHOR

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

COPYRIGHT

Copyright (C) 1998-2024 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/