skull_island 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb050b692cd4d7b01b5b1177d76199bd53c722b63dff53eaf86b09a60d9304df
-  data.tar.gz: 32fe27433b89c0fd2190666519d0f9c45ce8a63fbc0ac605feffcdfafb7c445c
+  metadata.gz: 19ab037beb02518e751019c8d59bd81cdf9165b373ea5b31287ed6dc829a4f21
+  data.tar.gz: 1a352da5080eaae1ce030f872fcda1e53dbbbca2dfb39af5536db2cb1772fe8e
 SHA512:
-  metadata.gz: c991510e113414534ea96b40fa9f66b510af040b7b772c61af92175562a2475ca9ec018c0b32ea0582cf11f286448ae9924525c56b2c3c441e8ce3e367de8cc4
-  data.tar.gz: cec7bb4bade7e1cd158d3c79d319dc32ec75301c25152439fd891e063f120916bd055221ceabc95b3d849d2f0a6a315be326d8d74fed8fa5be456ec02af580bc
+  metadata.gz: f5f1d27b7b1114ccad775df93c7db93d42279fcdb085cf76323efb2f1c2d5aa09dc6a83132e4ab7dbc9eefd349b420ff10f9f7c3abc53fe39839aa18e787c9cb
+  data.tar.gz: ee44a34f72104f02785949a609919230d511e39dbb332ee96ed4c13ec95d800e240d098613570b49b2d0814ac6b81f86f4cc201dfdb8bed93de1cdc320e451c9

data/.gitignore

@@ -9,3 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
+*.gem

data/.rubocop.yml

@@ -0,0 +1,39 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/ClassLength:
+  Max: 165
+
+Metrics/ModuleLength:
+  Max: 165
+
+Metrics/CyclomaticComplexity:
+  Max: 7
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - '*.gemspec'
+    - Rakefile
+    - 'spec/**/*_spec.rb'
+    - 'spec/spec_helper.rb'
+
+Layout/IndentHeredoc:
+  Enabled: false
+
+Security/Eval:
+  Exclude:
+    - Gemfile
+
+Style/NumericLiterals:
+  Exclude:
+    - 'spec/**/*_spec.rb'

data/.travis.yml

@@ -1,7 +1,14 @@
----
 sudo: false
 language: ruby
 cache: bundler
 rvm:
-  - 2.5.3
+- 2.5.3
 before_install: gem install bundler -v 2.0.1
+deploy:
+  provider: rubygems
+  api_key:
+    secure: Gj3+sg3iSZytx7vNsnu6U/I61BVwz2rFB3WoclMoFuqdWwUyK/4qd2wC0OIvQQJg6Ex1nBwws6VjHUUOCtRiUIF62yR7pDE/ITHkzjjEtZ/ru/6ZKkyHmpenV6Pu0TzENgEY7EIu7pGOJr/57INUuuq7bZM0qV5Rew6Feg2t9n3o8hAONS614MB64Ig6PHRSiGUkm9iogaksQodeb2RvHrQgCXNnhAxq/TdU0TPV7DDDtx4piM1hpdm4sMwznCqZKC89WV7WajeWhQJdaXoGWxDq2ZmF3gM5q8cnK5Uh5wf2pKWce3N8ikeOuiLe06RLQ2pH7UBU9ku9u3+naqFjDZb3d/2DRoxZFjy/P6CRinfoOrsR0k74pc5lnsyQlkxJsJILoOLz7hV4oi9MBi8tDafGz6XVi+UMGE34Nj/7oZjvnbmIuYRJSC+7564y7tsPykOXuCOV6BuDUclXLxTbaLUTLCRcbDluzNrxymbxs3KSZBfM6jli66oXroagaYCdL5zPiGDD5W0crv0c6eDRQAuDOTUllQy/75FRGFn5hbomHQBVM18pm9sx/k6AB+thanIcottdRKst6xh/EN3KnQsLV1M2hSq3gG8EyoqObkIhvcOtCKqfG5VId8qOxT01UcaKui4exyqAv8LAW0WCAL1kyl6Oty1ArZao5fibGUI=
+  gem: skull_island
+  on:
+    tags: true
+    repo: jgnagy/skull_island

data/Gemfile

@@ -1,4 +1,6 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in skull_island.gemspec
 gemspec

data/Gemfile.lock

@@ -0,0 +1,127 @@
+PATH
+  remote: .
+  specs:
+    skull_island (0.1.1)
+      json (~> 2.0)
+      linguistics (~> 2.1)
+      rest-client (~> 2.0)
+      will_paginate (~> 3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    ast (2.4.0)
+    backports (3.12.0)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    domain_name (0.5.20180417)
+      unf (>= 0.0.5, < 1.0.0)
+    ethon (0.12.0)
+      ffi (>= 1.3.0)
+    faraday (0.15.4)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.13.1)
+      faraday (>= 0.7.4, < 1.0)
+    ffi (1.10.0)
+    gh (0.15.1)
+      addressable (~> 2.4.0)
+      backports
+      faraday (~> 0.8)
+      multi_json (~> 1.0)
+      net-http-persistent (~> 2.9)
+      net-http-pipeline
+    highline (1.7.10)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    jaro_winkler (1.5.2)
+    json (2.1.0)
+    launchy (2.4.3)
+      addressable (~> 2.3)
+    linguistics (2.1.0)
+      loggability (~> 0.11)
+    loggability (0.14.0)
+    mime-types (3.2.2)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2018.0812)
+    multi_json (1.13.1)
+    multipart-post (2.0.0)
+    net-http-persistent (2.9.4)
+    net-http-pipeline (1.0.1)
+    netrc (0.11.0)
+    parallel (1.13.0)
+    parser (2.6.0.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    psych (3.1.0)
+    pusher-client (0.6.2)
+      json
+      websocket (~> 1.0)
+    rainbow (3.0.0)
+    rake (10.5.0)
+    rest-client (2.0.2)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.65.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      psych (>= 3.1.0)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    travis (1.8.9)
+      backports
+      faraday (~> 0.9)
+      faraday_middleware (~> 0.9, >= 0.9.1)
+      gh (~> 0.13)
+      highline (~> 1.6)
+      launchy (~> 2.1)
+      pusher-client (~> 0.4)
+      typhoeus (~> 0.6, >= 0.6.8)
+    typhoeus (0.8.0)
+      ethon (>= 0.8.0)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.5)
+    unicode-display_width (1.4.1)
+    websocket (1.2.8)
+    will_paginate (3.1.6)
+    yard (0.9.18)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rubocop (~> 0.50)
+  simplecov (~> 0.15)
+  skull_island!
+  travis (~> 1.8)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.0.1

data/README.md

@@ -1,6 +1,352 @@
-# SkullIsland
+# Skull Island
 
-Work In Progress
+Work In Progress for a full-featured SDK for Kong 0.14.x (with 1.0.x details added for future development).
+
+## Installation
+
+Either:
+
+```sh
+gem install skull_island
+```
+
+Or add this to your Gemfile:
+
+```ruby
+gem 'skull_island',  '~>0.1'
+```
+
+Or add this to your .gemspec:
+
+```ruby
+Gem::Specification.new do |spec|
+ # ...
+ spec.add_runtime_dependency 'skull_island', '~> 0.1'
+ # ...
+end
+```
+
+## Usage
+
+The API Client requires configuration before it can be used. For now, this is a matter of calling `APIClient.configure()`, passing a Hash, with Symbols for keys:
+
+```ruby
+require 'skull_island'
+include SkullIsland
+
+APIClient.configure(
+  server: 'https://api-admin.mydomain.com',
+  username: 'my-basicauth-user',
+  password: 'my-basicauth-password'
+)
+```
+
+This assumes that a basic-auth reverse proxy sits in front of your Kong Admin API. If this isn't the case (it really should be), then just don't pass `username` and `password` and the API client will work just fine.
+
+### The APIClient Singleton
+
+The API client provides a few helpful methods of its own. To learn about the overall service you've connected to (via the [node information endpoint](https://docs.konghq.com/0.14.x/admin-api/#retrieve-node-information)):
+
+```ruby
+APIClient.about_service
+# => {"plugins"=>...
+```
+
+It is also possible to check on the server status of the node you're accessing via the [node status endpoint](https://docs.konghq.com/0.14.x/admin-api/#retrieve-node-status):
+
+```ruby
+APIClient.server_status
+# => {"database"=>{"reachable"=>true...
+```
+
+This SDK also makes automatic (and mostly unobtrusive) caching behind the scenes. As long as this tool is the only tool making changes to the Admin API (at least while it is being used), this should be fine. Eventually, there will be an option to disable this cache (at the cost of poor performance). For now, it is possible to query this cache and even flushed it manually when required:
+
+```ruby
+APIClient.lru_cache
+# => #<SkullIsland::LRUCache:0x00007f9f1ebf3898 @max_size=1000...
+APIClient.lru_cache.flush # this empties the cache and resets statistics
+# => true
+```
+
+### Resources
+
+Most value provided by this SDK is through the ability to manipulate resources managed through the Admin API. These resources almost all have a few methods in common.
+
+For example, finder methods like these:
+
+```ruby
+# Get all instances of a resource type through `.all()`, returning a special collection class
+Resources::Consumer.all
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e3f9b38...
+
+# Find instances matching some criteria using `.where()`, returning the same kind of collection
+Resources::Consumer.where(:username, /.*foo.*/) # finds all Consumers with a matching username
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e3351c0...
+
+# Finding using other types of comparisons, like `<`
+#  Here, we find all Consumers made more than an hour ago
+Resources::Consumer.where(
+  :created_at, (Time.now - 3600).to_datetime, comparison: :<
+)
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e380924...
+
+# Finder methods can also be chained
+Resources::Consumer.where(:username, /.*foo.*/).and(:username, /\w{10,}/)
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e358964...
+Resources::Consumer.where(:username, /.*foo.*/).or(:custom_id, /.*bar.*/)
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e568410...
+
+# If you have the `id` of a particular resource, you can find it directly
+Resources::Consumer.get('1cad3055-1027-459d-b76e-f590dc5f0071')
+# => #<SkullIsland::Resources::Consumer:0x00007f9f201f6c58...
+```
+
+Once you have a resource, you can modify it:
+
+```ruby
+my_consumer = Resources::Consumer.get('1cad3055-1027-459d-b76e-f590dc5f0071')
+my_consumer.username
+# => "testuser"
+my_consumer.tainted?
+# => false
+my_consumer.username = 'someuser'
+my_consumer.tainted?
+# => true
+my_consumer.save
+# => true
+my_consumer.tainted?
+# => false
+my_consumer.username
+# => "someuser"
+```
+
+Some resource types are related to others, such as `Routes` and `Services`:
+
+```ruby
+service = Resources::Services.all.first
+# => #<SkullIsland::Resources::Services:0x00007f9f201f6f44...
+service.routes
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e569e1d...
+service.routes.size
+# => 3
+my_route = Resources::Route.new
+my_route.hosts = ['example.com', 'example.org']
+my_route.protocols = ['http', 'https']
+my_route.strip_path = true
+my_route.preserve_host = false
+service.add_route!(my_route)
+# => true
+service.routes.size
+# => 4
+```
+
+From here, the SDK mostly wraps the attributes described in the [Kong API Docs](https://docs.konghq.com/0.14.x/admin-api/). For simplicity, I'll go over the resource types and attributes this SDK supports manipulating. Rely on the API documentation to determine which attributes are required and under which conditions.
+
+#### Certificates
+
+```ruby
+resource = Resources::Certificate.new
+
+# These attributes can be set and read
+resource.cert = '-----BEGIN CERTIFICATE-----...'    # PEM-encoded public key
+resource.key  = '-----BEGIN RSA PRIVATE KEY-----...' # PEM-encoded private key
+resource.snis = ['example.com', 'example.org']      # Array of names for which this cert is valid
+
+resource.save
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+```
+
+#### Consumers
+
+```ruby
+resource = Resources::Consumer.new
+
+# These attributes can be set and read
+resource.custom_id = 'user1' # A string
+resource.username  = 'user1' # A string
+
+resource.save
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.plugins
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e564f3e...
+```
+
+#### Plugins
+
+Note that this doesn't _install_ plugins; it only allows using them.
+
+```ruby
+resource = Resources::Plugin.new
+
+# These attributes can be set and read
+resource.name     = 'rate-limiting' # The name of the plugin
+resource.enabled  = true            # A Boolean
+resource.config   = { 'minute' => 50, 'hour' => 1000 } # A Hash of config keys and values
+
+# Either reference related resources by ID
+resource.service  = { 'id' => '5fd1z584-1adb-40a5-c042-63b19db49x21' }
+resource.service
+# => #<SkullIsland::Resources::Services:0x00007f9f201f6f44...
+
+# Or reference related resources directly
+resource.consumer = Resources::Consumer.get('a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4')
+resource.consumer
+# => #<SkullIsland::Resources::Consumer:0x00007f9f201f6f98...
+
+resource.route    = Resources::Route.get('1cad3055-1027-459d-b76e-f590dc5f0023')
+resource.route
+# => #<SkullIsland::Resources::Route:0x00007f9f201f6f98...
+
+resource.save
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+
+# The resource class itself allows the following methods as well:
+
+# This provides a list of plugin names that are enabled
+Resources::Plugin.enabled_names
+# => ["response-transformer",...
+
+# This looks up the configuration schema for a particular plugin by its name
+Resources::Plugin.schema('acl')
+# => {"fields"=>{"hide_groups_header"=>{"default"=>false...
+```
+
+#### Routes
+
+```ruby
+resource = Resources::Route.new
+
+# These attributes can be set and read
+resource.hosts          = ['example.com', 'example.org']
+resource.protocols      = ['https']
+resource.methods        = ['GET', 'POST']
+resource.paths          = ['/some/path']
+resource.regex_priority = 10
+resource.strip_path     = false
+resource.preserve_host  = true
+
+# Either reference related resources by ID
+resource.service = { 'id' => '4e13f54a-bbf1-47a8-8777-255fed7116f2' }
+# Or reference related resources directly
+resource.service = Resources::Service.get('4e13f54a-bbf1-47a8-8777-255fed7116f2')
+resource.service
+# => #<SkullIsland::Resources::Service:0x00007f9f201f6f98...
+
+resource.save
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.updated_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.plugins
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e564f3e...
+```
+
+#### Services
+
+```ruby
+resource = Resources::Service.new
+
+# These attributes can be set and read
+resource.protocol        = 'http'
+resource.connect_timeout = 60000
+resource.host            = 'example.com'
+resource.port            = 80
+resource.path            = '/api'
+resource.name            = 'example-service'
+resource.retries         = 10
+resource.read_timeout    = 60000
+resource.write_timeout   = 60000
+
+resource.save
+
+# Add a related route
+my_route = Resources::Route.get(...)
+resource.add_route!(my_route) # adds a route to the service
+# => true
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.updated_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.routes
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e564f3f...
+resource.plugins
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e564f3e...
+```
+
+#### Upstreams (and their Targets)
+
+```ruby
+resource = Resources::Upstream.new
+
+# These attributes can be set and read
+resource.name          = 'service.v1.xyz'
+resource.hash_on       = 'none'
+resource.hash_fallback = 'none'
+resource.slots         = 1000
+resource.healthchecks  = {
+  'active' => {
+    'concurrency' => 5,
+    'healthy' => {
+      'http_statuses' => [200, 302],
+      'interval' => 0,
+      'successes' => 0
+    },
+    'http_path' => '/',
+    'timeout' => 1,
+    'unhealthy' => {
+      'http_failures' => 0,
+      'http_statuses' => [
+        429, 404, 500, 501, 502, 503, 504, 505
+      ],
+      'interval' => 0,
+      'tcp_failures' => 0,
+      'timeouts' => 0
+    }
+  }
+}
+
+resource.save
+
+my_upstream_node = Resources::UpstreamTarget.new
+my_upstream_node.target = '4.5.6.7:80'
+my_upstream_node.weight = 15
+resource.add_target!(my_upstream_node) # adds a target to the upstream
+# => true
+
+# These attributes are read-only
+resource.id
+# => "1cad3055-1027-459d-b76e-f590dc5f0071"
+resource.created_at
+# => #<DateTime: 2018-07-17T12:51:28+00:00 ((2458317j,46288s,0n),+0s,2299161j)>
+resource.health # returns a Hash of all upstream targets and their health statuses
+# => #<Hash...
+resource.targets
+# => #<SkullIsland::ResourceCollection:0x00007f9f1e564f3f...
+resource.target('1bef3055-1027-459d-b76e-f590dc5f0071') # get an Upstream Target by id
+```
 
 ## License
 

data/Rakefile

@@ -1,6 +1,16 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+YARD::Rake::YardocTask.new do |y|
+  y.options = [
+    '--markup', 'markdown'
+  ]
+end
 
-task :default => :spec
+task default: %i[spec rubocop yard]

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "skull_island"
+require 'bundler/setup'
+require 'skull_island'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "skull_island"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/core_extensions/string/transformations.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CoreExtensions
+  module String
+    # Monkey-patches for String to add some simple missing transformations
+    module Transformations
+      # Convert CamelCase to underscored_text
+      # @return [String]
+      def to_underscore
+        gsub(/::/, '/')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-', '_')
+          .downcase
+      end
+
+      # Convert underscored_text to CamelCase
+      # @return [String]
+      def to_camel
+        split('_').map(&:capitalize).join
+      end
+
+      # Attempt to guess a more human-like view of a string
+      # @return [String]
+      def humanize
+        gsub(/_id$/, '').tr('_', ' ').capitalize
+      end
+    end
+  end
+end

data/lib/skull_island/api_client.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # The API Client Singleton class
+  class APIClient < APIClientBase
+    include Singleton
+
+    def self.configure(opts = {})
+      instance.configure(opts)
+    end
+
+    def self.about_service
+      instance.about_service
+    end
+
+    def self.lru_cache
+      instance.lru_cache
+    end
+
+    def self.server_status
+      instance.server_status
+    end
+
+    def configure(opts = {})
+      # validations
+      validate_opts(opts)
+
+      # Set up the client's state
+      @server     = opts[:server] || 'http://localhost:8001'
+      @username   = opts[:username]
+      @password   = opts[:password]
+      @cache      = LRUCache.new(1000) # LRU cache of up to 1000 items
+      @configured = true
+    end
+  end
+end