Birst_Command 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6bad6616cef05fab628640a4acabc9b7c219baf4
-  data.tar.gz: d4e2bf27651cf4ef20d1038b064ee8f7f4b83bbe
+  metadata.gz: a54ea884b6fdfe9bdcb8e1927c3bfa1bc48d80c0
+  data.tar.gz: 643fea5022b6b6f58a616462dbbf1ea053ad0e7e
 SHA512:
-  metadata.gz: b3d0ba0d5ad7a2609aefde09576f90fe927a3caaeba804967510cfce381271878069e9524d1e72502c6b777c61a84ffa9376771ba715888a35bbe5af81372e5f
-  data.tar.gz: fa825d4847ec8e2d6dc06b7af1992e6e3f352f030649e64135bb622f51a3d5d5e156b7d38e5fa7f104ed7daae657350ea70f1a8c3521504923042c2222f46077
+  metadata.gz: 79b9f9032f8d8a9acfd3782560b9bc2a3f2164dc9862f3f9cb5c53c59156fbba418306c467a55fb99a8f8b3904c4487e0e0e647cbc08f5b7811268d8594d663d
+  data.tar.gz: 9563a4c7d0cced6aa03c3e4351ced654d56cce4286a2f30112358ba68448dab83b944b597fbca04c214896d8b3c837bbf61806515feaa4c22e09f7c713332cca

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Birst_Command.gemspec

@@ -1,7 +1,7 @@
-# -*- encoding: utf-8 -*-
+# -*- encoding: utf-8 mode: ruby -*-
 $:.push File.expand_path("../lib", __FILE__)
 
-require 'Birst_Command/version'
+require 'birst_command/version'
 
 Gem::Specification.new do |s|
   s.name        = "Birst_Command"
@@ -15,9 +15,10 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "Birst_Command"
 
   s.required_ruby_version = '~> 2'
-  s.add_runtime_dependency "savon", ["~> 2.0"]
+  s.add_runtime_dependency "savon", ["~> 2.5"]
   s.add_runtime_dependency "httpclient", ["~> 2.3"]
   s.add_runtime_dependency "envcrypt", ["~> 0.1"]
+  s.add_runtime_dependency "configatron", ["~> 3.2"]
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+Changelog
+==============
+
+### v0.6.0
+- Config file now uses YAML instead of JSON
+
+- Replaced the `Config` module with a `Settings` constant that uses
+  [Configatron](https://github.com/markbates/configatron) to configure
+  default settings for all subsequent sessions.
+
+- Remove the `start` method of `Birst_Command::Session`.  Sessions are now
+  created using `new`.  All arguments use `Settings` as defaults, but can
+  be overridden on a session-by-session basis.
+
+- Renamed `Session#token` to `Session#login_token`.
+
+- Renamed `Session#auth_cookies` to `Session#auth_cookie`.
+
+- Replaced `Session` option `use_cookie` with `auth_cookie`.
+
+
+### v0.5.0
+- Migrated password handling to use Envcrypt

data/Gemfile

@@ -1,4 +1,8 @@
+# -*- mode: ruby -*-
 source 'https://rubygems.org'
-gem 'savon', '~> 2.0'
-gem 'httpclient'
-gem 'envcrypt', '~> 0.1'
+ruby '2.0.0'
+
+gemspec
+group :development do
+  gem 'rspec', '~> 2.14'
+end

data/Gemfile.lock

@@ -0,0 +1,65 @@
+PATH
+  remote: .
+  specs:
+    Birst_Command (0.6.0)
+      configatron (~> 3.2)
+      envcrypt (~> 0.1)
+      httpclient (~> 2.3)
+      savon (~> 2.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    akami (1.2.2)
+      gyoku (>= 0.4.0)
+      nokogiri
+    builder (3.2.2)
+    configatron (3.2.0)
+    diff-lcs (1.2.5)
+    envcrypt (0.1.0)
+    gyoku (1.1.1)
+      builder (>= 2.1.2)
+    httpclient (2.4.0)
+    httpi (2.1.0)
+      rack
+      rubyntlm (~> 0.3.2)
+    macaddr (1.7.1)
+      systemu (~> 2.6.2)
+    mime-types (1.25.1)
+    mini_portile (0.6.0)
+    nokogiri (1.6.2.1)
+      mini_portile (= 0.6.0)
+    nori (2.4.0)
+    rack (1.5.2)
+    rspec (2.99.0)
+      rspec-core (~> 2.99.0)
+      rspec-expectations (~> 2.99.0)
+      rspec-mocks (~> 2.99.0)
+    rspec-core (2.99.0)
+    rspec-expectations (2.99.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.99.0)
+    rubyntlm (0.3.4)
+    savon (2.5.1)
+      akami (~> 1.2.0)
+      builder (>= 2.1.2)
+      gyoku (~> 1.1.0)
+      httpi (~> 2.1.0)
+      nokogiri (>= 1.4.0)
+      nori (~> 2.4.0)
+      uuid (~> 2.3.7)
+      wasabi (~> 3.3.0)
+    systemu (2.6.4)
+    uuid (2.3.7)
+      macaddr (~> 1.0)
+    wasabi (3.3.0)
+      httpi (~> 2.0)
+      mime-types (< 2.0.0)
+      nokogiri (>= 1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  Birst_Command!
+  rspec (~> 2.14)

data/README.md

@@ -11,8 +11,8 @@ Birst user that needed to set up a very basic Ruby interface.
 
 # Installation & Setup
 
-**SPECIAL NOTE:** Password management has changed since version 0.4.0.
-Read below for details.
+**SPECIAL NOTE:** Many changes since version 0.5.0.  Read the
+  [Changelog](CHANGELOG.md).
 
 Prerequisites: Ruby > 2.0 and rubygems.
 
@@ -21,15 +21,18 @@ rbenv/bundler as you prefer.
 
 After installing, you'll need to create a Birst Command config file
 that contains the credentials you'll use to connect to Birst.  This
-config file should look like,
-
-    {
-        "wsdl": "https://app2102.bws.birst.com/CommandWebService.asmx?WSDL",
-        "endpoint": "https://app2102.bws.birst.com/CommandWebService.asmx",
-        "username": "name@myplace.com",
-        "password": "encrypted pwd"
-    }
-
+is a yaml file that should look something like
+
+````yaml
+---
+session:
+  wsdl: "https://app2101.bws.birst.com/CommandWebService.asmx?WSDL"
+  endpoint: "https://app2101.bws.birst.com/CommandWebService.asmx"
+  username: "BirstUsername"
+  password: "EncryptedPassword"
+  soap_log: true
+  soap_log_level: :debug
+````
 Save it to `$HOME/.birstcl`.  Most users should only need to modify
 the username and password. (**Note**: do not use `login.bws.birst.com`
 since it does not use an updated WSDL; a specific app server must be
@@ -56,6 +59,15 @@ Copy and paste the encrypted password (aka "secret') into the
 running in a development environment, you can include these in your
 bash `~/.profile` file.
 
+Also note that the YAML config file is pre-processed with ERB.  So if
+you also want to keep your encrypted password in an environment
+variable, you could replace the `password` line above with
+````yaml
+  ...
+  password: "<%= ENV['MY_ENCRYPTED_PASSWORD'] %>"
+  ...
+````
+
 # Usage - Birst command line tool
 
 Birst Command also installs a rudimentary command line tool for interacting
@@ -106,9 +118,13 @@ In your Ruby program, include the Birst Command gem and load the config file via
 ````ruby
 require 'rubygems'
 require 'bundler/setup'
-require 'Birst_Command'
+require 'birst_command'
+
+Birst_Command.load_settings_from_file(file)
+
+# Or you can forego the settings file and set them explicitly in code via
+Birst_Command::Settings.session.username = "George"
 
-Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"config.json"))
 ````
 
 Birst commands are submitted in session blocks, which automatically
@@ -117,7 +133,7 @@ logging out.  For example, to list all spaces that you have rights to,
 you can submit the following code
 
 ````ruby
-Birst_Command::Session.start do |bc|
+Birst_Command::Session.new do |bc|
   spaces = bc.list_spaces
   puts "#{JSON.pretty_generate spaces}"
 end
@@ -153,7 +169,7 @@ as an argument hash.  All arguments are mandatory even if they're blank/null
 (Birst web API requirement).  For example, to create a new space,
 
 ````ruby
-Birst_Command::Session.start do |bc|
+Birst_Command::Session.new do |bc|
   new_space_id = bc.create_new_space :spaceName => "myNewSpace", :comments => "Just testing",:automatic => "false"
 end
 ````
@@ -167,16 +183,16 @@ a copy job and save the `session_cookie` and `job_token` in variables.
 ````ruby
 session_cookie = nil
 job_token = nil
-Session.start do |bc|
+Bist_Command::Session.new do |bc|
   job_token = bc.copy_space :spFromID => @from_id, :spToID => @to_id, :mode => "replicate", :options => "data;datastore;useunloadfeature"
-  session_cookie = bc.auth_cookies
+  session_cookie = bc.auth_cookie
 end
 ````
 In a subsequent session we can use the `session_cookie` on login via
 
 ````ruby
 is_job_complete = false
-Session.start use_cookie: session_cookie do |bc|
+Birst_Command::Session.new auth_cookie: session_cookie do |bc|
   is_job_complete = bc.is_job_complete :jobToken => job_token
 end
 puts "COMPLETE? #{is_job_complete}"
@@ -224,8 +240,3 @@ entirely consistent in its use of camelCase for arguments (e.g.,
 `listUsersInSpace`).  This inconsistency requires us to **submit
 commands as snake_case and arguments as the camelCase that Birst
 uses.**
-
-# Changelog
-
-* 0.5.0
-  * Migrated password handling to use Envcrypt

data/Rakefile

@@ -1,14 +1 @@
 # -*- mode: ruby -*-
-
-require 'rake/testtask'
-
-task :default => [:test_all]
-
-# Run a specific unit test with `rake test TEST=test/Datalib/test_datalib.rb`
-Rake::TestTask.new do |t|
-
-  t.libs << "test"
-  t.test_files = FileList['test/*/test_*.rb']
-  t.verbose = true
-
-end

data/bin/birstcl

@@ -50,13 +50,6 @@ module BirstCL
         @options[:arguments] = eval(opt)
       end
 
-=begin
-      @options[:json_full_path] = nil
-      opts.on("-f","--file <JSON FILE>","Path to JSON file containing command") do |opt|
-        @options[:json_full_path] = opt
-      end
-=end
-
       @options[:config_full_path] = "#{ENV['HOME']}/.birstcl"
       opts.on("-s","--config_file <CONFIG FILE>", "Path to config file containing credentials (default: $HOME/.birstcl)") do |opt|
         @options[:config_full_path] = opt
@@ -76,7 +69,7 @@ module BirstCL
 
 
   def read_config_file
-    Birst_Command::Config.read_config(@options[:config_full_path])
+    Birst_Command.load_settings_from_file(@options[:config_full_path])
   end
 
   def write_cookie_file(file_full_path)
@@ -96,11 +89,11 @@ module BirstCL
 
     output[:command] = @options[:command]
     output[:arguments] = @options[:arguments]
-    Birst_Command::Session.start use_cookie: @session_cookie do |bc|
-      output[:token] = bc.token
-      output[:auth_cookies] = bc.auth_cookies.inspect
+    Birst_Command::Session.new auth_cookie: @session_cookie do |bc|
+      output[:login_token] = bc.login_token
+      output[:auth_cookies] = bc.auth_cookie.inspect
       output[:result] = bc.send(@options[:command], @options[:arguments])
-      @session_cookie = bc.auth_cookies
+      @session_cookie = bc.auth_cookie
     end
     puts "#{JSON.pretty_generate output}"
     write_cookie_file(@options[:write_cookie_full_path])

data/lib/birst_command.rb

@@ -5,8 +5,10 @@ require 'base64'
 require 'securerandom'
 require 'json'
 require 'envcrypt'
+require 'configatron/core'
+require 'erb'
 
-require 'birst_command/config'
+require 'birst_command/settings'
 require 'birst_command/core_additions'
 require 'birst_command/version'
 require 'birst_command/session'

data/lib/birst_command/core_additions.rb

@@ -6,3 +6,11 @@ class String
     gsub /^#{self[/\A\s*/]}/, ''
   end
 end
+
+class Object
+  def symbolize_keys
+    return self.inject({}){|memo,(k,v)| memo[k.to_sym] = v.symbolize_keys; memo} if self.is_a? Hash
+    return self.inject([]){|memo,v    | memo           << v.symbolize_keys; memo} if self.is_a? Array
+    return self
+  end
+end

data/lib/birst_command/session.rb

@@ -1,74 +1,137 @@
 module Birst_Command
-  class Session
-    def initialize
-      @options = Birst_Command::Config.options
-
-      @client = Savon.client(
-        wsdl: @options[:wsdl],
-        endpoint: @options[:endpoint],
-        convert_request_keys_to: :none,
-        soap_version: 1,
-        pretty_print_xml: true,
-        filters: [:password],
-        log_level: @options[:soap_log_level],
-        log: @options[:soap_log]
-      )
-
-      @response = nil
-      @token = nil
-      @auth_cookies = nil
-    end
-
-    attr_reader :token
-    attr_reader :auth_cookies
-    attr_reader :response
 
+  # Public: Session class used to interact with Birst Web Services
+  class Session
 
-    def self.start(use_cookie: nil, &b)
-      session = self.new
-      session.login(use_cookie: use_cookie)
-      session.execute_block(&b)
-    ensure
-      session.logout
+    # Public: Initialize Session class
+    #
+    # wsdl           - URL of soap WSDL (default: Settings.session.wsdl)
+    # endpoint       - URL of soap endpoint (default: Settings.session.endpoint)
+    # soap_log       - Boolean switch indicating whether logging should be performed (default: Settings.session.soap_log)
+    # soap_logger    - Logger instance used to write log messages (default: Settings.session.soap_logger)
+    # soap_log_level - Logging level (default: Settings.session.soap_log_level)
+    # username       - Username to use to login to Birst Web Services (default: Settings.session.username)
+    # password       - Encrypted password for username (default: Settings.session.password)
+    # auth_cookie    - Use a previously generated authorization cookie
+    #
+    # Returns nothing
+    def initialize(opts = {}, &block)
+      @login_token = nil
+      @options = set_options(opts)
+      @client = new_client
+
+      if block_given?
+        login_and_run(&block)
+      end
     end
 
+    attr_reader :login_token
+    attr_reader :auth_cookie
 
-    def login(use_cookie: nil)
-      crypt = Envcrypt::Envcrypter.new
 
-      @auth_cookies = use_cookie
-      @response = @client.call(:login,
-        cookies: @auth_cookies,
+    # Public: Login to Birst using the username and password.  After login,
+    # the auth cookie and login token are captured and stored as an instance
+    # variable.
+    #
+    # Returns the Savon response.
+    def login
+      response = @client.call(:login,
+        cookies: @auth_cookie,
         message: {
-          username: @options[:username], 
-          password: crypt.decrypt(@options[:password])
+          username: @username, 
+          password: decrypt(@password)
         })
 
-      @auth_cookies = @response.http.cookies if @auth_cookies.nil?
-      @token = @response.hash[:envelope][:body][:login_response][:login_result]      
-    end
-
-
-    def execute_block(&b)
-      yield self
+      @auth_cookie = response.http.cookies if @auth_cookie.nil?
+      @login_token = response.hash[:envelope][:body][:login_response][:login_result]
+      response
     end
 
-
+    # Public: Method missing used to send commands to Birst Web Services.
+    #
+    # command_name - Symbol representing the name of the Birst command (snake_case)
+    # *args - Optional arguments that are passed to the Birst command.
+    #
+    # Returns - The soap result as a hash
     def method_missing(command_name, *args)
       command command_name, *args
     end
 
-
+    # Public: Runs the command that is obtained from the method_missing call.
+    #
+    # command_name - Name of Birst command (snake_case).
+    # *args - Optional arguments that are passed to the Birst command.
+    #
+    # Returns - The soap result as a hash
     def command(command_name, *args)
       response_key = "#{command_name}_response".to_sym
       result_key = "#{command_name}_result".to_sym
 
       message = args.last.is_a?(Hash) ? args.pop : {}
       result = @client.call command_name,
-                            cookies: @auth_cookies,
-                            message: { :token => @token }.merge(message)
+                            cookies: @auth_cookie,
+                            message: { :token => @login_token }.merge(message)
 
       result.hash[:envelope][:body][response_key][result_key]
     end
+
+    private
+
+    # Private: Reads in an options hash and applies global default Settings
+    # if applicable.  Options are converted into instance variables.
+    #
+    # Returns nothing.
+    def set_options(opts = {})
+      @wsdl           = opts[:wsdl]           || Settings.session.wsdl
+      @endpoint       = opts[:endpoint]       || Settings.session.endpoint
+      @soap_log       = opts[:soap_log]       || Settings.session.soap_log
+      @soap_logger    = opts[:soap_logger]    || Settings.session.soap_logger
+      @soap_log_level = opts[:soap_log_level] || Settings.session.soap_log_level
+      @username       = opts[:username]       || Settings.session.username
+      @password       = opts[:password]       || Settings.session.password
+      @auth_cookie    = opts[:auth_cookie]    || nil
+    end
+
+
+    # Private: Create a new Savon SOAP client.
+    #
+    # Returns a Savon instance configured with options specified in initialize.
+    def new_client
+      Savon.client(
+        wsdl:                    @wsdl,
+        endpoint:                @endpoint,
+        convert_request_keys_to: :none,
+        soap_version:            1,
+        pretty_print_xml:        true,
+        filters:                 [:password],
+        logger:                  @soap_logger,
+        log_level:               @soap_log_level,
+        log:                     @soap_log
+      )
+    end
+
+
+    # Private: Login, run session commands specified in block, log out.
+    #
+    # &block - The block from the constructor is passed here and executed.
+    #
+    # Returns nothing.
+    def login_and_run(&block)
+      login
+      yield self
+    ensure
+      logout
+    end
+
+
+    # Private: Decrypt encrypted password (via Envcrypt).
+    #
+    # password - encrypted password.
+    #
+    # Returns decrypted password.
+    def decrypt(password)
+      crypt = Envcrypt::Envcrypter.new
+      crypt.decrypt(password)
+    end
   end
 end