Class: CardDB::Configuration

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

Overview

Configuration class for CardDB client settings.

Examples:

Basic configuration

CardDB.configure do |config|
  config.api_key = "carddb_xxx"
end

With defaults and restrictions

CardDB.configure do |config|
  config.api_key = "carddb_xxx"
  config.default_publisher = "pokemon-company"
  config.default_game = "pokemon-tcg"
  config.allowed_publishers = ["pokemon-company"]
  config.allowed_games = { "pokemon-company" => ["pokemon-tcg"] }
end

With logging

CardDB.configure do |config|
  config.api_key = "carddb_xxx"
  config.logger = Logger.new(STDOUT)
  config.log_level = :debug
end

With auto-retry on rate limit

CardDB.configure do |config|
  config.api_key = "carddb_xxx"
  config.retry_on_rate_limit = true
  config.max_retries = 3
end

Constant Summary collapse

DEFAULT_ENDPOINT =

Default API endpoint

'https://carddb.xtda.org/query'
DEFAULT_TIMEOUT =

Default timeouts in seconds

30
DEFAULT_OPEN_TIMEOUT = 
10
DEFAULT_MAX_RETRIES =

Default retry settings

3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/carddb/configuration.rb', line 103

def initialize
  @endpoint = DEFAULT_ENDPOINT
  @timeout = DEFAULT_TIMEOUT
  @open_timeout = DEFAULT_OPEN_TIMEOUT
  @api_key = nil
  @publishable_key = nil
  @secret_key = nil
  @access_token = nil
  @environment = nil
  @default_publisher = nil
  @default_game = nil
  @allowed_publishers = nil
  @allowed_games = nil
  @logger = nil
  @log_level = :info
  @retry_on_rate_limit = false
  @max_retries = DEFAULT_MAX_RETRIES
  @cache = nil
  @cache_ttl = 300
  @cache_ttls = {}
end

Instance Attribute Details

#access_token ⇒ String?

Returns OAuth bearer token for user-authorized requests.

Returns:

  • (String, nil) —

    OAuth bearer token for user-authorized requests



54
55
56
 
# File 'lib/carddb/configuration.rb', line 54

def access_token
  @access_token
end

#allowed_games ⇒ Hash<String, Array<String>>?

Returns Map of publisher slug to allowed game keys.

Returns:

  • (Hash<String, Array<String>>, nil) —

    Map of publisher slug to allowed game keys



78
79
80
 
# File 'lib/carddb/configuration.rb', line 78

def allowed_games
  @allowed_games
end

#allowed_publishers ⇒ Array<String>?

Returns List of allowed publisher slugs (nil = all allowed).

Returns:

  • (Array<String>, nil) —

    List of allowed publisher slugs (nil = all allowed)



75
76
77
 
# File 'lib/carddb/configuration.rb', line 75

def allowed_publishers
  @allowed_publishers
end

#api_key ⇒ String?

Returns Legacy API key for authentication.

Returns:

  • (String, nil) —

    Legacy API key for authentication



45
46
47
 
# File 'lib/carddb/configuration.rb', line 45

def api_key
  @api_key
end

#cache ⇒ Object?

Returns Cache instance (must respond to read/write, e.g., Rails.cache or MemoryCache).

Returns:

  • (Object, nil) —

    Cache instance (must respond to read/write, e.g., Rails.cache or MemoryCache)



93
94
95
 
# File 'lib/carddb/configuration.rb', line 93

def cache
  @cache
end

#cache_ttl ⇒ Integer

Returns Default cache TTL in seconds (default: 300 = 5 minutes).

Returns:

  • (Integer) —

    Default cache TTL in seconds (default: 300 = 5 minutes)



96
97
98
 
# File 'lib/carddb/configuration.rb', line 96

def cache_ttl
  @cache_ttl
end

#cache_ttls ⇒ Hash<Symbol, Integer>

Returns Per-resource cache TTLs in seconds Keys are resource names (:publishers, :games, :datasets, :records) Values override the default cache_ttl for that resource.

Returns:

  • (Hash<Symbol, Integer>) —

    Per-resource cache TTLs in seconds Keys are resource names (:publishers, :games, :datasets, :records) Values override the default cache_ttl for that resource



101
102
103
 
# File 'lib/carddb/configuration.rb', line 101

def cache_ttls
  @cache_ttls
end

#default_game ⇒ String?

Returns Default game key for queries.

Returns:

  • (String, nil) —

    Default game key for queries



72
73
74
 
# File 'lib/carddb/configuration.rb', line 72

def default_game
  @default_game
end

#default_publisher ⇒ String?

Returns Default publisher slug for queries.

Returns:

  • (String, nil) —

    Default publisher slug for queries



69
70
71
 
# File 'lib/carddb/configuration.rb', line 69

def default_publisher
  @default_publisher
end

#endpoint ⇒ String

Returns GraphQL endpoint URL.

Returns:

  • (String) —

    GraphQL endpoint URL



60
61
62
 
# File 'lib/carddb/configuration.rb', line 60

def endpoint
  @endpoint
end

#environment ⇒ String?

Returns Client environment hint (‘TEST` or `LIVE`).

Returns:

  • (String, nil) —

    Client environment hint (‘TEST` or `LIVE`)



57
58
59
 
# File 'lib/carddb/configuration.rb', line 57

def environment
  @environment
end

#log_level ⇒ Symbol

Returns Log level (:debug, :info, :warn, :error).

Returns:

  • (Symbol) —

    Log level (:debug, :info, :warn, :error)



84
85
86
 
# File 'lib/carddb/configuration.rb', line 84

def log_level
  @log_level
end

#logger ⇒ Logger?

Returns Logger instance for debug output.

Returns:

  • (Logger, nil) —

    Logger instance for debug output



81
82
83
 
# File 'lib/carddb/configuration.rb', line 81

def logger
  @logger
end

#max_retries ⇒ Integer

Returns Maximum number of retries on rate limit.

Returns:

  • (Integer) —

    Maximum number of retries on rate limit



90
91
92
 
# File 'lib/carddb/configuration.rb', line 90

def max_retries
  @max_retries
end

#open_timeout ⇒ Integer

Returns Connection open timeout in seconds.

Returns:

  • (Integer) —

    Connection open timeout in seconds



66
67
68
 
# File 'lib/carddb/configuration.rb', line 66

def open_timeout
  @open_timeout
end

#publishable_key ⇒ String?

Returns Browser-safe publishable API key for public reads.

Returns:

  • (String, nil) —

    Browser-safe publishable API key for public reads



48
49
50
 
# File 'lib/carddb/configuration.rb', line 48

def publishable_key
  @publishable_key
end

#retry_on_rate_limit ⇒ Boolean

Returns Whether to automatically retry on rate limit errors.

Returns:

  • (Boolean) —

    Whether to automatically retry on rate limit errors



87
88
89
 
# File 'lib/carddb/configuration.rb', line 87

def retry_on_rate_limit
  @retry_on_rate_limit
end

#secret_key ⇒ String?

Returns Server-side secret API key for trusted workflows.

Returns:

  • (String, nil) —

    Server-side secret API key for trusted workflows



51
52
53
 
# File 'lib/carddb/configuration.rb', line 51

def secret_key
  @secret_key
end

#timeout ⇒ Integer

Returns Request timeout in seconds.

Returns:

  • (Integer) —

    Request timeout in seconds



63
64
65
 
# File 'lib/carddb/configuration.rb', line 63

def timeout
  @timeout
end

Instance Method Details

#cache_ttl_for(resource) ⇒ Integer

Get the cache TTL for a specific resource. Falls back to the default cache_ttl if no resource-specific TTL is configured.

Parameters:

  • resource (Symbol, String) —

    The resource name (:publishers, :games, :datasets, :records)

Returns:

  • (Integer) —

    The TTL in seconds



130
131
132
 
# File 'lib/carddb/configuration.rb', line 130

def cache_ttl_for(resource)
  cache_ttls[resource.to_sym] || cache_ttl
end

#effective_api_key ⇒ Object 



173
174
175
 
# File 'lib/carddb/configuration.rb', line 173

def effective_api_key
  api_key || publishable_key || secret_key
end

#merge(overrides = {}) ⇒ Configuration

Creates a copy of this configuration with optional overrides.

Parameters:

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

    Configuration options to override

Returns:



203
204
205
206
207
208
209
 
# File 'lib/carddb/configuration.rb', line 203

def merge(overrides = {})
  dup.tap do |config|
    overrides.each do |key, value|
      config.public_send(:"#{key}=", value) if config.respond_to?(:"#{key}=")
    end
  end
end

#require_secret_credential!(operation) ⇒ Object

Raises:



177
178
179
180
181
 
# File 'lib/carddb/configuration.rb', line 177

def require_secret_credential!(operation)
  return if !access_token && (api_key || (secret_key && !publishable_key))

  raise RestrictedError, "#{operation} requires a server-side secret_key or legacy api_key credential"
end

#resolve_game(game_key) ⇒ String?

Resolves the game key, using the default if not provided.

Parameters:

  • game_key (String, nil) —

    The provided game key

Returns:

  • (String, nil) —

    The resolved game key



195
196
197
 
# File 'lib/carddb/configuration.rb', line 195

def resolve_game(game_key)
  game_key || default_game
end

#resolve_publisher(publisher_slug) ⇒ String?

Resolves the publisher slug, using the default if not provided.

Parameters:

  • publisher_slug (String, nil) —

    The provided publisher slug

Returns:

  • (String, nil) —

    The resolved publisher slug



187
188
189
 
# File 'lib/carddb/configuration.rb', line 187

def resolve_publisher(publisher_slug)
  publisher_slug || default_publisher
end

#validate_access!(publisher_slug, game_key = nil) ⇒ void

This method returns an undefined value.

Validates both publisher and game if provided.

Parameters:

  • publisher_slug (String, nil) —

    The publisher slug

  • game_key (String, nil) (defaults to: nil) —

    The game key

Raises:



168
169
170
171
 
# File 'lib/carddb/configuration.rb', line 168

def validate_access!(publisher_slug, game_key = nil)
  validate_publisher!(publisher_slug) if publisher_slug
  validate_game!(publisher_slug, game_key) if publisher_slug && game_key
end

#validate_game!(publisher_slug, game_key) ⇒ void

This method returns an undefined value.

Validates that a game is allowed by the configuration.

Parameters:

  • publisher_slug (String) —

    The publisher slug

  • game_key (String) —

    The game key to validate

Raises:



152
153
154
155
156
157
158
159
160
 
# File 'lib/carddb/configuration.rb', line 152

def validate_game!(publisher_slug, game_key)
  return if allowed_games.nil?
  return unless allowed_games.key?(publisher_slug)

  allowed = allowed_games[publisher_slug]
  return if allowed.include?(game_key)

  raise RestrictedError, "Game '#{game_key}' is not allowed for publisher '#{publisher_slug}'"
end

#validate_publisher!(publisher_slug) ⇒ void

This method returns an undefined value.

Validates that a publisher is allowed by the configuration.

Parameters:

  • publisher_slug (String) —

    The publisher slug to validate

Raises:



139
140
141
142
143
144
 
# File 'lib/carddb/configuration.rb', line 139

def validate_publisher!(publisher_slug)
  return if allowed_publishers.nil?
  return if allowed_publishers.include?(publisher_slug)

  raise RestrictedError, "Publisher '#{publisher_slug}' is not in the allowed publishers list"
end