device_api 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 55ea06db2435c33d959c62aab352305c35a32864
+  data.tar.gz: 80d93f31e0607100e755fe6de7e97520a4486af9
+SHA512:
+  metadata.gz: e87c848043acf6f36d74a72a1e0ac6c698de8bb7fe4018444a43b561049ba86a04da195c155c1180366d9984b0e6e748b07b86e6ba5363ae0823b017a02be13e
+  data.tar.gz: 685aef3c25dcca463f9435146be72214eebfd7e61347bdbb52a12fad57db28bffe083923d503ffa177a365b4877aa6df47d2c0e2021da89965cd92f1727a861c

data/.gitignore

@@ -0,0 +1,38 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# rubymine
+.idea
+

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+group :test do 
+  gem 'rspec' 
+end
+

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 BBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# DeviceAPI
+
+*DeviceAPI* is a collection of gems that make working with physical devices easy
+and consistent. *DeviceAPI* provides common utilities such as device detection
+and identification, and useful helpers for installing applications and
+identifying problems with devices.
+
+We use *DeviceAPI* heavily to leverage devices in *Hive CI*. It’s also used by
+our test developers in their test code. It’s our interface to the devices we
+test against and is where we put all common code for interacting with our
+physical devices. It also provides an abstraction so we can deal with devices
+interchangeably.
+
+This is the base gem on which all *DeviceAPI* gems are built. It contains the
+common execution and logging methods, and the base Device class.
+
+## Testing
+
+Tests are written in rspec, you can run them with:
+    bundle install
+    bundle exec rspec
+
+## Creating a new DeviceAPI Gem
+
+*DeviceAPI* gems should take a consistent approach to their api where possible.
+
+A new *DeviceApi* gem should, as a minimum, include a detection method on the
+class. For example, a DeviceAPI implementation for TVs:
+
+    DeviceAPI::TV.devices
+    
+... should return an array of device objects of type DeviceAPI::TV.
+
+You should consider adding a way to directly detect a specific device, for
+example using the serial:
+
+    DeviceAPI::TV.device( serial_id )
+
+The device object should contain all accessors to the physical device
+information:
+
+    device.class  #=> DeviceAPI::TV
+    device.model  #=> 'sony'
+    device.serial # => 'a221s3144cc23'
+    
+And also expose functionality through the same object:
+
+    device.reboot()
+
+## License
+
+## License
+
+*DeviceAPI* is available to everyone under the terms of the MIT open source
+licence. Take a look at the LICENSE file in the code.
+
+Copyright (c) 2015 BBC

data/device_api.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |s|
+  s.name        = 'device_api'
+  s.version     = '1.0.1'
+  s.date        =  Time.now.strftime("%Y-%m-%d")
+  s.summary     = 'Physical Device Management API'
+  s.description = 'A common interface for physical devices'
+  s.authors     = ['BBC', 'David Buckhurst']
+  s.email       = 'david.buckhurst@bbc.co.uk'
+  s.files       = `git ls-files`.split "\n"
+  s.homepage    = 'https://github.com/bbc/device_api'
+  s.license     = 'MIT'
+  s.add_development_dependency 'rspec'
+end

data/lib/device_api.rb

@@ -0,0 +1,15 @@
+require 'device_api/sys_log'
+
+module DeviceAPI
+  attr_accessor :log
+
+  @@log = DeviceAPI::SysLog.new
+
+  def self.set_logger(log)
+    @@log = log
+  end
+
+  def self.log
+    @@log
+  end
+end

data/lib/device_api/device.rb

@@ -0,0 +1,6 @@
+# Encoding: utf-8
+module DeviceAPI
+  class Device
+    attr_accessor :serial
+  end
+end

data/lib/device_api/execution.rb

@@ -0,0 +1,79 @@
+# Encoding: utf-8
+require 'open3'
+require 'ostruct'
+require 'timeout'
+require 'device_api'
+
+module DeviceAPI
+  # Provides method to execute terminal commands in a reusable way
+  class Execution
+
+    # execute_with_timeout_and_retry constants
+    COMMAND_TIMEOUT = 30 # base number of seconds to wait until adb command times out
+    COMMAND_RETRIES = 5 # number of times we will retry the adb command.
+    # actual maximum seconds waited before timeout is
+    # (1 * s) + (2 * s) + (3 * s) ... up to (n * s)
+    # where s = COMMAND_TIMEOUT
+    # n = COMMAND_RETRIES
+
+    # Execute out to shell
+    # Returns a struct collecting the execution results
+    # struct = DeviceAPI::ADB.execute( 'adb devices' )
+    # struct.stdout #=> "std out"
+    # struct.stderr #=> ''
+    # strict.exit #=> 0
+    def self.execute(command)
+      result = OpenStruct.new
+
+      stdout, stderr, status = Open3.capture3(command)
+
+      result.exit = status.exitstatus
+      result.stdout = stdout
+      result.stderr = stderr
+
+      result
+    end
+
+    # Execute a command with retries if the command fails to return
+    def self.execute_with_timeout_and_retry(command)
+      retries_left = COMMAND_RETRIES
+      cmd_successful = false
+      result = 0
+
+      while (retries_left > 0) and (cmd_successful == false) do
+        begin
+          ::Timeout.timeout(COMMAND_TIMEOUT) do
+            result = execute(command)
+            cmd_successful = true
+          end
+        rescue ::Timeout::Error
+          retries_left -= 1
+          if retries_left > 0
+            DeviceAPI.log.error "Command #{command} timed out after #{COMMAND_TIMEOUT.to_s} sec, retrying,"\
+                + " #{retries_left.to_s} attempts left.."
+          end
+        end
+      end
+
+      if retries_left < COMMAND_RETRIES # if we had to retry
+        if cmd_successful == false
+          msg = "Command #{command} timed out after #{COMMAND_RETRIES.to_s} retries. !"\
+            + " Exiting.."
+          DeviceAPI.log.fatal(msg)
+          raise DeviceAPI::CommandTimeoutError.new(msg)
+        else
+          DeviceAPI.log.info "Command #{command} succeeded execution after retrying"
+        end
+      end
+
+      result
+    end
+  end
+
+  class CommandTimeoutError < StandardError
+    def initialize(msg)
+      super(msg)
+    end
+  end
+
+end

data/lib/device_api/sys_log.rb

@@ -0,0 +1,39 @@
+require 'syslog'
+
+module DeviceAPI
+  class SysLog
+
+    attr_accessor :syslog
+
+    def log(priority,message)
+      if @syslog and @syslog.opened?
+        @syslog = Syslog.reopen('device-api-gem', Syslog::LOG_PID, Syslog::LOG_DAEMON)
+      else
+        @syslog = Syslog.open('device-api-gem', Syslog::LOG_PID, Syslog::LOG_DAEMON)
+      end
+
+      @syslog.log(priority,message)
+      @syslog.close
+    end
+
+    def fatal(message)
+      self.log(Syslog::LOG_CRIT,message)
+    end
+
+    def error(message)
+      self.log(Syslog::LOG_ERR,message)
+    end
+
+    def warn(message)
+      self.log(Syslog::LOG_WARNING,message)
+    end
+
+    def info(message)
+      self.log(Syslog::LOG_INFO,message)
+    end
+
+    def debug(message)
+      self.log(Syslog::LOG_DEBUG,message)
+    end
+  end
+end

data/spec/execution_spec.rb

@@ -0,0 +1,54 @@
+$LOAD_PATH.unshift('./lib/')
+
+require 'device_api/execution'
+
+include RSpec
+
+ProcessStatusStub = Struct.new(:exitstatus)
+$STATUS_ZERO = ProcessStatusStub.new(0)
+
+describe DeviceAPI::Execution do
+  describe '.execute' do
+
+    before(:all) do
+      @result = DeviceAPI::Execution.execute('echo boo')
+    end
+
+    it 'returns an OpenStruct execution result' do
+      expect(@result).to be_a OpenStruct
+    end
+
+    it 'captures exit value in hash' do
+      expect(@result.exit).to eq(0)
+    end
+
+    it 'captures stdout in hash' do
+      expect(@result.stdout).to eq("boo\n")
+    end
+
+    it 'capture stderr in hash' do
+      expect(@result.stderr).to eq('')
+    end
+
+  end
+
+  describe '.execute_with_timeout_and_retry' do
+    it 'should raise an exception if the command takes too long to execute' do
+      stub_const('DeviceAPI::Execution::COMMAND_TIMEOUT',1)
+      stub_const('DeviceAPI::Execution::COMMAND_RETRIES',1)
+      sleep_time = 5
+      cmd = "sleep #{sleep_time.to_s}"
+      expect { DeviceAPI::Execution.execute_with_timeout_and_retry(cmd) }.to raise_error(DeviceAPI::CommandTimeoutError)
+    end
+
+    it 'should execute successfully if command returns before the timeout' do
+      stub_const('DeviceAPI::Execution::COMMAND_TIMEOUT',2)
+      stub_const('DeviceAPI::Execution::COMMAND_RETRIES',5)
+      sleep_time = 1
+      cmd = "sleep #{sleep_time.to_s}"
+      DeviceAPI::Execution.execute_with_timeout_and_retry(cmd)
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: device_api
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- BBC
+- David Buckhurst
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A common interface for physical devices
+email: david.buckhurst@bbc.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- device_api.gemspec
+- lib/device_api.rb
+- lib/device_api/device.rb
+- lib/device_api/execution.rb
+- lib/device_api/sys_log.rb
+- spec/execution_spec.rb
+homepage: https://github.com/bbc/device_api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Physical Device Management API
+test_files: []
+has_rdoc: