3scale_toolbox 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c162adffa46adcb9b43e88642bf1de4daaed45ae9db6abcaa93b388e56f9159a
-  data.tar.gz: 481d3485a91d038c6c7af04d7609f9a907d3e8e30e3264c4cb43b2e0f15f2b8c
+  metadata.gz: ae4791c3e86318f973f54abefb9df823abc7efe7ede820ca736697b23cd10653
+  data.tar.gz: 68cb54b32c6286593464dc1d7302343684cd4d2df043e18a5b3ff777e61f2920
 SHA512:
-  metadata.gz: 7faf8d5012d24d978a70d357fc1ff5aa9327edb67f4dc307cf8e32bfb3143b3bebe460238b6580a34b82220c8ea590877f3cd5ddc92eaee052a1bf9ec3c0484e
-  data.tar.gz: 44b6c5e32f13eb98c1d2494d6b198374567b9cc5d6e0cd1f3461a88270f10a699e9228d4a32cc1d095a1c195cac081e30a0117896c3e7cf0993120130bbf3393
+  metadata.gz: f36923df1c9961cb9a209a6228ecc50cd5e00b8b1d853384e561b3280d59550125c1793124a95cc7a9553cc42bea4453e898de2135496858d11b200333811242
+  data.tar.gz: 955e042f2a2b8cc62c56ce8bcedaa4de8a7800a16f39dbb83e37a6969a178b13ff4fdf94104d8240d2b402ab488ce7eb44400fceba0d58c8c7af5ef94a310ef3

data/README.md

@@ -8,13 +8,17 @@
    * [Copy a service](#copy-a-service)
    * [Update a service](#update-a-service)
    * [Import from CSV](#import-from-csv)
+   * [Import from OpenAPI definition](#import-openapi)
+   * [Remotes](#remotes)
 * [Development](#development)
+   * [Testing](#testing)
+   * [Develop your own core command](#develop-core-command)
 * [Plugins](#plugins)
 * [Troubleshooting](#troubleshooting)
 * [Contributing](#contributing)
 
 ## Installation
-Install the CLI:
+Install the toolbox:
 
     $ gem install 3scale_toolbox
 
@@ -23,28 +27,34 @@ Install the CLI:
 ```shell
 $ 3scale help
 NAME
-    3scale - 3scale CLI Toolbox
+    3scale - 3scale toolbox
 
 USAGE
-    3scale <command> [options]
+    3scale <sub-command> [options]
 
 DESCRIPTION
-    3scale CLI tools to manage your API from the terminal.
+    3scale toolbox to manage your API from the terminal.
 
 COMMANDS
-    copy       3scale copy command
+    copy       copy super command
     help       show help
-    import     3scale import command
-    update     3scale update command
+    import     import super command
+    remote     remotes super command
+    update     update super command
 
 OPTIONS
-    -k --insecure      Proceed and operate even for server connections
-                       otherwise considered insecure
-    -v --version       Prints the version of this command
+    -c --config-file=<value>      3scale toolbox configuration file (default:
+                                  /home/eguzki/.3scalerc.yaml)
+    -h --help                     show help for this command
+    -k --insecure                 Proceed and operate even for server
+                                  connections otherwise considered insecure
+    -v --version                  Prints the version of this command
 ```
 
 ### Copy a service
-Will create a new services, copy existing proxy settings, metrics, methods, application plans and mapping rules.
+Will create a new service, copy existing proxy settings, metrics, methods, application plans and mapping rules.
+
+3scale instances can be either a [URL](docs/remotes.md#remote-urls) or the name of a [remote](docs/remotes.md).
 
 Help message:
 
@@ -62,10 +72,10 @@ DESCRIPTION
     methods, application plans and mapping rules.
 
 OPTIONS
-    -d --destination=<value>             3scale target instance. Format:
-                                         "http[s]://<provider_key>@3scale_url"
-    -s --source=<value>                  3scale source instance. Format:
-                                         "http[s]://<provider_key>@3scale_url"
+    -d --destination=<value>             3scale target instance. Url or
+                                         remote name
+    -s --source=<value>                  3scale source instance. Url or
+                                         remote name
     -t --target_system_name=<value>      Target system name
 
 OPTIONS FOR COPY
@@ -77,13 +87,15 @@ OPTIONS FOR COPY
 ```
 
 ```shell
-3scale copy service NUMBER --source=https://provider_key@foo-admin.3scale.net --destination=https://provider_key@foo2-admin.3scale.net
+3scale copy service NUMBER --source=foo --destination=https://access_token@foo2-admin.3scale.net
 ```
 
 ### Update a service
 
 Will update existing service, update proxy settings, metrics, methods, application plans and mapping rules.
 
+3scale instances can be either a [URL](docs/remotes.md#remote-urls) or the name of a [remote](docs/remotes.md).
+
 Help message:
 
 ```shell
@@ -99,13 +111,13 @@ DESCRIPTION
     application plans and mapping rules.
 
 OPTIONS
-    -d --destination=<value>      3scale target instance. Format:
-                                  "http[s]://<provider_key>@3scale_url"
+    -d --destination=<value>      3scale target instance. Url or
+                                  remote name
     -f --force                    Overwrites the mapping rules by deleting
                                   all rules from target service first
     -r --rules-only               Updates only the mapping rules
-    -s --source=<value>           3scale source instance. Format:
-                                  "http[s]://<provider_key>@3scale_url"
+    -s --source=<value>           3scale source instance. Url or
+                                  remote name
 
 OPTIONS FOR UPDATE
     -h --help                     show help for this command
@@ -117,13 +129,15 @@ OPTIONS FOR UPDATE
 Example:
 
 ```shell
-$ 3scale update service -s https://9874598743@source.example.com -d https://2342342342342@destination.example.com 3 2
+$ 3scale update service -s https://9874598743@source.example.com -d foo 3 2
 ```
 
 ### Import from CSV
 
 Will create new services, metrics, methods, and mapping rules having as source comma separated values (CSV) formatted file.
 
+3scale instances can be either a [URL](docs/remotes.md#remote-urls) or the name of a [remote](docs/remotes.md).
+
 CSV header
 
 ```csv
@@ -153,8 +167,7 @@ DESCRIPTION
     formatted file
 
 OPTIONS
-    -d --destination=<value>      3scale target instance. Format:
-                                  "http[s]://<provider_key>@3scale_url"
+    -d --destination=<value>      3scale target instance. Url or remote name
     -f --file=<value>             CSV formatted file
 
 OPTIONS FOR IMPORT
@@ -170,12 +183,119 @@ Example:
 3scale import csv --destination=https://provider_key@user-admin.3scale.net --file=examples/import_example.csv
 ```
 
+### Import OpenAPI
+
+Using an API definition format like OpenAPI, import to your 3scale API
+
+Currently, only OpenAPI __2.0__ specification (f.k.a. __swagger__) is supported.
+
+[Import from OpenAPI](docs/openapi.md)
+
+### Remotes
+
+Manage set of 3scale instances.
+
+[Howto](docs/remotes.md)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. Run `bundle exec 3scale` to use the gem in this directory, ignoring other installed copies of this gem.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Testing
+
+To run all tests run `rake`.
+
+There are two kinds of tests:
+* unit (see [spec/unit](spec/unit))
+```bash
+rake spec:unit
+```
+
+* integration (see [spec/integration](spec/integration)).
+```bash
+rake spec:integration
+```
+
+Integration tests can be run locally or against a real 3scale account.
+When details of the account are set via environment variables,
+integration tests are run agains given account.
+Otherwise, tests are run locally with mocked 3scale clients.
+
+The easiest way to set everything up is it to have a `.env` file in the root of the project with the following environment variables (set your own values):
+
+```
+ENDPOINT=https://your-domain-admin.3scaledomain
+PROVIDER_KEY=abc123
+VERIFY_SSL=true (by default true)
+```
+### Develop Core Command
+
+Very simple core command to list existing services.
+Helps to illustrate basic command code structure and helper methods to deal with remotes.
+
+```
+$ cat lib/3scale_toolbox/commands/service_list_command.rb
+module ThreeScaleToolbox
+  module Commands
+    class ServiceListCommand < Cri::CommandRunner
+      include ThreeScaleToolbox::Command
+
+      def self.command
+        Cri::Command.define do
+          name        'service_list'
+          usage       'service_list <3scale_remote>'
+          summary     'service list'
+          description 'list available services'
+          param       :remote
+          runner ServiceListCommand
+        end
+      end
+
+      def run
+        puts threescale_client(arguments[:remote]).list_services
+      end
+    end
+  end
+end
+```
+A few things worth highlighting:
+- Your module must include the *ThreeScaleToolbox::Command* module. It allows your command to be added to the toobox command tree.
+- You must implement the `command` module function and return an instance of `Cri::Command` from [cri](https://github.com/ddfreyne/cri)
+- `threescale_client` helper method returns *3scale API* client instance. All the process remote parsing, fetching from remote list and client instantiation is done out of the box.
+
+Then register the core command in `lib/3scale_toolbox/commands.rb`
+```
+--- a/lib/3scale_toolbox/commands.rb
++++ b/lib/3scale_toolbox/commands.rb
+@@ -4,6 +4,7 @@ require '3scale_toolbox/commands/copy_command'
+ require '3scale_toolbox/commands/import_command'
+ require '3scale_toolbox/commands/update_command'
+ require '3scale_toolbox/commands/remote_command'
++require '3scale_toolbox/commands/service_list_command'
+
+ module ThreeScaleToolbox
+   module Commands
+@@ -12,7 +13,8 @@ module ThreeScaleToolbox
+       ThreeScaleToolbox::Commands::CopyCommand,
+       ThreeScaleToolbox::Commands::ImportCommand,
+       ThreeScaleToolbox::Commands::UpdateCommand,
+-      ThreeScaleToolbox::Commands::RemoteCommand::RemoteCommand
++      ThreeScaleToolbox::Commands::RemoteCommand::RemoteCommand,
++      ThreeScaleToolbox::Commands::ServiceListCommand
+     ].freeze
+   end
+ end
+```
+
+Running the new core command:
+
+```shell
+$ 3scale service_list my-3scale-instance
+{ ... }
+```
+
 ## Plugins
 
 As of 3scale Toolbox 0.5.0, 3scale Toolbox will load plugins installed in gems or $LOAD_PATH. Plugins are discovered via Gem::find_files then loaded.

data/exe/3scale

@@ -1,8 +1,15 @@
 #!/usr/bin/env ruby
 
-require '3scale_toolbox'
-require '3scale_toolbox/cli'
+def suppress_warnings
+  original_verbosity = $VERBOSE
+  $VERBOSE = nil
+  yield
+ensure
+  $VERBOSE = original_verbosity
+end
+
+suppress_warnings { require '3scale_toolbox' }
 
 args = ARGV.clone
 
-ThreeScaleToolbox::CLI.run args
+exit(ThreeScaleToolbox::CLI.run(args))

data/lib/3scale_toolbox.rb

@@ -1,4 +1,17 @@
+require '3scale_toolbox/version'
+require '3scale_toolbox/helper'
+require '3scale_toolbox/error'
+require '3scale_toolbox/configuration'
+require '3scale_toolbox/remotes'
+require '3scale_toolbox/3scale_client_factory'
+require '3scale_toolbox/entities'
+require '3scale_toolbox/tasks'
+require '3scale_toolbox/base_command'
+require '3scale_toolbox/commands'
+require '3scale_toolbox/cli'
+
 module ThreeScaleToolbox
+
   def self.load_plugins
     plugin_paths.each { |plugin_path| require plugin_path }
   end
@@ -6,4 +19,9 @@ module ThreeScaleToolbox
   def self.plugin_paths
     Gem.find_files('3scale_toolbox_plugin')
   end
+
+  def self.default_config_file
+    # THREESCALE_CLI_CONFIG env var has priority over $HOME/.3scalerc.yaml file
+    ENV['THREESCALE_CLI_CONFIG'] || File.join(Gem.user_home, '.3scalerc.yaml')
+  end
 end

data/lib/3scale_toolbox/3scale_client_factory.rb

@@ -0,0 +1,33 @@
+module ThreeScaleToolbox
+  class ThreeScaleClientFactory
+    class << self
+      def get(remotes, remote_str, verify_ssl)
+        new(remotes, remote_str, verify_ssl).call
+      end
+    end
+
+    attr_reader :remotes, :remote_str, :verify_ssl
+
+    def initialize(remotes, remote_str, verify_ssl)
+      @remotes = remotes
+      @remote_str = remote_str
+      @verify_ssl = verify_ssl
+    end
+
+    def call
+      begin
+        remote = Remotes.from_uri(remote_str)
+      rescue InvalidUrlError
+        remote = remotes.fetch(remote_str)
+      end
+
+      remote_client(remote.merge(verify_ssl: verify_ssl))
+    end
+
+    private
+
+    def remote_client(endpoint:, authentication:, verify_ssl:)
+      ThreeScale::API.new(endpoint: endpoint, provider_key: authentication, verify_ssl: verify_ssl)
+    end
+  end
+end

data/lib/3scale_toolbox/base_command.rb

@@ -1,28 +1,66 @@
 
 module ThreeScaleToolbox
   module Command
-    def subcommands
-      @subcommands ||= []
+    def self.included(base)
+      base.extend(ClassMethods)
     end
 
-    def add_subcommand(command)
-      subcommands << command
+    module ClassMethods
+      def subcommands
+        @subcommands ||= []
+      end
+
+      def add_subcommand(command)
+        subcommands << command
+      end
+
+      ##
+      # Override to command
+      #
+      def command
+        raise Exception, 'base command has no command definition'
+      end
+
+      ##
+      # Iterate recursively over command tree
+      #
+      def build_command
+        subcommands.each_with_object(command) do |subcommand, root_command|
+          root_command.add_command(subcommand.build_command)
+        end
+      end
     end
 
-    ##
-    # Override to command
-    #
-    def command
-      raise Exception, 'base command has no command definition'
+    def config
+      @config ||= ThreeScaleToolbox::Configuration.new(config_file)
+    end
+
+    def config_file
+      options[:'config-file']
+    end
+
+    def remotes
+      @remotes ||= Remotes.new(config)
     end
 
     ##
-    # Iterate recursively over command tree
+    # Input param can be endpoint url or remote name
     #
-    def build_command
-      subcommands.each_with_object(command) do |subcommand, root_command|
-        root_command.add_command(subcommand.build_command)
-      end
+    def threescale_client(str)
+      ThreeScaleClientFactory.get(remotes, str, verify_ssl)
+    end
+
+    def verify_ssl
+      # this is flag. It is either true or false. Cannot be nil
+      !options[:insecure]
+    end
+
+    def exit_with_message(message)
+      raise ThreeScaleToolbox::Error, message
+    end
+
+    def fetch_required_option(key)
+      options.fetch(key) { exit_with_message "error: Missing argument #{key}" }
     end
   end
 end

data/lib/3scale_toolbox/cli.rb

@@ -1,5 +1,4 @@
-require '3scale_toolbox'
-require '3scale_toolbox/commands'
+require '3scale_toolbox/cli/error_handler'
 
 module ThreeScaleToolbox::CLI
   def self.root_command
@@ -14,9 +13,31 @@ module ThreeScaleToolbox::CLI
     ThreeScaleToolbox::Commands::BUILTIN_COMMANDS.each(&method(:add_command))
   end
 
+  def self.install_signal_handlers
+    # Set exit handler
+    %w[INT TERM].each do |signal|
+      Signal.trap(signal) do
+        puts
+        exit!(0)
+      end
+    end
+
+    # Set stack trace dump handler
+    if !defined?(RUBY_ENGINE) || RUBY_ENGINE != 'jruby'
+      Signal.trap('USR1') do
+        puts 'Caught USR1; dumping a stack trace'
+        puts caller.map { |i| "  #{i}" }.join("\n")
+      end
+    end
+  end
+
   def self.run(args)
-    load_builtin_commands
-    ThreeScaleToolbox.load_plugins
-    root_command.build_command.run args
+    install_signal_handlers
+    err = ErrorHandler.error_watchdog do
+      load_builtin_commands
+      ThreeScaleToolbox.load_plugins
+      root_command.build_command.run args
+    end
+    err.nil? ? 0 : 1
   end
 end