package JWebmail::Model::ReadMails::Role;

use Params::Check qw(check last_error);

use Mojo::Base -role; # load after imports


package JWebmail::Model::ReadMails::Role::Shadow {

    use overload '""' => sub { '***' };

    sub new { my $cls = shift; bless \(shift.''), $cls }

    sub show_password { ${shift()} }

}

sub Auth {
    shift;
    state $AuthCheck = {
        user      => {required => 1, defined => 1},
        password  => {required => 1, defined => 1},
        challenge => {},
    };
    my $self = @_ == 1 ? $_[0] : {@_};

    local $Params::Check::WARNINGS_FATAL = 1;
    my $res = check($AuthCheck, $self, 0)
        or die 'Auth creation failed! ' . last_error;
    $res->{password} = JWebmail::Model::ReadMails::Role::Shadow->new($res->{password});
    return $res;
}

my @methods = (
    # Conduct the README for specification
    # Read operations
    'count',
    'folders',
    'verify_user',
    # Write operations
    'move',
    'read_headers_for',
    'search',
    'show',
    'raw',
);

requires(@methods);

around @methods => sub {
    my $orig = shift;
    my $safe = $_[1]->{password};
    $_[1]->{password} = $safe->show_password;
    my @res;
    my $succ = eval { @res = $orig->(@_); 1 };
    $_[1]->{password} = $safe;
    die unless $succ;
    return wantarray ? @res : $res[-1];
};

around read_headers_for => sub {
    my $orig = shift;
    my $self = shift;
    my $auth = shift;
    my $args = {@_};

    state $ArgsCheck = {
        start  => {required => 1},
        end    => {required => 1},
        sort   => {default => ''},
        folder => {default => ''},
    };

    local $Params::Check::ONLY_ALLOW_DEFINED = 1;
    $orig->($self, $auth, %{ check($ArgsCheck, $args, 0) or die last_error  })
};


1

__END__

=encoding utf-8

=head1 NAME

ReadMails::Role - Interface to a repository of mails

=head1 SYNOPSIS

    my $m = Some::Implementation->with_role('JWebmail::Model::ReadMails::Role');
    $m->search($auth, qr/Hot singles in your area/, '');

=head1 DESCRIPTION

The communication is assumed to be stateless.

=head1 INTERFACE

=head2 verify_user

Checks user name and password.

=head2 read_headers_for

Provides bundeled information on a subset of mails of a mailbox.
Can be sorted and of varying size.

Arguments:
    start..end   half open 0 based range

=head2 count

Returns size of the mail box folder in bytes the number of mails.

=head2 show

Returns a sepecific mail as a perl hash.

=head2 search

Searches for a message with the given pattern.

=head2 folders

List all mailbox sub folders.

=head2 move

Move mails between folders.

=head2 Auth

A sub that returns a hashref of bundled authentication data.

=head3 Attributes

=head4 user

The user name.

=head4 password

The users password in plaintext or as hmac if cram is used.

=head4 challenge

Optinal challange for when you use cram authentication.

=head1 SEE ALSO

L<JWebmail::Model::ReadMails::QMailAuthuser>, L<JWebmail::Model::ReadMails::Mock>, L<JWebmail>