remote_record 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a744d661d889b63488c0cae5a44803d4215e384f39d7c7d0671cae12c4e04600
+  data.tar.gz: cef3b04a970a6cf4a48a966beb6e935525a72c2697367f81d2bf64a3ce21f9e9
+SHA512:
+  metadata.gz: f580bbc02f2ea512f80101a0f4dc7d1b0c293db974c75b820b18e680a48c674a9d266b1542e42eb4988b366a111e30fbf342a59e4e47a3d93ba4658137096e81
+  data.tar.gz: '0792f2b3d53c925c348b500b768587eb7de9fea53cf80543f6cb3c4bb945749ad4be33006cb49e82fb17b46c53773e7e64bbd31df28988e19a22e4e8426a0109'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Simon Fish
+
+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,108 @@
+# RemoteRecord
+
+Ready-made remote resource structures.
+
+## Setup
+
+### Jargon
+
+**Remote resource** - the resource on the external API that you're trying to
+reach. In this example, we're trying to fetch a GitHub user.
+
+**Reference** - your record that points at the remote resource using its ID. In
+this example, these are `GitHub::UserReference`s.
+
+**Remote record class** - a class that defines the behavior used to fetch the
+remote resource. In this example, it's `RemoteRecord::GitHub::User`.
+
+### Creating a remote record class
+
+A standard RemoteRecord class looks like this. It should have a `get` method,
+which returns a hash of data you'd like to query on the user.
+
+`RemoteRecord::Base` exposes private methods for the `remote_resource_id` and
+`authorization` that you configure on the remote reference.
+
+```ruby
+module RemoteRecord
+  module GitHub
+    # :nodoc:
+    class User < RemoteRecord::Base
+      def get
+        client.user(remote_resource_id)
+      end
+
+      private
+
+      def client
+        Octokit::Client.new(access_token: authorization)
+      end
+    end
+  end
+end
+```
+
+### Creating a remote reference
+
+To start using your remote record class, `include RemoteRecord` into your reference. Now, whenever
+you initialize an instance of your class, it'll be fetched.
+
+Calling `remote_record` in addition to this lets you set some options:
+
+| Key           | Default                  | Purpose                                                                                                                                                                            |
+|--------------:|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| klass         | Inferred from class name | The Remote record class to use for fetching attributes                                                                                                                             |
+| id_field      | `:remote_resource_id`    | The field on the reference that contains the remote resource ID                                                                                                                    |
+| authorization | `''`                     | An object that can be used by the remote record class to authorize a request. This can be a value, or a proc that returns a value that can be used within the remote record class. |
+| memoize       | true                     | Whether reference instances should memoize the response that populates them                                                                                                        |
+
+```ruby
+module GitHub
+  # :nodoc:
+  class UserReference < ApplicationRecord
+    belongs_to :user
+    include RemoteRecord
+    remote_record do |c|
+      c.authorization { |record| record.user.github_auth_tokens.active.first.token }
+      # Defaults:
+      # c.id_field :remote_resource_id
+      # c.klass RemoteRecord::GitHub::User, # Inferred from module and class name
+      # c.memoize true
+    end
+  end
+end
+```
+
+If your API doesn't require authentication at all, you don't even need to
+configure it. So at its best, RemoteRecord can be as lightweight as:
+
+```ruby
+class JsonPlaceholderAPIReference < ApplicationRecord
+  include RemoteRecord
+  # Falls back to the defaults, so it's equivalent to then calling:
+  # remote_record do |c|
+    # c.authorization proc { }
+    # c.id_field :remote_resource_id
+    # c.klass RemoteRecord::JsonPlaceholderAPI, # Inferred from module and class name
+    # c.memoize true
+  # end
+end
+```
+
+## Usage
+
+Now you've got everything lined up to start using your remote reference.
+
+Whenever a `GitHub::UserReference` is initialized, e.g. by calling:
+
+```ruby
+user.github_user_references.first
+```
+
+...it'll be populated with the GitHub user's data. You can call methods that
+return attributes on the user, like `#login` or `#html_url`.
+
+By default, this'll only make a request on initialize. For services that manage
+caching by way of expiry or ETags, I recommend using `faraday-http-cache` for
+your clients and setting `memoize` to `false`. Remote Record will eventually
+gain support for caching.

data/lib/remote_record.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'remote_record/base'
+require 'remote_record/class_lookup'
+require 'remote_record/config'
+require 'remote_record/dsl'
+require 'remote_record/reference'
+require 'remote_record/version'
+
+# Generic interface for resources stored on external services.
+module RemoteRecord
+  extend ActiveSupport::Concern
+  included do
+    include Reference
+    include DSL
+  end
+
+  class RecordClassNotFound < StandardError; end
+end

data/lib/remote_record/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RemoteRecord
+  # Remote record classes should inherit from this class and define #get.
+  class Base
+    def self.default_config
+      Config.defaults.merge(remote_record_class: self)
+    end
+
+    def initialize(reference, options)
+      @reference = reference
+      @options = options.presence || default_config
+      @attrs = HashWithIndifferentAccess.new
+    end
+
+    def method_missing(method_name, *_args, &_block)
+      @attrs.fetch(method_name)
+    rescue KeyError
+      super
+    end
+
+    def respond_to_missing?(method_name, _include_private = false)
+      @attrs.key?(method_name)
+    end
+
+    def get
+      raise NotImplementedError.new, '#get should return a hash of data that represents the remote record.'
+    end
+
+    def fetch
+      @attrs.update(get)
+    end
+
+    private
+
+    def authorization
+      authz = @options.authorization
+      authz.respond_to?(:call) ? authz.call(@reference, @options) : authz
+    end
+
+    def remote_resource_id
+      @reference.send(@options.id_field)
+    end
+  end
+end

data/lib/remote_record/class_lookup.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RemoteRecord
+  # Looks up the class name to use to define the remote record's behavior.
+  class ClassLookup
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def remote_record_class(class_name_override = nil)
+      class_name = (class_name_override || infer_remote_record_class_name)
+      class_name.constantize
+    rescue NameError
+      raise RemoteRecord::RecordClassNotFound, "#{class_name} couldn't be found." \
+      "#{' Perhaps you need to define `remote_record_class`?' unless class_name_override}"
+    end
+
+    private
+
+    def infer_remote_record_class_name
+      "RemoteRecord::#{@klass.to_s.delete_suffix('Reference')}"
+    end
+  end
+end

data/lib/remote_record/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Configuration specific to a single remote record class.
+module RemoteRecord
+  # Configuration propagated between remote records and their references. When a
+  # new remote reference is initialized, its config is constructed using the
+  # defaults of the remote record class and the overrides set when
+  # `remote_record` is called.
+  class Config
+    OPTIONS = %i[remote_record_class authorization memoize id_field].freeze
+
+    def initialize(**options)
+      @options = options
+    end
+
+    def self.defaults
+      new(
+        authorization: '',
+        memoize: true,
+        id_field: :remote_resource_id
+      )
+    end
+
+    OPTIONS.each do |option|
+      define_method(option) do |new_value = nil, &block|
+        block_attr_accessor(option, new_value, &block)
+      end
+    end
+
+    # Returns the attribute value if called without args or a block. Otherwise,
+    # sets the attribute to the block or value passed.
+    def block_attr_accessor(attribute, new_value = nil, &block)
+      return @options.fetch(attribute) unless block_given? || !new_value.nil?
+
+      @options[attribute] = block_given? ? block : new_value
+      self
+    end
+
+    def to_h
+      @options
+    end
+
+    def merge(**overrides)
+      @options.merge!(**overrides)
+      self
+    end
+  end
+end

data/lib/remote_record/dsl.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RemoteRecord
+  # A DSL that's helpful for configuring remote references. To configure a
+  # remote reference, `include RemoteRecord`, then call `remote_record` to
+  # configure the module.
+  # See RemoteRecord::Config#defaults for the default configuration.
+  module DSL
+    extend ActiveSupport::Concern
+    class_methods do
+      def remote_record(remote_record_class: nil)
+        klass = RemoteRecord::ClassLookup.new(self).remote_record_class(remote_record_class)
+        config = RemoteRecord::Config.new(remote_record_class: klass)
+        config = yield(config) if block_given?
+        DSLPrivate.validate_config(config)
+        define_singleton_method(:remote_record_config) { config }
+      end
+    end
+  end
+
+  # Methods private to the DSL module.
+  module DSLPrivate
+    class << self
+      def responds_to_get?(klass)
+        klass.instance_methods(false).include? :get
+      end
+
+      def validate_config(config)
+        klass = RemoteRecord::ClassLookup.new(self.class.to_s)
+                                         .remote_record_class(config.to_h[:remote_record_class].to_s)
+        raise NotImplementedError.new, 'The remote record does not implement #get.' unless responds_to_get?(klass)
+      end
+    end
+  end
+end

data/lib/remote_record/reference.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RemoteRecord
+  # Core structure of a reference. A reference populates itself with all the
+  # data for a remote record using behavior defined by its associated remote
+  # record class (a descendant of RemoteRecord::Base). This is done on
+  # initialize by calling #get on an instance of the remote record class. These
+  # attributes are then accessible on the reference thanks to #method_missing.
+  module Reference
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def remote_record_class
+        ClassLookup.new(self).remote_record_class(
+          remote_record_config.to_h[:remote_record_class]&.to_s
+        )
+      end
+
+      # Default to an empty config, which falls back to the remote record
+      # class's default config and leaves the remote record class to be inferred
+      # from the reference class name
+      # This method is overridden using RemoteRecord::DSL#remote_record.
+      def remote_record_config
+        Config.new
+      end
+    end
+
+    included do
+      after_initialize do |reference|
+        config = reference.class.remote_record_class.default_config.merge(
+          reference.class.remote_record_config.to_h
+        )
+        reference.instance_variable_set('@remote_record_config', config)
+        reference.fetch_remote_resource
+      end
+
+      # This doesn't call `super` because it delegates to @instance in all
+      # cases.
+      def method_missing(method_name, *_args, &_block)
+        fetch_remote_resource unless @remote_record_config.memoize
+
+        @instance.public_send(method_name)
+      end
+
+      def respond_to_missing?(method_name, _include_private = false)
+        instance.respond_to?(method_name, false)
+      end
+
+      def initialize(**args)
+        @attrs = HashWithIndifferentAccess.new
+        super
+      end
+
+      def fetch_remote_resource
+        instance.fetch
+      end
+
+      private
+
+      def instance
+        @instance ||= @remote_record_config.remote_record_class.new(self, @remote_record_config)
+      end
+    end
+  end
+end

data/lib/remote_record/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RemoteRecord
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,224 @@
+--- !ruby/object:Gem::Specification
+name: remote_record
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Simon Fish
+- John Britton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  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'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rubocop-packaging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  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'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  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: Allows creating local instances of objects stored on remote services.
+email:
+- si@mon.fish
+- public@johndbritton.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/remote_record.rb
+- lib/remote_record/base.rb
+- lib/remote_record/class_lookup.rb
+- lib/remote_record/config.rb
+- lib/remote_record/dsl.rb
+- lib/remote_record/reference.rb
+- lib/remote_record/version.rb
+homepage: https://github.com/raisedevs/remote_record
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/raisedevs/remote_record
+  source_code_uri: https://github.com/raisedevs/remote_record
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: Ready-made remote resource structures.
+test_files: []