graphql-armory 0.1.0.pre4 → 0.1.0.pre5

data/lib/graphql/armory/persisted_queries.rb

@@ -40,20 +40,66 @@ module GraphQL
       # `store:` answers `fetch(id)` with an operation (`body` and `document`) or nil: a Manifest, or your own.
       # `strict: true` refuses raw queries unless the context holds `armory_allow_raw_query: true`.
       def self.use(schema, store:, strict: false)
-        if store.is_a?(Hash) || !store.respond_to?(:fetch)
-          raise ConfigurationError, "store: must answer fetch(id) with an operation or nil, like a Manifest"
-        end
-        raise ConfigurationError, "strict: must be true or false, got #{strict.inspect}" unless strict == true || strict == false
+        gate = Gate.build(store: store, strict: strict)
 
         if schema.singleton_class.include?(Guard)
           raise ConfigurationError, "#{schema} already uses PersistedQueries (here or in a parent schema): use it once"
         end
 
-        schema.instance_variable_set(:@armory_persisted_queries, [store, strict].freeze)
+        schema.instance_variable_set(:@armory_persisted_queries, gate)
         schema.singleton_class.prepend(Guard)
         schema.query_class(schema.query_class)
       end
 
+      # Decides what a request runs: answers `[refusal, document]`, where a refusal is the error message, a
+      # document is the stored operation to run instead of the request's text, and `[nil, nil]` runs the request
+      # as it came.
+      class Gate
+        # Wires the app's store with `use`'s defaults; `use` goes through here.
+        def self.build(store:, strict: false)
+          new(store: store, strict: strict)
+        end
+
+        # `new` is inert: with no store wired it refuses every request. It checks what it is given, so it never
+        # lets raw queries through without a store either.
+        def initialize(store: Store::Null.new, strict: true)
+          if store.is_a?(Hash) || !store.respond_to?(:fetch)
+            raise ConfigurationError, "store: must answer fetch(id) with an operation or nil, like a Manifest"
+          end
+          raise ConfigurationError, "strict: must be true or false, got #{strict.inspect}" unless strict == true || strict == false
+          raise ConfigurationError, "strict: false needs a store: with the Null store only raw queries would run" if !strict && store.is_a?(Store::Null)
+
+          @store = store
+          @strict = strict
+        end
+
+        def call(context, text, document)
+          operation_id = context[:operation_id] if context.respond_to?(:[])
+
+          if !operation_id.nil?
+            operation = operation_id.is_a?(String) ? @store.fetch(operation_id) : nil
+            if operation.nil?
+              [UNKNOWN_OPERATION, nil]
+            elsif document || (text && !same_query?(text, operation))
+              [MISMATCH, nil]
+            else
+              [nil, operation.document]
+            end
+          elsif @strict && !(context.respond_to?(:[]) && context[:armory_allow_raw_query] == true)
+            [RAW_QUERY_REFUSED, nil]
+          else
+            [nil, nil]
+          end
+        end
+
+        private
+
+        # Apollo's clients may send the query with its id; graphql-ruby's subscriptions resend it printed.
+        def same_query?(text, operation)
+          text == operation.body || text == operation.document.to_query_string
+        end
+      end
+
       # Keeps the lookup in every query class the schema uses, including one set after `use` or by a child schema.
       module Guard
         UNSET = Object.new.freeze
@@ -101,25 +147,9 @@ module GraphQL
       # Swaps the request's query for the stored document, or for nothing with an error when it is refused.
       module Lookup
         def initialize(schema, query_string = nil, **options)
-          store, strict = schema.armory_persisted_queries
-          context = options[:context]
-          operation_id = context[:operation_id] if context.respond_to?(:[])
           text = query_string || options[:query]
           text = nil if text == ""
-
-          refusal, document =
-            if !operation_id.nil?
-              operation = operation_id.is_a?(String) ? store.fetch(operation_id) : nil
-              if operation.nil?
-                UNKNOWN_OPERATION
-              elsif options[:document] || (text && !same_query?(text, operation))
-                MISMATCH
-              else
-                [nil, operation.document]
-              end
-            elsif strict && !(context.respond_to?(:[]) && context[:armory_allow_raw_query] == true)
-              RAW_QUERY_REFUSED
-            end
+          refusal, document = schema.armory_persisted_queries.(options[:context], text, options[:document])
 
           return super if refusal.nil? && document.nil?
           return super(schema, nil, **options, query: nil, document: document) if refusal.nil?
@@ -129,16 +159,11 @@ module GraphQL
           # with its own validator.
           super(schema, nil, **options, query: nil, document: options[:document] || EMPTY_DOCUMENT, validate: true, static_validator: Refusal.new(schema, refusal))
         end
-
-        private
-
-        # Apollo's clients may send the query with its id; graphql-ruby's subscriptions resend it printed.
-        def same_query?(text, operation)
-          text == operation.body || text == operation.document.to_query_string
-        end
       end
     end
   end
 end
 
 require "graphql/armory/persisted_queries/manifest"
+require "graphql/armory/persisted_queries/store"
+require "graphql/armory/persisted_queries/controls"

data/lib/graphql/armory/rate_limits/concurrency.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Lets each client run at most `limit` operations at the same time:
+      #
+      #   use GraphQL::Armory::RateLimits::Concurrency, store: GraphQL::Armory::RateLimits::MemoryStore.new,
+      #     limit: 5, soft: false
+      #
+      # A query analyzer takes a slot before the operation runs, or refuses it before any field resolves; a trace
+      # releases every slot its multiplex took when the multiplex ends, even when it raises. A slot a crashed
+      # process never released expires after `stale_after` seconds. Soft mode (the default) records but refuses
+      # nothing. What happened is in `context[:rate_limit_concurrency]`.
+      class Concurrency
+        CONTEXT_KEY = :rate_limit_concurrency
+        NAMESPACE = :graphql_armory
+
+        def self.use(schema, store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil)
+          concurrency = build(store: store, limit: limit, stale_after: stale_after, soft: soft, key: key, on_store_error: on_store_error)
+          schema.query_analyzer(Class.new(Analyzer) { define_method(:concurrency) { concurrency } })
+          schema.trace_with(Release)
+        end
+
+        # Wires the app's store with `use`'s defaults (soft mode); `use` goes through here.
+        def self.build(store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil)
+          new(store: store, limit: limit, stale_after: stale_after, soft: soft, key: key, on_store_error: on_store_error)
+        end
+
+        # `new` is inert: with no store wired it refuses every query. It checks every setting, so no partial
+        # configuration lets a query through either.
+        def initialize(store: Store::Null.new, limit: 1, stale_after: 60, soft: false, key: nil, on_store_error: nil)
+          unless Settings.store_answers?(store, acquire: %i[token limit ttl force], release: %i[token])
+            raise ConfigurationError, "store: must answer acquire(key, token:, limit:, ttl:, force:) and release(key, token:), like a MemoryStore"
+          end
+
+          @store = store
+          @limit = Settings.wired_limit(limit, store)
+          @stale_after = Settings.seconds(:stale_after, stale_after)
+          @soft = Settings.wired_soft(soft, store)
+          @key = Settings.key_reader(key)
+          @on_store_error = Settings.store_error_handler(on_store_error)
+        end
+
+        # Takes a slot for the query: the refusal when none is free, or nil to let it run.
+        def call(query)
+          unless query.current_trace.is_a?(Release)
+            raise ConfigurationError, "this query runs with its own trace (context[:trace]), so Concurrency could never release its slot: remove context[:trace] or add trace_with to that trace"
+          end
+
+          key = Settings.key_for(@key, query)
+          limit = Settings.limit_for(@limit, key, query)
+          if limit.nil?
+            record(query, key: key, limit: nil, active: nil, limited: false)
+            return nil
+          end
+
+          token = SecureRandom.hex(16)
+          answer = begin
+            @store.acquire(key, token: token, limit: limit, ttl: @stale_after, force: @soft)
+          rescue StandardError => error
+            @on_store_error.call(error, query)
+            return nil
+          end
+          acquired, active = Settings.checked(answer, :acquire, "the Integer slots held")
+
+          # Per query, not in the context hash: queries of a multiplex may share one hash.
+          query.context.namespace(NAMESPACE)[:concurrency_slot] = [self, key, token] if acquired || @soft
+          record(query, key: key, limit: limit, active: active, limited: !acquired)
+          refusal(limit, active) unless acquired || @soft
+        end
+
+        def release(query, key, token)
+          @store.release(key, token: token)
+        rescue StandardError => error
+          @on_store_error.call(error, query)
+        end
+
+        private
+
+        def record(query, **info)
+          query.context[CONTEXT_KEY] = { **info.slice(:key, :limit, :active), soft: @soft, limited: info[:limited] }
+        end
+
+        def refusal(limit, active)
+          GraphQL::AnalysisError.new(
+            "Too many operations at the same time: #{active} are already running for this client (limit #{limit}). Retry when one finishes.",
+            extensions: { "code" => "RATE_LIMITED", "limit" => limit, "active" => active }
+          )
+        end
+
+        # Takes the slot during analysis, before anything runs.
+        class Analyzer < GraphQL::Analysis::Analyzer
+          def result
+            concurrency.(query)
+          end
+        end
+
+        # Releases the slots of every query in the multiplex once it is done, whatever happened. Analysis runs
+        # inside `execute_multiplex` on both engines, so every slot taken is released here.
+        module Release
+          def execute_multiplex(multiplex:)
+            super
+          ensure
+            # Every slot is released even if one release raises (an on_store_error that raises); the first such
+            # error is raised afterwards.
+            failure = nil
+            multiplex.queries.each do |query|
+              slots = query.context.namespace(NAMESPACE)
+              concurrency, key, token = slots.delete(:concurrency_slot)
+              next unless concurrency
+
+              begin
+                concurrency.release(query, key, token)
+              rescue StandardError => error
+                failure ||= error
+              end
+            end
+            raise failure if failure
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits/controls.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Test data for the rate limiters, reusable by apps and other gems.
+      module Controls
+        # A Query type: `cheap` costs 1 point, `report` costs 40, `broken` raises when resolved.
+        module Query
+          def self.example
+            Class.new(GraphQL::Schema::Object) do
+              graphql_name "Query"
+              field :cheap, String, null: false
+              field :report, String, null: false, complexity: 40
+              field :broken, String, null: false
+            end
+          end
+        end
+
+        # The root object for Query.example; it adds the name of each field it resolves to `resolved`.
+        module Root
+          def self.example(resolved = [])
+            Class.new do
+              define_method(:cheap) { resolved << :cheap; "ok" }
+              define_method(:report) { resolved << :report; "big" }
+              define_method(:broken) { raise IOError, "disk on fire" }
+            end.new
+          end
+        end
+
+        # A query context naming its client.
+        module Context
+          def self.example(key: "user:1", **context)
+            { RateLimits::KEY => key, **context }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits/memory_store.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Buckets kept in this process's memory: for tests, development and single-process servers. Several
+      # processes each keep their own buckets, so a client gets the limit once per process; share a store between
+      # processes in production.
+      class MemoryStore
+        def self.monotonic_clock
+          -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        end
+
+        def initialize(clock: self.class.monotonic_clock)
+          @clock = clock
+          @buckets = {}
+          @slots = {}
+          @mutex = Mutex.new
+        end
+
+        # Token bucket: holds up to `limit` points and refills `limit` points every `window` seconds, continuously.
+        # Takes `cost` points when they are there; with `force: true` takes them anyway, down to zero. Answers
+        # whether they were there and the whole points left.
+        def take(key, cost:, limit:, window:, force: false)
+          @mutex.synchronize do
+            now = @clock.call
+            level, at = @buckets.fetch(key) { [limit, now] }
+            level = [level + ([now - at, 0].max * limit / window.to_f), limit].min
+
+            taken = cost <= level
+            level = [level - cost, 0].max if taken || force
+            @buckets[key] = [level, [now, at].max]
+
+            [taken, level.floor]
+          end
+        end
+
+        # Slots for operations running at the same time: at most `limit` per key, each held by a token until
+        # released or until `ttl` seconds pass (a process that crashed never releases). Takes a slot when one is
+        # free; with `force: true` takes it anyway. Answers whether one was free and the slots now held.
+        def acquire(key, token:, limit:, ttl:, force: false)
+          @mutex.synchronize do
+            now = @clock.call
+            slots = (@slots[key] ||= {})
+            slots.delete_if { |_token, expires_at| expires_at <= now }
+
+            acquired = slots.size < limit
+            slots[token] = now + ttl if acquired || force
+
+            [acquired, slots.size]
+          end
+        end
+
+        def release(key, token:)
+          @mutex.synchronize do
+            slots = @slots[key] or return
+            slots.delete(token)
+            @slots.delete(key) if slots.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits/points.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Charges each query its complexity, as graphql-ruby computes it before running it, against a bucket of
+      # points per client that refills over a window:
+      #
+      #   use GraphQL::Armory::RateLimits::Points, store: GraphQL::Armory::RateLimits::MemoryStore.new,
+      #     limit: 1_000, window: 60, soft: false
+      #
+      # A query that costs more than the client has left is refused before any field resolves, and charged
+      # nothing. Soft mode (the default) charges and records but refuses nothing. What happened is in
+      # `context[:rate_limit_points]`.
+      class Points
+        CONTEXT_KEY = :rate_limit_points
+        NAMESPACE = :graphql_armory
+
+        def self.use(schema, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false)
+          points = build(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, extensions: extensions)
+          schema.query_analyzer(Class.new(Analyzer) { define_method(:points) { points } })
+        end
+
+        # HTTP headers for the budget a result recorded: `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`
+        # (seconds until the bucket is full again). Empty when the query had no limit.
+        def self.headers(result)
+          info = result.context.namespace(NAMESPACE)[:points]
+          return {} unless info && info[:limit]
+
+          { "RateLimit-Limit" => info[:limit].to_s, "RateLimit-Remaining" => info[:remaining].to_s, "RateLimit-Reset" => reset_in(info).to_s }
+        end
+
+        def self.reset_in(info)
+          ((info[:limit] - info[:remaining]) * info[:window] / info[:limit].to_f).ceil
+        end
+
+        # Wires the app's store with `use`'s defaults (soft mode); `use` goes through here.
+        def self.build(store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false)
+          new(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, extensions: extensions)
+        end
+
+        # `new` is inert: with no store wired it refuses every query. It checks every setting, so no partial
+        # configuration lets a query through either.
+        def initialize(store: Store::Null.new, limit: 1, window: 60, soft: false, key: nil, on_store_error: nil, extensions: false)
+          unless Settings.store_answers?(store, take: %i[cost limit window force])
+            raise ConfigurationError, "store: must answer take(key, cost:, limit:, window:, force:), like a MemoryStore"
+          end
+          raise ConfigurationError, "extensions: must be true or false, got #{extensions.inspect}" unless extensions == true || extensions == false
+
+          @store = store
+          @limit = Settings.wired_limit(limit, store)
+          @window = Settings.seconds(:window, window)
+          @soft = Settings.wired_soft(soft, store)
+          @key = Settings.key_reader(key)
+          @on_store_error = Settings.store_error_handler(on_store_error)
+          @extensions = extensions
+        end
+
+        # The refusal for a query that costs `cost`, or nil to let it run.
+        def call(query, cost)
+          key = Settings.key_for(@key, query)
+          limit = Settings.limit_for(@limit, key, query)
+          if limit.nil?
+            record(query, key: key, cost: cost, limit: nil, remaining: nil, limited: false)
+            return nil
+          end
+
+          answer = begin
+            @store.take(key, cost: cost, limit: limit, window: @window, force: @soft)
+          rescue StandardError => error
+            # No record: a context hash shared with an earlier query must not keep its numbers.
+            query.context[CONTEXT_KEY] = nil
+            @on_store_error.call(error, query)
+            return nil
+          end
+          taken, remaining = Settings.checked(answer, :take, "the Integer points left")
+
+          info = record(query, key: key, cost: cost, limit: limit, remaining: remaining, limited: !taken)
+          if @extensions
+            query.context.response_extensions["rateLimit"] =
+              { "cost" => cost, "limit" => limit, "remaining" => remaining, "resetIn" => self.class.reset_in(info) }
+          end
+          refusal(cost, limit, remaining) unless taken || @soft
+        end
+
+        private
+
+        # In the context hash for instrumentation, and per query for `headers`: queries of a multiplex may share one
+        # context hash, where the last query's record wins.
+        def record(query, **info)
+          info = { **info.slice(:key, :cost, :limit, :remaining), window: @window, soft: @soft, limited: info[:limited] }
+          query.context.namespace(NAMESPACE)[:points] = info
+          query.context[CONTEXT_KEY] = info
+        end
+
+        def refusal(cost, limit, remaining)
+          if cost > limit
+            return GraphQL::AnalysisError.new(
+              "Rate limit exceeded: this query costs #{cost} points and the limit is #{limit} every #{@window} seconds, so it can never run.",
+              extensions: { "code" => "RATE_LIMITED", "cost" => cost, "limit" => limit }
+            )
+          end
+
+          retry_after = ((cost - remaining) * @window / limit.to_f).ceil
+          GraphQL::AnalysisError.new(
+            "Rate limit exceeded: this query costs #{cost} points and #{remaining} remain (#{limit} every #{@window} seconds). Retry in #{retry_after} seconds.",
+            extensions: { "code" => "RATE_LIMITED", "cost" => cost, "remaining" => remaining, "retryAfter" => retry_after }
+          )
+        end
+
+        # graphql-ruby's own complexity analysis, then the charge.
+        class Analyzer < GraphQL::Analysis::QueryComplexity
+          def result
+            cost = super
+            unless cost.is_a?(Numeric) && cost.finite? && !cost.negative?
+              raise ConfigurationError, "the query complexity is #{cost.inspect}: field complexities must be numbers of zero or more"
+            end
+
+            # Fractional complexities (`complexity: 0.5`) are charged whole points, rounded up.
+            points.(query, cost.ceil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits/redis_store.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Buckets and slots kept in Redis, shared by every process of the app: the store for production.
+      #
+      #   store = GraphQL::Armory::RateLimits::RedisStore.new(redis: Redis.new(url: ENV.fetch("REDIS_URL")))
+      #
+      # Each change is one Lua script, so concurrent requests never race, and the time comes from Redis's own clock,
+      # so processes on different machines agree on it. Keys live under `prefix` and expire once they no longer
+      # matter. `redis:` is a redis-rb client (>= 4.8), or anything answering `eval` and `evalsha` the same way;
+      # its errors reach the limiters, which let the query through and call `on_store_error`. This gem does not
+      # depend on the redis gem: the app adds it.
+      class RedisStore
+        DEFAULT_PREFIX = "graphql-armory:rate-limits:"
+
+        # The time in seconds: the one given by the caller (tests), or Redis's own clock.
+        CLOCK = <<~LUA
+          local function clock(given)
+            if given ~= "" then return tonumber(given) end
+            local time = redis.call("TIME")
+            return tonumber(time[1]) + tonumber(time[2]) / 1000000
+          end
+        LUA
+
+        # Same token bucket as MemoryStore#take. The bucket expires once a whole window has passed: it is full
+        # again by then, the same as no bucket at all. An expiry is only ever pushed later, never brought closer, so
+        # a limiter with a shorter window sharing the key cannot cut it short. The points left go back as a string:
+        # Redis would truncate a Lua number past 2**63. A bucket whose fields are not numbers is an error, so the
+        # limiter calls on_store_error instead of reading it as full.
+        TAKE = <<~LUA
+          #{CLOCK}
+          local cost, limit, window = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
+          local force, now = ARGV[4] == "1", clock(ARGV[5])
+          local state = redis.call("HMGET", KEYS[1], "level", "at")
+          local level, at = tonumber(state[1]), tonumber(state[2])
+          if not (state[1] or state[2]) then
+            level, at = limit, now
+          elseif not (level and at) or level ~= level or at ~= at or level < 0 or level == math.huge or math.abs(at) == math.huge then
+            return redis.error_reply("graphql-armory: corrupt rate limit bucket at " .. KEYS[1])
+          end
+          level = math.min(level + math.max(now - at, 0) * limit / window, limit)
+
+          local taken = cost <= level
+          if taken or force then level = math.max(level - cost, 0) end
+          redis.call("HSET", KEYS[1], "level", string.format("%.17g", level), "at", string.format("%.17g", math.max(now, at)))
+          local keep = math.ceil(window * 1000) + 1000
+          if redis.call("PTTL", KEYS[1]) < keep then redis.call("PEXPIRE", KEYS[1], keep) end
+
+          return { taken and 1 or 0, string.format("%.0f", math.floor(level)) }
+        LUA
+
+        # Same slots as MemoryStore#acquire: a sorted set of tokens scored by when they expire. The key lives as long
+        # as its latest slot, whatever ttl each acquire passed.
+        ACQUIRE = <<~LUA
+          #{CLOCK}
+          local token, limit, ttl = ARGV[1], tonumber(ARGV[2]), tonumber(ARGV[3])
+          local force, now = ARGV[4] == "1", clock(ARGV[5])
+          redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", string.format("%.17g", now))
+
+          local acquired = redis.call("ZCARD", KEYS[1]) < limit
+          if acquired or force then
+            redis.call("ZADD", KEYS[1], string.format("%.17g", now + ttl), token)
+            local latest = tonumber(redis.call("ZRANGE", KEYS[1], -1, -1, "WITHSCORES")[2])
+            redis.call("PEXPIRE", KEYS[1], math.ceil((latest - now) * 1000) + 1000)
+          end
+
+          return { acquired and 1 or 0, redis.call("ZCARD", KEYS[1]) }
+        LUA
+
+        RELEASE = <<~LUA
+          return redis.call("ZREM", KEYS[1], ARGV[1])
+        LUA
+
+        def initialize(redis:, prefix: DEFAULT_PREFIX, clock: nil)
+          unless redis.respond_to?(:eval) && redis.respond_to?(:evalsha)
+            raise ConfigurationError, "redis: must be a Redis client that runs scripts (eval and evalsha), like Redis.new from the redis gem"
+          end
+          raise ConfigurationError, "prefix: must be a non-empty String, got #{prefix.inspect}" unless prefix.is_a?(String) && !prefix.empty?
+          raise ConfigurationError, "clock: must be nil (Redis's clock) or answer call with the time in seconds" unless clock.nil? || clock.respond_to?(:call)
+
+          @redis = redis
+          @prefix = prefix
+          @clock = clock
+        end
+
+        def take(key, cost:, limit:, window:, force: false)
+          taken, level = script(TAKE, "#{@prefix}points:#{key}", cost, limit, seconds(window), flag(force), now)
+          [taken == 1, Integer(level, 10)]
+        end
+
+        def acquire(key, token:, limit:, ttl:, force: false)
+          acquired, held = script(ACQUIRE, "#{@prefix}slots:#{key}", token, limit, seconds(ttl), flag(force), now)
+          [acquired == 1, held]
+        end
+
+        def release(key, token:)
+          script(RELEASE, "#{@prefix}slots:#{key}", token)
+          nil
+        end
+
+        private
+
+        def flag(value)
+          value ? "1" : "0"
+        end
+
+        # Lua reads decimal numbers only: not "1/2" (a Rational) nor a Time.
+        def seconds(value)
+          Float(value).to_s
+        end
+
+        def now
+          @clock ? seconds(@clock.call.to_f) : ""
+        end
+
+        # EVALSHA sends only the script's digest; Redis forgets scripts on restart or SCRIPT FLUSH, and then EVAL
+        # sends it whole once more.
+        def script(source, key, *argv)
+          argv = argv.map(&:to_s)
+          @redis.evalsha(Digest::SHA1.hexdigest(source), keys: [key], argv: argv)
+        rescue StandardError => error
+          raise unless error.message.start_with?("NOSCRIPT")
+
+          @redis.eval(source, keys: [key], argv: argv)
+        end
+      end
+    end
+  end
+end