timex 0.1.0

data/lib/timex/propagation/rack_middleware.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Propagation
+    # Rack middleware: parses inbound {HttpHeader::HEADER_NAME}, stores
+    # +env["timex.deadline"]+, optionally clamps and rejects abusive values, and
+    # can echo remaining budget on the response.
+    #
+    # @note The header is **untrusted** on public networks. Combine +max_seconds:+,
+    #   +max_depth:+, and network controls; see class body for threat summary.
+    #
+    # @see HttpHeader
+    # @see Deadline.from_header
+    class RackMiddleware
+
+      ENV_KEY              = "timex.deadline"
+      RAW_HEADER_KEY       = HttpHeader::RACK_HEADER_KEY
+
+      # Rack 3 mandates lower-case response header names; Rack 2 (and many
+      # 3rd-party middlewares that haven't migrated) still emit canonical
+      # case. Pass `header_case: :canonical` to switch the response header
+      # names to `Content-Type` / `X-TIMEx-*` for Rack-2-era stacks.
+      HEADER_NAMES = {
+        rack3: {
+          remaining: "x-timex-remaining-ms",
+          outcome: "x-timex-outcome",
+          content_type: "content-type"
+        }.freeze,
+        canonical: {
+          remaining: "X-TIMEx-Remaining-Ms",
+          outcome: "X-TIMEx-Outcome",
+          content_type: "Content-Type"
+        }.freeze
+      }.freeze
+
+      # @param app [#call] inner Rack application
+      # @param default_seconds [Numeric, nil] installed when no header is present
+      # @param max_seconds [Numeric, nil] clamps inbound deadlines to at most this budget
+      # @param max_depth [Integer, nil] rejects requests whose parsed +depth+ exceeds this value
+      # @param expose_remaining [Boolean] when +true+, adds remaining-ms response header
+      # @param clamp_infinite_to_default [Boolean] when +true+ with +default_seconds+, maps inbound infinite to default
+      # @param header_case [:rack3, :canonical] response header casing
+      # @raise [ArgumentError] when +header_case+ is unknown
+      def initialize(app, default_seconds: nil, max_seconds: nil, max_depth: nil, # rubocop:disable Metrics/ParameterLists
+                     expose_remaining: false, clamp_infinite_to_default: false,
+                     header_case: :rack3)
+        raise ArgumentError, "header_case must be :rack3 or :canonical" unless HEADER_NAMES.key?(header_case)
+
+        @app = app
+        @default_seconds = default_seconds
+        @max_seconds = max_seconds
+        @max_depth = max_depth
+        @expose_remaining = expose_remaining
+        @clamp_infinite_to_default = clamp_infinite_to_default
+        @headers = HEADER_NAMES.fetch(header_case)
+      end
+
+      # Security: this header is taken from the inbound HTTP request without
+      # authentication. An attacker who can reach this endpoint can send
+      # `ms=0` to force an immediate 503, or a large `ms=` value to extend a
+      # request's allowed processing window beyond what your server intended.
+      # Only mount this middleware on networks where the upstream is trusted
+      # (e.g. internal service mesh, signed/authenticated requests).
+      #
+      # For internet-facing deployments, **always** pass `max_seconds:` so any
+      # incoming deadline is clamped to that ceiling, and `max_depth:` to bound
+      # propagation hops (example: `use TIMEx::Propagation::RackMiddleware, max_seconds: 30, max_depth: 8`).
+      #
+      # `Deadline.from_header` also caps untrusted input length at
+      # `Deadline::MAX_HEADER_BYTESIZE`, rejects non-finite/negative/very large
+      # `ms=` values, and clamps `depth=` at `Deadline::MAX_DEPTH`.
+      #
+      # `max_depth` is enforced on the *parsed inbound* deadline before
+      # `max_seconds` clamping. Clamping via {Deadline#min} can yield a fresh
+      # deadline without propagation metadata; checking depth only after clamp
+      # would let a client bypass the hop limit with an oversized `ms=`.
+      #
+      # @param env [Hash{String => Object}]
+      # @return [Array(Integer, Hash, #each)] Rack triplet
+      def call(env)
+        # Distinguish "no header sent" from "header present but unparseable":
+        # the latter is suspicious (truncation, smuggling attempt) and
+        # deserves a telemetry signal even though we still fall through to
+        # `default_seconds` / unbounded handling.
+        raw = env[RAW_HEADER_KEY]
+        deadline = HttpHeader.from_rack_env(env)
+        if raw && !raw.empty? && deadline.nil?
+          TIMEx::Telemetry.emit(
+            event: "rack.deadline.unparseable",
+            bytesize: raw.bytesize
+          )
+        end
+
+        if depth_exceeded?(deadline)
+          TIMEx::Telemetry.emit(
+            event: "rack.deadline.rejected",
+            reason: :max_depth_exceeded,
+            depth: deadline.depth,
+            origin: deadline.origin
+          )
+          return reject_response("max-depth-exceeded", "Deadline propagation depth exceeded")
+        end
+
+        deadline = nil if deadline&.infinite? && @clamp_infinite_to_default && @default_seconds
+        deadline = clamp(deadline)
+        deadline ||= Deadline.in(@default_seconds) if @default_seconds
+
+        if deadline
+          env[ENV_KEY] = deadline
+          env[RAW_HEADER_KEY] = deadline.to_header
+        else
+          env.delete(RAW_HEADER_KEY)
+        end
+
+        if deadline&.expired?
+          TIMEx::Telemetry.emit(
+            event: "rack.deadline.rejected",
+            reason: :expired_on_arrival,
+            origin: deadline.origin
+          )
+          return reject_response("expired-on-arrival", "Deadline expired before request handling")
+        end
+
+        status, headers, body = @app.call(env)
+        headers = inject_remaining(headers, deadline) if @expose_remaining
+        [status, headers, body]
+      end
+
+      private
+
+      # @param outcome [String] value for the outcome response header
+      # @param body [String] plain-text body (wrapped in a single-element array)
+      # @return [Array(Integer, Hash, Array<String>)]
+      def reject_response(outcome, body)
+        [
+          503,
+          {
+            @headers[:content_type] => "text/plain",
+            @headers[:outcome] => outcome
+          },
+          [body]
+        ]
+      end
+
+      # @param deadline [Deadline, nil]
+      # @return [Deadline, nil]
+      def clamp(deadline)
+        return deadline unless deadline && @max_seconds
+
+        deadline.min(Deadline.in(@max_seconds))
+      end
+
+      # @param deadline [Deadline, nil]
+      # @return [Boolean]
+      def depth_exceeded?(deadline)
+        return false unless deadline && @max_depth
+
+        deadline.depth > @max_depth
+      end
+
+      # @param headers [Hash, Object]
+      # @param deadline [Deadline, nil]
+      # @return [Hash, Object]
+      def inject_remaining(headers, deadline)
+        return headers unless deadline && !deadline.infinite?
+        return headers unless headers.is_a?(Hash) || headers.respond_to?(:merge)
+
+        value = deadline.remaining_ms.round.to_s
+        key = @headers[:remaining]
+        if headers.frozen?
+          headers.merge(key => value)
+        else
+          headers[key] = value
+          headers
+        end
+      end
+
+    end
+  end
+end

data/lib/timex/registry.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Copy-on-write registry of named strategies.
+  #
+  # Reads are lock-free against the frozen backing hash; writes synchronize and
+  # replace the hash atomically. Suited for boot-time registration and per-call
+  # resolution on the hot path.
+  #
+  # @see TIMEx.deadline
+  # @see Registry.resolve_for_call
+  module Registry
+
+    @strategies = {}.freeze
+    @write_mutex = Mutex.new
+    @default_selector = nil
+    @cached_default = nil
+    @cached_default_key = nil
+
+    extend self
+
+    # @param name [Symbol, String] registration key
+    # @param strategy [#call] callable strategy object
+    # @return [void]
+    # @raise [ArgumentError] when +strategy+ does not respond to +#call+
+    def register(name, strategy)
+      raise ArgumentError, "strategy must respond to :call, got #{strategy.inspect}" unless strategy.respond_to?(:call)
+
+      @write_mutex.synchronize do
+        @strategies = @strategies.merge(name.to_sym => strategy).freeze
+        invalidate_default_cache
+      end
+    end
+
+    # @param name [Symbol, String]
+    # @return [#call]
+    # @raise [StrategyNotFoundError] when unknown
+    def fetch(name)
+      sym = name.to_sym
+      strategies = @strategies
+      strategies.fetch(sym) do
+        raise StrategyNotFoundError, "no strategy registered as #{name.inspect}; " \
+                                     "available: #{strategies.keys.inspect}"
+      end
+    end
+
+    # @return [Array<Symbol>] known registration keys (snapshot)
+    def known
+      @strategies.keys
+    end
+
+    # Resolves a symbol to a registered strategy; passes callables through; +nil+ stays +nil+.
+    #
+    # @param strategy_or_name [Symbol, #call, nil]
+    # @return [#call, nil]
+    # @raise [StrategyNotFoundError] when a symbol names an unknown strategy
+    def resolve(strategy_or_name)
+      case strategy_or_name
+      when Symbol then fetch(strategy_or_name)
+      when nil then nil
+      else strategy_or_name
+      end
+    end
+
+    # Resolves the callable used by {TIMEx.deadline}: the configured default when
+    # +strategy+ is +nil+, a registered entry when it is a {Symbol}, otherwise
+    # the object must respond to +#call+ (strategy class or instance).
+    #
+    # @param strategy [Symbol, #call, nil]
+    # @return [#call]
+    # @raise [StrategyNotFoundError] when +strategy+ names an unknown registration
+    # @raise [ArgumentError] when +strategy+ is neither +nil+, a {Symbol}, nor +#call+-able
+    def resolve_for_call(strategy)
+      case strategy
+      when nil then select_default
+      when Symbol then fetch(strategy)
+      else
+        if strategy.respond_to?(:call)
+          strategy
+        else
+          raise ArgumentError,
+            "strategy must be a Symbol, Class, or instance responding to " \
+            "#call, got #{strategy.inspect}"
+        end
+      end
+    end
+
+    # Installs or returns the optional default-strategy selector block.
+    #
+    # @yieldreturn [Symbol, nil] strategy key to resolve, or +nil+ to fall through to config
+    # @return [Proc, nil] current selector when called without a block
+    def default_selector(&block)
+      if block
+        @write_mutex.synchronize do
+          @default_selector = block
+          invalidate_default_cache
+        end
+      end
+      @default_selector
+    end
+
+    # Resolves {TIMEx.config} default strategy with optional selector and caching.
+    #
+    # @return [#call]
+    #
+    # @note Hot path: caches static {Configuration#default_strategy} resolutions; a
+    #   configured selector disables the cache because results may vary per call.
+    def select_default
+      if @default_selector
+        sym = @default_selector.call
+        return fetch(sym) if sym
+      end
+
+      key = TIMEx.config.default_strategy
+      return @cached_default if key == @cached_default_key && @cached_default
+
+      resolved = fetch(key)
+      @cached_default_key = key
+      @cached_default = resolved
+      resolved
+    end
+
+    private
+
+    # @return [void]
+    def invalidate_default_cache
+      @cached_default = nil
+      @cached_default_key = nil
+    end
+
+  end
+end

data/lib/timex/result.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Discriminated outcome from work executed under a deadline when errors are
+  # captured instead of raised (+on_timeout: :result+, non-raising strategies, etc.).
+  #
+  # Instances are frozen at construction and support pattern matching via
+  # {#deconstruct} / {#deconstruct_keys}.
+  #
+  # @see TIMEx.deadline
+  class Result
+
+    OK      = :ok
+    TIMEOUT = :timeout
+    ERROR   = :error
+
+    attr_reader :outcome, :value, :strategy, :elapsed_ms, :error, :deadline_ms
+
+    # @param outcome [Symbol] one of +OK+, +TIMEOUT+, or +ERROR+
+    # @param value [Object, nil] success payload when +outcome == OK+
+    # @param strategy [Symbol, nil] component name when known
+    # @param elapsed_ms [Numeric, nil] elapsed time in ms when known
+    # @param error [Exception, nil] underlying exception for timeout/error paths
+    # @param deadline_ms [Numeric, nil] original budget in ms for timeout paths
+    # @return [void]
+    #
+    # @note Freezes +self+ before returning.
+    def initialize(outcome:, value: nil, strategy: nil, elapsed_ms: nil, error: nil, deadline_ms: nil) # rubocop:disable Metrics/ParameterLists
+      @outcome = outcome
+      @value = value
+      @strategy = strategy
+      @elapsed_ms = elapsed_ms
+      @error = error
+      @deadline_ms = deadline_ms
+      freeze
+    end
+
+    # @param value [Object] success value
+    # @param strategy [Symbol, nil]
+    # @param elapsed_ms [Numeric, nil]
+    # @return [Result] frozen OK result
+    def self.ok(value, strategy: nil, elapsed_ms: nil)
+      new(outcome: OK, value:, strategy:, elapsed_ms:)
+    end
+
+    # Builds a timeout result, always carrying an {Expired} in +#error+ so {#value!}
+    # can re-raise with uniform metadata.
+    #
+    # @param strategy [Symbol, nil]
+    # @param expired [Expired, nil] existing {Expired} (preferred)
+    # @param elapsed_ms [Numeric, nil] used with +deadline_ms+ to synthesize {Expired} when +expired+ omitted
+    # @param deadline_ms [Numeric, nil] used with +elapsed_ms+ to synthesize {Expired} when +expired+ omitted
+    # @return [Result] frozen timeout result
+    def self.timeout(strategy:, expired: nil, elapsed_ms: nil, deadline_ms: nil)
+      expired ||= Expired.new(
+        "deadline expired",
+        strategy:,
+        deadline_ms:,
+        elapsed_ms:
+      )
+      new(
+        outcome: TIMEOUT,
+        strategy:,
+        error: expired,
+        elapsed_ms: elapsed_ms || expired.elapsed_ms,
+        deadline_ms: deadline_ms || expired.deadline_ms
+      )
+    end
+
+    # @param error [Exception]
+    # @param strategy [Symbol, nil]
+    # @param elapsed_ms [Numeric, nil]
+    # @return [Result] frozen error result
+    # @raise [ArgumentError] when +error+ is not an +Exception+
+    def self.error(error, strategy: nil, elapsed_ms: nil)
+      raise ArgumentError, "error must be an Exception, got #{error.class}" unless error.is_a?(Exception)
+
+      new(outcome: ERROR, error:, strategy:, elapsed_ms:)
+    end
+
+    # @return [Boolean]
+    def ok?      = @outcome == OK
+
+    # @return [Boolean]
+    def timeout? = @outcome == TIMEOUT
+
+    # @return [Boolean]
+    def error?   = @outcome == ERROR
+
+    # Returns the success value or raises the captured exception.
+    #
+    # @return [Object] +@value+ when {#ok?}
+    # @raise [Expired, Exception] when {#timeout?} or {#error?}
+    # @raise [Error] when not OK and no +@error+ is present
+    def value!
+      return @value if ok?
+      raise @error if @error
+
+      raise Error, "result has no value"
+    end
+    alias unwrap value!
+
+    # Returns +@value+ when the result is OK, otherwise the +default+ (or the
+    # block's return value if a block is given).
+    #
+    # @param default [Object] fallback when not OK and no block given
+    # @yieldparam result [Result] +self+ for inspecting +error+, +strategy+, etc.
+    # @return [Object]
+    def value_or(default = nil)
+      if ok?
+        @value
+      else
+        (block_given? ? yield(self) : default)
+      end
+    end
+    alias unwrap_or value_or
+
+    # @return [Array(Symbol, Object, Exception, nil)] array shape for pattern matching
+    def deconstruct
+      [@outcome, @value, @error]
+    end
+
+    # @param _keys [Array<Symbol>, nil] ignored; present for Ruby pattern-matching protocol
+    # @return [Hash{Symbol => Object}] hash shape for pattern matching
+    def deconstruct_keys(_keys)
+      {
+        outcome: @outcome,
+        value: @value,
+        error: @error,
+        strategy: @strategy,
+        elapsed_ms: @elapsed_ms,
+        deadline_ms: @deadline_ms
+      }
+    end
+
+  end
+end

data/lib/timex/strategies/base.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Strategies
+    # Abstract strategy: runs user code against a {Deadline} and maps {Expired}
+    # to +on_timeout:+ behavior via {TimeoutHandling}.
+    #
+    # Subclasses implement {#run}. Telemetry wraps each invocation when a
+    # non-null adapter is configured.
+    #
+    # @see TIMEx.deadline
+    # @see Registry
+    class Base
+
+      include TIMEx::NamedComponent
+      include TIMEx::TimeoutHandling
+
+      class << self
+
+        # Convenience constructor: +new(**opts).call(...)+.
+        #
+        # @param deadline [Deadline, Numeric, Time, nil] budget or absolute deadline
+        # @param on_timeout [Symbol, Proc] timeout dispatch mode
+        # @param opts [Hash{Symbol => Object}] subclass-specific options forwarded to +#initialize+
+        # @yieldparam deadline [Deadline] coerced deadline passed to user block
+        # @return [Object] block result or handler return (see {TimeoutHandling})
+        def call(deadline:, on_timeout: :raise, **opts, &block)
+          new(**opts).call(deadline:, on_timeout:, &block)
+        end
+
+      end
+
+      # Coerces +deadline+, optionally instruments, and runs {#run}.
+      #
+      # @param deadline [Deadline, Numeric, Time, nil]
+      # @param on_timeout [Symbol, Proc]
+      # @yieldparam deadline [Deadline]
+      # @return [Object]
+      def call(deadline:, on_timeout: :raise, &block)
+        deadline = Deadline.coerce(deadline)
+
+        # Resolve the adapter exactly once per call. `Telemetry.adapter` walks
+        # `Telemetry.@adapter || TIMEx.config.telemetry_adapter || ...` on
+        # every access; we hand the resolved object straight to `instrument`
+        # to avoid re-walking it under the hot-path null check.
+        adapter = TIMEx::Telemetry.adapter
+        return run_unobserved(deadline, on_timeout, &block) if adapter.is_a?(TIMEx::Telemetry::Adapters::Null)
+
+        deadline_ms = deadline.infinite? ? nil : deadline.remaining_ms.round
+        TIMEx::Telemetry.instrument(
+          event: "strategy.call",
+          strategy: self.class.name_symbol,
+          deadline_ms:
+        ) do |payload|
+          run(deadline, &block)
+        rescue Expired => e
+          payload[:outcome] = :timeout
+          handle_timeout(on_timeout, e)
+        end
+      end
+
+      protected
+
+      # @param deadline [Deadline]
+      # @yieldparam deadline [Deadline]
+      # @return [Object]
+      # @raise [NotImplementedError] on +Base+
+      def run(_deadline)
+        raise NotImplementedError
+      end
+
+      private
+
+      # Telemetry-free path when the adapter is {Telemetry::Adapters::Null}.
+      #
+      # @param deadline [Deadline]
+      # @param on_timeout [Symbol, Proc]
+      # @yieldparam deadline [Deadline]
+      # @return [Object]
+      def run_unobserved(deadline, on_timeout, &)
+        run(deadline, &)
+      rescue Expired => e
+        handle_timeout(on_timeout, e)
+      end
+
+    end
+  end
+end

data/lib/timex/strategies/closeable.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Strategies
+    # Invokes +close_method+ on a watchdog thread after the deadline so blocking
+    # I/O surfaces as +IOError+ / +EBADF+ / +EPIPE+ (etc.), then maps those to
+    # {Expired} when the close was timer-driven.
+    #
+    # @note +close_method+ runs **concurrently** with the user block. It must be
+    #   safe to call while the block uses the resource; avoid mutual deadlocks on
+    #   the same mutex.
+    #
+    # @see Base
+    class Closeable < Base
+
+      # @param resource [Object] object receiving +close_method+
+      # @param close_method [Symbol] method name invoked to unblock I/O
+      def initialize(resource:, close_method: :close)
+        super()
+        @resource     = resource
+        @close_method = close_method
+      end
+
+      protected
+
+      # @param deadline [Deadline]
+      # @yieldparam resource [Object] the configured resource
+      # @yieldparam deadline [Deadline]
+      # @return [Object]
+      # @raise [Expired] when I/O errors follow a timer-driven close
+      def run(deadline)
+        return yield(@resource, deadline) if deadline.infinite?
+
+        state = { closed_by_timer: false, block_done: false, mutex: Mutex.new }
+        timer = Thread.new do
+          remaining = deadline.remaining
+          ::Kernel.sleep(remaining) if remaining.positive?
+          # We claim the right to close under the mutex, but invoke
+          # `close_method` OUTSIDE it. A blocking `close` implementation
+          # would otherwise hold the mutex while the user's block reaches
+          # its ensure clause (which also acquires the mutex), causing
+          # deadlock.
+          should_close = state[:mutex].synchronize do
+            next false if state[:block_done]
+
+            state[:closed_by_timer] = true
+            true
+          end
+          if should_close
+            begin
+              @resource.public_send(@close_method)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+        begin
+          yield(@resource, deadline)
+        rescue IOError,
+               Errno::EBADF, Errno::EPIPE, Errno::ECONNRESET,
+               Errno::ENOTCONN, Errno::ESHUTDOWN => e
+          raise unless state[:closed_by_timer]
+
+          raise deadline.expired_error(
+            strategy: :closeable,
+            message: "closeable deadline expired (#{e.class})"
+          )
+        ensure
+          state[:mutex].synchronize { state[:block_done] = true }
+          if timer.alive?
+            timer.kill
+            timer.join(0.1)
+          end
+        end
+      end
+
+    end
+  end
+end
+
+TIMEx::Registry.register(:closeable, TIMEx::Strategies::Closeable)

data/lib/timex/strategies/cooperative.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Strategies
+    # Default strategy: runs the block, then performs a final {#Deadline#check!}
+    # so purely CPU-bound work still observes expiry at cooperative points only.
+    #
+    # @see Base
+    class Cooperative < Base
+
+      protected
+
+      # @param deadline [Deadline]
+      # @yieldparam deadline [Deadline]
+      # @return [Object] block result after post-check
+      # @raise [Expired] when past deadline after the block returns
+      def run(deadline)
+        result = yield(deadline)
+        deadline.check!(strategy: :cooperative)
+        result
+      end
+
+    end
+  end
+end
+
+TIMEx::Registry.register(:cooperative, TIMEx::Strategies::Cooperative)