Class: ApiSampler::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/api_sampler/configuration.rb

Overview

A class to hold the configuration of api_sampler.

Constant Summary collapse

PATH_PARAMS_BLACKLIST =

Default keys to exclude from the path parameters of the request.

[:action, :controller].freeze
TAG_COLORS =
%w(red orange yellow olive green teal blue
violet purple pink brown grey black).freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeConfiguration

Returns a new instance of Configuration


13
14
15
# File 'lib/api_sampler/configuration.rb', line 13

def initialize
  @path_params_blacklist = PATH_PARAMS_BLACKLIST.dup
end

Instance Attribute Details

#path_params_blacklist<Symbol>?

List of keys to exclude from the path parameters of the request. Keys from PATH_PARAMS_BLACKLIST are excluded by default.

Examples:

Exclude :id from path parameters

ApiSampler.configure do |config|
  config.path_params_blacklist = %i(id)
end

Don't exclude any parameters from path parameters

ApiSampler.configure do |config|
  config.path_params_blacklist = nil
end

Returns:

  • (<Symbol>, nil)

See Also:


260
261
262
# File 'lib/api_sampler/configuration.rb', line 260

def path_params_blacklist
  @path_params_blacklist
end

#request_blacklistArray<RequestMatcher> (readonly)

Note:

these rules take precedence over the rules in #request_whitelist.

Returns the set of rules to determine denied requests.

Returns:

  • (Array<RequestMatcher>)

    the set of rules to determine denied requests.


109
110
111
# File 'lib/api_sampler/configuration.rb', line 109

def request_blacklist
  @request_blacklist ||= []
end

#request_tagsArray<RequestMatcher> (readonly)

Returns the set of pairs (tag, rule).

Returns:


221
222
223
# File 'lib/api_sampler/configuration.rb', line 221

def request_tags
  @request_tags ||= []
end

#request_whitelistArray<RequestMatcher> (readonly)

Note:

these rules may be overriden by the rules in #request_blacklist.

Returns the set of rules to determine allowed requests.

Returns:

  • (Array<RequestMatcher>)

    the set of rules to determine allowed requests.


100
101
102
# File 'lib/api_sampler/configuration.rb', line 100

def request_whitelist
  @request_whitelist ||= []
end

#samples_expiration_durationActiveSupport::Duration? (readonly)

Returns the duration during which collected samples should be stored.

Returns:

  • (ActiveSupport::Duration, nil)

    the duration during which collected samples should be stored.


138
139
140
# File 'lib/api_sampler/configuration.rb', line 138

def samples_expiration_duration
  @samples_expiration_duration
end

#samples_quota_countInteger? (readonly)

Returns the maximum number of collected samples per #samples_quota_duration.

Returns:


167
168
169
# File 'lib/api_sampler/configuration.rb', line 167

def samples_quota_count
  @samples_quota_count
end

#samples_quota_durationActiveSupport::Duration? (readonly)

Returns the duration during which at most #samples_quota_count samples can be collected.

Returns:

  • (ActiveSupport::Duration, nil)

    the duration during which at most #samples_quota_count samples can be collected.


172
173
174
# File 'lib/api_sampler/configuration.rb', line 172

def samples_quota_duration
  @samples_quota_duration
end

#tag_colors{ #to_s => String} (readonly)

Returns a mapping from tags to colors.

Returns:

  • ({ #to_s => String})

    a mapping from tags to colors.


227
228
229
# File 'lib/api_sampler/configuration.rb', line 227

def tag_colors
  @tag_colors ||= {}
end

Instance Method Details

#allow(rule) ⇒ void #allow {|request| ... } ⇒ void

Note:

rules defined here may be overriden by the rules defined in #deny.

This method returns an undefined value.

Allow requests matching the given rule.

You can invoke this method multiple times to define a set of rules; a request is considered allowed as long as it matches any rule from that set.

Examples:

Allow requests with query parameter "foo"

ApiSampler.configure do |config|
  config.allow do |request|
    request.GET.key?('foo')
  end
end

Allow POST requests and request to "/api/v1/*" endpoints

ApiSampler.configure do |config|
  config.allow %r{^/api/v1/}
  config.allow ->(r) { r.post? }
end

Overloads:

  • #allow(rule) ⇒ void

    Parameters:

    • rule (Regexp, #call)

      the rule determining whether the particular request should match.

      If rule is Regexp, match is determined by testing the regexp against the request path. If rule responds to #call, it is invoked with the current request as the argument; the request is considered matched if #call returns a truthy value.

  • #allow {|request| ... } ⇒ void

    Yields:

    • (request)

      block which takes the request and returns whether that request matches.

    Yield Parameters:

    • request (Rack::Request)

      the current request.

    Yield Returns:

    • (Boolean)

Raises:

  • (ArgumentError)

    if the rule has invalid type or if both rule and the block are specified, or if none of them are specified.


52
53
54
55
56
# File 'lib/api_sampler/configuration.rb', line 52

def allow(rule = nil, &block)
  validate_rule(rule, block)

  request_whitelist << RequestMatcher.new(rule || block)
end

#deny(rule) ⇒ void #deny {|request| ... } ⇒ void

Note:

rules defined here take precedence over the rules defined in #allow.

This method returns an undefined value.

Define rules to deny requests previously matched by #allow rules.

You can invoke this method multiple times to define a set of rules; a request is considered denied as long as it matches any rule from that set.

Examples:

Deny POST requests

ApiSampler.configure do |config|
  config.deny(&:post?)
end

Allow all requests to "/api/v1/*" endpoints except PUT requests

ApiSampler.configure do |config|
  config.allow %r{^/api/v1/}
  config.deny(&:put?)
end

Overloads:

  • #deny(rule) ⇒ void

    Parameters:

    • rule (Regexp, #call)

      the rule determining whether the particular request should match.

      If rule is Regexp, match is determined by testing the regexp against the request path. If rule responds to #call, it is invoked with the current request as the argument; the request is considered matched if #call returns a truthy value.

  • #deny {|request| ... } ⇒ void

    Yields:

    • (request)

      block which takes the request and returns whether that request matches.

    Yield Parameters:

    • request (Rack::Request)

      the current request.

    Yield Returns:

    • (Boolean)

Raises:

  • (ArgumentError)

    if the rule has invalid type or if both rule and the block are specified, or if none of them are specified.


89
90
91
92
93
# File 'lib/api_sampler/configuration.rb', line 89

def deny(rule = nil, &block)
  validate_rule(rule, block)

  request_blacklist << RequestMatcher.new(rule || block)
end

#samples_expire_in(duration) ⇒ void

Note:

Samples are stored indefinetely by default.

This method returns an undefined value.

Set the duration during which collected samples should be stored.

Examples:

Store collected samples for one day

ApiSampler.configure do |config|
  config.samples_expire_in 1.day
end

Parameters:

  • duration (ActiveSupport::Duration, nil)

    the duration specifying the lifetime of collected samples. Passing nil means storing collected samples indefinetely.

Raises:

  • (ArgumentError)

    if duration has invalid type.


129
130
131
132
133
134
# File 'lib/api_sampler/configuration.rb', line 129

def samples_expire_in(duration)
  raise ArgumentError, 'expected ActiveSupport::Duration or nil' unless
    duration.nil? || duration.is_a?(ActiveSupport::Duration)

  @samples_expiration_duration = duration
end

#samples_quota(count:, per:) ⇒ void

This method returns an undefined value.

Set maxumum number of samples collected per time inteval.

Examples:

Collect at most 100 samples per day

ApiSampler.configure do |config|
  config.samples_quota count: 100, per: 1.day
end

Parameters:

  • count (Integer)

    the maximum number of collected samples per specified duration.

  • per (ActiveSupport::Duration)

    the duration during which at most count samples can be collected.

Raises:

  • (ArgumentError)

    if provided arguments of invalid types.


155
156
157
158
159
160
161
162
163
# File 'lib/api_sampler/configuration.rb', line 155

def samples_quota(count:, per:)
  raise ArgumentError, "`count' must be an Integer" unless
    count.is_a?(Integer)
  raise ArgumentError, "`per' must be an ActiveSupport::Duration" unless
    per.is_a?(ActiveSupport::Duration)

  @samples_quota_count = count
  @samples_quota_duration = per
end

#tag_color(tag) ⇒ String?

Returns the color assigned to the tag, if any (and the assigned color is a known color from TAG_COLORS), nil otherwise.

Parameters:

  • tag (#to_s)

    the tag name.

Returns:

  • (String, nil)

    the color assigned to the tag, if any (and the assigned color is a known color from TAG_COLORS), nil otherwise.


235
236
237
238
239
240
241
242
# File 'lib/api_sampler/configuration.rb', line 235

def tag_color(tag)
  color = tag_colors[tag.to_s]

  return if color.nil?
  return unless TAG_COLORS.include?(color)

  color
end

#tag_with(tag, rule) ⇒ void #tag_with(tag) {|request| ... } ⇒ void

Note:

rules defined here may be overriden by the rules defined in #deny.

This method returns an undefined value.

Tag matched requests with the specified labels.

Examples:

Tag slow requests with the tag 'slow':

ApiSampler.configure do |config|
  config.tag_with(:slow) { |request| request.time > 200 }
end

Assigning color to tags:

ApiSampler.configure do |config|
  config.tag_with(:deprecated, %r{^/api/v1/.*}, color: 'red')
end

Overloads:

  • #tag_with(tag, rule) ⇒ void

    Parameters:

    • tag (#to_s)

      a non-blank label which should tag matching requests.

    • color (#to_s)

      an optional tag color. See TAG_COLORS for the list of available color names.

    • rule (Regexp, #call)

      the rule determining whether the particular request should match.

      If rule is Regexp, match is determined by testing the regexp against the request path. If rule responds to #call, it is invoked with the current request as the argument; the request is considered matched if #call returns a truthy value.

  • #tag_with(tag) {|request| ... } ⇒ void

    Parameters:

    • tag (#to_s)

      a non-blank label which should tag matching requests.

    • color (#to_s)

      an optional tag color. See TAG_COLORS for the list of available color names.

    Yields:

    • (request)

      block which takes the request and returns whether that request matches.

    Yield Parameters:

    • request (Rack::Request)

      the current request.

    Yield Returns:

    • (Boolean)

Raises:

  • (ArgumentError)

    if arguments are invalid.


211
212
213
214
215
216
# File 'lib/api_sampler/configuration.rb', line 211

def tag_with(tag, rule = nil, color: nil, &block)
  validate_rule(rule, block)

  request_tags << RequestTag.new(tag, RequestMatcher.new(rule || block))
  tag_colors[tag.to_s] = color.to_s.strip unless color.blank?
end