ncore 2.3.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad2896952813c29015f47f4f9abbbadaaedeeb1751ca400665ed139bf6701743
-  data.tar.gz: 7fe5ce49a086118502a711bffe0913a307e1ca87f1a3bec32545b9bdc8efd1f2
+  metadata.gz: 0104ef39fd536e1845266782c236e1a00af04c0c6187b62567f247f3558f51bd
+  data.tar.gz: 99668e3c3ee5b104f2ec649a6dce845821943c9b67e361d0721a64ea9e5e94f0
 SHA512:
-  metadata.gz: fb9af96b8efe29b420f88538e6b64f2215de16d2b3d05f48a1bc91bbbaa133e1975aec395f6ed45099773c2411721853fba930b0d7fb36a06b85d8ab8734a4e3
-  data.tar.gz: 1f85607319bb2047d2efa8434db0f703db884a27c8606667f764bd67ceb871cf560b015d029c44d1d1dac156319f7d8344a8d72bb333f7fc52d5d2d23521cf07
+  metadata.gz: 257d7bd01c3f0c77b5b7c6f65d6bba245c8a7331627003ea1a72af9664eaf8a19026bc21df976c2499106f3701ef712a9b0a92b3754ec784468b9eb2783171b8
+  data.tar.gz: 2858e6b9cd9c067b41ebe4ba2968747db8553af7fe37c2a3e69abda1f22d60f8e841fce7e4b8dcf204ba6a5bbf6debf601fb18b111cc4a6f050ce47195042685

data/CHANGELOG.md

@@ -1,6 +1,68 @@
+#### 3.3.0
+
+- Allow  headers: {}  as part of params/attribs everywhere
+- Drop ActiveModel <= 5.1
+- Remove ValidationError
+
+#### 3.2.1
+
+DEPRECATION NOTICE
+- Support for ActiveModel < 5.2 is deprecated and will be removed in 3.3.
+
+Other changes
+- Allow ActiveModel 6.1
+
+#### 3.2.0
+
+- Use system's CA certificate store by default
+  To use bundled CAs instead:
+    SomeAppName::Api.ssl_cert_bundle = :bundled
+  On failure reading specified bundle, raises exception instead of warning
+
+#### 3.1.0
+
+- Add .bulk_update and bulk_update!
+
+#### 3.0.0
+
+BREAKING CHANGES
+- Update has_many, belongs_to signatures
+- Rename Base#url -> #resource_path
+- Drop ActiveModel <= 4.1
+- `#errors` is now always an ActiveModel::Errors instance
+
+DEPRECATION NOTICE
+- ValidationError is deprecated and will be removed in 3.1.
+
+Other changes
+- Add :cache option for requests
+  Set default store at MyApi::Api.cache_store=
+    See example railtie.rb for auto-config
+  Examples:
+    SomeResource.all(cache: true)
+      uses MyApi::Api.cache_store
+    SomeResource.find(id, cache: {expires_in: 5.minutes})
+      uses MyApi::Api.cache_store with specified options
+    SomeResource.find(id, cache: Dalli::Store.new(...))
+      uses provided cache store (with its default options)
+- Make bearer_credential_key allow strings or symbols
+- Warn on attr name collision
+- Update CA certificates
+- Better default output for #as_json
+- Allow ActiveModel/Support 6.0
+- Resolve deprecation messages on Ruby 2.6
+- Add #factory
+- API response :errors may be hash or array
+- Add RecordInvalid#errors
+- Better Ruby and ActiveModel integration
+  - #eql?, #==, #hash
+  - #model_name
+  - #i18n_scope, config via Api.i18n_scope=
+  - #cache_key, #cache_version, #cache_key_with_version
+
 #### 2.3.1
 
-- Allow ActiveSupport 6.1
+- Allow ActiveModel 6.1
 
 #### 2.3.0
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2018 Notioneer, Inc.
+Copyright (c) 2014-2021 Notioneer, Inc.
 
 MIT License
 

data/README.md

@@ -3,7 +3,7 @@
 NCore is a Ruby gem designed to help build REST API clients. It is not an API
 client by itself, but provides several useful building blocks to build one.
 
-It relies on `excon` for HTTP handling and `activesupport`.
+It relies on `excon` for HTTP handling and `activemodel`.
 
 If present, uses `multi_json`. Otherwise, the stdlib 'json' is used.
 'multi_json' with an accelerated json gem is recommended.

data/example/lib/my_api/api_config.rb

@@ -21,6 +21,8 @@ module MyApi
 
     self.strict_attributes = false
 
+    self.i18n_scope = :my_api
+
     self.instrument_key = 'request.my_api'
 
     self.status_page = 'http://my.api.status.page'
@@ -30,6 +32,14 @@ module MyApi
     # self.bearer_credential_key = :api_key
 
     self.credentials_error_message = %Q{Missing API credentials. Set default credentials using "MyApi.credentials = {api_user: YOUR_API_USER, api_key: YOUR_API_KEY}"}
+
+    # self.verify_ssl = true
+
+    # Uses system/OS bundle by default
+    # self.ssl_cert_bundle = :bundled   # uses excon's included bundle
+    # self.ssl_cert_bundle = 'path/to/bundle.crt'
+
+    # self.logger = Logger.new(STDOUT)
   end
 
 end

data/example/lib/my_api/rails/railtie.rb

@@ -1,6 +1,10 @@
 module MyApi
   class Railtie < Rails::Railtie
 
+    config.after_initialize do
+      MyApi::Api.cache_store = Rails.cache
+    end
+
     initializer "my_api.log_runtime" do |app|
       require 'my_api/rails/log_subscriber'
       ActiveSupport.on_load(:action_controller) do

data/lib/ncore.rb

@@ -1,15 +1,42 @@
 require 'active_support/all'
+require 'active_model'
 require 'excon'
 require 'pp'
 
-%w(version builder configuration associations attributes client collection exceptions identity lifecycle util base singleton_base).each do |f|
+%w(
+  version
+  builder
+  configuration
+  associations
+  attributes
+  client
+  client_cache
+  collection
+  exceptions
+  identity
+  lifecycle
+  util
+  base
+  singleton_base
+).each do |f|
   require "ncore/#{f}"
 end
 
-%w(all build count create delete delete_bulk delete_single find find_single update).each do |f|
+%w(
+  all
+  build
+  count
+  create
+  delete
+  delete_bulk
+  delete_single
+  find
+  find_single
+  update
+  update_bulk
+).each do |f|
   require "ncore/methods/#{f}"
 end
 
 require 'ncore/rails/action_controller' if defined?(::ActionController)
-require 'ncore/rails/active_model' if defined?(::ActiveModel)
-require 'ncore/rails/module_fix'
+require 'ncore/rails/active_model'

data/lib/ncore/associations.rb

@@ -1,17 +1,17 @@
 module NCore
   module Associations
 
-    def has_many(assoc, klass=nil)
+    def has_many(assoc, class_name: nil)
       assoc = assoc.to_s
-      klass ||= "#{module_name}::#{assoc.camelize.singularize}"
+      klass = class_name || "#{module_name}::#{assoc.camelize.singularize}"
       key = "#{attrib_name}_id"
       class_eval <<-M1, __FILE__, __LINE__+1
         def #{assoc}(params={})
           return [] unless id
           reload = params.delete :reload
-          params = parse_request_params(params).reverse_merge credentials: api_creds
           cacheable = params.except(:credentials, :request).empty?
-          params.merge! #{key}: id
+          params = parse_request_params(params).reverse_merge credentials: api_creds
+          params[:#{key}] = id
           if cacheable
             # only cache unfiltered, default api call
             @attribs[:#{assoc}] = (!reload && @attribs[:#{assoc}]) || #{klass}.all(params)
@@ -24,7 +24,7 @@ module NCore
         def find_#{assoc.singularize}(aid, params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.find(aid, params)
         end
       M2
@@ -33,7 +33,7 @@ module NCore
         def create_#{assoc.singularize}(params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.create(params)
         end
       M3
@@ -42,7 +42,7 @@ module NCore
         def update_#{assoc.singularize}(aid, params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.update(aid, params)
         end
       M4
@@ -50,7 +50,7 @@ module NCore
         def create_#{assoc.singularize}!(params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.create!(params)
         end
       M5
@@ -58,7 +58,7 @@ module NCore
         def update_#{assoc.singularize}!(aid, params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.update!(aid, params)
         end
       M6
@@ -67,7 +67,7 @@ module NCore
         def delete_#{assoc.singularize}(aid, params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.delete(aid, params)
         end
       M7
@@ -75,15 +75,15 @@ module NCore
         def delete_#{assoc.singularize}!(aid, params={})
           raise UnsavedObjectError unless id
           params = parse_request_params(params).reverse_merge credentials: api_creds
-          params.merge! #{key}: id
+          params[:#{key}] = id
           #{klass}.delete!(aid, params)
         end
       M8
     end
 
-    def belongs_to(assoc, klass=nil)
+    def belongs_to(assoc, class_name: nil)
       assoc = assoc.to_s
-      klass ||= "#{module_name}::#{assoc.camelize}"
+      klass = class_name || "#{module_name}::#{assoc.camelize}"
       class_eval <<-M1, __FILE__, __LINE__+1
         attr :#{assoc}_id
         def #{assoc}(params={})

data/lib/ncore/attributes.rb

@@ -10,6 +10,7 @@ module NCore
     module ClassMethods
       def attr(*attrs)
         attrs.each do |attr|
+          check_existing_method(attr)
           class_eval <<-AR, __FILE__, __LINE__+1
             def #{attr}
               self[:#{attr}]
@@ -20,6 +21,7 @@ module NCore
 
       def attr_datetime(*attrs)
         attrs.each do |attr|
+          check_existing_method(attr)
           class_eval <<-AD, __FILE__, __LINE__+1
             def #{attr}
               case self[:#{attr}]
@@ -39,6 +41,7 @@ module NCore
 
       def attr_decimal(*attrs)
         attrs.each do |attr|
+          check_existing_method(attr)
           class_eval <<-AD, __FILE__, __LINE__+1
             def #{attr}
               case self[:#{attr}]
@@ -52,10 +55,20 @@ module NCore
         end
       end
 
+      def check_existing_method(attr)
+        if method_defined?(attr) || private_method_defined?(attr)
+          sc = self
+          sc = sc.superclass while sc.superclass != Object
+          warn "Warning: Existing method #{sc.name}##{attr} being overwritten at #{caller[3]}"
+        end
+      end
+
       def parse_request_params(params={}, opts={})
         params = params.with_indifferent_access
         req = params.delete(:request)
+        hdr = params.delete(:headers)
         creds = params.delete(:credentials)
+        cache = params.delete(:cache)
         if opts[:json_root]
           if params.key?(opts[:json_root])
             o = params
@@ -66,7 +79,9 @@ module NCore
           o = params
         end
         o[:request] = req if req
+        o[:headers] = hdr if hdr
         o[:credentials] = creds if creds
+        o[:cache] = cache if cache
         o
       end
     end
@@ -86,23 +101,18 @@ module NCore
       creds_attr = attribs.delete(:credentials)
       @api_creds = api_creds || creds_attr
 
-      if attribs.keys.sort == %w(data error metadata)
-        load_attrs = attribs
-      else
-        load_attrs = {
-          metadata: attribs.delete(:metadata),
-          errors: attribs.delete(:errors),
-          data: attribs.delete(:data) || attribs
-        }
-      end
-      load(load_attrs)
+      load(
+        metadata: attribs.delete(:metadata),
+        errors: attribs.delete(:errors),
+        data: attribs.delete(:data) || attribs
+      )
     end
 
 
     def attributes
       Util.deep_clone(@attribs)
     end
-
+    alias_method :as_json, :attributes
 
     def [](attr)
       @attribs[attr]
@@ -150,10 +160,10 @@ module NCore
     end
 
 
-    def load(parsed)
-      self.metadata = parsed[:metadata] || {}.with_indifferent_access
-      self.errors = parsed[:errors] || {}.with_indifferent_access
-      parsed[:data].each do |k,v|
+    def load(data:, errors: nil, metadata: nil)
+      self.metadata = metadata || {}.with_indifferent_access
+      self.errors = parse_errors(errors)
+      data.each do |k,v|
         if respond_to? "#{k}="
           send "#{k}=", self.class.interpret_type(v, api_creds)
         else
@@ -163,6 +173,17 @@ module NCore
       self
     end
 
+    def parse_errors(errors)
+      errors ||= []
+      if errors.is_a?(::ActiveModel::Errors)
+        errors
+      else
+        ::ActiveModel::Errors.new(self).tap do |e0|
+          errors.each{|msg| e0.add :base, msg }
+        end
+      end
+    end
+
   end
 
 

data/lib/ncore/base.rb

@@ -4,8 +4,10 @@ module NCore
     
     included do
       extend Associations
+      include ActiveModel
       include Attributes
       include Client
+      include Client::Cache
       include Identity
       include Lifecycle
       include Util
@@ -21,15 +23,16 @@ module NCore
         include DeleteBulk if types.include? :delete_bulk
         include Find   if types.include? :find
         include Update if types.include? :update
+        include UpdateBulk if types.include? :update_bulk
       end
 
-      def url
+      def resource_path
         class_name.underscore.pluralize
       end
     end
 
-    def url
-      "#{self.class.url}/#{CGI.escape((id||'-').to_s)}"
+    def resource_path
+      "#{self.class.resource_path}/#{CGI.escape((id||'-').to_s)}"
     end
 
   end

data/lib/ncore/client.rb

@@ -6,11 +6,12 @@ module NCore
 
     module ClassMethods
 
-      # opts - {params: {}, headers: {}, credentials: {}}
+      # opts - {params: {}, headers: {}, credentials: {}, cache: {}}
       #   unknown keys assumed to be :params if :params is missing
       def request(method, url, opts={})
         opts = opts.with_indifferent_access
         request_credentials = opts.delete 'credentials'
+        cache_opts = opts.delete 'cache'
         headers = opts.delete('headers') || {}
         params = opts['params'] || opts
 
@@ -48,7 +49,7 @@ module NCore
           write_timeout: 50,
         }
 
-        response = execute_request(rest_opts)
+        response = execute_request(rest_opts, cache_opts)
         parsed = parse_response(response)
         [parsed, request_credentials]
       end
@@ -58,7 +59,7 @@ module NCore
 
       def retrieve_credentials
         if credentials.blank?
-          raise parent::Error, credentials_error_message
+          raise module_parent::Error, credentials_error_message
         end
         credentials
       end
@@ -69,7 +70,7 @@ module NCore
 
       def retrieve_default_url
         if default_url.blank?
-          raise parent::Error, credentials_error_message
+          raise module_parent::Error, credentials_error_message
         end
         default_url
       end
@@ -87,12 +88,12 @@ module NCore
 
       def build_query_string(params)
         if params.any?
-          query_string = params.map do |k,v|
+          query_string = params.sort.map do |k,v|
             if v.is_a?(Array)
               if v.empty?
                 "#{k.to_s}[]="
               else
-                v.map do |v2|
+                v.sort.map do |v2|
                   "#{k.to_s}[]=#{CGI::escape(v2.to_s)}"
                 end.join('&')
               end
@@ -163,7 +164,7 @@ module NCore
       end
 
 
-      def execute_request(rest_opts)
+      def execute_request(rest_opts, _)
         debug_request rest_opts if debug
 
         tries = 0
@@ -175,7 +176,8 @@ module NCore
             begin
               tries += 1
               response = connection.request rest_opts.except(:url)
-            rescue Excon::Errors::SocketError, Excon::Error::Timeout, Errno::EADDRNOTAVAIL => e
+            rescue Excon::Error::Socket, Excon::Errors::SocketError, Excon::Error::Timeout,
+                Errno::EADDRNOTAVAIL => e
               # retry when keepalive was closed
               if tries <= 1 #&& e.message =~ /end of file reached/
                 retry
@@ -187,30 +189,30 @@ module NCore
             debug_response response if debug
           end
         rescue Errno::ECONNRESET
-          raise parent::ConnectionError, "Connection reset for #{host_for_error rest_opts[:url]} : check network or visit #{status_page}."
+          raise module_parent::ConnectionError, "Connection reset for #{host_for_error rest_opts[:url]} : check network or visit #{status_page}."
         rescue Errno::ECONNREFUSED
-          raise parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+          raise module_parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
         rescue Excon::Error::Timeout => e
           case e.message
           when /timeout reached/
-            raise parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+            raise module_parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
           else
             raise e
           end
         rescue Excon::Errors::SocketError => e
           case e.message
           when /Unable to verify certificate/
-            raise parent::ConnectionError, "Unable to verify certificate for #{host_for_error rest_opts[:url]} : verify URL, set ssl_cert_bundle=, or disable SSL certificate verification (insecure)."
+            raise module_parent::ConnectionError, "Unable to verify certificate for #{host_for_error rest_opts[:url]} : verify URL, set ssl_cert_bundle=, or disable SSL certificate verification (insecure)."
           when /Name or service not known/, /No address associated with hostname/
-            raise parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+            raise module_parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
           when /Errno::ECONNREFUSED/
-            raise parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+            raise module_parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
           else
             raise e
           end
         rescue SocketError => e
           if e.message =~ /nodename nor servname provided/
-            raise parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+            raise module_parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
           else
             raise e
           end
@@ -218,21 +220,21 @@ module NCore
 
         case response.status
         when 401 # API auth valid; API call itself is an auth-related call and failed
-          raise parent::AuthenticationFailed
+          raise module_parent::AuthenticationFailed
         when 402
-          raise parent::AccountInactive, "Account inactive; login to portal to check account status."
+          raise module_parent::AccountInactive, "Account inactive; login to portal to check account status."
         when 403 # API auth failed or insufficient permissions
-          raise parent::AccessDenied, "Access denied; check your API credentials and permissions."
+          raise module_parent::AccessDenied, "Access denied; check your API credentials and permissions."
         when 404
-          raise parent::RecordNotFound
+          raise module_parent::RecordNotFound
         when 409, 422
           # pass through
         when 429
-          raise parent::RateLimited
+          raise module_parent::RateLimited
         when 400..499
-          raise parent::Error, "Client error: #{response.status}\n  #{response.body}"
+          raise module_parent::Error, "Client error: #{response.status}\n  #{response.body}"
         when 500..599
-          raise parent::Error, "Server error: #{response.status}\n  #{response.body}"
+          raise module_parent::Error, "Server error: #{response.status}\n  #{response.body}"
         end
         response
       end
@@ -245,20 +247,20 @@ module NCore
             begin
               json = MultiJson.load(response.body, symbolize_keys: false) || {}
             rescue MultiJson::ParseError
-              raise parent::Error, "Unable to parse API response; HTTP status: #{response.status}; body: #{response.body.inspect}"
+              raise module_parent::Error, "Unable to parse API response; HTTP status: #{response.status}; body: #{response.body.inspect}"
             end
           else
             begin
               json = JSON.parse(response.body, symbolize_names: false) || {}
             rescue JSON::ParserError
-              raise parent::Error, "Unable to parse API response; HTTP status: #{response.status}; body: #{response.body.inspect}"
+              raise module_parent::Error, "Unable to parse API response; HTTP status: #{response.status}; body: #{response.body.inspect}"
             end
           end
         end
         json = json.with_indifferent_access
         errors = json.delete(:errors) || []
         if errors.any?
-          errors = errors.values.flatten
+          errors = errors.values.flatten if errors.is_a?(Hash)
           metadata, json = json, {}
         else
           errors = []
@@ -299,12 +301,12 @@ module NCore
           if ssl_cert_bundle
             bundle_readable = File.readable?(ssl_cert_bundle) rescue false
             unless bundle_readable
-              raise parent::CertificateError, "Unable to read SSL cert bundle #{ssl_cert_bundle}."
+              raise module_parent::CertificateError, "Unable to read SSL cert bundle #{ssl_cert_bundle}."
             end
           end
           @verify_ssl_cert = true
         else
-          m = "WARNNG: SSL cert verification is disabled. Enable verification with: #{parent}::Api.verify_ssl = true."
+          m = "WARNNG: SSL cert verification is disabled. Enable verification with: #{module_parent}::Api.verify_ssl = true."
           $stderr.puts m
           @verify_ssl_cert = false
         end