/
cache.rb
990 lines (880 loc) · 36.9 KB
/
cache.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
# frozen_string_literal: true
require "active_support/core_ext/array/extract_options"
require "active_support/core_ext/enumerable"
require "active_support/core_ext/module/attribute_accessors"
require "active_support/core_ext/numeric/bytes"
require "active_support/core_ext/object/to_param"
require "active_support/core_ext/object/try"
require "active_support/core_ext/string/inflections"
require_relative "cache/entry"
require_relative "cache/serializer_with_fallback"
module ActiveSupport
# See ActiveSupport::Cache::Store for documentation.
module Cache
autoload :FileStore, "active_support/cache/file_store"
autoload :MemoryStore, "active_support/cache/memory_store"
autoload :MemCacheStore, "active_support/cache/mem_cache_store"
autoload :NullStore, "active_support/cache/null_store"
autoload :RedisCacheStore, "active_support/cache/redis_cache_store"
# These options mean something to all cache implementations. Individual cache
# implementations may support additional options.
UNIVERSAL_OPTIONS = [:namespace, :compress, :compress_threshold, :expires_in, :expire_in, :expired_in, :race_condition_ttl, :coder, :skip_nil]
DEFAULT_COMPRESS_LIMIT = 1.kilobyte
# Mapping of canonical option names to aliases that a store will recognize.
OPTION_ALIASES = {
expires_in: [:expire_in, :expired_in]
}.freeze
module Strategy
autoload :LocalCache, "active_support/cache/strategy/local_cache"
end
@format_version = 6.1
class << self
attr_accessor :format_version
# Creates a new Store object according to the given options.
#
# If no arguments are passed to this method, then a new
# ActiveSupport::Cache::MemoryStore object will be returned.
#
# If you pass a Symbol as the first argument, then a corresponding cache
# store class under the ActiveSupport::Cache namespace will be created.
# For example:
#
# ActiveSupport::Cache.lookup_store(:memory_store)
# # => returns a new ActiveSupport::Cache::MemoryStore object
#
# ActiveSupport::Cache.lookup_store(:mem_cache_store)
# # => returns a new ActiveSupport::Cache::MemCacheStore object
#
# Any additional arguments will be passed to the corresponding cache store
# class's constructor:
#
# ActiveSupport::Cache.lookup_store(:file_store, '/tmp/cache')
# # => same as: ActiveSupport::Cache::FileStore.new('/tmp/cache')
#
# If the first argument is not a Symbol, then it will simply be returned:
#
# ActiveSupport::Cache.lookup_store(MyOwnCacheStore.new)
# # => returns MyOwnCacheStore.new
def lookup_store(store = nil, *parameters)
case store
when Symbol
options = parameters.extract_options!
# clean this up once Ruby 2.7 support is dropped
# see https://github.com/rails/rails/pull/41522#discussion_r581186602
if options.empty?
retrieve_store_class(store).new(*parameters)
else
retrieve_store_class(store).new(*parameters, **options)
end
when Array
lookup_store(*store)
when nil
ActiveSupport::Cache::MemoryStore.new
else
store
end
end
# Expands out the +key+ argument into a key that can be used for the
# cache store. Optionally accepts a namespace, and all keys will be
# scoped within that namespace.
#
# If the +key+ argument provided is an array, or responds to +to_a+, then
# each of elements in the array will be turned into parameters/keys and
# concatenated into a single key. For example:
#
# ActiveSupport::Cache.expand_cache_key([:foo, :bar]) # => "foo/bar"
# ActiveSupport::Cache.expand_cache_key([:foo, :bar], "namespace") # => "namespace/foo/bar"
#
# The +key+ argument can also respond to +cache_key+ or +to_param+.
def expand_cache_key(key, namespace = nil)
expanded_cache_key = namespace ? +"#{namespace}/" : +""
if prefix = ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"]
expanded_cache_key << "#{prefix}/"
end
expanded_cache_key << retrieve_cache_key(key)
expanded_cache_key
end
private
def retrieve_cache_key(key)
case
when key.respond_to?(:cache_key_with_version) then key.cache_key_with_version
when key.respond_to?(:cache_key) then key.cache_key
when key.is_a?(Array) then key.map { |element| retrieve_cache_key(element) }.to_param
when key.respond_to?(:to_a) then retrieve_cache_key(key.to_a)
else key.to_param
end.to_s
end
# Obtains the specified cache store class, given the name of the +store+.
# Raises an error when the store class cannot be found.
def retrieve_store_class(store)
# require_relative cannot be used here because the class might be
# provided by another gem, like redis-activesupport for example.
require "active_support/cache/#{store}"
rescue LoadError => e
raise "Could not find cache store adapter for #{store} (#{e})"
else
ActiveSupport::Cache.const_get(store.to_s.camelize)
end
end
# = Active Support \Cache \Store
#
# An abstract cache store class. There are multiple cache store
# implementations, each having its own additional features. See the classes
# under the ActiveSupport::Cache module, e.g.
# ActiveSupport::Cache::MemCacheStore. MemCacheStore is currently the most
# popular cache store for large production websites.
#
# Some implementations may not support all methods beyond the basic cache
# methods of #fetch, #write, #read, #exist?, and #delete.
#
# ActiveSupport::Cache::Store can store any Ruby object that is supported by
# its +coder+'s +dump+ and +load+ methods.
#
# cache = ActiveSupport::Cache::MemoryStore.new
#
# cache.read('city') # => nil
# cache.write('city', "Duckburgh")
# cache.read('city') # => "Duckburgh"
#
# cache.write('not serializable', Proc.new {}) # => TypeError
#
# Keys are always translated into Strings and are case sensitive. When an
# object is specified as a key and has a +cache_key+ method defined, this
# method will be called to define the key. Otherwise, the +to_param+
# method will be called. Hashes and Arrays can also be used as keys. The
# elements will be delimited by slashes, and the elements within a Hash
# will be sorted by key so they are consistent.
#
# cache.read('city') == cache.read(:city) # => true
#
# Nil values can be cached.
#
# If your cache is on a shared infrastructure, you can define a namespace
# for your cache entries. If a namespace is defined, it will be prefixed on
# to every key. The namespace can be either a static value or a Proc. If it
# is a Proc, it will be invoked when each key is evaluated so that you can
# use application logic to invalidate keys.
#
# cache.namespace = -> { @last_mod_time } # Set the namespace to a variable
# @last_mod_time = Time.now # Invalidate the entire cache by changing namespace
#
class Store
cattr_accessor :logger, instance_writer: true
cattr_accessor :raise_on_invalid_cache_expiration_time, default: false
attr_reader :silence, :options
alias :silence? :silence
class << self
private
DEFAULT_POOL_OPTIONS = { size: 5, timeout: 5 }.freeze
private_constant :DEFAULT_POOL_OPTIONS
def retrieve_pool_options(options)
if options.key?(:pool)
pool_options = options.delete(:pool)
elsif options.key?(:pool_size) || options.key?(:pool_timeout)
pool_options = {}
if options.key?(:pool_size)
ActiveSupport.deprecator.warn(<<~MSG)
Using :pool_size is deprecated and will be removed in Rails 7.2.
Use `pool: { size: #{options[:pool_size].inspect} }` instead.
MSG
pool_options[:size] = options.delete(:pool_size)
end
if options.key?(:pool_timeout)
ActiveSupport.deprecator.warn(<<~MSG)
Using :pool_timeout is deprecated and will be removed in Rails 7.2.
Use `pool: { timeout: #{options[:pool_timeout].inspect} }` instead.
MSG
pool_options[:timeout] = options.delete(:pool_timeout)
end
else
pool_options = true
end
case pool_options
when false, nil
return false
when true
pool_options = DEFAULT_POOL_OPTIONS
when Hash
pool_options[:size] = Integer(pool_options[:size]) if pool_options.key?(:size)
pool_options[:timeout] = Float(pool_options[:timeout]) if pool_options.key?(:timeout)
pool_options = DEFAULT_POOL_OPTIONS.merge(pool_options)
else
raise TypeError, "Invalid :pool argument, expected Hash, got: #{pool_options.inspect}"
end
pool_options unless pool_options.empty?
end
end
# Creates a new cache.
#
# ==== Options
#
# [+:namespace+]
# Sets the namespace for the cache. This option is especially useful if
# your application shares a cache with other applications.
#
# [+:coder+]
# Replaces the default serializer for cache entries. +coder+ must
# respond to +dump+ and +load+. Using a custom coder disables automatic
# compression.
#
# Alternatively, you can specify <tt>coder: :message_pack</tt> to use a
# preconfigured coder based on ActiveSupport::MessagePack that supports
# automatic compression and includes a fallback mechanism to load old
# cache entries from the default coder. However, this option requires
# the +msgpack+ gem.
#
# Any other specified options are treated as default options for the
# relevant cache operations, such as #read, #write, and #fetch.
def initialize(options = nil)
@options = options ? normalize_options(options) : {}
@options[:compress] = true unless @options.key?(:compress)
@options[:compress_threshold] ||= DEFAULT_COMPRESS_LIMIT
@coder = @options.delete(:coder) { default_coder } || :passthrough
@coder = Cache::SerializerWithFallback[@coder] if @coder.is_a?(Symbol)
@coder_supports_compression = @coder.respond_to?(:dump_compressed)
end
# Silences the logger.
def silence!
@silence = true
self
end
# Silences the logger within a block.
def mute
previous_silence, @silence = defined?(@silence) && @silence, true
yield
ensure
@silence = previous_silence
end
# Fetches data from the cache, using the given key. If there is data in
# the cache with the given key, then that data is returned.
#
# If there is no such data in the cache (a cache miss), then +nil+ will be
# returned. However, if a block has been passed, that block will be passed
# the key and executed in the event of a cache miss. The return value of the
# block will be written to the cache under the given cache key, and that
# return value will be returned.
#
# cache.write('today', 'Monday')
# cache.fetch('today') # => "Monday"
#
# cache.fetch('city') # => nil
# cache.fetch('city') do
# 'Duckburgh'
# end
# cache.fetch('city') # => "Duckburgh"
#
# ==== Options
#
# Internally, +fetch+ calls #read_entry, and calls #write_entry on a cache
# miss. Thus, +fetch+ supports the same options as #read and #write.
# Additionally, +fetch+ supports the following options:
#
# * <tt>force: true</tt> - Forces a cache "miss," meaning we treat the
# cache value as missing even if it's present. Passing a block is
# required when +force+ is true so this always results in a cache write.
#
# cache.write('today', 'Monday')
# cache.fetch('today', force: true) { 'Tuesday' } # => 'Tuesday'
# cache.fetch('today', force: true) # => ArgumentError
#
# The +:force+ option is useful when you're calling some other method to
# ask whether you should force a cache write. Otherwise, it's clearer to
# just call +write+.
#
# * <tt>skip_nil: true</tt> - Prevents caching a nil result:
#
# cache.fetch('foo') { nil }
# cache.fetch('bar', skip_nil: true) { nil }
# cache.exist?('foo') # => true
# cache.exist?('bar') # => false
#
# * +:race_condition_ttl+ - Specifies the number of seconds during which
# an expired value can be reused while a new value is being generated.
# This can be used to prevent race conditions when cache entries expire,
# by preventing multiple processes from simultaneously regenerating the
# same entry (also known as the dog pile effect).
#
# When a process encounters a cache entry that has expired less than
# +:race_condition_ttl+ seconds ago, it will bump the expiration time by
# +:race_condition_ttl+ seconds before generating a new value. During
# this extended time window, while the process generates a new value,
# other processes will continue to use the old value. After the first
# process writes the new value, other processes will then use it.
#
# If the first process errors out while generating a new value, another
# process can try to generate a new value after the extended time window
# has elapsed.
#
# # Set all values to expire after one minute.
# cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 1.minute)
#
# cache.write('foo', 'original value')
# val_1 = nil
# val_2 = nil
# sleep 60
#
# Thread.new do
# val_1 = cache.fetch('foo', race_condition_ttl: 10.seconds) do
# sleep 1
# 'new value 1'
# end
# end
#
# Thread.new do
# val_2 = cache.fetch('foo', race_condition_ttl: 10.seconds) do
# 'new value 2'
# end
# end
#
# cache.fetch('foo') # => "original value"
# sleep 10 # First thread extended the life of cache by another 10 seconds
# cache.fetch('foo') # => "new value 1"
# val_1 # => "new value 1"
# val_2 # => "original value"
#
# ==== Dynamic Options
#
# In some cases it may be necessary to to dynamically compute options based
# on the cached value. For this purpose, a ActiveSupport::Cache::WriteOptions
# instance is passed as a second argument to the block
#
# cache.fetch("authentication-token:#{user.id}") do |key, options|
# token = authenticate_to_service
# options.expires_at = token.expires_at
# token
# end
#
# Only some options can be set dynamically:
#
# - +:expires_in+
# - +:expires_at+
# - +:version+
#
def fetch(name, options = nil, &block)
if block_given?
options = merged_options(options)
key = normalize_key(name, options)
entry = nil
unless options[:force]
instrument(:read, name, options) do |payload|
cached_entry = read_entry(key, **options, event: payload)
entry = handle_expired_entry(cached_entry, key, options)
entry = nil if entry && entry.mismatched?(normalize_version(name, options))
payload[:super_operation] = :fetch if payload
payload[:hit] = !!entry if payload
end
end
if entry
get_entry_value(entry, name, options)
else
save_block_result_to_cache(name, options, &block)
end
elsif options && options[:force]
raise ArgumentError, "Missing block: Calling `Cache#fetch` with `force: true` requires a block."
else
read(name, options)
end
end
# Reads data from the cache, using the given key. If there is data in
# the cache with the given key, then that data is returned. Otherwise,
# +nil+ is returned.
#
# Note, if data was written with the <tt>:expires_in</tt> or
# <tt>:version</tt> options, both of these conditions are applied before
# the data is returned.
#
# ==== Options
#
# * +:namespace+ - Replace the store namespace for this call.
# * +:version+ - Specifies a version for the cache entry. If the cached
# version does not match the requested version, the read will be treated
# as a cache miss. This feature is used to support recyclable cache keys.
#
# Other options will be handled by the specific cache store implementation.
def read(name, options = nil)
options = merged_options(options)
key = normalize_key(name, options)
version = normalize_version(name, options)
instrument(:read, name, options) do |payload|
entry = read_entry(key, **options, event: payload)
if entry
if entry.expired?
delete_entry(key, **options)
payload[:hit] = false if payload
nil
elsif entry.mismatched?(version)
payload[:hit] = false if payload
nil
else
payload[:hit] = true if payload
entry.value
end
else
payload[:hit] = false if payload
nil
end
end
end
# Reads multiple values at once from the cache. Options can be passed
# in the last argument.
#
# Some cache implementation may optimize this method.
#
# Returns a hash mapping the names provided to the values found.
def read_multi(*names)
return {} if names.empty?
options = names.extract_options!
options = merged_options(options)
instrument_multi :read_multi, names, options do |payload|
read_multi_entries(names, **options, event: payload).tap do |results|
payload[:hits] = results.keys
end
end
end
# Cache Storage API to write multiple values at once.
def write_multi(hash, options = nil)
return hash if hash.empty?
options = merged_options(options)
instrument_multi :write_multi, hash, options do |payload|
entries = hash.each_with_object({}) do |(name, value), memo|
memo[normalize_key(name, options)] = Entry.new(value, **options.merge(version: normalize_version(name, options)))
end
write_multi_entries entries, **options
end
end
# Fetches data from the cache, using the given keys. If there is data in
# the cache with the given keys, then that data is returned. Otherwise,
# the supplied block is called for each key for which there was no data,
# and the result will be written to the cache and returned.
# Therefore, you need to pass a block that returns the data to be written
# to the cache. If you do not want to write the cache when the cache is
# not found, use #read_multi.
#
# Returns a hash with the data for each of the names. For example:
#
# cache.write("bim", "bam")
# cache.fetch_multi("bim", "unknown_key") do |key|
# "Fallback value for key: #{key}"
# end
# # => { "bim" => "bam",
# # "unknown_key" => "Fallback value for key: unknown_key" }
#
# You may also specify additional options via the +options+ argument. See #fetch for details.
# Other options are passed to the underlying cache implementation. For example:
#
# cache.fetch_multi("fizz", expires_in: 5.seconds) do |key|
# "buzz"
# end
# # => {"fizz"=>"buzz"}
# cache.read("fizz")
# # => "buzz"
# sleep(6)
# cache.read("fizz")
# # => nil
def fetch_multi(*names)
raise ArgumentError, "Missing block: `Cache#fetch_multi` requires a block." unless block_given?
return {} if names.empty?
options = names.extract_options!
options = merged_options(options)
instrument_multi :read_multi, names, options do |payload|
if options[:force]
reads = {}
else
reads = read_multi_entries(names, **options)
end
writes = {}
ordered = names.index_with do |name|
reads.fetch(name) { writes[name] = yield(name) }
end
writes.compact! if options[:skip_nil]
payload[:hits] = reads.keys
payload[:super_operation] = :fetch_multi
write_multi(writes, options)
ordered
end
end
# Writes the value to the cache with the key. The value must be supported
# by the +coder+'s +dump+ and +load+ methods.
#
# By default, cache entries larger than 1kB are compressed. Compression
# allows more data to be stored in the same memory footprint, leading to
# fewer cache evictions and higher hit rates.
#
# ==== Options
#
# * <tt>compress: false</tt> - Disables compression of the cache entry.
#
# * +:compress_threshold+ - The compression threshold, specified in bytes.
# \Cache entries larger than this threshold will be compressed. Defaults
# to +1.kilobyte+.
#
# * +:expires_in+ - Sets a relative expiration time for the cache entry,
# specified in seconds. +:expire_in+ and +:expired_in+ are aliases for
# +:expires_in+.
#
# cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 5.minutes)
# cache.write(key, value, expires_in: 1.minute) # Set a lower value for one entry
#
# * +:expires_at+ - Sets an absolute expiration time for the cache entry.
#
# cache = ActiveSupport::Cache::MemoryStore.new
# cache.write(key, value, expires_at: Time.now.at_end_of_hour)
#
# * +:version+ - Specifies a version for the cache entry. When reading
# from the cache, if the cached version does not match the requested
# version, the read will be treated as a cache miss. This feature is
# used to support recyclable cache keys.
#
# Other options will be handled by the specific cache store implementation.
def write(name, value, options = nil)
options = merged_options(options)
instrument(:write, name, options) do
entry = Entry.new(value, **options.merge(version: normalize_version(name, options)))
write_entry(normalize_key(name, options), entry, **options)
end
end
# Deletes an entry in the cache. Returns +true+ if an entry is deleted.
#
# Options are passed to the underlying cache implementation.
def delete(name, options = nil)
options = merged_options(options)
instrument(:delete, name) do
delete_entry(normalize_key(name, options), **options)
end
end
# Deletes multiple entries in the cache.
#
# Options are passed to the underlying cache implementation.
def delete_multi(names, options = nil)
return 0 if names.empty?
options = merged_options(options)
names.map! { |key| normalize_key(key, options) }
instrument_multi :delete_multi, names do
delete_multi_entries(names, **options)
end
end
# Returns +true+ if the cache contains an entry for the given key.
#
# Options are passed to the underlying cache implementation.
def exist?(name, options = nil)
options = merged_options(options)
instrument(:exist?, name) do |payload|
entry = read_entry(normalize_key(name, options), **options, event: payload)
(entry && !entry.expired? && !entry.mismatched?(normalize_version(name, options))) || false
end
end
def new_entry(value, options = nil) # :nodoc:
Entry.new(value, **merged_options(options))
end
# Deletes all entries with keys matching the pattern.
#
# Options are passed to the underlying cache implementation.
#
# Some implementations may not support this method.
def delete_matched(matcher, options = nil)
raise NotImplementedError.new("#{self.class.name} does not support delete_matched")
end
# Increments an integer value in the cache.
#
# Options are passed to the underlying cache implementation.
#
# Some implementations may not support this method.
def increment(name, amount = 1, options = nil)
raise NotImplementedError.new("#{self.class.name} does not support increment")
end
# Decrements an integer value in the cache.
#
# Options are passed to the underlying cache implementation.
#
# Some implementations may not support this method.
def decrement(name, amount = 1, options = nil)
raise NotImplementedError.new("#{self.class.name} does not support decrement")
end
# Cleans up the cache by removing expired entries.
#
# Options are passed to the underlying cache implementation.
#
# Some implementations may not support this method.
def cleanup(options = nil)
raise NotImplementedError.new("#{self.class.name} does not support cleanup")
end
# Clears the entire cache. Be careful with this method since it could
# affect other processes if shared cache is being used.
#
# The options hash is passed to the underlying cache implementation.
#
# Some implementations may not support this method.
def clear(options = nil)
raise NotImplementedError.new("#{self.class.name} does not support clear")
end
private
def default_coder
case Cache.format_version
when 6.1
ActiveSupport.deprecator.warn <<~EOM
Support for `config.active_support.cache_format_version = 6.1` has been deprecated and will be removed in Rails 7.2.
Check the Rails upgrade guide at https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#new-activesupport-cache-serialization-format
for more information on how to upgrade.
EOM
Cache::SerializerWithFallback[:marshal_6_1]
when 7.0
Cache::SerializerWithFallback[:marshal_7_0]
when 7.1
Cache::SerializerWithFallback[:marshal_7_1]
else
Cache::SerializerWithFallback[Cache.format_version]
end
end
# Adds the namespace defined in the options to a pattern designed to
# match keys. Implementations that support delete_matched should call
# this method to translate a pattern that matches names into one that
# matches namespaced keys.
def key_matcher(pattern, options) # :doc:
prefix = options[:namespace].is_a?(Proc) ? options[:namespace].call : options[:namespace]
if prefix
source = pattern.source
if source.start_with?("^")
source = source[1, source.length]
else
source = ".*#{source[0, source.length]}"
end
Regexp.new("^#{Regexp.escape(prefix)}:#{source}", pattern.options)
else
pattern
end
end
# Reads an entry from the cache implementation. Subclasses must implement
# this method.
def read_entry(key, **options)
raise NotImplementedError.new
end
# Writes an entry to the cache implementation. Subclasses must implement
# this method.
def write_entry(key, entry, **options)
raise NotImplementedError.new
end
def serialize_entry(entry, **options)
options = merged_options(options)
if @coder_supports_compression && options[:compress]
@coder.dump_compressed(entry, options[:compress_threshold])
else
@coder.dump(entry)
end
end
def deserialize_entry(payload)
payload.nil? ? nil : @coder.load(payload)
end
# Reads multiple entries from the cache implementation. Subclasses MAY
# implement this method.
def read_multi_entries(names, **options)
names.each_with_object({}) do |name, results|
key = normalize_key(name, options)
entry = read_entry(key, **options)
next unless entry
version = normalize_version(name, options)
if entry.expired?
delete_entry(key, **options)
elsif !entry.mismatched?(version)
results[name] = entry.value
end
end
end
# Writes multiple entries to the cache implementation. Subclasses MAY
# implement this method.
def write_multi_entries(hash, **options)
hash.each do |key, entry|
write_entry key, entry, **options
end
end
# Deletes an entry from the cache implementation. Subclasses must
# implement this method.
def delete_entry(key, **options)
raise NotImplementedError.new
end
# Deletes multiples entries in the cache implementation. Subclasses MAY
# implement this method.
def delete_multi_entries(entries, **options)
entries.count { |key| delete_entry(key, **options) }
end
# Merges the default options with ones specific to a method call.
def merged_options(call_options)
if call_options
call_options = normalize_options(call_options)
if call_options.key?(:expires_in) && call_options.key?(:expires_at)
raise ArgumentError, "Either :expires_in or :expires_at can be supplied, but not both"
end
expires_at = call_options.delete(:expires_at)
call_options[:expires_in] = (expires_at - Time.now) if expires_at
if call_options[:expires_in].is_a?(Time)
expires_in = call_options[:expires_in]
raise ArgumentError.new("expires_in parameter should not be a Time. Did you mean to use expires_at? Got: #{expires_in}")
end
if call_options[:expires_in]&.negative?
expires_in = call_options.delete(:expires_in)
handle_invalid_expires_in("Cache expiration time is invalid, cannot be negative: #{expires_in}")
end
if options.empty?
call_options
else
options.merge(call_options)
end
else
options
end
end
def handle_invalid_expires_in(message)
error = ArgumentError.new(message)
if ActiveSupport::Cache::Store.raise_on_invalid_cache_expiration_time
raise error
else
ActiveSupport.error_reporter&.report(error, handled: true, severity: :warning)
logger.error("#{error.class}: #{error.message}") if logger
end
end
# Normalize aliased options to their canonical form
def normalize_options(options)
options = options.dup
OPTION_ALIASES.each do |canonical_name, aliases|
alias_key = aliases.detect { |key| options.key?(key) }
options[canonical_name] ||= options[alias_key] if alias_key
options.except!(*aliases)
end
options
end
# Expands and namespaces the cache key.
# Raises an exception when the key is +nil+ or an empty string.
# May be overridden by cache stores to do additional normalization.
def normalize_key(key, options = nil)
str_key = expanded_key(key)
raise(ArgumentError, "key cannot be blank") if !str_key || str_key.empty?
namespace_key str_key, options
end
# Prefix the key with a namespace string:
#
# namespace_key 'foo', namespace: 'cache'
# # => 'cache:foo'
#
# With a namespace block:
#
# namespace_key 'foo', namespace: -> { 'cache' }
# # => 'cache:foo'
def namespace_key(key, options = nil)
options = merged_options(options)
namespace = options[:namespace]
if namespace.respond_to?(:call)
namespace = namespace.call
end
if key && key.encoding != Encoding::UTF_8
key = key.dup.force_encoding(Encoding::UTF_8)
end
if namespace
"#{namespace}:#{key}"
else
key
end
end
# Expands key to be a consistent string value. Invokes +cache_key+ if
# object responds to +cache_key+. Otherwise, +to_param+ method will be
# called. If the key is a Hash, then keys will be sorted alphabetically.
def expanded_key(key)
return key.cache_key.to_s if key.respond_to?(:cache_key)
case key
when Array
if key.size > 1
key.collect { |element| expanded_key(element) }
else
expanded_key(key.first)
end
when Hash
key.collect { |k, v| "#{k}=#{v}" }.sort!
else
key
end.to_param
end
def normalize_version(key, options = nil)
(options && options[:version].try(:to_param)) || expanded_version(key)
end
def expanded_version(key)
case
when key.respond_to?(:cache_version) then key.cache_version.to_param
when key.is_a?(Array) then key.map { |element| expanded_version(element) }.tap(&:compact!).to_param
when key.respond_to?(:to_a) then expanded_version(key.to_a)
end
end
def instrument(operation, key, options = nil, &block)
_instrument(operation, key: key, options: options, &block)
end
def instrument_multi(operation, keys, options = nil, &block)
_instrument(operation, multi: true, key: keys, options: options, &block)
end
def _instrument(operation, multi: false, options: nil, **payload, &block)
if logger && logger.debug? && !silence?
debug_key =
if multi
": #{payload[:key].size} key(s) specified"
elsif payload[:key]
": #{normalize_key(payload[:key], options)}"
end
debug_options = " (#{options.inspect})" unless options.blank?
logger.debug "Cache #{operation}#{debug_key}#{debug_options}"
end
payload[:store] = self.class.name
payload.merge!(options) if options.is_a?(Hash)
ActiveSupport::Notifications.instrument("cache_#{operation}.active_support", payload) do
block&.call(payload)
end
end
def handle_expired_entry(entry, key, options)
if entry && entry.expired?
race_ttl = options[:race_condition_ttl].to_i
if (race_ttl > 0) && (Time.now.to_f - entry.expires_at <= race_ttl)
# When an entry has a positive :race_condition_ttl defined, put the stale entry back into the cache
# for a brief period while the entry is being recalculated.
entry.expires_at = Time.now.to_f + race_ttl
write_entry(key, entry, expires_in: race_ttl * 2)
else
delete_entry(key, **options)
end
entry = nil
end
entry
end
def get_entry_value(entry, name, options)
instrument(:fetch_hit, name, options)
entry.value
end
def save_block_result_to_cache(name, options)
result = instrument(:generate, name, options) do
yield(name, WriteOptions.new(options))
end
write(name, result, options) unless result.nil? && options[:skip_nil]
result
end
end
class WriteOptions
def initialize(options) # :nodoc:
@options = options
end
def version
@options[:version]
end
def version=(version)
@options[:version] = version
end
def expires_in
@options[:expires_in]
end
def expires_in=(expires_in)
@options.delete(:expires_at)
@options[:expires_in] = expires_in
end
def expires_at
@options[:expires_at]
end
def expires_at=(expires_at)
@options.delete(:expires_in)
@options[:expires_at] = expires_at
end
end
end
end