sugar_utils 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6fa1916d16c20d95a15c4efe888721b1ba36a526
-  data.tar.gz: ca2efdbff746c027cf648c2c6ea362283b44482c
+  metadata.gz: c614940d4ed952e41a7b52798188e3a0ac39a983
+  data.tar.gz: f5ddaf4709df842179c3d85f1b4abdf67c39c636
 SHA512:
-  metadata.gz: 51daa978771f007d6e9bd816ee1d7a5652e348446627212c54de0f2a1476b7a0100e22fb9ed95a69cb04920433a3eea49bb9ecf096b59702ed9ce8f1de04dd6c
-  data.tar.gz: 9fc27c24a3bc54294499ace731d3b649b51d5ffdff9499e94f1a0d7a387e2957d92686ce10caca6d5874c968de18710f76a9ccceff344f9e5b2519f0e29b4134
+  metadata.gz: e09c44845626a114fbacc8a9a8ba82db43abf86d40951eaf4e880d1779469459407cc020c6861a278dbee23f2cbe1cae8f0bbcb64f137e97965b51dc913f3332
+  data.tar.gz: 64f9577e97eafbd53f4b9f8c2a8d8bdd114677bfbd2b73c45e9564bbc5245f9a665271f4bc32db4829094e74f9a12ffcc9b07033bf8f331c002ee2b566e10523

data/.travis.yml

@@ -1,3 +1,10 @@
 language: ruby
 rvm:
-  - 2.0.0
+  - 2.0
+  - 2.1
+  - 2.2
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+sudo: false

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.2.0] - 2016-07-21
+### Added
+- SugarUtils::File.flock, for file locking with a timeout
+- SugarUtils::File.read_json, with locking and error handling
+- SugarUtils::File.write_json, with locking and error handling
+- this CHANGELOG.md, following the http://keepachangelog.com/ guidelines
+
+## [0.1.0] - 2016-07-09
+### Added
+- SugarUtils.ensure_boolean
+- SugarUtils.ensure_integer

data/lib/sugar_utils/file.rb

@@ -0,0 +1,91 @@
+# -*- encoding : utf-8 -*-
+
+require 'solid_assert'
+require 'fileutils'
+require 'multi_json'
+
+module SugarUtils
+  module File
+    class Error < StandardError; end
+
+    # flock with a timeout to ensure that it does not flock forever.
+    #
+    # @see http://www.codegnome.com/blog/2013/05/26/locking-files-with-ruby/
+    #
+    # @param [File] file
+    # @param [File::LOCK_EX, File::LOCK_SH] locking_constant
+    # @param [Hash] options
+    # @option options [Integer] :timeout (10)
+    #
+    # @return [void]
+    def self.flock(file, locking_constant, options = {})
+      timeout = options[:timeout] || 10
+      Timeout.timeout(timeout) { file.flock(locking_constant) }
+    end
+
+    # @param [String] filename
+    # @param [Hash] options
+    # @option options [Integer] :timeout (10)
+    # @option options [Boolean] :raise_on_missing (true)
+    #
+    # @raise [SugarUtils::File::Error)
+    #
+    # @return [Object]
+    def self.read_json(filename, options = {})
+      assert(options.is_a?(Hash), 'options MUST be a Hash')
+
+      options[:raise_on_missing] = true if options[:raise_on_missing].nil?
+
+      ::File.open(filename, ::File::RDONLY) do |file|
+        flock(file, ::File::LOCK_SH, options)
+        MultiJson.load(file.read)
+      end
+    rescue SystemCallError, IOError
+      raise(Error, "Cannot read #{filename}") if options[:raise_on_missing]
+      {}
+    rescue MultiJson::ParseError
+      raise(Error, "Cannot parse #{filename}")
+    rescue Timeout::Error
+      raise(Error, "Cannot read #{filename} because it is locked")
+    end
+
+    # @param [String] filename
+    # @param [#to_json]  data
+    # @param [Hash] options
+    # @option options [Integer] :timeout (10)
+    # @option options [Boolean] :flush (false)
+    # @option options [Integer] :perm (0666)
+    #
+    # @raise [SugarUtils::File::Error)
+    #
+    # @return [void]
+    def self.write_json(filename, data, options = {})
+      perm  = options[:perm] || 0666
+      flush = options[:flush] || false
+
+      FileUtils.mkdir_p(::File.dirname(filename))
+      ::File.open(filename, ::File::RDWR | ::File::CREAT, perm) do |file|
+        flock(file, ::File::LOCK_EX, options)
+
+        file.truncate(0) # Ensure file is empty before proceeding.
+        file.puts(MultiJson.dump(data, pretty: true))
+
+        # Flush and fsync to be 100% sure we write this data out now because we
+        # are often reading it immediately and if the OS is buffering, it is
+        # possible we might read it before it is been physically written to disk.
+        # We are not worried about speed here, so this should be OKAY.
+        if flush
+          file.flush
+          file.fsync
+        end
+
+        # Ensure that the permissions are correct if the file already existed.
+        file.chmod(perm)
+      end
+    rescue Timeout::Error
+      raise(Error, "Unable to write #{filename} because it is locked")
+    rescue SystemCallError, IOError => boom
+      raise(Error, "Unable to write #{filename} with #{boom}")
+    end
+  end
+end

data/lib/sugar_utils/version.rb

@@ -1,5 +1,5 @@
 # -*- encoding : utf-8 -*-
 
 module SugarUtils
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/sugar_utils.rb

@@ -1,6 +1,7 @@
 # -*- encoding : utf-8 -*-
 
 require 'sugar_utils/version'
+require 'sugar_utils/file'
 
 module SugarUtils
   # @param [Object] value

data/spec/spec_helper.rb

@@ -4,4 +4,11 @@ $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'sugar_utils'
 require 'simplecov'
 require 'rspec/tabular'
+require 'fakefs/spec_helpers'
 SimpleCov.start 'rails'
+
+SolidAssert.enable_assertions
+
+RSpec.configure do |config|
+  config.include FakeFS::SpecHelpers, fakefs: true
+end

data/spec/sugar_utils/file_spec.rb

@@ -0,0 +1,168 @@
+# -*- encoding : utf-8 -*-
+
+require 'spec_helper'
+require 'fileutils'
+
+describe SugarUtils::File do
+  describe '.flock' do
+    subject { described_class.flock(file, :locking_constant, options) }
+    let(:file) { instance_double(File) }
+    before do
+      expect(Timeout).to receive(:timeout).with(expected_timeout).and_yield
+      expect(file).to receive(:flock).with(:locking_constant)
+    end
+
+    inputs            :options,           :expected_timeout
+    side_effects_with Hash[],             10
+    side_effects_with Hash[timeout: nil], 10
+    side_effects_with Hash[timeout: 5],   5
+  end
+
+  describe '.read_json', :fakefs do
+    subject { described_class.read_json('filename.json', options) }
+
+    context 'missing file' do
+      inputs           :options
+      raise_error_with Hash[],                        described_class::Error
+      raise_error_with Hash[],                        'Cannot read filename.json'
+      raise_error_with Hash[raise_on_missing: true],  described_class::Error
+      raise_error_with Hash[raise_on_missing: true],  'Cannot read filename.json'
+      it_with          Hash[raise_on_missing: false], {}
+    end
+
+    context 'file present' do
+      let(:options) { {} }
+      before { write('filename.json', content) }
+
+      context 'SysteCallError' do
+        let(:options) { {} }
+        let(:content) { '' }
+        let(:exception) { SystemCallError.new(nil) }
+        before { allow(File).to receive(:open).and_raise(exception) }
+        it { expect_raise_error('Cannot read filename.json') }
+      end
+
+      context 'IOError' do
+        let(:options) { {} }
+        let(:content) { '' }
+        let(:exception) { IOError.new(nil) }
+        before { allow(File).to receive(:open).and_raise(exception) }
+        it { expect_raise_error('Cannot read filename.json') }
+      end
+
+      context 'and locked' do
+        let(:content) { '' }
+        before { expect_flock(File::LOCK_SH, options).and_raise(Timeout::Error) }
+        it { expect_raise_error('Cannot read filename.json because it is locked') }
+      end
+
+      context 'and unlocked' do
+        before { expect_flock(File::LOCK_SH, options) }
+
+        inputs           :content
+        raise_error_with 'I am not json',                described_class::Error
+        raise_error_with 'I am not json',                'Cannot parse filename.json'
+        it_with          Hash['key' => 'value'].to_json, Hash['key' => 'value']
+      end
+    end
+  end
+
+  describe '.write_json', :fakefs do
+    subject { described_class.write_json(filename, data, options) }
+    let(:data)     { { 'key' => 'value' } }
+    let(:filename) { 'dir1/dir2/filename.json' }
+
+    context 'SystemCallError' do
+      let(:options) { {} }
+      let(:exception) { SystemCallError.new(nil) }
+      before { allow(File).to receive(:open).and_raise(exception) }
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'IOError' do
+      let(:options) { {} }
+      let(:exception) { IOError.new(nil) }
+      before { allow(File).to receive(:open).and_raise(exception) }
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'locked' do
+      let(:options) { {} }
+      before { expect_flock(File::LOCK_EX, options).and_raise(Timeout::Error) }
+      it { expect_raise_error("Unable to write #{filename} because it is locked") }
+    end
+
+    context 'unlocked' do
+      shared_examples_for 'file is written' do
+        before { expect_flock(File::LOCK_EX, options) }
+
+        context 'default options' do
+          let(:options) { {} }
+          before { subject }
+          specify do
+            expect(File.exist?(filename)).to eq(true)
+            expect(MultiJson.load(File.read(filename))).to eq(data)
+            expect(sprintf('%o', File.stat(filename).mode)).to eq('100666')
+          end
+        end
+
+        context 'options' do
+          let(:options) { { flush: true, perm: 0600 } }
+          before do
+            expect_any_instance_of(File).to receive(:flush)
+            expect_any_instance_of(File).to receive(:fsync)
+            subject
+          end
+          specify do
+            expect(File.exist?(filename)).to eq(true)
+            expect(MultiJson.load(File.read(filename))).to eq(data)
+            expect(sprintf('%o', File.stat(filename).mode)).to eq('100600')
+          end
+        end
+      end
+
+      context 'and not exist' do
+        it_behaves_like 'file is written'
+      end
+
+      context 'and exists' do
+        before { write(filename, 'foobar', 0777) }
+        context 'not locked' do
+          it_behaves_like 'file is written'
+        end
+      end
+    end
+  end
+
+  ##############################################################################
+
+  # @param [File::LOCK_SH, File::LOCK_EX] locking_constant
+  # @param [Hash] options
+  def expect_flock(locking_constant, options)
+    expect(described_class).to receive(:flock)
+      .with(kind_of(File), locking_constant, options)
+  end
+
+  # @param [String] message
+  def expect_raise_error(message)
+    expect { subject }.to raise_error(described_class::Error, message)
+  end
+
+  # @overload write(filename, content)
+  #   @param [String] filename
+  #   @param [String] content
+  #
+  # @overload write(filename, content, perm)
+  #   @param [String] filename
+  #   @param [String] content
+  #   @param [Integer] perm
+  #
+  # @return [void]
+  def write(filename, content, perm = nil)
+    FileUtils.mkdir_p(::File.dirname(filename))
+    File.write(filename, content)
+    FileUtils.chmod(perm, filename) if perm
+  end
+
+
+end

data/sugar_utils.gemspec

@@ -17,7 +17,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler',       '~> 1.9'
+  spec.add_dependency 'multi_json',   '~> 1.12.1'
+  spec.add_dependency 'solid_assert', '~> 1.0'
+
+  spec.add_development_dependency 'bundler',       '~> 1.7'
   spec.add_development_dependency 'rake',          '~> 10.0'
   spec.add_development_dependency 'rspec',         '~> 3.4.0'
   spec.add_development_dependency 'rspec-tabular', '~> 0.1.0'
@@ -25,4 +28,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop',       '~> 0.37'
   spec.add_development_dependency 'yard',          '~> 0.8.7.6'
   spec.add_development_dependency 'yardstick',     '~> 0.9.9'
+  spec.add_development_dependency 'fakefs',        '~> 0.7'
 end

metadata

@@ -1,29 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: sugar_utils
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Sullivan Cant
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-09 00:00:00.000000000 Z
+date: 2016-07-21 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.12.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.12.1
+- !ruby/object:Gem::Dependency
+  name: solid_assert
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +150,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.9
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
 description: 
 email:
 - acant@sugarcrm.com
@@ -133,6 +175,7 @@ files:
 - .rspec
 - .rubocop.yml
 - .travis.yml
+- CHANGELOG.md
 - CONTRIBUTING.md
 - CONTRIBUTOR_TERMS.md
 - Gemfile
@@ -140,8 +183,10 @@ files:
 - README.md
 - Rakefile
 - lib/sugar_utils.rb
+- lib/sugar_utils/file.rb
 - lib/sugar_utils/version.rb
 - spec/spec_helper.rb
+- spec/sugar_utils/file_spec.rb
 - spec/sugar_utils_spec.rb
 - sugar_utils.gemspec
 homepage: http://github.com/sugarcrm/sugar_utils
@@ -170,5 +215,6 @@ specification_version: 4
 summary: Utility methods extracted from SugarCRM Ruby projects.
 test_files:
 - spec/spec_helper.rb
+- spec/sugar_utils/file_spec.rb
 - spec/sugar_utils_spec.rb
 has_rdoc: