ecoportal-api-v2 1.1.8 → 2.0.0

data/lib/ecoportal/api/v2/s3/files.rb

@@ -0,0 +1,132 @@
+module Ecoportal
+  module API
+    class V2
+      # @attr_reader client [Common::Client] a `Common::Client` object that
+      #   holds the configuration of the api connection.
+      class S3
+        class Files
+          class FailedPollRequest < StandardError; end
+          class CantCheckStatus < StandardError; end
+
+          extend Common::BaseClass
+
+          POLL_TIMEOUT       = 240
+          DELAY_STATUS_CHECK = 5
+
+          class_resolver :poll_class, "Ecoportal::API::V2::S3::Files::Poll"
+          class_resolver :poll_status_class, "Ecoportal::API::V2::S3::Files::PollStatus"
+
+          attr_reader :client, :s3_api
+
+          # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+          # @param s3_api [V2::S3] the parent S3 api object.
+          # @return [Schemas] an instance object ready to make schema api requests.
+          def initialize(client, s3_api:)
+            @client = client
+            @s3_api = s3_api
+          end
+
+          # Helper to upload multiple files at once
+          def upload!(files, **kargs, &block)
+            BatchUpload.new(files, files_api: self).upload!(**kargs, &block)
+          end
+
+          # Tell ecoPortal to register the file in an actual File Container
+          # @note this is essential to do for the file to be attachable.
+          #   - eP will scan the file and give create the proper data model that
+          #     refers to the file (FileContainer).
+          #   - FileContainers also have a file versioning sytem.
+          #   - A file container belongs only to one single organization.
+          # @yield [poll] block early, when the poll is created
+          # @yieldparam poll [Ecoportal::API::V2::S3::Files::Poll, NilClass] the creatd poll
+          # @param s3_file_reference [Hash]
+          # @return [Ecoportal::API::V2::S3::Files::PollStatus, NilClass]
+          #    when finalized (success, failed or timeout)
+          def poll!(
+            s3_file_reference,
+            check_delay:   DELAY_STATUS_CHECK,
+            raise_timeout: false
+          )
+            raise ArgumentError, "Block required. None given" unless block_given?
+
+            poll = create_poll(s3_file_reference)
+            yield(poll) if block_given?
+
+            wait_for_poll_completion(poll.id, check_delay: check_delay).tap do |status|
+              poll.status = status
+
+              next unless raise_timeout
+              next if status&.complete?
+
+              msg  = "File poll `#{poll.id}` not complete. "
+              msg << "Probably timeout after #{POLL_TIMEOUT} seconds. "
+              msg << "Current status: #{poll.status.status}"
+
+              raise Ecoportal::API::Errors::TimeOut, msg
+            end
+          end
+
+          # Create Poll Request to ecoPortal so it registers the file
+          # in an actual File Container
+          # @param s3_file_reference [Hash]
+          # @return [Ecoportal::API::V2::S3::Files::Poll, NilClass]
+          def create_poll(s3_file_reference)
+            response = client.post("/s3/files", data: s3_file_reference)
+            body     = body_data(response.body)
+
+            return poll_class.new(body) if response.success?
+
+            msg = "Could not create poll request for\n"
+            msg << JSON.pretty_generate(s3_file_reference)
+            msg << "\n - Error #{response.status}: #{body}"
+            raise FailedPollRequest, msg
+          end
+
+          # Check progress on the File Poll status
+          # @param poll_id [String]
+          def poll_status(poll_id)
+            response = client.get("/s3/files/poll/#{poll_id}")
+            body     = body_data(response.body)
+
+            return poll_status_class.new(body) if response.success?
+
+            msg = "Could not get status for poll '#{poll_id}' "
+            msg << "- Error #{response.status}: #{body}"
+            raise CantCheckStatus, msg
+          end
+
+          private
+
+          def body_data(body)
+            return body unless body.is_a?(Hash)
+            return body unless body.key?("data")
+
+            body["data"]
+          end
+
+          # @note timeout library is evil. So we make poor-man timeout.
+          #   https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
+          def wait_for_poll_completion(poll_id, check_delay: DELAY_STATUS_CHECK)
+            before = Time.now
+
+            loop do
+              status = poll_status(poll_id)
+              break status if status&.complete?
+
+              if Time.now >= before + POLL_TIMEOUT
+                status&.status = 'timeout'
+                break status
+              end
+
+              sleep(check_delay)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/v2/s3/files/poll'
+require 'ecoportal/api/v2/s3/files/poll_status'
+require 'ecoportal/api/v2/s3/files/batch_upload'

data/lib/ecoportal/api/v2/s3/upload.rb

@@ -0,0 +1,154 @@
+module Ecoportal
+  module API
+    class V2
+      class S3
+        class Upload
+          class MissingFile < ArgumentError; end
+
+          DEFAULT_MIME_TYPE = 'application/octet-stream'.freeze
+          EXPECTED_CODE     = "204".freeze # No Content
+          MAX_RETRIES       = 5
+
+          attr_reader :filename
+
+          def initialize(credentials, file:)
+            msg = "Expecting #{credentials_class}. Given: #{credentials.class}"
+            raise ArgumentError, msg unless credentials.is_a?(credentials_class)
+
+            @credentials = credentials
+            @filename    = file
+          end
+
+          def upload!
+            require_deps!
+
+            @response = Net::HTTP.start(
+              uri.hostname,
+              uri.port,
+              use_ssl: true
+            ) do |https|
+              https.max_retries = self.class::MAX_RETRIES
+              https.request(request)
+            end
+
+            return unless success?
+
+            yield(s3_file_reference) if block_given?
+            s3_file_reference
+          end
+
+          def failed?
+            return false unless response
+
+            response.code != EXPECTED_CODE
+          end
+
+          def success?
+            return false unless response
+
+            response.code == EXPECTED_CODE
+          end
+
+          def s3_file_reference
+            return unless success?
+
+            @s3_file_reference ||= {
+              'filename' => file_basename,
+              'filetype' => mime_type,
+              'filesize' => file_size,
+              'path'     => s3_file_path
+            }
+          end
+
+          private
+
+          attr_reader :credentials
+          attr_reader :response
+
+          def request
+            Net::HTTP::Post.new(uri).tap do |req|
+              req.set_form form_data, 'multipart/form-data'
+            end
+          end
+
+          def uri
+            @uri ||= URI(credentials[:s3_endpoint])
+          end
+
+          def form_data
+            [
+              ['key', s3_file_path],
+              *aws_params,
+              *file_params
+            ]
+          end
+
+          def s3_file_path
+            "#{user_tmpdir}/#{file_basename}"
+          end
+
+          def user_tmpdir
+            credentials[:user_tmpdir]
+          end
+
+          def aws_params
+            params = %i[AWSAccessKeyId policy signature x-amz-server-side-encryption]
+            params.map do |key|
+              [key.to_s, credentials[key]]
+            end
+          end
+
+          def file_params
+            [
+              ['content-type', mime_type],
+              ['file',         io_stream]
+            ]
+          end
+
+          def mime_type
+            @mime_type ||= lib_mime_type || DEFAULT_MIME_TYPE
+          end
+
+          def lib_mime_type
+            MIME::Types.type_for(file_extension).first&.content_type
+          end
+
+          def io_stream
+            require_file!
+            File.open(file_fullname)
+          end
+
+          def credentials_class
+            Ecoportal::API::V2::S3::Data
+          end
+
+          def file_size
+            @file_size ||= File.size(file_fullname)
+          end
+
+          def file_extension
+            @file_extension ||= File.extname(filename)[1..]
+          end
+
+          def file_basename
+            @file_basename ||= File.basename(filename)
+          end
+
+          def file_fullname
+            @file_fullname ||= File.expand_path(filename)
+          end
+
+          def require_file!
+            msg = "File '#{file_basename}' doesn't exist"
+            raise MissingFile, msg unless File.exist?(file_fullname)
+          end
+
+          def require_deps!
+            require 'net/http'
+            require 'mime/types'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v2/s3.rb

@@ -0,0 +1,66 @@
+module Ecoportal
+  module API
+    class V2
+      # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+      class S3
+        class MissingLocalFile < ArgumentError; end
+        class CredentialsGetFailed < StandardError; end
+
+        extend Common::BaseClass
+
+        class_resolver :data_class, "Ecoportal::API::V2::S3::Data"
+        class_resolver :files_class, "Ecoportal::API::V2::S3::Files"
+
+        attr_reader :client
+
+        # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+        # @return [Schemas] an instance object ready to make schema api requests.
+        def initialize(client)
+          @client = client
+        end
+
+        # Gets the S3 credentials to upload files
+        # @return [Ecoportal::API::V2::S3::Data]
+        def data
+          response = client.get("/s3/data")
+          body     = body_data(response.body)
+
+          return data_class.new(body) if response.success?
+
+          msg = "Could not get S3 credentials - Error #{response.status}: #{body}"
+          raise CredentialsGetFailed, msg
+        end
+
+        # @param file [String] full path to existing local file
+        # @param credentials [Ecoportal::API::V2::S3::Data, NilClass]
+        # @return [Hash, NilClass] with the s3_file_reference on success, and `nil` otherwise
+        def upload_file(file, credentials: data, &block)
+          msg = "The file '#{file}' does not exist"
+          raise MissingLocalFile, msg unless File.exist?(file)
+
+          credentials ||= data
+          Upload.new(credentials, file: file).upload!(&block)
+        end
+
+        # Obtain specific object for eP file api requests.
+        # @return [Files] an instance object ready to make eP file api requests.
+        def files
+          files_class.new(client, s3_api: self)
+        end
+
+        private
+
+        def body_data(body)
+          return body unless body.is_a?(Hash)
+          return body unless body.key?("data")
+
+          body["data"]
+        end
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/v2/s3/data'
+require 'ecoportal/api/v2/s3/upload'
+require 'ecoportal/api/v2/s3/files'

data/lib/ecoportal/api/v2.rb

@@ -8,10 +8,10 @@ module Ecoportal
       extend Common::BaseClass
       include Common::Logging
 
-      VERSION = "v2"
+      VERSION = "v2".freeze
 
       class << self
-        def v2key (ukey, gkey)
+        def v2key(ukey, gkey)
           Base64.urlsafe_encode64({
             organization: gkey,
             user:         ukey
@@ -22,6 +22,7 @@ module Ecoportal
       class_resolver :people_class,    "Ecoportal::API::V2::People"
       class_resolver :registers_class, "Ecoportal::API::V2::Registers"
       class_resolver :pages_class,     "Ecoportal::API::V2::Pages"
+      class_resolver :s3_class,        "Ecoportal::API::V2::S3"
 
       attr_reader :client, :logger
 
@@ -64,6 +65,12 @@ module Ecoportal
         pages_class.new(client)
       end
 
+      # Obtain specific object for file api requests.
+      # @return [S3] an instance object ready to make files api requests.
+      def s3 # rubocop:disable Naming/VariableNumber
+        s3_class.new(client)
+      end
+
       private
 
       def get_key(api_key: nil, user_key: nil, org_key: nil)
@@ -72,7 +79,6 @@ module Ecoportal
         raise "You need to provide either an api_key or user_key" unless user_key
         raise "You need to provide an org_key as well (not just a user_key)" unless org_key
       end
-
     end
   end
 end
@@ -80,3 +86,4 @@ end
 require 'ecoportal/api/v2/people'
 require 'ecoportal/api/v2/pages'
 require 'ecoportal/api/v2/registers'
+require 'ecoportal/api/v2/s3'

data/lib/ecoportal/api/v2_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GEM2_VERSION = "1.1.8".freeze
+    GEM2_VERSION = "2.0.0".freeze
   end
 end

metadata

@@ -1,55 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 1.1.8
+  version: 2.0.0
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-22 00:00:00.000000000 Z
+date: 2024-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.4.12
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.4.12
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
-- !ruby/object:Gem::Dependency
-  name: rspec
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.12.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '0.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.12.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -71,32 +45,32 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '14'
 - !ruby/object:Gem::Dependency
-  name: yard
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.34
+        version: 3.6.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.34
+        version: 3.6.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '4'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: 3.12.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '4'
@@ -106,44 +80,58 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: 3.12.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '4'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: 0.9.34
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: 0.9.34
 - !ruby/object:Gem::Dependency
   name: ecoportal-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.6
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.6
-    - - "<"
+        version: 3.5.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '3.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.2
 description:
 email:
 - rien@ecoportal.co.nz
@@ -154,8 +142,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".markdownlint.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -169,6 +159,7 @@ files:
 - lib/ecoportal/api/common.v2.rb
 - lib/ecoportal/api/common/concerns.rb
 - lib/ecoportal/api/common/concerns/benchmarkable.rb
+- lib/ecoportal/api/common/concerns/threadable.rb
 - lib/ecoportal/api/common/content.rb
 - lib/ecoportal/api/common/content/array_model.rb
 - lib/ecoportal/api/common/content/class_helpers.rb
@@ -249,11 +240,19 @@ files:
 - lib/ecoportal/api/v2/registers/stage_result.rb
 - lib/ecoportal/api/v2/registers/stages_result.rb
 - lib/ecoportal/api/v2/registers/template.rb
+- lib/ecoportal/api/v2/s3.rb
+- lib/ecoportal/api/v2/s3/data.rb
+- lib/ecoportal/api/v2/s3/files.rb
+- lib/ecoportal/api/v2/s3/files/batch_upload.rb
+- lib/ecoportal/api/v2/s3/files/poll.rb
+- lib/ecoportal/api/v2/s3/files/poll_status.rb
+- lib/ecoportal/api/v2/s3/upload.rb
 - lib/ecoportal/api/v2_version.rb
 homepage: https://www.ecoportal.com
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -262,14 +261,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.2
+      version: 3.2.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: A collection of helpers for interacting with the ecoPortal MS's V2 API