File Coverage

blib/lib/WebService/GoogleAPI/Client.pm

Criterion	Covered	Total	%
statement	106	149	71.1
branch	46	86	53.4
condition	5	11	45.4
subroutine	16	21	76.1
pod	2	6	33.3
total	175	273	64.1

use strictures;
use 5.14.0;

package WebService::GoogleAPI::Client;

our $VERSION = '0.27';    # VERSION

use Data::Dump qw/pp/;
use Moo;
use WebService::GoogleAPI::Client::UserAgent;
use WebService::GoogleAPI::Client::Discovery;
use WebService::GoogleAPI::Client::AuthStorage::GapiJSON;
use WebService::GoogleAPI::Client::AuthStorage::ServiceAccount;
use Carp;
use CHI;
use Mojo::Util;

#TODO- batch requests. The only thing necessary is to send  a
#multipart request as I wrote in that e-mail.
#
#TODO- allow using promises instead of just calling. Also allow
#      for full access to the tx instead of assuming it's always
#      returning the res. Perhaps mix in something that delegates the
#      json method to the res?

# ABSTRACT: Google API Discovery and SDK

#   FROM MCE POD --


has 'debug' => (is => 'rw', default => 0, lazy => 1);
has 'ua' => (
  handles => [qw/do_autorefresh auth_storage get_access_token scopes user/],
  is      => 'ro',
  default => sub { WebService::GoogleAPI::Client::UserAgent->new(debug => shift->debug) },
  lazy    => 1,
);

sub get_scopes_as_array {
  carp 'get_scopes_as_array has deprecated in favor of the shorter "scopes"';
  return $_[0]->scopes;
}

has 'chi' => (
  is      => 'rw',
  default => sub {
    CHI->new(driver => 'File', max_key_length => 512, namespace => __PACKAGE__);
  },
  lazy => 1
);

has 'discovery' => (
  handles => [
    qw/  discover_all
        get_method_details
        get_api_document service_exists
        methods_available_for_google_api_id list_api_ids  /
  ],
  is      => 'ro',
  default => sub {
    my $self = shift;
    return WebService::GoogleAPI::Client::Discovery->new(
      debug => $self->debug,
      ua    => $self->ua,
      chi   => $self->chi
    );
  },
  lazy => 1,
);

## provides a way of augmenting constructor (new) without overloading it
##  see https://metacpan.org/pod/distribution/Moose/lib/Moose/Manual/Construction.pod if like me you an new to Moose


#NOTE- in terms of implementing google's ADC
# (see https://cloud.google.com/docs/authentication/production and also
#  https://github.com/googleapis/python-cloud-core/blob/master/google/cloud/client.py)
# I looked into it and based on that, it seems that every environment has different reqs,
#  so it's a maintenance liability
sub BUILD {
  my ($self, $params) = @_;

  my ($storage, $file);
  if ($params->{auth_storage}) {
    $storage = $params->{auth_storage};
  } elsif ($file = $params->{gapi_json}) {
    $storage = WebService::GoogleAPI::Client::AuthStorage::GapiJSON->new(path => $file);
  } elsif ($file = $params->{service_account}) {
    $storage = WebService::GoogleAPI::Client::AuthStorage::ServiceAccount->new(
      path   => $file,
      scopes => $params->{scopes}
    );
  } elsif ($file = $ENV{GOOGLE_APPLICATION_CREDENTIALS}) {
    $storage = WebService::GoogleAPI::Client::AuthStorage::ServiceAccount->new(
      path   => $file,
      scopes => $params->{scopes}
    );
  }
  $self->auth_storage($storage) if $storage;

  $self->user($params->{user}) if (defined $params->{user});
}


## ASSUMPTIONS:
##   - no complex parameter checking ( eg required mediaUpload in endpoint gmail.users.messages.send ) so user assumes responsiiblity
## TODO: Exceeding a rate limit will cause an HTTP 403 or HTTP 429 Too Many Requests response and your app should respond by retrying with exponential backoff. (https://developers.google.com/gmail/api/v1/reference/quota)
##  follows the method spec reqeust reference to the api spec schema api_discovery_struct->{schemas}{Message};
##  THE METHOD SPEC CONTAINS
##          'request' => {
##                       '$ref' => 'Message'
##                     },
##  THE SCHEMA api_discovery_struct->{schemas}{Message} CONTAINS
##    'id' => 'Message',
##    'properties' => {
##       'raw' => {
##           {annotations}{required}[ 'gmail.users.drafts.create','gmail.users.drafts.update','gmail.users.messages.insert','gmail.users.messages.send' ]

## NB - uses the ua api_query to execute the server request
##################################################
sub api_query {
  my ($self, @params_array) = @_;

  ## TODO - find a more elgant idiom to do this - pulled this off top of head for quick imeplementation
  my $params = {};
  if (scalar(@params_array) == 1 && ref($params_array[0]) eq 'HASH') {
    $params = $params_array[0];
  } else {
    $params = {@params_array};    ## what happens if not even count
  }
  carp(pp $params) if $self->debug > 10;

  croak "Missing neccessary scopes to access $params->{api_endpoint_id}"
      unless $self->has_scope_to_access_api_endpoint($params->{api_endpoint_id});

  ## used to collect pre-query validation errors - if set we return a response
  #  with 418 I'm a teapot
  my @teapot_errors = ();
  ## pre-query validation if api_id parameter is included
  @teapot_errors = $self->_process_params($params)
      if (defined $params->{api_endpoint_id});

  ## either as param or from discovery
  if (not defined $params->{path}) {
    push @teapot_errors, 'path is a required parameter';
    $params->{path} = '';
  }
  push @teapot_errors, "Path '$params->{path}' includes unfilled variable after processing"
      if ($params->{path} =~ /\{.+\}/xms);
  ## carp and include in 418 TEAPOT ERROR - response body with @teapot errors
  if (@teapot_errors > 0) {
    carp(join("\n", @teapot_errors)) if $self->debug;
    return Mojo::Message::Response->new(
      content_type => 'text/plain',
      code         => 418,
      message      => 'Teapot Error - Reqeust blocked before submitting to server with pre-query validation errors',
      body         => join("\n", @teapot_errors)
    );
  } else {
    ## query looks good - send to user agent to execute
    return $self->ua->validated_api_query($params);
  }
}
##################################################

##################################################
## _ensure_api_spec_has_defined_fields is really only used to allow carping without undef warnings if needed
sub _ensure_api_spec_has_defined_fields {
  my ($self, $api_discovery_struct) = @_;
  ## Ensure API Discovery has expected fields defined
  foreach my $expected_key (
    qw/path title ownerName version id discoveryVersion
    revision description documentationLink rest/
  ) {
    $api_discovery_struct->{$expected_key} = ''
        unless defined $api_discovery_struct->{$expected_key};
  }
  $api_discovery_struct->{canonicalName} = $api_discovery_struct->{title}
      unless defined $api_discovery_struct->{canonicalName};
  return $api_discovery_struct;
}
##################################################

##################################################
sub _process_params_for_api_endpoint_and_return_errors {
  warn '_process_params_for_api_endpoint_and_return_errors has been deprecated. Please use _process_params';
  _process_params(@_);
}

sub _process_params {
  ## nb - api_endpoint is a param - param key values are modified through this sub
  my ($self, $params) = @_;

  croak('this should never happen - this method is internal only!')
      unless defined $params->{api_endpoint_id};

  ## $api_discovery_struct requried for service base URL
  my $api_discovery_struct
      = $self->_ensure_api_spec_has_defined_fields($self->discovery->get_api_document($params->{api_endpoint_id}));
  ## remove trailing '/' from baseUrl
  $api_discovery_struct->{baseUrl} =~ s/\/$//sxmg;

  ## if can get discovery data for google api endpoint then continue to perform
  #  detailed checks
  my $method_discovery_struct = $self->get_method_details($params->{api_endpoint_id});

  #save away original path so we can know if it's fiddled with
  #later
  $method_discovery_struct->{origPath} = $method_discovery_struct->{path};

  ## allow optional user callback pre-processing of method_discovery_struct
  $method_discovery_struct = &{ $params->{cb_method_discovery_modify} }($method_discovery_struct)
      if (defined $params->{cb_method_discovery_modify}
        && ref($params->{cb_method_discovery_modify}) eq 'CODE');

  my @teapot_errors = ();    ## errors are pushed into this as encountered
  $params->{method} = $method_discovery_struct->{httpMethod} || 'GET'
      if (not defined $params->{method});
  push(@teapot_errors,
    "method mismatch - you requested a $params->{method} which conflicts with discovery spec requirement for $method_discovery_struct->{httpMethod}"
  ) if ($params->{method} !~ /^$method_discovery_struct->{httpMethod}$/sxim);

  ## Set default path iff not set by user - NB - will prepend baseUrl later
  $params->{path} = $method_discovery_struct->{path} unless $params->{path};
  push @teapot_errors, 'path is a required parameter' unless $params->{path};

  push @teapot_errors,
      $self->_interpolate_path_parameters_append_query_params_and_return_errors($params, $method_discovery_struct);

  $params->{path} =~ s/^\///sxmg;                                            ## remove leading '/'  from path
  $params->{path} = "$api_discovery_struct->{baseUrl}/$params->{path}"
      unless $params->{path} =~ /^$api_discovery_struct->{baseUrl}/ixsmg;    ## prepend baseUrl if required

  ## if errors - add detail available in the discovery struct for the method and service to aid debugging
  push @teapot_errors,
      qq{ $api_discovery_struct->{title} $api_discovery_struct->{rest} API into $api_discovery_struct->{ownerName} $api_discovery_struct->{canonicalName} $api_discovery_struct->{version} with id $method_discovery_struct->{id} as described by discovery document version $api_discovery_struct->{discoveryVersion} revision $api_discovery_struct->{revision} with documentation at $api_discovery_struct->{documentationLink} \nDescription: $method_discovery_struct->{description}\n}
      if @teapot_errors;

  return @teapot_errors;
}
##################################################

#small subs to convert between these_types to theseTypes of params
#TODO- should probs move this into a Util module
sub camel { shift if @_ > 1; $_[0] =~ s/ _(\w) /\u$1/grx }
sub snake { shift if @_ > 1; $_[0] =~ s/([[:upper:]])/_\l$1/grx }

##################################################
sub _interpolate_path_parameters_append_query_params_and_return_errors {
  my ($self, $params, $discovery_struct) = @_;
  my @teapot_errors = ();

  my @get_query_params = ();

  #create a hash of whatever the expected params may be
  my %path_params;
  my $param_regex = qr/\{ \+? ([^\}]+) \}/x;
  if ($params->{path} ne $discovery_struct->{origPath}) {

    #check if the path was given as a custom path. If it is, just
    #interpolate things directly, and assume the user is responsible
    %path_params = map { $_ => 'custom' } ($params->{path} =~ /$param_regex/xg);
  } else {

    #label which param names are from the normal path and from the
    #flat path
    %path_params = map { $_ => 'plain' } ($discovery_struct->{path} =~ /$param_regex/xg);
    if ($discovery_struct->{flatPath}) {
      %path_params = (%path_params, map { $_ => 'flat' } ($discovery_struct->{flatPath} =~ /$param_regex/xg));
    }
  }


  #switch the path we're dealing with to the flat path if any of
  #the parameters match the flat path
  $params->{path} = $discovery_struct->{flatPath}
      if grep { $_ eq 'flat' }
      map { $path_params{ camel $_} || () } keys %{ $params->{options} };


  #loop through params given, placing them in the path or query,
  #or leaving them for the request body
  for my $param_name (keys %{ $params->{options} }) {

    #first check if it needs to be interpolated into the path
    if ($path_params{$param_name} || $path_params{ camel $param_name}) {

      #pull out the value from the hash, and remove the key
      my $param_value = delete $params->{options}{$param_name};

      #Camelize the param name if not passed in customly, allowing
      #the user to pass in camelCase or snake_case param names.
      #This implictly allows for a non camelCased param to be left
      #alone in a custom param.
      $param_name = camel $param_name if $path_params{ camel $param_name};

      #first deal with any param that doesn't have a plus, b/c
      #those just get interpolated
      $params->{path} =~ s/\{$param_name\}/$param_value/;

      #if there's a plus in the path spec, we need more work
      if ($params->{path} =~ /\{ \+ $param_name \}/x) {
        my $pattern = $discovery_struct->{parameters}{$param_name}{pattern};

        #if the given param matches google's pattern for the
        #param, just interpolate it straight
        if ($param_value =~ /$pattern/) {
          $params->{path} =~ s/\{\+$param_name\}/$param_value/;
        } else {

          #N.B. perhaps support passing an arrayref or csv for those
          #params such as jobs.projects.jobs.delete which have two
          #dynamic parts. But for now, unnecessary

          #remove the regexy parts of the pattern to interpolate it
          #into the path, assuming the user has provided just the
          #dynamic portion of the param.
          $pattern =~ s/^\^ | \$$//gx;
          my $placeholder = qr/ \[ \^ \/ \] \+ /x;
          $params->{path} =~ s/\{\+$param_name\}/$pattern/x;
          $params->{path} =~ s/$placeholder/$param_value/x;
          push @teapot_errors, "Not enough parameters given for {+$param_name}."
              if $params->{path} =~ /$placeholder/;
        }
      }

      #skip to the next run, so I don't need an else clause later
      next;    #I don't like nested if-elses
    }

    #if it's not in the list of params, then it goes in the
    #request body, and our work here is done
    next unless $discovery_struct->{parameters}{$param_name};

    #it must be a GET type query param, so push the name and value
    #on our param stack and take it off of the options list
    push @get_query_params, $param_name, delete $params->{options}{$param_name};
  }

  #if there are any query params...
  if (@get_query_params) {

    #interpolate and escape the get query params built up in our
    #former for loop
    $params->{path} .= ($params->{path} =~ /\?/) ? '&' : '?';
    $params->{path} .= Mojo::Parameters->new(@get_query_params);
  }

  #interpolate default value for path params if not given. Needed
  #for things like the gmail API, where userID is 'me' by default
  for my $param_name ($params->{path} =~ /$param_regex/g) {
    my $param_value = $discovery_struct->{parameters}{$param_name}{default};
    $params->{path} =~ s/\{$param_name\}/$param_value/ if $param_value;
  }
  push @teapot_errors, "Missing a parameter for {$_}." for $params->{path} =~ /$param_regex/g;

  #print pp $params;
  #exit;
  return @teapot_errors;
}
##################################################


sub has_scope_to_access_api_endpoint {
  my ($self, $api_ep) = @_;
  my $method_spec = $self->get_method_details($api_ep);

  if (keys %$method_spec) {
    my $configured_scopes = $self->scopes;    ## get user scopes arrayref
    ## create a hashindex to facilitate quick lookups
    my %configured_scopes_hash = map { (s/\/$//xr, 1) } @$configured_scopes;
    ## NB r switch as per https://www.perlmonks.org/?node_id=613280 to filter
    #out any trailing '/'
    my $granted = 0;
    ## assume permission not granted until we find a matching scope
    my $required_scope_count = 0;
    ## if the final count of scope constraints = 0 then we will assume permission is granted - this has proven necessary for the experimental Google My Business because scopes are not defined in the current discovery data as at 14/10/18
    for my $method_scope (map {s/\/$//xr} @{ $method_spec->{scopes} }) {
      $required_scope_count++;
      $granted = 1 if defined $configured_scopes_hash{$method_scope};
      last         if $granted;
    }
    $granted = 1 if $required_scope_count == 0;
    return $granted;
  } else {
    return 0;
  }

}


#TODO: Consider rename to return_fetched_google_v1_apis_discovery_structure
#
#TODO - handle auth required error and resubmit request with OAUTH headers if response indicates
#       access requires auth ( when exceed free access limits )


1;

__END__