Module: BerkeleyLibrary::Util::URIs

Extended by:
URIs
Includes:
Logging
Included in:
URIs
Defined in:
lib/berkeley_library/util/uris.rb,
lib/berkeley_library/util/uris/appender.rb,
lib/berkeley_library/util/uris/requester.rb,
lib/berkeley_library/util/uris/validator.rb,
lib/berkeley_library/util/uris/requester/class_methods.rb

Defined Under Namespace

Modules: Validator Classes: Appender, Requester

Constant Summary collapse

UTF_8 = 
Encoding::UTF_8
ALLOWED_BYTES_BY_MODE =

TODO: extend to cover other modes - host, zone, path, password, query, fragment cf. https://github.com/golang/go/blob/master/src/net/url/url.go

{
  path_segment: [0x24, 0x26, 0x2b, 0x3a, 0x3d, 0x40] # @ & = + $
}.freeze

Instance Method Summary collapse

Instance Method Details

#append(uri, *elements) ⇒ URI

Appends the specified paths to the path of the specified URI, removing any extraneous slashes and merging additional query parameters, and returns a new URI with that path and the same scheme, host, query, fragment, etc. as the original.

Parameters:

  • uri (URI, String) —

    the original URI

  • elements (Array<String, Symbol>) —

    the URI elements to join.

Returns:

  • (URI) —

    a new URI appending the joined path elements.

Raises:

  • URI::InvalidComponentError if appending the specified elements would create an invalid URI



25
26
27
 
# File 'lib/berkeley_library/util/uris.rb', line 25

def append(uri, *elements)
  Appender.new(uri, *elements).to_uri
end

#get(uri, params: {}, headers: {}, log: true) ⇒ String

Performs a GET request and returns the response body as a string.

Parameters:

  • uri (URI, String) —

    the URI to GET

  • params (Hash) (defaults to: {}) —

    the query parameters to add to the URI. (Note that the URI may already include query parameters.)

  • headers (Hash) (defaults to: {}) —

    the request headers.

  • log (Boolean) (defaults to: true) —

    whether to log each request URL and response code

Returns:

  • (String) —

    the body as a string.

Raises:

  • (RestClient::Exception) —

    in the event of an unsuccessful request.



37
38
39
 
# File 'lib/berkeley_library/util/uris.rb', line 37

def get(uri, params: {}, headers: {}, log: true)
  Requester.get(uri, params: params, headers: headers, log: log)
end

#get_response(uri, params: {}, headers: {}, log: true) ⇒ RestClient::Response

Performs a GET request and returns the response, even in the event of a failed request.

Parameters:

  • uri (URI, String) —

    the URI to GET

  • params (Hash) (defaults to: {}) —

    the query parameters to add to the URI. (Note that the URI may already include query parameters.)

  • headers (Hash) (defaults to: {}) —

    the request headers.

  • log (Boolean) (defaults to: true) —

    whether to log each request URL and response code

Returns:

  • (RestClient::Response) —

    the response



62
63
64
 
# File 'lib/berkeley_library/util/uris.rb', line 62

def get_response(uri, params: {}, headers: {}, log: true)
  Requester.get_response(uri, params: params, headers: headers, log: log)
end

#head(uri, params: {}, headers: {}, log: true) ⇒ Integer

Performs a HEAD request and returns the response status as an integer. Note that unlike BerkeleyLibrary::Util::URIs::Requester::ClassMethods#get, this does not raise an error in the event of an unsuccessful request.

Parameters:

  • uri (URI, String) —

    the URI to HEAD

  • params (Hash) (defaults to: {}) —

    the query parameters to add to the URI. (Note that the URI may already include query parameters.)

  • headers (Hash) (defaults to: {}) —

    the request headers.

  • log (Boolean) (defaults to: true) —

    whether to log each request URL and response code

Returns:

  • (Integer) —

    the response code as an integer.



50
51
52
 
# File 'lib/berkeley_library/util/uris.rb', line 50

def head(uri, params: {}, headers: {}, log: true)
  Requester.head(uri, params: params, headers: headers, log: log)
end

#head_response(uri, params: {}, headers: {}, log: true) ⇒ RestClient::Response

Performs a HEAD request and returns the response, even in the event of a failed request.

Parameters:

  • uri (URI, String) —

    the URI to HEAD

  • params (Hash) (defaults to: {}) —

    the query parameters to add to the URI. (Note that the URI may already include query parameters.)

  • headers (Hash) (defaults to: {}) —

    the request headers.

  • log (Boolean) (defaults to: true) —

    whether to log each request URL and response code

Returns:

  • (RestClient::Response) —

    the response



74
75
76
 
# File 'lib/berkeley_library/util/uris.rb', line 74

def head_response(uri, params: {}, headers: {}, log: true)
  Requester.head_response(uri, params: params, headers: headers, log: log)
end

#path_escape(s) ⇒ Object

Escapes the specified string so that it can be used as a URL path segment, replacing disallowed characters (including /) with percent-encodings as needed.

Raises:

  • (ArgumentError) 


89
90
91
92
93
94
95
96
97
98
 
# File 'lib/berkeley_library/util/uris.rb', line 89

def path_escape(s)
  raise ArgumentError, "Can't escape #{s.inspect}: not a string" unless s.respond_to?(:encoding)

  s = s.encode(UTF_8) unless s.encoding == UTF_8
  ''.tap do |escaped|
    s.bytes.each do |b|
      escaped << (should_escape?(b, :path_segment) ? '%%%02X' % b : b.chr)
    end
  end
end

#safe_parse_uri(url) ⇒ URI?

Returns the specified URL as a URI, or nil if the URL cannot be parsed.

Parameters:

  • url (Object, nil) —

    the URL.

Returns:

  • (URI, nil) —

    the URI, or nil.



104
105
106
107
108
109
110
 
# File 'lib/berkeley_library/util/uris.rb', line 104

def safe_parse_uri(url)
  # noinspection RubyMismatchedArgumentType
  uri_or_nil(url)
rescue URI::InvalidURIError => e
  logger.warn("Error parsing URL #{url.inspect}", e)
  nil
end

#uri_or_nil(url) ⇒ URI

Returns the specified URL as a URI, or nil if the URL is nil.

Parameters:

  • url (String, URI, nil) —

    the URL.

Returns:

  • (URI) —

    the URI, or nil.

Raises:

  • (URI::InvalidURIError) —

    if url is not nil and cannot be parsed as a URI.



83
84
85
 
# File 'lib/berkeley_library/util/uris.rb', line 83

def uri_or_nil(url)
  Validator.uri_or_nil(url)
end