Class: Api2Convert::Result::FileDownload

Inherits:
Object
  • Object
show all
Defined in:
lib/api2convert/result.rb

Overview

A downloadable output file.

Returned by client.download(output) and used internally by ConversionResult. A password supplied at conversion time (or to client.download(output, password)) is remembered and sent automatically on every download; an explicit password argument to #save/#contents overrides the remembered one for that call.

Instance Method Summary collapse

Constructor Details

#initialize(transport, output, download_password = nil) ⇒ FileDownload

Returns a new instance of FileDownload.



16
17
18
19
20
 
# File 'lib/api2convert/result.rb', line 16

def initialize(transport, output, download_password = nil)
  @transport = transport
  @output = output
  @download_password = download_password
end

Instance Method Details

#contents(download_password = nil) ⇒ Object

Download the file and return its contents. This buffers the whole body in memory by design — use #save for a large file to stream it to disk.



49
50
51
52
53
54
 
# File 'lib/api2convert/result.rb', line 49

def contents(download_password = nil)
  password = resolve_password(download_password)
  # A passwordless download follows storage redirects; a password-protected
  # one must not (the X-Api2convert-Download-Password header could leak on a redirect).
  @transport.download(@output.uri, headers(password), follow_redirects: password.nil?)
end

#inspect ⇒ Object

Redacted representation — the remembered download password is masked.



57
58
59
60
 
# File 'lib/api2convert/result.rb', line 57

def inspect
  "#<#{self.class.name} url=#{@output.uri.inspect} " \
    "download_password=#{Support::Secret.mask(@download_password)}>"
end

#save(path_or_dir, download_password = nil) ⇒ Object

Stream the file to disk. path_or_dir is a file path, or a directory (the API filename is used). The body is streamed chunk-by-chunk to a sibling temp file (never buffered whole in memory), then atomically renamed over the target only after a clean write+close — so an arbitrarily large output cannot exhaust memory and a mid-stream failure never truncates the target nor destroys a pre-existing complete file at that path. Returns the path written.



33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/api2convert/result.rb', line 33

def save(path_or_dir, download_password = nil)
  target = resolve_target(path_or_dir.to_s)
  parent = File.dirname(target)
  parent = "." if parent.empty?
  begin
    FileUtils.mkdir_p(parent)
  rescue SystemCallError
    raise Api2Convert::Error, "Could not create directory: #{parent}"
  end

  stream_to_file(target, resolve_password(download_password))
  target
end

#to_s ⇒ Object 



62
63
64
 
# File 'lib/api2convert/result.rb', line 62

def to_s
  inspect
end

#url ⇒ Object

The self-contained download URL (no auth required).



23
24
25
 
# File 'lib/api2convert/result.rb', line 23

def url
  @output.uri
end