module Supercast::Util
Constants
- COLOR_CODES
private
- OPTS_COPYABLE
Options that should be copyable from one
DataObject
to another including options that may be internal.- OPTS_PERSISTABLE
Options that should be persisted between API requests. This includes client, which is an object containing an HTTP client to reuse.
- OPTS_USER_SPECIFIED
Options that a user is allowed to specify.
Public Class Methods
# File lib/supercast/util.rb, line 185 def self.check_api_key!(key) raise TypeError, 'api_key must be a string' unless key.is_a?(String) key end
# File lib/supercast/util.rb, line 179 def self.check_string_argument!(key) raise TypeError, 'argument must be a string' unless key.is_a?(String) key end
Converts a hash of fields or an array of hashes into a DataObject
or array of +DataObject+s. These new objects will be created as a concrete type as dictated by their `object` field (e.g. an `object` value of `creator` would create an instance of Creator
), but if `object` is not present or of an unknown type, the newly created instance will fall back to being a DataObject
.
Attributes¶ ↑
-
data
- Hash of fields and values to be converted into aDataObject
. -
opts
- Options forDataObject
like an API key that will be reused on subsequent API calls.
# File lib/supercast/util.rb, line 55 def self.convert_to_supercast_object(data, opts = {}) opts = normalize_opts(opts) case data when Array data.map { |i| convert_to_supercast_object(i, opts) } when Hash # Try converting to a known object class. If none available, fall back # to generic DataObject object_classes.fetch(data[:object], DataObject).construct_from(data, opts) else data end end
Encodes a hash of parameters in a way that's suitable for use as query parameters in a URI or as form parameters in a request body. This mainly involves escaping special characters from parameter keys and values (e.g. `&`).
# File lib/supercast/util.rb, line 106 def self.encode_parameters(params) Util.flatten_params(params) .map { |k, v| "#{url_encode(k)}=#{url_encode(v)}" }.join('&') end
# File lib/supercast/util.rb, line 122 def self.flatten_params(params, parent_key = nil) result = [] # do not sort the final output because arrays (and arrays of hashes # especially) can be order sensitive, but do sort incoming parameters params.each do |key, value| calculated_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s if value.is_a?(Hash) result += flatten_params(value, calculated_key) elsif value.is_a?(Array) result += flatten_params_array(value, calculated_key) else result << [calculated_key, value] end end result end
# File lib/supercast/util.rb, line 141 def self.flatten_params_array(value, calculated_key) result = [] value.each_with_index do |elem, i| if elem.is_a?(Hash) result += flatten_params(elem, "#{calculated_key}[#{i}]") elsif elem.is_a?(Array) result += flatten_params_array(elem, calculated_key) else result << ["#{calculated_key}[#{i}]", elem] end end result end
# File lib/supercast/util.rb, line 78 def self.log_debug(message, data = {}) log_at_level(Supercast::LEVEL_DEBUG, message, data, color: :blue) end
# File lib/supercast/util.rb, line 70 def self.log_error(message, data = {}) log_at_level(Supercast::LEVEL_ERROR, message, data, color: :cyan) end
# File lib/supercast/util.rb, line 74 def self.log_info(message, data = {}) log_at_level(Supercast::LEVEL_INFO, message, data, color: :cyan) end
Normalizes header keys so that they're all lower case and each hyphen-delimited section starts with a single capitalized letter. For example, `request-id` becomes `Request-Id`. This is useful for extracting certain key values when the user could have set them with a variety of diffent naming schemes.
# File lib/supercast/util.rb, line 196 def self.normalize_headers(headers) headers.each_with_object({}) do |(k, v), new_headers| k = k.to_s.tr('_', '-') if k.is_a?(Symbol) k = k.split('-').reject(&:empty?).map(&:capitalize).join('-') new_headers[k] = v end end
# File lib/supercast/util.rb, line 155 def self.normalize_id(id) if id.is_a?(Hash) # overloaded id params_hash = id.dup id = params_hash.delete(:id) else params_hash = {} end [id, params_hash] end
The secondary opts argument can either be a string or hash Turn this value into an api_key and a set of headers
# File lib/supercast/util.rb, line 167 def self.normalize_opts(opts) case opts when String { api_key: opts } when Hash check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key) opts.clone else raise TypeError, 'normalize_opts expects a string or a hash' end end
# File lib/supercast/util.rb, line 39 def self.object_classes @object_classes ||= Supercast::DataTypes.object_names_to_classes end
# File lib/supercast/util.rb, line 24 def self.objects_to_ids(obj) case obj when Resource obj.id when Hash res = {} obj.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? } res when Array obj.map { |v| objects_to_ids(v) } else obj end end
Constant time string comparison to prevent timing attacks Code borrowed from ActiveSupport
# File lib/supercast/util.rb, line 207 def self.secure_compare(str_a, str_b) return false unless str_a.bytesize == str_b.bytesize l = str_a.unpack "C#{str_a.bytesize}" res = 0 str_b.each_byte { |byte| res |= byte ^ l.shift } res.zero? end
# File lib/supercast/util.rb, line 82 def self.symbolize_names(object) case object when Hash new_hash = {} object.each do |key, value| key = (begin key.to_sym rescue StandardError key end) || key new_hash[key] = symbolize_names(value) end new_hash when Array object.map { |value| symbolize_names(value) } else object end end
Encodes a string in a way that makes it suitable for use in a set of query parameters in a URI or in a set of form parameters in a request body.
# File lib/supercast/util.rb, line 114 def self.url_encode(key) CGI.escape(key.to_s). # Don't use strict form encoding by changing the square bracket control # characters back to their literals. This is fine by the server, and # makes these parameter strings easier to read. gsub('%5B', '[').gsub('%5D', ']') end
Private Class Methods
Uses an ANSI escape code to colorize text if it's going to be sent to a TTY.
# File lib/supercast/util.rb, line 236 def self.colorize(val, color, isatty) return val unless isatty mode = 0 # default foreground = 30 + COLOR_CODES.fetch(color) background = 40 + COLOR_CODES.fetch(:default) "\033[#{mode};#{foreground};#{background}m#{val}\033[0m" end
Turns an integer log level into a printable name.
# File lib/supercast/util.rb, line 248 def self.level_name(level) case level when LEVEL_DEBUG then 'debug' when LEVEL_ERROR then 'error' when LEVEL_INFO then 'info' else level end end
# File lib/supercast/util.rb, line 258 def self.log_at_level(level, message, data = {}, opts = {}) log_internal(message, data, { level: level, logger: Supercast.logger, out: $stdout }.merge(opts)) if !Supercast.logger.nil? || !Supercast.log_level.nil? && Supercast.log_level <= level end
TODO: Make these named required arguments when we drop support for Ruby 2.0.
# File lib/supercast/util.rb, line 265 def self.log_internal(message, data = {}, color: nil, level: nil, logger: nil, out: nil) data_str = data.reject { |_k, v| v.nil? } .map do |(k, v)| format('%<key>s=%<value>s', key: colorize(k, color, logger.nil? && !out.nil? && out.isatty), value: wrap_logfmt_value(v)) end.join(' ') if !logger.nil? # the library's log levels are mapped to the same values as the # standard library's logger logger.log(level, format('message=%<message>s %<data_str>s', message: wrap_logfmt_value(message), data_str: data_str)) elsif out.isatty out.puts format('%<level>s %<message>s %<data_str>s', level: colorize(level_name(level)[0, 4].upcase, color, out.isatty), message: message, data_str: data_str) else out.puts format('message=%<message>s level=%<level>s %<data_str>s', message: wrap_logfmt_value(message), level: level_name(level), data_str: data_str) end end
Wraps a value in double quotes if it looks sufficiently complex so that it can be read by logfmt parsers.
# File lib/supercast/util.rb, line 297 def self.wrap_logfmt_value(val) # If value is any kind of number, just allow it to be formatted directly # to a string (this will handle integers or floats). return val if val.is_a?(Numeric) # Hopefully val is a string, but protect in case it's not. val = val.to_s if %r{[^\w\-/]}.match?(val) # If the string contains any special characters, escape any double # quotes it has, remove newlines, and wrap the whole thing in quotes. format(%("%<value>s"), value: val.gsub('"', '\"').delete("\n")) else # Otherwise use the basic value if it looks like a standard set of # characters (and allow a few special characters like hyphens, and # slashes) val end end