Class: IOStreams::Paths::HTTP

Inherits:
IOStreams::Path show all
Defined in:
lib/io_streams/paths/http.rb

Instance Attribute Summary collapse

Attributes inherited from IOStreams::Path

#path

Attributes inherited from Stream

#io_stream

Instance Method Summary collapse

Methods inherited from IOStreams::Path

#<=>, #==, #absolute?, #children, #compressed?, #copy_from, #delete, #delete_all, #directory, #each_child, #encrypted?, #exist?, #inspect, #join, #mkdir, #mkpath, #move_to, #partial_files_visible?, #realpath, #size

Methods inherited from Stream

#basename, #copy_from, #copy_to, #dirname, #each, #extension, #extname, #file_name, #file_name=, #format, #format=, #format_options, #format_options=, #option, #option_or_stream, #pipeline, #read, #reader, #remove_from_pipeline, #setting, #stream, #write, #writer

Constructor Details

#initialize(url, username: nil, password: nil, http_redirect_count: 10, parameters: nil, allow_hosts: nil, maximum_file_size: nil) ⇒ HTTP

Stream to/from a remote file over http(s).

Parameters:

url: [String]
   URI of the file to download.
  Example:
    https://www5.fdic.gov/idasp/Offices2.zip
    http://hostname/path/file_name

  Full url showing all the optional elements that can be set via the url:
    https://username:password@hostname/path/file_name

username: [String]
  When supplied, basic authentication is used with the username and password.

password: [String]
  Password to use use with basic authentication when the username is supplied.

http_redirect_count: [Integer]
  Maximum number of http redirects to follow.
  Set to 0 to disable following redirects entirely.
  Default: 10

allow_hosts: [String | Array<String>]
  Optional allow-list of host names that may be contacted, applied to the
  supplied url and to every redirect that is followed.
  When supplied, a request to any other host raises CommunicationsFailure.
  Use this to limit Server Side Request Forgery (SSRF) exposure when the url
  can be influenced by untrusted input.
  Default: nil (any host is allowed).

maximum_file_size: [Integer]
  Optional maximum number of bytes to download.
  When the response body exceeds this size the download is aborted with a
  CommunicationsFailure, protecting against unbounded (denial of service) responses.
  Default: nil (no limit).

Security notes:

  • Redirect targets are supplied by the remote server. Validating only the url that is passed in is therefore not sufficient to prevent SSRF: use ‘allow_hosts` (or disable redirects with `http_redirect_count: 0`) when the url is not fully trusted.

  • Basic authentication credentials are only sent to the original host. They are not resent when a redirect points at a different scheme, host, or port, so that a redirect cannot leak the credentials to another server.



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/io_streams/paths/http.rb', line 53

def initialize(url, username: nil, password: nil, http_redirect_count: 10, parameters: nil,
               allow_hosts: nil, maximum_file_size: nil)
  uri = URI.parse(url)
  unless %w[http https].include?(uri.scheme)
    raise(
      ArgumentError,
      "Invalid URL. Required Format: 'http://<host_name>/<file_name>', or 'https://<host_name>/<file_name>'"
    )
  end

  @username            = username || uri.user
  @password            = password || uri.password
  @http_redirect_count = http_redirect_count
  @allow_hosts         = allow_hosts.nil? ? nil : Array(allow_hosts)
  @maximum_file_size   = maximum_file_size
  @url                 = parameters ? "#{url}?#{URI.encode_www_form(parameters)}" : url
  super(uri.path)
end

Instance Attribute Details

#http_redirect_count ⇒ Object (readonly)

Returns the value of attribute http_redirect_count.



7
8
9
 
# File 'lib/io_streams/paths/http.rb', line 7

def http_redirect_count
  @http_redirect_count
end

#password ⇒ Object (readonly)

Returns the value of attribute password.



7
8
9
 
# File 'lib/io_streams/paths/http.rb', line 7

def password
  @password
end

#url ⇒ Object (readonly)

Returns the value of attribute url.



7
8
9
 
# File 'lib/io_streams/paths/http.rb', line 7

def url
  @url
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



7
8
9
 
# File 'lib/io_streams/paths/http.rb', line 7

def username
  @username
end

Instance Method Details

#relative? ⇒ Boolean

Does not support relative file names since there is no concept of current working directory

Returns:

  • (Boolean) 


73
74
75
 
# File 'lib/io_streams/paths/http.rb', line 73

def relative?
  false
end

#to_s ⇒ Object 



77
78
79
 
# File 'lib/io_streams/paths/http.rb', line 77

def to_s
  url
end