Ferto

A Ruby client for skroutz/downloader.

Installation

Add this line to your application's Gemfile:

gem 'ferto'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ferto

Usage

Creating a client

client = Ferto::Client.new(
  scheme: 'http',
  host: 'localhost',
  port: 8000
)

Downloading a file

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

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' },
                          request_headers: { "Accept" => "application/html,application/xhtml+html" })

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

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' },
                          request_headers: { "Accept" => "application/html,application/xhtml+html" })

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).

If the connection with the downloader API was successful, the aforementioned dl_resp is a Ferto::Response object. If the client failed to connect, a Ferto::ConnectionError exception is raised. Also if the download call, results to a response with code either 40X or 50X then a Ferto::ResponseError is raised with the response object encapsulated in the raised exception in order to be further handled by the end user.

To handle the actual callback message, e.g. from inside a Rails controller:

class DownloaderController < ApplicationConroller
  def callback
    cb = Ferto::Callback.new(callback_params)

    if cb.download_successful?
      # Download cb.download_url
    else
      # Log failure
    end
  end

  def callback_params
    params.permit!.to_h
  end
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, callback payload).

A Note on User-Agent

We continue to expose the user_agent field as tools like curl and wget do. Along with that we will follow their paradigm where if both a user-agent flag and a User-Agent in the request headers are provided then the user-agent in the request headers is preferred.

Also if the user_agent is provided but the request headers do not contain a User-Agent key, then the user_agent is copied to the headers

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/skroutz/ferto.