ferto 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 76fec12269881aa711adb29ed09b8e2cbc26293a
-  data.tar.gz: 88650a43a3c84ccdd7f7a6ae5e0a9f3c60c170b2
+  metadata.gz: 97a79db2d44895104a87860165f149d3b08ebe7b
+  data.tar.gz: 28bd5801d93445f394629766cf18d6bc2547ece3
 SHA512:
-  metadata.gz: c210b51e0d3710ba281a8fb1ce98ac90470c234a0feb582ebfaa821a466e773508ee59d9cadf80cdc0074536e72d6e9ca47ea583e40b616b3cfb0a5e42711e6d
-  data.tar.gz: 5ec118b21be2e3b7359cb6477d6038dce4a23a5a0ca6526e8e3e5f10086d0e3f770d113f2e9dd33c5b48e0679c30ad8441e32ea2f93f39cac5574d8106f58eb7
+  metadata.gz: 7c04fbf4d9943121888bb8d211a4a31d8098e891150154f7c6853e4309d55fb87f46b2c86046fca8589d981d2d7eb5827fee54487d6f8ce12109abcad6bb2690
+  data.tar.gz: 05d6a9d9f3f4064d7e461eb57a4702eed647e9fca734e722e21db50ab973a901335fcb0f0e4a9ef339ffe2ecbaa01c5c00a6307d25a74ce50e748a165869177c

data/README.md

@@ -35,23 +35,49 @@ client = Ferto::Client.new(
 
 ### Downloading a file
 
-```ruby
-client.download(aggr_id: 'bucket1',
-                aggr_limit: '3',
-                url: 'http://example.com/',
-                mime_type: 'text/html',
-                callback_url: 'http://myservice.com/downloader_callback',
-                extra: { some_extra_info: 'info' })
+[downloader](https://github.com/skroutz/downloader) supports multiple
+notification backends for the download results. Currently, there are two
+supported options: an HTTP and a Kafka backend. Let's see how to issue a
+download request in each case:
+
+#### HTTP-based notification backend
 
+```ruby
+dl_resp = client.download(aggr_id: 'bucket1',
+                          aggr_limit: 3,
+                          url: 'http://example.com/',
+                          mime_type: 'text/html',
+                          callback_type: 'http',
+                          callback_dst: 'http://myservice.com/downloader_callback',
+                          extra: { some_extra_info: 'info' })
 ```
 
-For the semantics of those options refer to [downloader's documentation](https://github.com/skroutz/downloader#endpoints)
+In order for a service to consume downloader's result, it *must* accept the HTTP
+callback in the endpoint denoted by `callback_dst`.
+
+#### Kafka-based notification backend
 
+```ruby
+dl_resp = client.download(aggr_id: 'bucket1',
+                          aggr_limit: 3,
+                          url: 'http://example.com/',
+                          mime_type: 'text/html',
+                          callback_type: 'kafka',
+                          callback_dst: 'my-kafka-topic',
+                          extra: { some_extra_info: 'info' })
+```
 
-In order for a service to consume downloader's result, it must accept the HTTP
-callback in some endpoint passed in `callback_url`.
+To consume the downloader's result, you can use your favorite Kafka library and
+consume the callback message from `my-kafka-topic` (passed in `callback_dst`).
 
-To consume the callback, e.g. from inside a Rails controller:
+If the connection with the `downloader` API was successful, the aforementioned
+`dl_resp` is a
+[`Ferto::Response`](https://github.com/skroutz/ferto/blob/master/lib/ferto/response.rb#L2)
+object. If the client failed to connect, a
+[`Ferto::ConnectionError`](https://github.com/skroutz/ferto/blob/master/lib/ferto.rb#L18)
+exception is raised.
+
+To handle the actual callback message, e.g. from inside a Rails controller:
 
 ```ruby
 class DownloaderController < ApplicationConroller
@@ -71,6 +97,12 @@ class DownloaderController < ApplicationConroller
 end
 ```
 
+> For the detailed semantics of each option and the format of the callback
+> payload, please, refer to the official downloader's documentation ([download
+> parameters](https://github.com/skroutz/downloader#endpoints), [callback
+> payload](https://github.com/skroutz/downloader/tree/kafka-backend#usage)).
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/skroutz/ferto.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/skroutz/ferto.

data/lib/ferto.rb

@@ -14,4 +14,6 @@ module Ferto
     timeout: 6,
     aggr_limit: 4
   }.freeze
+
+  class ConnectionError < StandardError; end
 end

data/lib/ferto/client.rb

@@ -1,3 +1,6 @@
+require "curl"
+require "json"
+
 module Ferto
   class Client
     # @return [String]
@@ -46,27 +49,38 @@ module Ferto
     #
     # @example
     #   downloader = Ferto::Client.new
-    #   downloader.download(
+    #   dl_resp = downloader.download(
     #     aggr_id: 'msystems',
     #     aggr_limit: 3,
     #     url: 'http://foo.bar/a.jpg',
-    #     callback_url: 'http://example.com/downloads/myfile',
+    #     callback_type: 'http',
+    #     callback_dst: 'http://example.com/downloads/myfile',
     #     extra: { groupno: 'foobar' }
     #   )
     #
-    # @return [Ferto::Client::Response]
+    # @raise [Ferto::ConnectionError] if the client failed to connect to the
+    #   downloader API
+    #
+    # @return [Ferto::Response]
     def download(aggr_id:, aggr_limit: @aggr_limit, url:,
-                 callback_url:, mime_type: "", extra: {})
+                 callback_url: "", callback_dst: "",
+                 callback_type: "", mime_type: "", extra: {})
       uri = URI::HTTP.build(
         scheme: scheme, host: host, port: port, path: path
       )
       body = build_body(
-        aggr_id, aggr_limit, url, callback_url, mime_type, extra)
+        aggr_id, aggr_limit, url, callback_url, callback_type, callback_dst,
+        mime_type, extra
+      )
       # Curl.post reuses the same handler
-      res = Curl.post(uri.to_s, body.to_json) do |handle|
-        handle.headers = build_header(aggr_id)
-        handle.connect_timeout = connect_timeout
-        handle.timeout = timeout
+      begin
+        res = Curl.post(uri.to_s, body.to_json) do |handle|
+          handle.headers = build_header(aggr_id)
+          handle.connect_timeout = connect_timeout
+          handle.timeout = timeout
+        end
+      rescue Curl::Err::ConnectionFailedError => e
+        raise Ferto::ConnectionError.new(e)
       end
 
       Ferto::Response.new res
@@ -77,18 +91,25 @@ module Ferto
     def build_header(aggr_id)
       {
         'Content-Type': 'application/json',
-        'X-Aggr':      aggr_id.to_s
+        'X-Aggr': aggr_id.to_s
       }
     end
 
-    def build_body(aggr_id, aggr_limit, url, callback_url, mime_type, extra)
+    def build_body(aggr_id, aggr_limit, url, callback_url, callback_type,
+                   callback_dst, mime_type, extra)
       body = {
         aggr_id: aggr_id,
         aggr_limit: aggr_limit,
-        url: url,
-        callback_url: callback_url
+        url: url
       }
 
+      if callback_url.empty?
+        body[:callback_type] = callback_type
+        body[:callback_dst] = callback_dst
+      else
+        body[:callback_url] = callback_url
+      end
+
       if !mime_type.empty?
         body[:mime_type] = mime_type
       end

data/lib/ferto/version.rb

@@ -1,3 +1,3 @@
 module Ferto
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ferto
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Aggelos Avgerinos
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-26 00:00:00.000000000 Z
+date: 2019-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curb