Users.pod6

use v6;

=begin pod

=TITLE class MongoDB::Users

=SUBTITLE Administration of accounts used for authentication.

  package MongoDB { class Users { ... } }

=head1 Synopsis

  # Initialize
  #
  my MongoDB::Connection client .= new(:uri<mongodb://>);
  my MongoDB::Database $database = $client.database('test1');
  my MongoDB::Users $users .= new(:$database);

  my BSON::Document $doc = $users.create-user(
    'John', 'simple',
    :custom-data((license => 'to_kill'),),
    :roles(['readWrite'])
  );

  $users.set-pw-security(
    :min-un-length(5),
    :min-pw-length(8),
    :pw_attribs($MongoDB::PW-OTHER-CHARS)
  );

  my BSON::Document $doc = $users.create-user(
    :'Long-John', 'N0t-s0-S!mPl3',
    :custom-data((license => 'to_kill'),),
    :roles([${role => 'readWrite', db => 'test3'},])
  );

  $doc = $users.update-user(
    'John',
    :password('mt+++'),
    :custom-data({license => 'to_heal'}),
    :roles( [ {role => 'readWrite', db => 'test1'},
              {role => 'dbAdmin', db => 'test2'}
            ]
          )
  );


=head1 Readonly attributes

=head2 database

  has MongoDB::Database $.database;

Database on which a user can be administrated if not global.


=head2 min-un-length

  has Int $.min-un-length = 2;

Minimum username length.


=head2 min-pw-length

  has Int $.min-pw-length = 2;

Minimum password length.


=head2 pw-attribs-code

  has Int $.pw-attribs-code = MongoDB::C-PW-LOWERCASE;

Password checking attribute. See set-pw-security() below.


=head1 Methods

=head2 set-pw-security

  method set-pw-security (
    Int :$min-un-length where $min-un-length >= 2,
    Int :$min-pw-length where $min-pw-length >= 2,
    Int :$pw-attribs = MongoDB::C-PW-LOWERCASE
  )

Method to specify checks upon usernames and passwords. Default values for
the username minimal length is 2. For passwords idem depending on the password
attribute code. $pw-attribs specifies how passwords are to be checked. There are
4 codes recognized.

=item B<MongoDB::C-PW-LOWERCASE>: All is accepted but lowercase characters must
at least be used. When $min-pw-length is not set it will be set to 2.

=item B<MongoDB::C-PW-UPPERCASE>: All is accepted but lowercase and uppercase
characters must at least be used. When $min-pw-length is not set it will be set
to 2.

=item B<MongoDB::C-PW-NUMBERS>: All is accepted but lowercase, uppercase
characters and numbers must at least be used. When $min-pw-length is not set it
will be set to 3.

=item B<MongoDB::C-PW-OTHER-CHARS>: All is accepted but lowercase, uppercase
characters, numbers and special characters like @ ! $ etcetera, must at least be
used. When $min-pw-length is not set it will be set to 4.

If e.g. C<MongoDB::C-PW-OTHER-CHARS> and C<$min-pw-length> is set to 2 then when
using a password of less the 4 characters the call is bound to fail.


=head2 create-user

  method create-user (
    Str:D $user, Str:D $password,
    :$custom-data, Array :$roles
    --> BSON::Document
  )

Method to create a user. Database roles can be specified in several ways.
It is an array with entries of strings or as a list of pairs. When it is
a string it specifies the role assigned to the user. When it is a list, the
list must have two pairs. One has C<role> key and the other has C<db>. In
this case the role is assigned to the user but only for a specific database.

Some examples of the roles option;

  :roles(['readWrite'])

  :roles([(role => 'readWrite', db => 'test1'),
          (role => 'dbAdmin', db => 'test2')
         ]
        )

  :roles([(role => 'dbAdmin', db => 'test2'),])


=head2 update-user

  method update-user (
    Str:D $user, Str :$password,
    :$custom-data, Array :$roles
    --> BSON::Document
  )

Update user accont data.


=end pod