Class: Colore::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/colore/client.rb,
lib/colore/client/version.rb

Overview

Client for interacting with the Colore service.

Constant Summary collapse

VERSION =

The current version of the Colore client.

'1.0.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(app:, base_uri:, logger: Logger.new(nil), backtrace: false, user_agent: 'Colore Client') ⇒ Client

Constructor.

Parameters:

  • base_uri (String) —

    The base URI of the Colore service that you wish to attach to

  • app (String) —

    The name of your application. All documents will be stored under this name

  • logger (Logger) (defaults to: Logger.new(nil)) —

    An optional logger, which will log all requests and responses. Defaults to ‘Logger.new(nil)`

  • backtrace (Bool) (defaults to: false) —

    Used for debugging purposes, to extract backtraces from Colore. Defaults to ‘false`

  • user_agent (String) (defaults to: 'Colore Client') —

    User Agent header that will be sent to Colore. Defaults to ‘Colore Client`



33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/colore/client.rb', line 33

def initialize(app:, base_uri:, logger: Logger.new(nil), backtrace: false, user_agent: 'Colore Client')
  @base_uri = base_uri
  @app = app
  @backtrace = backtrace
  @logger = logger
  @connection = Faraday.new(url: base_uri, headers: { 'User-Agent' => user_agent }) do |faraday|
    faraday.request :multipart
    faraday.request :url_encoded
    faraday.adapter :net_http
  end
end

Instance Attribute Details

#app ⇒ Object (readonly)

Returns the value of attribute app.



19
20
21
 
# File 'lib/colore/client.rb', line 19

def app
  @app
end

#backtrace ⇒ Object (readonly)

Returns the value of attribute backtrace.



19
20
21
 
# File 'lib/colore/client.rb', line 19

def backtrace
  @backtrace
end

#base_uri ⇒ Object (readonly)

Returns the value of attribute base_uri.



19
20
21
 
# File 'lib/colore/client.rb', line 19

def base_uri
  @base_uri
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



19
20
21
 
# File 'lib/colore/client.rb', line 19

def logger
  @logger
end

Class Method Details

.generate_doc_id ⇒ Object

Generates a document id that is reasonably guaranteed to be unique for your app.



22
23
24
 
# File 'lib/colore/client.rb', line 22

def self.generate_doc_id
  SecureRandom.uuid
end

Instance Method Details

#convert(content:, action:, language: 'en') ⇒ Hash

Performs a foreground conversion of a file.

Parameters:

  • content (String) —

    the file contents

  • action (String) —

    the conversion to perform

  • language (String) (defaults to: 'en') —

    the language of the file (defaults to ‘en’) - only needed for OCR operations

Returns:

  • (Hash) —

    a standard response



213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/colore/client.rb', line 213

def convert(content:, action:, language: 'en')
  params = {}

  response = nil
  with_tempfile(content) do |io|
    params[:file] = file_param(io)
    params[:action] = action
    params[:language] = language if language
    params[:backtrace] = backtrace if backtrace
    response = send_request :post, 'convert', params
  end
  response
end

#create_document(doc_id:, filename:, content:, title: nil, author: nil, actions: nil, callback_url: nil) ⇒ Hash

Stores the specified document on Colore.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • filename (String) —

    the name of the file to store

  • content (String or IO) —

    the body of the file

  • title (String) (defaults to: nil) —

    An optional short description of the document

  • author (String) (defaults to: nil) —

    An optional name of the author of the document

  • actions (Array) (defaults to: nil) —

    a list of optional conversions to perform once the file has been stored (e.g. [‘ocr’, ‘ocr_text’]

  • callback_url (String) (defaults to: nil) —

    an optional callback URL that Colore will send the results of its conversions to (one per action). It is your responsibility to have something listening on this URL, ready to take a JSON object with the results of the conversion in it

Returns:

  • (Hash) —

    a standard response



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/colore/client.rb', line 72

def create_document(doc_id:, filename:, content:, title: nil, author: nil, actions: nil, callback_url: nil)
  params = {}
  params[:title] = title if title
  params[:actions] = actions if actions
  params[:author] = author if author
  params[:callback_url] = callback_url if callback_url
  params[:backtrace] = backtrace if backtrace

  base_filename = File.basename(filename)

  response = nil
  with_tempfile(content) do |io|
    params[:file] = file_param(io)
    response = send_request :put, "#{url_for_base doc_id}/#{encode_param(base_filename)}", params, :json
  end
  response
end

#delete_document(doc_id:) ⇒ Hash

Completely deletes a document

Parameters:

  • doc_id (String) —

    the document’s unique identifier

Returns:

  • (Hash) —

    a standard response



160
161
162
163
164
 
# File 'lib/colore/client.rb', line 160

def delete_document(doc_id:)
  params = {}
  params[:backtrace] = backtrace if backtrace
  send_request :delete, url_for_base(doc_id), params, :json
end

#delete_version(doc_id:, version:) ⇒ Hash

Completely deletes a document’s version (you cannot delete the current one)

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • version (String) —

    the version to delete

Returns:

  • (Hash) —

    a standard response



172
173
174
175
176
 
# File 'lib/colore/client.rb', line 172

def delete_version(doc_id:, version:)
  params = {}
  params[:backtrace] = backtrace if backtrace
  send_request :delete, "#{url_for_base doc_id}/#{version}", params, :json
end

#generate_doc_id ⇒ Object

Generates a document id that is reasonably guaranteed to be unique for your app.



46
47
48
 
# File 'lib/colore/client.rb', line 46

def generate_doc_id
  self.class.generate_doc_id
end

#get_document(doc_id:, filename:, version: Colore::CURRENT) ⇒ String

Retrieves a document.

Please note that this method puts unwanted load on the Colore service and it is recommended that you access the document directly, using a proxying web server such as Nginx.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • version (String) (defaults to: Colore::CURRENT) —

    the version to delete

  • filename (String) —

    the name of the file to retrieve

Returns:

  • (String) —

    the file contents



189
190
191
192
193
 
# File 'lib/colore/client.rb', line 189

def get_document(doc_id:, filename:, version: Colore::CURRENT)
  params = {}
  params[:backtrace] = backtrace if backtrace
  send_request :get, path_for(doc_id, filename, version), {}
end

#get_document_info(doc_id:) ⇒ Hash

Retrieves information about a document.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

Returns:

  • (Hash) —

    a list of document details



200
201
202
203
204
 
# File 'lib/colore/client.rb', line 200

def get_document_info(doc_id:)
  params = {}
  params[:backtrace] = backtrace if backtrace
  send_request :get, url_for_base(doc_id), params, :json
end

#path_for(doc_id, filename, version = Colore::CURRENT) ⇒ String

Generates a path for the document based on its ID, filename, and version.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • filename (String) —

    the name of the file

  • version (String) (defaults to: Colore::CURRENT) —

    the version of the document (defaults to Colore::CURRENT)

Returns:

  • (String) —

    the generated path



233
234
235
 
# File 'lib/colore/client.rb', line 233

def path_for(doc_id, filename, version = Colore::CURRENT)
  "#{url_for_base doc_id}/#{version}/#{File.basename(filename)}"
end

#ping ⇒ Object

Tests the connection with Colore. Will raise an error if the connection cannot be established.



52
53
54
55
 
# File 'lib/colore/client.rb', line 52

def ping
  send_request :head, '/'
  true
end

#request_conversion(doc_id:, filename:, action:, version: Colore::CURRENT, callback_url: nil) ⇒ Hash

Requests a conversion of an existing document.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • filename (String) —

    the name of the file to convert

  • version (String) (defaults to: Colore::CURRENT) —

    the version to store (defaults to Colore::CURRENT)

  • action (String) —

    the conversion to perform

  • callback_url (String) (defaults to: nil) —

    an optional callback URL that Colore will send the results of its conversion to. It is your responsibility to have something listening on this URL, ready to take a JSON object with the results of the conversion in it

Returns:

  • (Hash) —

    a standard response



147
148
149
150
151
152
153
 
# File 'lib/colore/client.rb', line 147

def request_conversion(doc_id:, filename:, action:, version: Colore::CURRENT, callback_url: nil)
  params = {}
  params[:callback_url] = callback_url if callback_url
  params[:backtrace] = backtrace if backtrace

  send_request :post, "#{path_for(doc_id, filename, version)}/#{action}", params, :json
end

#update_document(doc_id:, filename:, content: nil, author: nil, actions: nil, callback_url: nil) ⇒ Hash

Updates the specified document on Colore - creates a new version and stores the new file.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • filename (String) —

    the name of the file to store

  • content (String or IO) (defaults to: nil) —

    the body of the file

  • author (String) (defaults to: nil) —

    An optional name of the author of the new version

  • actions (Array) (defaults to: nil) —

    a list of optional conversions to perform once the file has been stored (e.g. [‘ocr’, ‘ocr_text’]

  • callback_url (String) (defaults to: nil) —

    an optional callback URL that Colore will send the results of its conversions to (one per action). It is your responsibility to have something listening on this URL, ready to take a JSON object with the results of the conversion in it

Returns:

  • (Hash) —

    a standard response



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/colore/client.rb', line 104

def update_document(doc_id:, filename:, content: nil, author: nil, actions: nil, callback_url: nil)
  params = {}
  params[:actions] = actions if actions
  params[:author] = author if author
  params[:callback_url] = callback_url if callback_url
  params[:backtrace] = backtrace if backtrace

  base_filename = File.basename(filename)

  response = nil
  if content
    with_tempfile(content) do |io|
      params[:file] = file_param(io)
      response = send_request :post, "#{url_for_base(doc_id)}/#{encode_param(base_filename)}", params, :json
    end
  else
    response = send_request :post, "#{url_for_base(doc_id)}/#{encode_param(base_filename)}", params, :json
  end
  response
end

#update_title(doc_id:, title:) ⇒ Hash

Updates the document title.

Parameters:

  • doc_id (String) —

    the document’s unique identifier

  • title (String) —

    A short description of the document

Returns:

  • (Hash) —

    a standard response



131
132
133
 
# File 'lib/colore/client.rb', line 131

def update_title(doc_id:, title:)
  send_request :post, "#{url_for_base(doc_id)}/title/#{encode_param(title)}", {}, :json
end