restforce-db 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0cc0005c0f2912c195d0c16866ab8f0f2052e4db
+  data.tar.gz: 2b28c71a8c76b6bc4c08535d8d5c71a4ed1c7aef
+SHA512:
+  metadata.gz: d93308753057f5b9a020d59202f8acb3d1140cc18264d8669cd11e5c8818e960f3105870d6a02dbe4f1a2c88ca5b6f7e9f4eabd863cf070becf1b20ae18b38bd
+  data.tar.gz: 52ff1b22102b140ccec6021b57af2d2bd60996f3df4f47368e236f03642e4216389a588864c423c4fa6062d4df1b295309959b102fa6561a0c1aabadec412b12

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.ruby-gemset
+/.ruby-version
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/test/config/*
+
+.DS_Store

data/.rubocop/custom/method_documentation.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+
+module RuboCop
+
+  module Cop
+
+    module Style
+
+      # This cop checks for missing method-level documentation.
+      class MethodDocumentation < Cop
+        include AnnotationComment
+
+        MSG = "Missing method-level documentation comment."
+
+        # Public: Investigate the source for undocumented methods.
+        def investigate(processed_source)
+          ast = processed_source.ast
+          return unless ast
+
+          ast_with_comments = Parser::Source::Comment.associate(
+            ast,
+            processed_source.comments
+          )
+
+          check(ast, ast_with_comments)
+        end
+
+        private
+
+        # Internal: Ensure that documentation is required for all methods. Adds
+        # an offense when undocumented methods are detected.
+        #
+        # Returns nothing.
+        def check(ast, ast_with_comments)
+          ast.each_node(:def) do |node|
+            _name, body = *node
+
+            next if associated_comment?(node, ast_with_comments)
+            add_offense(node, :keyword, MSG)
+          end
+        end
+
+        # Internal: Does the node have a non-annotation comment on the preceding
+        # line?
+        #
+        # Returns a Boolean.
+        def associated_comment?(node, ast_with_comments)
+          return false if ast_with_comments[node].empty?
+
+          preceding_comment = ast_with_comments[node].last
+          distance = node.loc.keyword.line - preceding_comment.loc.line
+          return false if distance > 1
+
+          # As long as there's at least one comment line that isn't an
+          # annotation, it's OK.
+          ast_with_comments[node].any? { |comment| !annotation?(comment) }
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/.rubocop.yml

@@ -0,0 +1,39 @@
+require:
+  - ./.rubocop/custom/method_documentation.rb
+
+AllCops:
+  Exclude:
+    - ".bundle/**/*"
+    - "vendor/**/*"
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/EmptyLinesAroundBlockBody:
+  Exclude:
+    # These are naturally DSL-y, and so let's be lenient
+    - "test/**/*"
+
+Style/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines
+
+Style/EmptyLinesAroundModuleBody:
+  EnforcedStyle: empty_lines
+
+Style/SignalException:
+  EnforcedStyle: only_raise
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingComma:
+  EnforcedStyleForMultiline: comma
+
+Style/TrivialAccessors:
+  ExactNameMatch: true

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.0

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in restforce-db.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Table XI Partners, LLC
+
+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,68 @@
+# Restforce::DB
+
+Restforce::DB is an attempt at simplifying data integrations between a Salesforce setup and a Rails application. It provides a background worker which continuously polls for updated records both in Salesforce and in the database, and updates both systems with that data according to user-defined attribute mappings.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "restforce-db"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install restforce-db
+
+## Usage
+
+First, you'll want to install the default bin and configuration files, which is handled by the included Rails generator:
+
+    $ bundle exec rails g restforce
+
+This gem assumes that you're running Rails 4 or greater, therefore the `bin` file should be checked into the repository with the rest of your code. The `config/restforce-db.yml` file should be managed the same way you manage your secrets files, and probably not checked into the repository.
+
+To register a Salesforce mapping in an `ActiveRecord` model, you need to add a few lines of DSL-style code to your class definition:
+
+```ruby
+class LineCook < ActiveRecord::Base
+
+  include Restforce::DB::Model
+
+  map_to "Line_Cook__c", name: "Name", specialty: "Favorite_Food__c"
+
+end
+```
+
+This will automatically register the model with an entry in the `Restforce::DB::RecordType` collection. Your schema **must** contain a `salesforce_id` column for each table you wish to synchronize with a record type in Salesforce. 
+
+To run the worker, you'll want to run the binstub installed through the generator (see above). Then you can run the self-daemonizing executable.
+
+        $ bin/restforce-db start
+
+By default, this will load the credentials at the same location the generator installed them. You can explicitly pass the location of your configuration file with the `-c` option:
+
+        $ bin/restforce-db -c /path/to/my/config.yml start
+
+For additional information and a full set of options, you can run:
+
+        $ bin/restforce-db -h
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/tablexi/restforce-db/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Ensure that your changes pass all style checks and tests (`rake`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,13 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/**/*_test.rb"
+end
+
+RuboCop::RakeTask.new
+
+task default: [:rubocop, :test]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "restforce/db"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/restforce_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators/base"
+
+# :nodoc:
+class RestforceGenerator < Rails::Generators::Base
+
+  source_root File.expand_path("../templates", __FILE__)
+
+  # :nodoc:
+  def create_config_file
+    template "config.yml", "config/restforce-db.yml"
+  end
+
+  # :nodoc:
+  def create_executable_file
+    template "script", "bin/restforce-db"
+    chmod "bin/restforce-db", 0755
+  end
+
+end

data/lib/generators/templates/config.yml

@@ -0,0 +1,8 @@
+---
+client:
+  username:       "<username@example.com>"
+  password:       "<password>"
+  security_token: "<your salesforce security token>"
+  client_id:      "<your salesforce remote app client id>"
+  client_secret:  "<your salesforce remote app client secret>"
+  host:           "login.salesforce.com"

data/lib/generators/templates/script

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "config", "environment"))
+require "restforce/db/command"
+
+Restforce::DB::Command.new(ARGV).daemonize

data/lib/restforce/db/command.rb

@@ -0,0 +1,98 @@
+require "daemons"
+require "optparse"
+
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Command represents the command line interface for our
+    # daemonized processing loop. It captures a set of options from the command
+    # line to configure the running worker thread for synchronizing data.
+    class Command
+
+      # Public: Initialize a new Restforce::DB::Command.
+      #
+      # args - A set of command line arguments to pass to the OptionParser.
+      def initialize(args)
+        @options = {
+          verbose: false,
+          pid_dir: Rails.root.join("tmp", "pids"),
+          config:  Rails.root.join("config", "restforce-db.yml"),
+        }
+
+        @args = parser.parse!(args)
+      end
+
+      # Public: Initialize the daemonized processing loop for Restforce::DB.
+      #
+      # Returns nothing.
+      def daemonize
+        dir = @options[:pid_dir]
+        Dir.mkdir(dir) unless File.exist?(dir)
+
+        daemon_args = {
+          dir: @options[:pid_dir],
+          dir_mode: :normal,
+          monitor: @monitor,
+          ARGV: @args,
+        }
+
+        Restforce::DB::Worker.before_fork
+        Daemons.run_proc("restforce-db", daemon_args) do |*_args|
+          run @options
+        end
+      end
+
+      private
+
+      # Internal: Initiate a worker thread for Restforce::DB's record
+      # synchronization processing loop.
+      #
+      # options - A Hash of run configuration options for the worker.
+      #
+      # Returns nothing.
+      def run(options = {})
+        Dir.chdir(Rails.root)
+
+        Restforce::DB::Worker.after_fork
+        Restforce::DB::Worker.logger ||= Logger.new(File.join(Rails.root, "log", "restforce-db.log"))
+
+        worker = Restforce::DB::Worker.new(options)
+        worker.start
+      rescue => e
+        Restforce::DB::Worker.logger.fatal e
+        STDERR.puts e.message
+        exit 1
+      end
+
+      # Internal: Get an OptionParser for the Restforce::DB CLI.
+      #
+      # Returns an OptionParser.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = "Usage: #{File.basename($PROGRAM_NAME)} [options] start|stop|restart|run"
+
+          opt.on("-h", "--help", "Show this message") do
+            puts opt
+            exit 1
+          end
+          opt.on("-c FILE", "--config FILE", "The location of a Restforce credentials file.") do |file|
+            @options[:config] = file
+          end
+          opt.on("-i N", "--interval N", "Amount of time to wait between synchronizations.") do |n|
+            @options[:interval] = n.to_i
+          end
+          opt.on("--pid-dir DIR", "The directory in which to store the pidfile.") do |dir|
+            @options[:pid_dir] = dir
+          end
+          opt.on("-v", "--verbose", "Turn on noisy logging.") do
+            @options[:verbose] = true
+          end
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/configuration.rb

@@ -0,0 +1,50 @@
+require "yaml"
+
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Configuration exposes a handful of straightforward write
+    # and read methods to allow users to configure Restforce::DB.
+    class Configuration
+
+      attr_accessor(*%i(
+        username
+        password
+        security_token
+        client_id
+        client_secret
+        host
+      ))
+
+      # Public: Parse a supplied YAML file for a set of credentials, and use
+      # them to populate the attributes on this configuraton object.
+      #
+      # file_path - A String or Path referencing a client configuration file.
+      #
+      # Returns nothing.
+      def parse(file_path)
+        settings = YAML.load_file(file_path)
+        load(settings["client"])
+      end
+
+      # Public: Populate this configuration object from a Hash of credentials.
+      #
+      # configurations - A Hash of credentials, with keys matching the names
+      #                  of the attributes for this class.
+      #
+      # Returns nothing.
+      def load(configurations)
+        self.username       = configurations["username"]
+        self.password       = configurations["password"]
+        self.security_token = configurations["security_token"]
+        self.client_id      = configurations["client_id"]
+        self.client_secret  = configurations["client_secret"]
+        self.host           = configurations["host"]
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/instances/active_record.rb

@@ -0,0 +1,48 @@
+module Restforce
+
+  module DB
+
+    module Instances
+
+      # Restforce::DB::Instances::ActiveRecord serves as a wrapper for
+      # ActiveRecord::Base-compatible objects, exposing a common API to
+      # reconcile record attributes with Salesforce instances.
+      class ActiveRecord < Base
+
+        # Public: Get a common identifier for this record.
+        #
+        # Returns a String.
+        def id
+          @record.salesforce_id
+        end
+
+        # Public: Has this record been synced to a Salesforce record?
+        #
+        # Returns a Boolean.
+        def synced?
+          @record.salesforce_id?
+        end
+
+        # Public: Get the time of the last update to this record.
+        #
+        # Returns a Time-compatible object.
+        def last_update
+          @record.updated_at
+        end
+
+        private
+
+        # Internal: Get a description of the expected attribute Hash format.
+        #
+        # Returns a Symbol.
+        def conversion
+          :database
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/instances/base.rb

@@ -0,0 +1,66 @@
+module Restforce
+
+  module DB
+
+    module Instances
+
+      # Restforce::DB::Instances::Base defines common behavior for the other
+      # models defined in the Restforce::DB::Instances namespace.
+      class Base
+
+        attr_reader :record
+
+        # Public: Initialize a new Restforce::DB::Instances::Base instance.
+        #
+        # record  - The Salesforce or database record to manage.
+        # mapping - An instance of Restforce::DB::Mapping.
+        def initialize(record, mapping = Mapping.new)
+          @record = record
+          @mapping = mapping
+        end
+
+        # Public: Update the instance with the passed attributes.
+        #
+        # attributes - A Hash mapping attribute names to values.
+        #
+        # Returns a truthy value.
+        # Raises if the update fails for any reason.
+        def update!(attributes)
+          record.update!(attributes)
+        end
+
+        # Public: Update the instance with attributes copied from the passed
+        # record.
+        #
+        # record - An object responding to `#attributes`. Must return a Hash of
+        #          attributes corresponding to the configured mappings for this
+        #          instance.
+        #
+        # Returns a truthy value.
+        # Raises if the update fails for any reason.
+        def copy!(from_record)
+          update! @mapping.convert(conversion, from_record.attributes)
+        end
+
+        # Public: Get a Hash mapping the configured attributes names to their
+        # values for this instance.
+        #
+        # Returns a Hash.
+        def attributes
+          @mapping.attributes(conversion) { |attribute| record.send(attribute) }
+        end
+
+        # Public: Has this record been synced with Salesforce?
+        #
+        # Returns a Boolean.
+        def synced?
+          true
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/instances/salesforce.rb

@@ -0,0 +1,46 @@
+module Restforce
+
+  module DB
+
+    module Instances
+
+      # Restforce::DB::Instances::Salesforce serves as a wrapper for Salesforce
+      # objects, exposing a common API to reconcile record attributes with
+      # ActiveRecord instances.
+      class Salesforce < Base
+
+        INTERNAL_ATTRIBUTES = %w(
+          Id
+          SystemModstamp
+        ).freeze
+
+        # Public: Get a common identifier for this record.
+        #
+        # Returns a String.
+        def id
+          @record.Id
+        end
+
+        # Public: Get the time of the last update to this record.
+        #
+        # Returns a Time-compatible object.
+        def last_update
+          Time.parse(@record.SystemModstamp)
+        end
+
+        private
+
+        # Internal: Get a description of the expected attribute Hash format.
+        #
+        # Returns a Symbol.
+        def conversion
+          :salesforce
+        end
+
+      end
+
+    end
+
+  end
+
+end