File Coverage

blib/lib/cPanel/APIClient.pm

Criterion	Covered	Total	%
statement	46	54	85.1
branch	12	22	54.5
condition	2	6	33.3
subroutine	6	6	100.0
pod	1	1	100.0
total	67	89	75.2

package cPanel::APIClient;

use strict;
use warnings;

our $VERSION = '0.09_90';

=encoding utf-8

=head1 NAME

cPanel::APIClient - L APIs, à la TIMTOWTDI!

=head1 SYNOPSIS

Create a L object
to call cPanel APIs:

    my $cpanel = cPanel::APIClient->create(
        service => 'cpanel',
        transport => [ 'CLISync' ],
    );

    my $resp = $cpanel->call_uapi( 'Email', 'list_pops' );

    my $pops_ar = $resp->get_data();

Create a L object
to call WHM APIs:

    my $whm = cPanel::APIClient->create(
        service => 'whm',
        transport => [ 'CLISync' ],
    );

    my $resp = $whm->call_api1( 'listaccts' );

    my $accts_ar = $resp->get_data();

=head1 DESCRIPTION

cPanel & WHM exposes a number of ways to access its APIs: different transport
mechanisms, different authentication schemes, etc. This library provides
client logic with sufficient abstractions to accommodate most supported
access mechanisms via a unified interface.

This library intends to supersede L as the preferred way
to access cPanel & WHM’s APIs from Perl. It can also serve as a model for
similar client libraries in other languages.

=head1 FEATURES

=over

=item * Fully object-oriented.

=item * Can use blocking or non-blocking I/O. Non-blocking I/O implementation
works with almost any modern Perl event loop interface.

=item * Uses minimal dependencies: no L &c.

=item * Extensively tested.

=item * Can run in pure Perl.

=back

=head1 CHARACTER ENCODING

cPanel & WHM’s API is character-set-agnostic. All text that you give to this
library should thus be encoded to binary, and all strings that you’ll receive
back will be binary.

This means that if you character-decode your inputs—as L
recommends—then you’ll need to encode your strings back to bytes before
giving them to this module.

Use of UTF-8 encoding is B recommended!

=head1 FUNCTIONS

=head2 $client = cPanel::APIClient->create( %OPTS )

A factory function that creates a “client” object that your code can
use to call the APIs.

%OPTS are:

=over

=item * C - Required. The service that exposes the API(s) to call.
This controls the class of the returned object. Recognized values are:

=over

=item * C - Function will return a L
instance.

=item * C - Function will return a L
instance.

=back

=item * C - Required. An array reference that describes the
transport mechanism to use. The first member of this array names the mechanism;
remaining arguments are key-value pairs of attributes to give to the
mechanism class’s constructor.

Currently supported mechanisms are:

=over

=item * L (C) -
Synchronous HTTP requests.

=item * L (C) -
Synchronous local requests via cPanel & WHM’s command-line API tools.

=item * L (C) -
Asynchronous HTTP requests via
L, which can use any event loop interface.
As of this writing it supports L, L, and L
out-of-the-box.

=item * L (C) -
Asynchronous HTTP requests via L (pure Perl).

=back

Which of the above to use will depend on your needs. If your application
is local to the cPanel & WHM server you might find it easiest to use
C. For HTTP C offers the best flexibility
and (probably) speed, whereas C and C can run in
pure Perl (assuming you have L).

There currently is no documentation for how to create a 3rd-party transport
mechanism (e.g., if you want to use a different HTTP library). Submissions
via pull request will be evaluated on a case-by-case basis.

=item * C - Some transports require this; others don’t.
The recognized schemes are:

=over

=item * C & C - Authenticate with an API token

=item * C & C - Authenticate with a password

=item * C, C, & C - Authenticate with a
password and two-factor authentication (2FA) token.

=item * C only - Implicit authentication, only usable for local
transports.

=back

=back

Depending on the C given, this function returns an instance of
either L or
L.

=cut

my @_REQUIRED = ( 'service', 'transport' );

sub create {

    # We don’t need the class, but we mandate arrow syntax rather
    # than static because it seems more consistent with Perl programmers’
    # expectations of what it looks like to call a function whose purpose
    # is to create an object.
    shift;

    my (%opts) = @_;

    my @missing = grep { !defined $opts{$_} } @_REQUIRED;
    die "Missing: @missing" if @missing;

    my $creds = delete $opts{'credentials'};

    my ( $svc, $transport ) = delete @opts{@_REQUIRED};

    if ( my @extra = sort keys %opts ) {
        die "Extra: @extra";
    }

    my $full_ns = "cPanel::APIClient::Service::$svc";
    _require($full_ns);

    my $authn = $creds && _parse_creds($creds);

    $transport = _parse_transport( $transport, $authn, $svc );

    return $full_ns->new( $transport, $authn );
}

sub _parse_transport {
    my ( $transport, $authn, $service_name ) = @_;

    if ( 'ARRAY' ne ref $transport ) {
        die "“transport” should be an ARRAY reference, not $transport!";
    }

    my ( $module, @args ) = (
        @$transport,
        service_name => $service_name,
    );

    $module = "cPanel::APIClient::Transport::$module";
    _require($module);

    if ( $module->NEEDS_CREDENTIALS() && !$authn ) {
        die "Transporter “$transport” requires credentials!";
    }

    return $module->new( $authn, @args );
}

sub _require {
    my ($full_ns) = @_;

    die if !eval "require $full_ns; 1";
}

sub _parse_creds {
    my ($creds_hr) = @_;

    my %creds_copy = %$creds_hr;

    my $username = delete $creds_copy{'username'};

    if ( !defined $username ) {
        die "Credentials need “username”!";
    }

    my ( @extras, $class );

    if ( exists $creds_copy{'api_token'} ) {
        @extras = ('api_token');
        $class  = 'cPanel::APIClient::Authn::Token';
    }
    elsif ( exists $creds_copy{'password'} ) {
        @extras = ('password');

        if ( exists $creds_copy{'tfa_token'} ) {
            push @extras, 'tfa_token';
            $class = 'cPanel::APIClient::Authn::Password2FA';
        }
        else {
            $class = 'cPanel::APIClient::Authn::Password';
        }
    }
    else {
        $class = 'cPanel::APIClient::Authn::Username';
    }

    for my $key (@extras) {
        my $val = delete $creds_copy{$key};
        if ( !defined $val ) {
            die "Undefined “$key” is invalid!";
        }
    }

    die "Bad “credentials”!" if %creds_copy;

    _require($class);

    return $class->new( $username, @{$creds_hr}{@extras} );
}

=head1 LICENSE

Copyright 2020 cPanel, L. L. C. All rights reserved. L

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

=cut

1;