Merge default_options, and add default_options_overwrite

[skunkworker]

Summary

Each call to ActiveRemote::Cached.default_options replaced the options. In a Rails app, the railtie sets :expires_in (5 minutes) and :race_condition_ttl (5 seconds), and then the app initializers run. An initializer that called default_options with other options removed the TTL. Every cached finder call with no :expires_in then wrote an entry that never expired.

# railtie:      { :expires_in => 5.minutes, :race_condition_ttl => 5.seconds }
ActiveRemote::Cached.default_options(:active_remote_cached_replace_characters => true)
# before:       { :active_remote_cached_replace_characters => true }
# after:        { :expires_in => 5.minutes, :race_condition_ttl => 5.seconds, :active_remote_cached_replace_characters => true }

The README said "In Rails apps, the :race_condition_ttl option defaults to 5 seconds". That was false for any app that called default_options.

Changes

• default_options(hash) merges the hash into the current options. A key in the new hash wins. With no argument or nil, it reads the options, as before.
• New default_options_overwrite(hash) replaces the options and returns them. default_options_overwrite({}) clears them.
• Neither method changes the hash that the caller passed. default_options[:key] = value still works.
• The specs reset state with default_options_overwrite({}).
• README: the default options section, and an "Upgrading to 1.3.0" section.
• VERSION is 1.3.0.

Breaking change

default_options({}) no longer clears the options. It now does nothing. Use default_options_overwrite({}).

Apps that call default_options with other options get the railtie TTL back, so their finders call the remote service more often.

This PR bumps the version to 1.3.0, and the README has an "Upgrading to 1.3.0" section.

Evidence

• 7 new specs. 6 fail on master, and all pass with this change.

• Full suite: 189 examples, 0 failures (Ruby 3.4.9). RuboCop: 18 files, no offenses.

• A Rails 7.1 app (JRuby 10.0.6.0) whose initializer calls default_options(:active_remote_cached_replace_characters => true):

  this branch:  default_options={expires_in: 5 minutes, race_condition_ttl: 5 seconds, active_remote_cached_replace_characters: true}
                Redis TTL of a cached finder key: 600
  1.1.1:        default_options={active_remote_cached_replace_characters: true}
                Redis TTL of a cached finder key: -1
  

🤖 Generated with Claude Code