ncore 2.3.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57e1ee1a969b6a8679b297f537fe6d2c6d95418d75db88cce96c8342e3ff29ac
-  data.tar.gz: 45b8e54512221b1510ed57a9c594d2818cf4b1b86dce448145d1786422c8e788
+  metadata.gz: 63b5e71f6a7f803b1a270e81b5f443f41490274387873395dbcc9c05a5cdcca2
+  data.tar.gz: 875e34f54fd4ba0e014c91ab371be8b6d1202e908cd6470b11666e12e82577b8
 SHA512:
-  metadata.gz: a9b61a2fcba5cdd6640b37ba99400acd45348ae4ee65d51f56b4cb3a25a180670e3b4b02a53276b68fca0e77d5c669e0a835fe7c7057df9006e8e71e7b797080
-  data.tar.gz: 7e146be87089170ce8fd889bcfc3c055caf476f918297707d174bc86ad395db7eaafc61e3c0e49c912b90909b675a61eec35b97d0be36897f8a7bec7d9bbd4c0
+  metadata.gz: 06c85c6685ae41485761e725fb370688846df1b38e5097cf60222f97c7040f2b94f74d250fb37efdc8feff8dbe3b15ca8e366ff2c9f87204de36bea395ee5d2a
+  data.tar.gz: f5ae351e39942821b41e95a6ae17baa9536696a806847c98e693f3526345c999ef42b9babee6b25fcbae5cf79efdaebd4341c14f01f4c91c6251b8a8320c7155

data/CHANGELOG.md

@@ -1,25 +1,39 @@
-#### 2.3.3
-
-- Improve keepalive handling
-
-#### 2.3.2
-
-- Allow ActiveSupport 7.0
-
-#### 2.3.1
-
-- Allow ActiveSupport 6.1
-
-#### 2.3.0
-
-- Use system's CA certificate store by default (backport from v3.2.0)
-  To use bundled CAs instead:
-    SomeAppName::Api.ssl_cert_bundle = :bundled
-  On failure reading specified bundle, raises exception instead of warning
-
-#### 2.2.2
-
-- Update certs
+#### 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.2.1
 
@@ -110,4 +124,4 @@
 
 #### 1.0.0
 
-- Initial release
+- Initial release

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2018 Notioneer, Inc.
+Copyright (c) 2014-2020 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,12 @@ 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
+
+    # 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/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,19 @@ 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)
         creds = params.delete(:credentials)
+        cache = params.delete(:cache)
         if opts[:json_root]
           if params.key?(opts[:json_root])
             o = params
@@ -67,6 +79,7 @@ module NCore
         end
         o[:request] = req if req
         o[:credentials] = creds if creds
+        o[:cache] = cache if cache
         o
       end
     end
@@ -86,23 +99,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 +158,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 +171,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
@@ -23,13 +25,13 @@ module NCore
         include Update if types.include? :update
       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
@@ -176,7 +177,7 @@ module NCore
               tries += 1
               response = connection.request rest_opts.except(:url)
             rescue Excon::Error::Socket, Excon::Errors::SocketError, Excon::Error::Timeout,
-                Errno::EADDRNOTAVAIL, Errno::ECONNRESET => e
+                Errno::EADDRNOTAVAIL => e
               # retry when keepalive was closed
               if tries <= 1 #&& e.message =~ /end of file reached/
                 retry
@@ -188,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 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
@@ -219,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
@@ -246,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 = []
@@ -296,16 +297,17 @@ module NCore
 
       def verify_ssl_cert?
         return @verify_ssl_cert unless @verify_ssl_cert.nil?
-        if verify_ssl
-          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}."
-            end
-          end
+        bundle_readable = File.readable?(ssl_cert_bundle)
+        if verify_ssl && bundle_readable
           @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.'
+          unless verify_ssl
+            m += " Enable verification with: #{module_parent}::Api.verify_ssl = true."
+          end
+          unless bundle_readable
+            m += " Unable to read CA bundle #{ssl_cert_bundle}."
+          end
           $stderr.puts m
           @verify_ssl_cert = false
         end

data/lib/ncore/client_cache.rb

@@ -0,0 +1,48 @@
+module NCore
+  module Client::Cache
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      private
+
+      # cache_opts: true
+      #   use *::Api.cache_store
+      # cache_opts: {...}
+      #   use: *::Api.cache_store, with options: {...}
+      #   hint: add  force: true  execute the query and rewrite the cache
+      # cache_opts: Store.new
+      #   use Store.new as-is
+      def execute_request(req, cache_opts=nil)
+        case cache_opts
+        when true
+          store, cache_opts = cache_store, {}
+        when Hash
+          store, cache_opts = cache_store, cache_opts.symbolize_keys
+        when nil, false
+          store = false
+        else
+          store, cache_opts = cache_opts, {}
+        end
+
+        if store && req[:method] == :get
+          store.fetch request_cache_key(req.slice(:url, :headers)), cache_opts do
+            super
+          end
+        else
+          super
+        end
+      end
+
+
+      def request_cache_key(url:, headers:)
+        [ 'ncore',
+          url.gsub(/[^a-zA-Z0-9]+/,'-'),
+          Digest::MD5.hexdigest(headers.sort.to_s)
+        ].join ':'
+      end
+
+    end
+
+  end
+end

data/lib/ncore/configuration.rb

@@ -28,6 +28,9 @@ module NCore
         mattr_accessor :strict_attributes
         self.strict_attributes = true
 
+        mattr_accessor :i18n_scope
+        self.i18n_scope = :ncore
+
         mattr_accessor :instrument_key
         self.instrument_key = 'request.ncore'
 
@@ -37,42 +40,31 @@ module NCore
         mattr_accessor :auth_header_prefix
         self.auth_header_prefix = 'X-Api'
 
-        mattr_accessor :bearer_credential_key
+        mattr_reader :bearer_credential_key
+        class_eval <<-MTH
+          def self.bearer_credential_key=(v)
+            @@bearer_credential_key = v&.to_s
+          end
+          def bearer_credential_key=(v)
+            @@bearer_credential_key = v&.to_s
+          end
+        MTH
 
         mattr_accessor :credentials_error_message
-        self.credentials_error_message = %Q{Missing API credentials. Set default credentials using "#{self.parent.name}.credentials = {api_user: YOUR_API_USER, api_key: YOUR_API_KEY}"}
+        self.credentials_error_message = %Q{Missing API credentials. Set default credentials using "#{self.module_parent.name}.credentials = {api_user: YOUR_API_USER, api_key: YOUR_API_KEY}"}
 
         mattr_accessor :verify_ssl
         self.verify_ssl = true
 
-        mattr_reader :ssl_cert_bundle
-        class_eval <<-MTH
-          def self.ssl_cert_bundle=(v)
-            v = find_excon_bundle if v==:bundled
-            @@ssl_cert_bundle = v
-          end
-          def ssl_cert_bundle=(v)
-            v = find_excon_bundle if v==:bundled
-            @@ssl_cert_bundle = v
-          end
-        MTH
+        mattr_accessor :ssl_cert_bundle
+        self.ssl_cert_bundle = File.dirname(__FILE__)+'/ssl/ca-certificates.crt'
+
+        mattr_accessor :cache_store
 
         mattr_accessor :logger
         self.logger = Logger.new(STDOUT)
       end
 
-
-      private
-
-      def find_excon_bundle
-        b = Gem.find_files_from_load_path('../data/cacert.pem').select{|p| p=~/excon/}.first
-        if b
-          b.freeze
-        else
-          raise parent::CertificateError, 'Failed to locate CA cert bundle from excon. Specify a full path instead.'
-        end
-      end
-
     end
 
   end