NAME

Mojolicious::Plugin::Google::Cloud::UserAgent - A user agent for GCP

SYNOPSIS

  # Mojolicious
  $self->plugin('Google::Cloud::UserAgent');

  # Mojolicious::Lite
  plugin 'Google::Cloud::UserAgent' => {
    gcp_auth_file => $ENV{GCP_AUTH_FILE},
    scopes        => ['https://www.googleapis.com/auth/pubsub'],
    duration      => 3600
  };

  # in a controller
  get '/' => sub {
    my $c = shift;
    $c->render_later;

    $c->gcp_ua(GET => "https://pubsub.googleapis.com/v1/projects/$ENV{GCP_PROJECT}/topics",
               sub {  ## response handler
                   my $tx = pop;
                   $c->render(json => $tx->res->json, status => $tx->res->code);
               },
               sub {  ## error sub
                   my $tx = pop;
                   $c->render(json => $tx->res->json, status => $tx->res->code);
               }
    );
  };

DESCRIPTION

Mojolicious::Plugin::Google::Cloud::UserAgent is a Mojolicious plugin for interacting with Google Cloud Platform. It performs 2-legged OAuth described here: https://cloud.google.com/docs/authentication.

First, create a service account key:

https://console.cloud.google.com/apis/credentials?project=your-project

Download this JSON file; you may hard-code the path to the JSON service account key file when you load this plugin, or set an environment variable, etc.

Next, determine the proper scopes for the user agent. Each GCP API has a section in its documentation describing the scopes required to invoke the API. For example, here is the Logging API scopes:

https://cloud.google.com/logging/docs/api/tasks/authorization

Once you have these two items, pass them to the plugin as configuration:

   plugin 'Google::Cloud::UserAgent' => {
     gcp_auth_file => $ENV{GCP_AUTH_FILE},
     scopes        => ['https://www.googleapis.com/auth/logging.write',
                       'https://www.googleapis.com/auth/logging.read'],
   };

METHODS

Mojolicious::Plugin::Google::Cloud::UserAgent inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

  $plugin->register(Mojolicious->new);

Register plugin in Mojolicious application.

gcp_ua

  $c->gcp_ua(METHOD => $gcp_url, $headers, $type => $payload, $cb, $error_cb);

Makes a non-blocking HTTP request of the given method to the given GCP url. Like Mojo::UserAgent's HTTP methods, $headers, $type, and $payload are optional. If the OAuth step succeeds, the $cb callback will be invoked, otherwise, the $error_cb will be invoked.

The success callback will be passed a delay object and a transaction object. Note that while the OAuth succeeded if this callback is invoked, the API method itself may have failed, so you would check that like this:

  $c->gcp_ua(GET => $api,
             sub {
                 my $tx = pop;
                 unless ($tx->success) {
                     $c->render(json => { error => "Had a boo-boo" },
                                status => 503);
                 }

                 ## everything is ok
                 ...
            },
            sub { }  ## error cb
            );

The second (error) callback is invoked if the OAuth attempt fails. It will be passed a controller object and a transaction object.

  $c->gcp_ua(GET => $api,
             sub { },  ## success cb
             sub {
               my $tx = pop;
               $c->render(json => { error => $tx->res->body },
                          status => 403);
             });

Here is a more complete example to demonstrate headers and using a JSON generator:

  $c->gcp_ua(POST => $api,
             { 'Accept' => 'application/json' },
             json => { message => "the payload" },
             sub {
               my $tx = pop;
               $c->render(json => $tx->res->json,
                          status => $tx->res->code);
             },
             sub {
               my $tx = pop;
               $c->app->log->warn("OAuth failed: " . $tx->res->body);
               $c->render(json => { error => "Could not auth" },
                          status => 403);
             });

SEE ALSO

Mojo::UserAgent, Mojo::JWT::Google