testingbot 0.2.2 → 1.0.0

data/bin/testingbot

@@ -1,19 +1,40 @@
 #!/usr/bin/env ruby
 
+begin
+  require 'io/console'
+rescue LoadError
+  # io/console is unavailable (e.g. some JRuby builds); fall back to plain gets.
+end
+
 if ARGV.any?
-  api_key, api_secret = ARGV.first.split(':')
+  api_key, api_secret = ARGV.first.split(':', 2)
 else
-  
-  p "This utility will help you set up your system to use TestingBot's infrastructure."
-  p "Once you have entered your API key and secret you will be ready to use our grid"
-  p "You can get these credentials from the TestingBot dashboard: https://testingbot.com/members"
+  puts "This utility will help you set up your system to use TestingBot's infrastructure."
+  puts "Once you have entered your API key and secret you will be ready to use our grid."
+  puts "You can get these credentials from the TestingBot dashboard: https://testingbot.com/members"
+
+  print "Please enter your TestingBot API KEY: "
+  api_key = (gets || '').chomp
 
-  p "Please enter your testingbot API KEY:"
-  api_key = gets.chomp
-  p "Please enter your testingbot API SECRET:"
-  api_secret = gets.chomp
+  print "Please enter your TestingBot API SECRET: "
+  api_secret =
+    if $stdin.respond_to?(:noecho) && $stdin.tty?
+      value = $stdin.noecho(&:gets)
+      puts
+      (value || '').chomp
+    else
+      (gets || '').chomp
+    end
 end
 
-File.open(File.expand_path("~/.testingbot"), 'w') {|f| f.write("#{api_key}:#{api_secret}") }
+if api_key.to_s.empty? || api_secret.to_s.empty?
+  abort "Both an API key and secret are required. Nothing was written."
+end
+
+config_file = File.join(Dir.home, ".testingbot")
+File.open(config_file, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+  f.write("#{api_key}:#{api_secret}")
+end
+File.chmod(0o600, config_file)
 
-p "Your system is now ready to use TestingBot's grid infrastructure."
+puts "Your system is now ready to use TestingBot's grid infrastructure."

data/lib/testingbot/api.rb

@@ -1,230 +1,155 @@
+require 'cgi'
+require 'uri'
+require 'digest'
 require 'json'
-require "rest-client"
 
-module TestingBot
+require 'testingbot/errors'
+require 'testingbot/connection'
+
+require 'testingbot/resources/user'
+require 'testingbot/resources/team'
+require 'testingbot/resources/platform'
+require 'testingbot/resources/tests'
+require 'testingbot/resources/builds'
+require 'testingbot/resources/screenshots'
+require 'testingbot/resources/tunnels'
+require 'testingbot/resources/storage'
+require 'testingbot/resources/jobs'
+require 'testingbot/resources/lab'
+require 'testingbot/resources/lab_suites'
+require 'testingbot/resources/sharing'
 
+module TestingBot
+  # Ruby client for the TestingBot REST API (https://testingbot.com/support/api).
+  #
+  # Credentials are resolved, in order, from: explicit arguments, the
+  # ~/.testingbot file, the TESTINGBOT_KEY/TESTINGBOT_SECRET environment
+  # variables, then TB_KEY/TB_SECRET.
+  #
+  # Endpoint methods live in the TestingBot::Resources::* mixins (one per API
+  # category) and are included below; they call the private get/post/put/delete
+  # helpers and @connection. Transport (timeouts, retries, error handling) lives
+  # in TestingBot::Connection; a custom connection can be injected via
+  # options[:connection] for testing.
   class Api
-
-    VERSION = 1
-    API_URL = "https://api.testingbot.com"
+    # Public API version used in the URL path (https://api.testingbot.com/v1/...).
+    API_URL     = Connection::API_URL
+    API_VERSION = Connection::API_VERSION
+    # Deprecated alias kept for backward compatibility (this is the *API* version,
+    # not the gem version — see TestingBot::VERSION for the gem version).
+    VERSION = API_VERSION
+
+    include Resources::User
+    include Resources::Team
+    include Resources::Platform
+    include Resources::Tests
+    include Resources::Builds
+    include Resources::Screenshots
+    include Resources::Tunnels
+    include Resources::Storage
+    include Resources::Jobs
+    include Resources::Lab
+    include Resources::LabSuites
+    include Resources::Sharing
 
     attr_reader :key, :secret, :options
 
     def initialize(key = nil, secret = nil, options = {})
-      @key = key
-      @secret = secret
-      @options = {
-        :debug => false
-      }.merge(options)
-      if @key.nil? || @secret.nil?
-        cached_credentials = load_config_file
-        @key, @secret = cached_credentials unless cached_credentials.nil?
-      end
-
-      if @key.nil? || @secret.nil?
-        @key = ENV["TESTINGBOT_KEY"] if ENV["TESTINGBOT_KEY"]
-        @secret = ENV["TESTINGBOT_SECRET"] if ENV["TESTINGBOT_SECRET"]
-      end
-
-      if @key.nil? || @secret.nil?
-        @key = ENV["TB_KEY"] if ENV["TB_KEY"]
-        @secret = ENV["TB_SECRET"] if ENV["TB_SECRET"]
-      end
+      @options = { :debug => false }.merge(options)
+      @key     = key
+      @secret  = secret
+      resolve_credentials!
 
-      raise "Please supply a TestingBot Key" if @key.nil?
+      raise "Please supply a TestingBot Key"    if @key.nil?
       raise "Please supply a TestingBot Secret" if @secret.nil?
-    end
-
-    def get_user_info
-      get("/user")
-    end
 
-    def get_browsers
-      get("/browsers")
+      @connection = @options[:connection] ||
+                    Connection.new(key: @key, secret: @secret, options: @options)
     end
 
-    def get_devices
-      get("/devices")
-    end
+    private
 
-    def get_available_devices
-      get("/devices/available")
+    def get(path)
+      @connection.request(:get, path)
     end
 
-    def update_user_info(params = {})
-      new_params = {}
-      params.keys.each do |key|
-        new_params["user[#{key}]"] = params[key]
-      end
-      response = put("/user", new_params)
-      response["success"]
+    def post(path, params = {})
+      @connection.request(:post, path, params)
     end
 
-    def get_tests(offset = 0, count = 10)
-      get("/tests?offset=#{offset}&count=#{count}")
+    def put(path, params = {})
+      @connection.request(:put, path, params)
     end
 
-    def get_test(test_id)
-      get("/tests/#{test_id}")
+    def delete(path, params = {})
+      @connection.request(:delete, path, params)
     end
 
-    def update_test(test_id, params = {})
-      new_params = {}
-      params.keys.each do |key|
-        new_params["test[#{key}]"] = params[key]
+    # Wrap a flat hash under a bracketed prefix, e.g. wrap_params("test", name: "x")
+    # => { "test[name]" => "x" } — the form encoding the Rails-style backend expects.
+    def wrap_params(prefix, params)
+      params.each_with_object({}) do |(key, value), memo|
+        memo["#{prefix}[#{key}]"] = value
       end
-      response = put("/tests/#{test_id}", new_params)
-      response["success"]
-    end
-
-    def delete_test(test_id)
-      response = delete("/tests/#{test_id}")
-      response["success"]
-    end
-
-    def stop_test(test_id)
-      response = put("/tests/#{test_id}/stop")
-      response["success"]
-    end
-
-    def get_builds(offset = 0, count = 10)
-      get("/builds?offset=#{offset}&count=#{count}")
-    end
-
-    def get_build(build_identifier)
-      get("/builds/#{build_identifier}")
-    end
-
-    def delete_build(build_identifier)
-      delete("/builds/#{build_identifier}")
-    end
-
-    def get_tunnels
-      get("/tunnel/list")
     end
 
-    def delete_tunnel(tunnel_identifier)
-      delete("/tunnel/#{tunnel_identifier}")
+    # Build a "?a=1&b=2" query string from a hash, dropping nil values and
+    # URL-encoding keys/values. Returns "" when nothing is left.
+    def query(params)
+      filtered = params.reject { |_, value| value.nil? }
+      return "" if filtered.empty?
+      "?" + URI.encode_www_form(filtered)
     end
 
-    def get_authentication_hash(identifier)
-      Digest::MD5.hexdigest("#{@key}:#{@secret}:#{identifier}")
+    # URL-encode a path segment (numeric IDs, session IDs, etc.).
+    def escape(value)
+      CGI.escape(value.to_s)
     end
 
-    def upload_local_file(file_path)
-      response = RestClient::Request.execute(
-        method: :post,
-        url: API_URL + "/v1/storage",
-        user: @key,
-        password: @secret,
-        timeout: 600,
-        payload: {
-          multipart: true,
-          file: File.new(file_path, 'rb')
-        }
-      )
-      parsed = JSON.parse(response.body)
-      parsed
+    # Strip the tb:// scheme from an app URL. The value targets a wildcard route,
+    # so any remaining slashes are intentionally preserved (not escaped).
+    def strip_scheme(app_url)
+      app_url.to_s.gsub(%r{tb://}, '')
     end
 
-    def upload_remote_file(url)
-      post("/storage/", {
-        :url => url
-      })
+    def success?(response)
+      response.is_a?(Hash) ? !!response["success"] : false
     end
 
-    def get_uploaded_files(offset = 0, count = 10)
-      get("/storage?offset=#{offset}&count=#{count}")
-    end
-
-    def get_uploaded_file(app_url)
-      get("/storage/#{app_url.gsub(/tb:\/\//, '')}")
-    end
-
-    def delete_uploaded_file(app_url)
-      response = delete("/storage/#{app_url.gsub(/tb:\/\//, '')}")
-      response["success"]
-    end
-
-    private
-
-    def load_config_file
-      is_windows = false
-
-      begin
-        require 'rbconfig'
-        is_windows = (RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/)
-      rescue
-        is_windows = (RUBY_PLATFORM =~ /w.*32/) || (ENV["OS"] && ENV["OS"] == "Windows_NT")
-      end
-      
-      if is_windows
-        config_file = "#{ENV['HOMEDRIVE']}\\.testingbot"
-      else
-        config_file = File.expand_path("#{Dir.home}/.testingbot")
-      end
-      
-      if File.exists?(config_file)
-        str = File.open(config_file) { |f| f.readline }.chomp
-        return str.split(':')
+    def resolve_credentials!
+      if @key.nil? || @secret.nil?
+        cached = load_config_file
+        @key, @secret = cached unless cached.nil?
       end
-      
-      return nil
-    end
-
-    def get(url)
-      uri = API_URL + '/v' + VERSION.to_s + url
 
-      response = RestClient::Request.execute method: :get, url: uri, user: @key, password: @secret
-      parsed = JSON.parse(response.body)
-
-      p parsed if @options[:debug]
-      if !parsed.is_a?(Array) && !parsed["error"].nil? && !parsed["error"].empty?
-        raise parsed["error"]
+      if @key.nil? || @secret.nil?
+        @key    = ENV["TESTINGBOT_KEY"]    if ENV["TESTINGBOT_KEY"]
+        @secret = ENV["TESTINGBOT_SECRET"] if ENV["TESTINGBOT_SECRET"]
       end
 
-      parsed
-    end
-
-    def put(url, params = {})
-      uri = API_URL + '/v' + VERSION.to_s + url
-
-      response = RestClient::Request.execute method: :put, url: uri, payload: params, user: @key, password: @secret
-      parsed = JSON.parse(response.body)
-
-      p parsed if @options[:debug]
-      if !parsed.is_a?(Array) && !parsed["error"].nil? && !parsed["error"].empty?
-        raise parsed["error"]
+      if @key.nil? || @secret.nil?
+        @key    = ENV["TB_KEY"]    if ENV["TB_KEY"]
+        @secret = ENV["TB_SECRET"] if ENV["TB_SECRET"]
       end
-
-      parsed
     end
 
-    def delete(url, params = {})
-      uri = API_URL + '/v' + VERSION.to_s + url
-      response = RestClient::Request.execute method: :delete, url: uri, payload: params, user: @key, password: @secret
-      parsed = JSON.parse(response.body)
+    def load_config_file
+      config_file = File.join(Dir.home, ".testingbot")
+      return nil unless File.exist?(config_file)
 
-      p parsed if @options[:debug]
-      if !parsed.is_a?(Array) && !parsed["error"].nil? && !parsed["error"].empty?
-        raise parsed["error"]
+      if insecure_permissions?(config_file)
+        warn("TestingBot: #{config_file} is readable by other users; run `chmod 600 #{config_file}`")
       end
 
-      parsed
+      str = File.open(config_file) { |f| f.readline }.chomp
+      # Split on the first colon only, so a secret containing ':' is preserved.
+      str.split(':', 2)
     end
 
-    def post(url, params = {})
-      uri = API_URL + '/v' + VERSION.to_s + url
-
-      response = RestClient::Request.execute method: :post, url: uri, payload: params, user: @key, password: @secret
-      parsed = JSON.parse(response.body)
-
-      p parsed if @options[:debug]
-      if !parsed.is_a?(Array) && !parsed["error"].nil? && !parsed["error"].empty?
-        raise parsed["error"]
-      end
-
-      parsed
+    def insecure_permissions?(path)
+      (File.stat(path).mode & 0o077) != 0
+    rescue StandardError
+      false
     end
   end
 end

data/lib/testingbot/connection.rb

@@ -0,0 +1,193 @@
+require 'json'
+require 'rest-client'
+
+require 'testingbot/errors'
+
+module TestingBot
+  # Transport layer for the TestingBot API.
+  #
+  # Owns the base URL, API version, credentials and HTTP client, and exposes a
+  # single +request+ entry point that every endpoint goes through. Centralising
+  # transport here means timeouts, retries/backoff, rate-limit handling, JSON
+  # parsing, error mapping and debug redaction all live in one place.
+  #
+  # The HTTP client is injectable (+http:+) so the gem can be unit-tested
+  # without real network access.
+  class Connection
+    API_URL     = "https://api.testingbot.com".freeze
+    API_VERSION = 1
+
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES  = 3
+
+    # Verbs safe to retry automatically. POST is excluded so we never replay a
+    # side-effecting create/upload.
+    IDEMPOTENT = [:get, :put, :delete].freeze
+
+    # Transient failures worth retrying on idempotent verbs.
+    RETRYABLE = [
+      RestClient::RequestTimeout,        # 408
+      RestClient::TooManyRequests,       # 429
+      RestClient::InternalServerError,   # 500
+      RestClient::BadGateway,            # 502
+      RestClient::ServiceUnavailable,    # 503
+      RestClient::GatewayTimeout,        # 504
+      RestClient::Exceptions::Timeout,   # open/read timeout
+      RestClient::ServerBrokeConnection,
+      SocketError,
+      Errno::ECONNRESET,
+      Errno::ECONNREFUSED,
+      Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT
+    ].freeze
+
+    # Response keys whose values are redacted in debug output.
+    REDACT_KEYS = %w[key secret api_key api_secret client_key token password].freeze
+
+    def initialize(key:, secret:, options: {}, http: RestClient::Request)
+      @key     = key
+      @secret  = secret
+      @options = options || {}
+      @http    = http
+    end
+
+    # Execute an HTTP request and return the parsed JSON body.
+    #
+    # verb   - one of :get, :post, :put, :delete
+    # path   - path after the version prefix, e.g. "/tests/123"
+    # params - request payload (ignored for :get and for empty payloads)
+    # opts   - per-call overrides, e.g. { timeout: 600 } for uploads
+    def request(verb, path, params = {}, opts = {})
+      idempotent = IDEMPOTENT.include?(verb)
+      attempt = 0
+
+      begin
+        parse(execute(verb, path, params, opts))
+      rescue *RETRYABLE => e
+        attempt += 1
+        if idempotent && attempt <= max_retries
+          sleep(delay_for(e, attempt))
+          retry
+        end
+        raise map_exception(e)
+      rescue RestClient::ExceptionWithResponse => e
+        raise map_exception(e)
+      end
+    end
+
+    private
+
+    def execute(verb, path, params, opts)
+      args = {
+        method:       verb,
+        url:          build_url(path),
+        user:         @key,
+        password:     @secret,
+        open_timeout: @options.fetch(:open_timeout, DEFAULT_OPEN_TIMEOUT),
+        read_timeout: @options.fetch(:read_timeout, DEFAULT_READ_TIMEOUT)
+      }
+      args[:timeout] = opts[:timeout] if opts[:timeout]
+      args[:payload] = params if verb != :get && !blank_payload?(params)
+      @http.execute(**args)
+    end
+
+    def parse(response)
+      body = response.body.to_s
+      return {} if body.strip.empty?
+
+      parsed = begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise ParseError.new(
+          "TestingBot API returned a non-JSON response (HTTP #{response.code}): #{body[0, 200]}",
+          http_status: response.code, body: body
+        )
+      end
+
+      log(parsed) if @options[:debug]
+
+      if parsed.is_a?(Hash) && !parsed["error"].to_s.empty?
+        raise ApiError.new(parsed["error"], http_status: response.code, body: body)
+      end
+
+      parsed
+    end
+
+    def build_url(path)
+      "#{API_URL}/v#{API_VERSION}#{path}"
+    end
+
+    def blank_payload?(params)
+      params.nil? || (params.respond_to?(:empty?) && params.empty?)
+    end
+
+    def max_retries
+      @options.fetch(:max_retries, DEFAULT_MAX_RETRIES)
+    end
+
+    def delay_for(error, attempt)
+      if error.is_a?(RestClient::TooManyRequests)
+        seconds = retry_after(error)
+        return [seconds, 120].min if seconds && seconds > 0
+      end
+      backoff(attempt)
+    end
+
+    # Exponential backoff (base 0.5s, doubling) with +/-20% jitter.
+    def backoff(attempt)
+      base   = 0.5 * (2**(attempt - 1))
+      jitter = base * 0.2
+      base + ((rand * 2) - 1) * jitter
+    end
+
+    def retry_after(error)
+      headers = error.response && error.response.headers
+      return nil unless headers
+      (headers[:retry_after] || headers["Retry-After"]).to_i
+    end
+
+    def map_exception(error)
+      case error
+      when RestClient::Unauthorized, RestClient::Forbidden
+        AuthenticationError.new(error.message, http_status: error.http_code, body: response_body(error))
+      when RestClient::ResourceNotFound
+        NotFoundError.new(error.message, http_status: error.http_code, body: response_body(error))
+      when RestClient::TooManyRequests
+        RateLimitError.new(error.message, http_status: error.http_code,
+                           body: response_body(error), retry_after: retry_after(error))
+      when RestClient::ExceptionWithResponse
+        code = error.http_code
+        klass = code && code >= 500 ? ServerError : ClientError
+        klass.new(error.message, http_status: code, body: response_body(error))
+      when RestClient::Exceptions::Timeout, SocketError, SystemCallError
+        ConnectionError.new(error.message)
+      else
+        Error.new(error.message)
+      end
+    end
+
+    def response_body(error)
+      error.response && error.response.body
+    rescue StandardError
+      nil
+    end
+
+    def log(parsed)
+      warn(redact(parsed).inspect)
+    end
+
+    def redact(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), memo|
+          memo[k] = REDACT_KEYS.include?(k.to_s.downcase) ? "[REDACTED]" : redact(v)
+        end
+      when Array
+        obj.map { |v| redact(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/testingbot/errors.rb

@@ -0,0 +1,52 @@
+module TestingBot
+  # Base class for every error raised by this gem. Rescue +TestingBot::Error+
+  # to catch any failure originating from the client.
+  #
+  # Instances carry the HTTP status (when the failure came from an HTTP
+  # response) and the raw response body for diagnostics.
+  class Error < StandardError
+    attr_reader :http_status, :body
+
+    def initialize(message = nil, http_status: nil, body: nil)
+      @http_status = http_status
+      @body = body
+      super(message)
+    end
+  end
+
+  # Network-level failure: connection refused/reset, DNS failure, or a
+  # request that exceeded the configured open/read timeout.
+  class ConnectionError < Error; end
+
+  # The API returned a body that could not be parsed as JSON (e.g. an HTML
+  # gateway/maintenance page) or an empty body where JSON was expected.
+  class ParseError < Error; end
+
+  # Any 4xx response that is not covered by a more specific subclass.
+  class ClientError < Error; end
+
+  # 401/403 — missing or invalid credentials, or an account lacking the
+  # required permission.
+  class AuthenticationError < ClientError; end
+
+  # 404 — the requested resource does not exist or does not belong to you.
+  class NotFoundError < ClientError; end
+
+  # 429 — the account hit the API rate limit. +retry_after+ exposes the
+  # server-provided Retry-After value (seconds) when present.
+  class RateLimitError < ClientError
+    attr_reader :retry_after
+
+    def initialize(message = nil, http_status: nil, body: nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message, http_status: http_status, body: body)
+    end
+  end
+
+  # 5xx — the API encountered a server-side error.
+  class ServerError < Error; end
+
+  # A 2xx response whose JSON body carried an application-level
+  # <tt>{"error": "..."}</tt> field.
+  class ApiError < Error; end
+end

data/lib/testingbot/resources/builds.rb

@@ -0,0 +1,21 @@
+module TestingBot
+  module Resources
+    # Endpoints under /builds.
+    module Builds
+      def get_builds(offset = 0, count = 10)
+        get("/builds#{query(:offset => offset, :count => count)}")
+      end
+
+      # +params+ accepts optional offset/count/skip_fields query params.
+      # The build identifier maps to a wildcard route, so it is passed through
+      # unescaped to preserve any slashes it may contain.
+      def get_build(build_identifier, params = {})
+        get("/builds/#{build_identifier}#{query(params)}")
+      end
+
+      def delete_build(build_identifier)
+        delete("/builds/#{build_identifier}")
+      end
+    end
+  end
+end

data/lib/testingbot/resources/jobs.rb

@@ -0,0 +1,11 @@
+module TestingBot
+  module Resources
+    # Endpoints under /jobs.
+    module Jobs
+      # Poll the status/result of an asynchronous job (e.g. a Codeless Lab run).
+      def get_job(job_id)
+        get("/jobs/#{escape(job_id)}")
+      end
+    end
+  end
+end