/ 
Amazon-API-2.8.1
⭐ Starred 0 / Amazon::API::Role::Botocore

NAME

Amazon::API::Role::Botocore - role providing an interface to Botocore metadata

SYNOPSIS

package Amazon::API::MyGenerator;

use Role::Tiny::With;
with 'Amazon::API::Role::Botocore';

sub get_botocore_path { return $ENV{BOTOCORE_PATH} }

...

my $self     = __PACKAGE__->new;
my $services = $self->fetch_boto_services;

$self->create_stub(
  output_path => '/tmp/build',
  module_name => 'STS',
  service     => 'sts',
);

DESCRIPTION

Amazon::API::Role::Botocore is a Role::Tiny role that encapsulates the Botocore-facing operations used to generate Amazon::API service classes. It enumerates the AWS services present in a Botocore checkout, loads and normalizes their service-2.json, paginators-1.json, endpoint-rule-set-1.json definitions, generates a runtime service stub together with a serialized metadata image, and resolves a Botocore service name to the Amazon::API package that implements it.

It reads two sources: the raw Botocore checkout (located via "get_botocore_path" or $ENV{BOTOCORE_PATH}) and, for name resolution, the pre-built botocore-metadata.api registry shipped with Amazon::API. The role is consumed via with by the amzn-api generator and by the Amazon::API build factory; a consuming class need only supply "get_botocore_path".

REQUIRED METHODS

The composing class must provide:

get_botocore_path

Returns the filesystem path to the Botocore checkout (the directory containing the botocore/ subtree). $ENV{BOTOCORE_PATH} takes precedence over this method when it is set.

METHODS AND SUBROUTINES

create_stub

$self->create_stub(
  output_path => $path,
  module_name => $module_name,
  service     => $service,
);

Generates an Amazon::API::<module_name> service stub from the Botocore service definition and writes two files beneath $output_path/Amazon/API/:

  • <module_name>.pm - the runtime stub (package Amazon::API::<module_name>), rendered from stub.pm.tmpl.

  • <module_name>.api.gz - a gzipped, canonical Storable image of the service metadata (metadata, operations, shapes, raw paginators, compiled paginators and their SHA-256 digests) that the runtime loads instead of re-parsing Botocore at run time.

Before serializing, each operation's requestUri is parsed and baked in as parsed_request_uri so the runtime can build request URIs from the stored metadata, and developer-facing documentation is stripped from operations and shapes (it is never read by the runtime; POD is rendered separately by Amazon::API::Help). The content type is derived from the Botocore protocol (query, json, rest-json), and the service version is taken from the API date (service_version keeps the raw YYYY-MM-DD; version is the dotted YYYY.MM.DD form used for the distribution).

Arguments are passed as key/value pairs; all three are required.

output_path

Base output directory. The Amazon/API/ tree is created beneath it if it does not exist.

module_name

The package suffix, e.g. S3 yields Amazon::API::S3.

service

The Botocore service key, e.g. s3, dynamodb.

An existing .pm is renamed to .pm.bak before writing. Returns nothing; croaks on a missing argument, an uncreatable output path, or a missing stub.pm.tmpl.

fetch_boto_services

my $services = $self->fetch_boto_services;
my $services = $self->fetch_boto_services($want_metadata);

Walks the Botocore tree ($ENV{BOTOCORE_PATH} or $self->get_botocore_path, under botocore/) and returns a hash reference of every AWS service, keyed by service name, resolved to its most recent API version. Each value contains at least the service's API date and the path to its file (its service-2.json).

If $want_metadata is true, each entry is additionally populated with its decoded metadata and the service_2_digest / paginators_1_digest SHA-256 digests.

Croaks if no Botocore path is found, the botocore/ subdirectory is absent, or no services are discovered.

get_service_descriptions

my $descriptions = $self->get_service_descriptions($boto_services);
my $descriptions = $self->get_service_descriptions($boto_services, @services);

Given the service index returned by "fetch_boto_services", loads and normalizes the full Botocore description for the named @services (or every service in $boto_services if none are named). Returns an array reference of single-key hash references, one per service, each of the form { $service => \%description }.

Each %description collects the service's actions, operations, shapes, paginators, metadata (plus endpoint_prefix, json_version, protocol, service_name, target_prefix), version (the API date), and the service_2_digest / paginators_1_digest SHA-256 digests. Services whose definition has no operations are skipped.

Croaks if a named service is not present in $boto_services.

module_name

my $package = $self->module_name($service);

Resolves a Botocore service name to the Amazon::API package that implements it, read from the pre-built botocore-metadata.api registry. For example:

my $package = $self->module_name('sts');   # Amazon::API::STS

Croaks if botocore-metadata.api cannot be located.

SEE ALSO

Amazon::API, Amazon::API::Help, Amazon::API::Botocore::Shape::Utils, Role::Tiny

LICENSE AND COPYRIGHT

This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself.

AUTHOR

Rob Lauer - <rlauer@treasurersbriefcase.com>