Class: Aws::SessionStore::DynamoDB::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/session_store/dynamo_db/configuration.rb

Overview

This class provides a Configuration object for all DynamoDB session store operations by pulling configuration options from Runtime, the ENV, a YAML file, and default settings, in that order.

Environment Variables

The Configuration object can load default values from your environment. All configuration keys are supported except for :dynamo_db_client and :error_handler. The keys take the form of AWS_DYNAMO_DB_SESSION_<KEY_NAME>. Example:

export AWS_DYNAMO_DB_SESSION_TABLE_NAME='Sessions'
export AWS_DYNAMO_DB_SESSION_TABLE_KEY='id'

Locking Strategy

By default, locking is disabled for session store access. To enable locking, set the :enable_locking option to true. The locking strategy is pessimistic, meaning that only one read can be made on a session at once. While the session is being read by the process with the lock, other processes may try to obtain a lock on the same session but will be blocked. See the initializer for how to configure the pessimistic locking strategy to your needs.

Handling Errors

There are two configurable options for error handling: :raise_errors and :error_handler.

If you would like to use the Default Error Handler, you can decide to set :raise_errors to true or false depending on whether you want all errors, regardless of class, to be raised up the stack and essentially throw a 500.

If you decide to use your own Error Handler, you must implement the BaseErrorHandler class and pass it into the :error_handler option.

DynamoDB Specific Options

You may configure the table name and table hash key value of your session table with the :table_name and :table_key options. You may also configure performance options for your table with the :consistent_read, :read_capacity, :write_capacity. For more information about these configurations see CreateTable method for Amazon DynamoDB.

See Also:

  • Interface for Error Handling for DynamoDB Session Store.

Constant Summary collapse

MEMBERS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

{
  table_name: 'sessions',
  table_key: 'session_id',
  secret_key: nil,
  consistent_read: true,
  read_capacity: 10,
  write_capacity: 5,
  raise_errors: false,
  error_handler: nil,
  max_age: nil,
  max_stale: nil,
  enable_locking: false,
  lock_expiry_time: 500,
  lock_retry_delay: 500,
  lock_max_wait_time: 1,
  serializer: :marshal,
  config_file: nil,
  dynamo_db_client: nil
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Configuration

Provides configuration object that allows access to options defined during Runtime, in the ENV, in a YAML file, and by default.

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :table_name (String) — default: "sessions" —

    Name of the session table.

  • :table_key (String) — default: "session_id" —

    The hash key of the session table.

  • :secret_key (String) —

    Secret key for HMAC encryption.

  • :consistent_read (Boolean) — default: true —

    If true, a strongly consistent read is used. If false, an eventually consistent read is used. @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html

  • :read_capacity (Integer) — default: 10 —

    The maximum number of strongly consistent reads consumed per second before DynamoDB raises a ThrottlingException. @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/read-write-operations.html

  • :write_capacity (Integer) — default: 5 —

    The maximum number of writes consumed per second before DynamoDB returns a ThrottlingException. @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/read-write-operations.html

  • :raise_errors (Boolean) — default: false —

    If true, all errors are raised up the stack when default ErrorHandler. If false, Only specified errors are raised up the stack when the default ErrorHandler is used.

  • :error_handler (#handle_error) — default: Errors::DefaultHandler —

    An error handling object that handles all exceptions thrown during execution of the rack application.

  • :max_age (Integer) — default: nil —

    Maximum number of seconds earlier from the current time that a session was created.

  • :max_stale (Integer) — default: nil —

    Maximum number of seconds before current time that session was last accessed.

  • :enable_locking (Integer) — default: false —

    If true, a pessimistic locking strategy will be used for all session accesses.

  • :lock_expiry_time (Integer) — default: 500 —

    Time in milliseconds after which the lock expires on session.

  • :lock_retry_delay (Integer) — default: 500 —

    Time in milliseconds to wait before retrying to obtain lock once an attempt to obtain the lock has been made and has failed.

  • :lock_max_wait_time (Integer) — default: 500 —

    Maximum time in seconds to wait to acquire the lock before giving up.

  • :serializer (Symbol) — default: :marshal —

    The serializer for session data.

    • :json - Serialize and deserialize with JSON only. Raises an error if legacy Marshal-encoded data is encountered.
    • :json_allow_marshal - Serialize with JSON, but fall back to deserializing with Marshal if JSON parsing fails. Use this during migration from Marshal to JSON.
    • :marshal - Serialize and deserialize with Marshal only (legacy behavior, not recommended).

    Note: When using :json or :json_allow_marshal, session data must consist of JSON-compatible types only (strings, numbers, booleans, arrays, hashes with string keys). Symbol keys are converted to strings, and complex objects (e.g., Time, custom classes) are not preserved across serialization.

  • :config_file (String, Pathname) —

    Path to a YAML file that contains configuration options.

  • :dynamo_db_client (Aws::DynamoDB::Client) — default: Aws::DynamoDB::Client.new —

    DynamoDB client used to perform database operations inside of the rack application.



114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/aws/session_store/dynamo_db/configuration.rb', line 114

def initialize(options = {})
  opts = options
  opts = env_options.merge(opts)
  opts = file_options(opts).merge(opts)
  MEMBERS.each_pair do |opt_name, default_value|
    opts[opt_name] = default_value unless opts.key?(opt_name)
  end
  opts = opts.merge(dynamo_db_client: default_dynamo_db_client(opts))
  opts = opts.merge(error_handler: default_error_handler(opts)) unless opts[:error_handler]

  set_attributes(opts)
end

Instance Method Details

#to_hash ⇒ Hash

Returns The merged configuration hash.

Returns:

  • (Hash) —

    The merged configuration hash.



132
133
134
135
136
 
# File 'lib/aws/session_store/dynamo_db/configuration.rb', line 132

def to_hash
  MEMBERS.each_with_object({}) do |(key, _), hash|
    hash[key] = send(key)
  end
end