client: Allow passing custom download URLs to the download API

CHANGELOG.md

@@ -4,7 +4,13 @@ Breaking changes are prefixed with a "[BREAKING]" label.
 
 ## master (unreleased)
 
+## 0.2.0 (2025-10-01)
+
 - Add compatibility for Ruby 3.4 and 3.5
+- Add support for `Ferto::Job#download` method to accept a custom `download_url` parameter.
+  - This parameter will be the URL prefix (scheme://host) in downloader's
+  callback download_url in order for the client to be able to locate the job's
+  result file.
 
 ## 0.1.0 (2023-06-16)
 

lib/ferto/callback.rb

@@ -1,3 +1,5 @@
+require 'uri'
+
 module Ferto
   class Callback
     # @return [String, NilClass] The error message of the download or nil if there was
@@ -11,6 +13,9 @@ class Callback
     #   fetched.
     attr_reader :download_url
 
+    # @return [String] The download URL scheme
+    attr_reader :download_url_scheme
+
     # @return [String] The original resource URL of the job.
     attr_reader :resource_url
 
@@ -39,6 +44,13 @@ def initialize(params)
       @error = params[:error]
       @extra = params[:extra]
       @download_url = params[:download_url]
+
+      begin
+        @download_url_scheme = URI.parse(@download_url).scheme
+      rescue URI::Error, TypeError
+        @download_url_scheme = nil
+      end
+
       @resource_url = params[:resource_url]
       @job_id = params[:job_id]
       @response_code = params[:response_code]

lib/ferto/client.rb

@@ -69,6 +69,8 @@ def initialize(opts = {})
     #   the desired resource
     # @param subpath [String] the subfolder(s) that the jobs will be stored
     #   under the top level directory of storage backend
+    # @param download_url [String] the URL prefix (scheme://host) that will be used in the callback to
+    #   signify the job result file location
     #
     # @example
     #   client.download(
@@ -82,6 +84,7 @@ def initialize(opts = {})
     #     mime_type: "image/jpeg",
     #     request_headers: { "Accept" => "image/*,*/*;q=0.8" },
     #     extra: { something: 'someone' }
+    #     download_url: 'https://mybucket.s3.amazonaws.com/a.jpg'
     #   )
     #
     # @raise [Ferto::ConnectionError] if there was an error scheduling the
@@ -97,7 +100,8 @@ def download(aggr_id:, aggr_limit: @aggr_limit, url:,
                  callback_error_type: "", callback_error_dst: "",
                  mime_type: "", extra: {},
                  request_headers: {},
-                 s3_bucket: nil, s3_region: nil, subpath: nil)
+                 s3_bucket: nil, s3_region: nil, subpath: nil,
+                 download_url: nil)
       uri = URI::HTTP.build(
         scheme: scheme, host: host, port: port, path: path
       )
@@ -107,7 +111,7 @@ def download(aggr_id:, aggr_limit: @aggr_limit, url:,
         callback_error_type, callback_error_dst,
         aggr_proxy, download_timeout, user_agent,
         mime_type, extra, request_headers,
-        s3_bucket, s3_region, subpath
+        s3_bucket, s3_region, subpath, download_url
       )
       # Curl.post reuses the same handler
       begin
@@ -144,7 +148,7 @@ def build_body(aggr_id, aggr_limit, url, callback_url, callback_type,
                    callback_dst, callback_error_type, callback_error_dst,
                    aggr_proxy, download_timeout, user_agent,
                    mime_type, extra, request_headers,
-                   s3_bucket, s3_region, subpath)
+                   s3_bucket, s3_region, subpath, download_url)
       body = {
         aggr_id: aggr_id,
         aggr_limit: aggr_limit,
@@ -198,6 +202,8 @@ def build_body(aggr_id, aggr_limit, url, callback_url, callback_type,
 
       body[:request_headers] = request_headers
 
+      body[:download_url] = download_url unless download_url.to_s.empty?
+
       body
     end
   end

lib/ferto/version.rb

@@ -1,3 +1,3 @@
 module Ferto
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

spec/ferto/callback_spec.rb

@@ -10,6 +10,14 @@
       it 'processes the download url' do
         expect(subject).to be_download_successful
       end
+
+      context 'with custom download URL' do
+        let(:params) { FactoryBot.build(:successful_callback, download_url: 's3://bucket/key')}
+
+        it 'parses the download URL scheme' do
+          expect(subject.download_url_scheme).to eq('s3')
+        end
+      end
     end
 
     context 'when there are errors' do

spec/ferto/client_spec.rb

@@ -40,7 +40,8 @@
         callback_dst: 'http://example.com/downloads/myfile',
         user_agent: "Downloader Agent v1.0",
         extra: { product: 1234, actor: 'actor1' },
-        request_headers: { "Accept" => "image/*" }
+        request_headers: { "Accept" => "image/*" },
+        download_url: "s3://a-beautiful-bucket.s3.amazonaws.com/path/to/file"
       }
     end
     let(:body_args) do
@@ -49,7 +50,7 @@
         "", params[:callback_type], params[:callback_dst], "", "",
         nil, nil, params[:user_agent],
         "", params[:extra], params[:request_headers],
-        nil, nil, nil
+        nil, nil, nil, "s3://a-beautiful-bucket.s3.amazonaws.com/path/to/file"
       ]
     end
     let(:post_params) do
@@ -173,7 +174,7 @@
           "", "", "", "", "",
           nil, nil, params[:user_agent],
           "", params[:extra], params[:request_headers],
-          params[:s3_bucket], params[:s3_region], nil
+          params[:s3_bucket], params[:s3_region], nil, nil
         ]
       end
 
@@ -241,7 +242,7 @@
           "", params[:callback_type], params[:callback_dst], "","",
           nil, nil, params[:user_agent],
           "", params[:extra], params[:request_headers],
-          params[:s3_bucket], params[:s3_region], nil
+          params[:s3_bucket], params[:s3_region], nil, nil
         ]
       end
 
@@ -306,7 +307,7 @@
           "", params[:callback_type], params[:callback_dst], "", "",
           nil, nil, params[:user_agent],
           "", params[:extra], params[:request_headers],
-          nil, nil, params[:subpath]
+          nil, nil, params[:subpath], nil
         ]
       end
 
@@ -357,7 +358,7 @@
           params[:callback_error_type], params[:callback_error_dst],
           nil, nil, params[:user_agent],
           "", params[:extra], params[:request_headers],
-          params[:s3_bucket], params[:s3_region], nil
+          params[:s3_bucket], params[:s3_region], nil, nil
         ]
       end