aws-partitions 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bcd64cee1eb0c323f8692ff5a4c7dca11389772b
+  data.tar.gz: 0adcedec22ecafcc3d905eef56a8e44db74ab6d3
+SHA512:
+  metadata.gz: e5bf87351f61caedae8f502e12e6697fd30983961307e629ba2829990a95e6e58abd16ab4602a6f602ed9f308ece8779f4ea5313fc92c2bce084e98da8ef77cb
+  data.tar.gz: ecdb63091ac2d9a8023ab1637d95299a4d418d7d2a2c0131c13166129d1eb89b02ed7d5d7a0773a8f0e04696e35477b592c514d964f651f987e358b8dc6a1764

data/lib/aws-partitions.rb

@@ -0,0 +1,306 @@
+require_relative 'aws-partitions/endpoint_provider'
+require_relative 'aws-partitions/partition'
+require_relative 'aws-partitions/partition_list'
+require_relative 'aws-partitions/region'
+require_relative 'aws-partitions/service'
+
+require 'json'
+
+module Aws
+
+  # A {Partition} is a group of AWS {Region} and {Service} objects. You
+  # can use a partition to determine what services are available in a region,
+  # or what regions a service is available in.
+  #
+  # ## Partitions
+  #
+  # **AWS accounts are scoped to a single partition**. You can get a partition
+  # by name. Valid partition names include:
+  #
+  # * `"aws"` - Public AWS partition
+  # * `"aws-cn"` - AWS China
+  # * `"aws-us-gov"` - AWS GovCloud
+  #
+  # To get a partition by name:
+  #
+  #     aws = Aws::Partitions.partition('aws')
+  #
+  # You can also enumerate all partitions:
+  #
+  #     Aws::Partitions.each do |partition|
+  #       puts partition.name
+  #     end
+  #
+  # ## Regions
+  #
+  # A {Partition} is divided up into one or more regions. For example, the
+  # "aws" partition contains, "us-east-1", "us-west-1", etc. You can get
+  # a region by name. Calling {Partition#region} will return an instance
+  # of {Region}.
+  #
+  #     region = Aws::Partitions.partition('aws').region('us-west-2')
+  #     region.name
+  #     #=> "us-west-2"
+  #
+  # You can also enumerate all regions within a partition:
+  #
+  #     Aws::Partitions.partition('aws').regions.each do |region|
+  #       puts region.name
+  #     end
+  #
+  # Each {Region} object has a name, description and a list of services
+  # available to that region:
+  #
+  #     us_west_2 = Aws::Partitions.partition('aws').region('us-west-2')
+  #
+  #     us_west_2.name #=> "us-west-2"
+  #     us_west_2.description #=> "US West (Oregon)"
+  #     us_west_2.partition_name "aws"
+  #     us_west_2.services #=> #<Set: {"APIGateway", "AutoScaling", ... }
+  #
+  # To know if a service is available within a region, you can call `#include?`
+  # on the set of service names:
+  #
+  #     region.services.include?('DynamoDB') #=> true/false
+  #
+  # The service name should be the service's module name as used by
+  # the AWS SDK for Ruby. To find the complete list of supported
+  # service names, see {Partition#services}.
+  #
+  # Its also possible to enumerate every service for every region in
+  # every partition.
+  #
+  #     Aws::Partitions.partitions.each do |partition|
+  #       partition.regions.each do |region|
+  #         region.services.each do |service_name|
+  #           puts "#{partition.name} -> #{region.name} -> #{service_name}"
+  #         end
+  #       end
+  #     end
+  #
+  # ## Services
+  #
+  # A {Partition} has a list of services available. You can get a
+  # single {Service} by name:
+  #
+  #     Aws::Partitions.partition('aws').service('DynamoDB')
+  #
+  # You can also enumerate all services in a partition:
+  #
+  #     Aws::Partitions.partition('aws').services.each do |service|
+  #       puts service.name
+  #     end
+  #
+  # Each {Service} object has a name, and information about regions
+  # that service is available in.
+  #
+  #     service.name #=> "DynamoDB"
+  #     service.partition_name #=> "aws"
+  #     service.regions #=> #<Set: {"us-east-1", "us-west-1", ... }
+  #
+  # Some services have multiple regions, and others have a single partition
+  # wide region. For example, {Aws::IAM} has a single region in the "aws"
+  # partition. The {Service#regionalized?} method indicates when this is
+  # the case.
+  #
+  #     iam = Aws::Partitions.partition('aws').service('IAM')
+  #
+  #     iam.regionalized? #=> false
+  #     service.partition_region #=> "aws-global"
+  #
+  # Its also possible to enumerate every region for every service in
+  # every partition.
+  #
+  #     Aws::Partitions.partitions.each do |partition|
+  #       partition.services.each do |service|
+  #         service.regions.each do |region_name|
+  #           puts "#{partition.name} -> #{region_name} -> #{service.name}"
+  #         end
+  #       end
+  #     end
+  #
+  # ## Service Names
+  #
+  # {Service} names are those used by the the AWS SDK for Ruby. They
+  # correspond to the service's module.
+  #
+  module Partitions
+
+    class << self
+
+      include Enumerable
+
+      # @return [Enumerable<Partition>]
+      def each(&block)
+        default_partition_list.each(&block)
+      end
+
+      # Return the partition with the given name. A partition describes
+      # the services and regions available in that partition.
+      #
+      #     aws = Aws::Partitions.partition('aws')
+      #
+      #     puts "Regions available in the aws partition:\n"
+      #     aws.regions.each do |region|
+      #       puts region.name
+      #     end
+      #
+      #     puts "Services available in the aws partition:\n"
+      #     aws.services.each do |services|
+      #       puts services.name
+      #     end
+      #
+      # @param [String] name The name of the partition to return.
+      #   Valid names include "aws", "aws-cn", and "aws-us-gov".
+      #
+      # @return [Partition]
+      #
+      # @raise [ArgumentError] Raises an `ArgumentError` if a partition is
+      #   not found with the given name. The error message contains a list
+      #   of valid partition names.
+      def partition(name)
+        default_partition_list.partition(name)
+      end
+
+      # Returns an array with every partitions. A partition describes
+      # the services and regions available in that partition.
+      #
+      #     Aws::Partitions.partitions.each do |partition|
+      #
+      #       puts "Regions available in #{partition.name}:\n"
+      #       partition.regions.each do |region|
+      #         puts region.name
+      #       end
+      #
+      #       puts "Services available in #{partition.name}:\n"
+      #       partition.services.each do |service|
+      #         puts service.name
+      #       end
+      #     end
+      #
+      # @return [Enumerable<Partition>] Returns an enumerable of all
+      #   known partitions.
+      def partitions
+        default_partition_list
+      end
+
+      # @param [Hash] new_partitions
+      # @api private For internal use only.
+      def add(new_partitions)
+        new_partitions['partitions'].each do |partition|
+          default_partition_list.add_partition(Partition.build(partition))
+          defaults['partitions'] << partition
+        end
+      end
+
+      # @api private For internal use only.
+      def clear
+        default_partition_list.clear
+        defaults['partitions'].clear
+      end
+
+      # @return [PartitionList]
+      # @api private
+      def default_partition_list
+        @default_partition_list ||= PartitionList.build(defaults)
+      end
+
+      # @return [Hash]
+      # @api private
+      def defaults
+        @defaults ||= begin
+          path = File.expand_path('../../partitions.json', __FILE__)
+          JSON.load(File.read(path))
+        end
+      end
+
+      # @return [Hash<String,String>] Returns a map of service module names
+      #   to their id as used in the endpoints.json document.
+      # @api private For internal use only.
+      def service_ids
+        @service_ids ||= begin
+          # service ids
+          {
+            'ACM' => 'acm',
+            'APIGateway' => 'apigateway',
+            'ApplicationAutoScaling' => 'application-autoscaling',
+            'ApplicationDiscoveryService' => 'discovery',
+            'AutoScaling' => 'autoscaling',
+            'Budgets' => 'budgets',
+            'CloudFormation' => 'cloudformation',
+            'CloudFront' => 'cloudfront',
+            'CloudHSM' => 'cloudhsm',
+            'CloudSearch' => 'cloudsearch',
+            'CloudTrail' => 'cloudtrail',
+            'CloudWatch' => 'monitoring',
+            'CloudWatchEvents' => 'events',
+            'CloudWatchLogs' => 'logs',
+            'CodeCommit' => 'codecommit',
+            'CodeDeploy' => 'codedeploy',
+            'CodePipeline' => 'codepipeline',
+            'CognitoIdentity' => 'cognito-identity',
+            'CognitoIdentityProvider' => 'cognito-idp',
+            'CognitoSync' => 'cognito-sync',
+            'ConfigService' => 'config',
+            'DataPipeline' => 'datapipeline',
+            'DatabaseMigrationService' => 'dms',
+            'DeviceFarm' => 'devicefarm',
+            'DirectConnect' => 'directconnect',
+            'DirectoryService' => 'ds',
+            'DynamoDB' => 'dynamodb',
+            'DynamoDBStreams' => 'streams.dynamodb',
+            'EC2' => 'ec2',
+            'ECR' => 'ecr',
+            'ECS' => 'ecs',
+            'EFS' => 'elasticfilesystem',
+            'EMR' => 'elasticmapreduce',
+            'ElastiCache' => 'elasticache',
+            'ElasticBeanstalk' => 'elasticbeanstalk',
+            'ElasticLoadBalancing' => 'elasticloadbalancing',
+            'ElasticLoadBalancingV2' => 'elasticloadbalancing',
+            'ElasticTranscoder' => 'elastictranscoder',
+            'ElasticsearchService' => 'es',
+            'Firehose' => 'firehose',
+            'GameLift' => 'gamelift',
+            'Glacier' => 'glacier',
+            'IAM' => 'iam',
+            'ImportExport' => 'importexport',
+            'Inspector' => 'inspector',
+            'IoT' => 'iot',
+            'IoTDataPlane' => 'data.iot',
+            'KMS' => 'kms',
+            'Kinesis' => 'kinesis',
+            'KinesisAnalytics' => 'kinesisanalytics',
+            'Lambda' => 'lambda',
+            'LambdaPreview' => 'lambda',
+            'MachineLearning' => 'machinelearning',
+            'MarketplaceCommerceAnalytics' => 'marketplacecommerceanalytics',
+            'MarketplaceMetering' => 'metering.marketplace',
+            'OpsWorks' => 'opsworks',
+            'RDS' => 'rds',
+            'Redshift' => 'redshift',
+            'Route53' => 'route53',
+            'Route53Domains' => 'route53domains',
+            'S3' => 's3',
+            'SES' => 'email',
+            'SMS' => 'sms',
+            'SNS' => 'sns',
+            'SQS' => 'sqs',
+            'SSM' => 'ssm',
+            'STS' => 'sts',
+            'SWF' => 'swf',
+            'ServiceCatalog' => 'servicecatalog',
+            'SimpleDB' => 'sdb',
+            'Snowball' => 'snowball',
+            'StorageGateway' => 'storagegateway',
+            'Support' => 'support',
+            'WAF' => 'waf',
+            'WorkSpaces' => 'workspaces',
+          }
+          # end service ids
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-partitions/endpoint_provider.rb

@@ -0,0 +1,115 @@
+module Aws
+  module Partitions
+    # @api private
+    class EndpointProvider
+
+      # Intentionally marked private. The format of the endpoint rules
+      # is an implementation detail.
+      # @api private
+      def initialize(rules)
+        @rules = rules
+      end
+
+      # @param [String] region
+      # @param [String] service The endpoint prefix for the service, e.g. "monitoring" for
+      #   cloudwatch.
+      # @api private Use the static class methods instead.
+      def resolve(region, service)
+        "https://" + endpoint_for(region, service)
+      end
+
+      # @api private Use the static class methods instead.
+      def signing_region(region, service)
+        get_partition(region).
+          fetch("services", {}).
+          fetch(service, {}).
+          fetch("endpoints", {}).
+          fetch(region, {}).
+          fetch("credentialScope", {}).
+          fetch("region", region)
+      end
+
+      # @api private Use the static class methods instead.
+      def dns_suffix_for(region)
+        partition = get_partition(region)
+        partition['dnsSuffix']
+      end
+
+      private
+
+      def endpoint_for(region, service)
+        partition = get_partition(region)
+        endpoint = default_endpoint(partition, service, region)
+        service_cfg = partition.fetch("services", {}).fetch(service, {})
+
+        # Check for service-level default endpoint.
+        endpoint = service_cfg.fetch("defaults", {}).fetch("hostname", endpoint)
+
+        # Check for global endpoint.
+        if service_cfg["isRegionalized"] == false
+          region = service_cfg.fetch("partitionEndpoint", region)
+        end
+
+        # Check for service/region level endpoint.
+        endpoint = service_cfg.fetch("endpoints", {}).
+          fetch(region, {}).fetch("hostname", endpoint)
+
+        endpoint
+      end
+
+      def default_endpoint(partition, service, region)
+        hostname_template = partition["defaults"]["hostname"]
+        hostname_template.
+          sub('{region}', region).
+          sub('{service}', service).
+          sub('{dnsSuffix}', partition["dnsSuffix"])
+      end
+
+      def get_partition(region)
+        partition_containing_region(region) ||
+        partition_matching_region(region) ||
+        default_partition
+      end
+
+      def partition_containing_region(region)
+        @rules['partitions'].find do |p|
+          p['regions'].key?(region)
+        end
+      end
+
+      def partition_matching_region(region)
+        @rules['partitions'].find do |p|
+          region.match(p["regionRegex"]) ||
+          p['services'].values.find { |svc| svc['endpoints'].key?(region) }
+        end
+      end
+
+      def default_partition
+        @rules['partitions'].find { |p| p["partition"] == "aws" } ||
+        @rules['partitions'].first
+      end
+
+      class << self
+
+        def resolve(region, service)
+          default_provider.resolve(region, service)
+        end
+
+        def signing_region(region, service)
+          default_provider.signing_region(region, service)
+        end
+
+        def dns_suffix_for(region)
+          default_provider.dns_suffix_for(region)
+        end
+
+        private
+
+        def default_provider
+          @default_provider ||= EndpointProvider.new(Partitions.defaults)
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-partitions/partition.rb

@@ -0,0 +1,95 @@
+module Aws
+  module Partitions
+    class Partition
+
+      # @option options [required, String] :name
+      # @option options [required, Hash<String,Region>] :regions
+      # @option options [required, Hash<String,Service>] :services
+      # @api private
+      def initialize(options = {})
+        @name = options[:name]
+        @regions = options[:regions]
+        @services = options[:services]
+      end
+
+      # @return [String] The partition name, e.g. "aws", "aws-cn", "aws-us-gov".
+      attr_reader :name
+
+      # @param [String] region_name The name of the region, e.g. "us-east-1".
+      # @return [Region]
+      # @raise [ArgumentError] Raises `ArgumentError` for unknown region name.
+      def region(region_name)
+        if @regions.key?(region_name)
+          @regions[region_name]
+        else
+          msg = "invalid region name #{region_name.inspect}; valid region "
+          msg << "names include %s" % [@regions.keys.join(', ')]
+          raise ArgumentError, msg
+        end
+      end
+
+      # @return [Array<Region>]
+      def regions
+        @regions.values
+      end
+
+      # @param [String] service_name The service module name.
+      # @return [Service]
+      # @raise [ArgumentError] Raises `ArgumentError` for unknown service name.
+      def service(service_name)
+        if @services.key?(service_name)
+          @services[service_name]
+        else
+          msg = "invalid service name #{service_name.inspect}; valid service "
+          msg << "names include %s" % [@services.keys.join(', ')]
+          raise ArgumentError, msg
+        end
+      end
+
+      # @return [Array<Service>]
+      def services
+        @services.values
+      end
+
+      class << self
+
+        # @api private
+        def build(partition)
+          Partition.new(
+            name: partition['partition'],
+            regions: build_regions(partition),
+            services: build_services(partition),
+          )
+        end
+
+        private
+
+        # @param [Hash] partition
+        # @return [Hash<String,Region>]
+        def build_regions(partition)
+          partition['regions'].inject({}) do |regions, (region_name, region)|
+            unless region_name == "#{partition['partition']}-global"
+              regions[region_name] = Region.build(region_name, region, partition)
+            end
+            regions
+          end
+        end
+
+        # @param [Hash] partition
+        # @return [Hash<String,Service>]
+        def build_services(partition)
+          Partitions.service_ids.inject({}) do |services, (svc_name, svc_id)|
+            if partition['services'].key?(svc_id)
+              svc_data = partition['services'][svc_id]
+              services[svc_name] = Service.build(svc_name, svc_data, partition)
+            else
+              services[svc_name] = Service.build(svc_name, {'endpoints' => {}}, partition)
+            end
+            services
+          end
+        end
+
+      end
+    end
+  end
+end