timex 0.1.0

data/lib/timex/strategies/wakeup.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Strategies
+    # Pipe-based wakeup primitive: blocked I/O on {#read_io} unblocks when the
+    # deadline fires (or {#cancel!} is called), and the {CancellationToken}
+    # transitions to {#fired?}. Use to wake threads blocked in +IO.select+ on
+    # resources without native deadlines.
+    #
+    # Each instance is **single-use**: the pipe is created lazily and closed in
+    # +ensure+ after {#run}. Construct a fresh instance per operation.
+    #
+    # @note Accessing {#read_io} / {#write_io} before {#arm} without a constructor
+    #   deadline creates the pipe but does **not** install a timer; the read end
+    #   blocks until {#cancel!} unless you pass a deadline to {#initialize} or call {#arm}.
+    #
+    # @see CancellationToken
+    # @see Base
+    class Wakeup < Base
+
+      attr_reader :token
+
+      # @param deadline [Deadline, Numeric, Time, nil] when given, calls {#arm} immediately
+      def initialize(deadline = nil)
+        super()
+        @token = CancellationToken.new
+        @read_io = nil
+        @write_io = nil
+        @timer = nil
+        @closed = false
+        @io_mutex = Mutex.new
+        arm(deadline) if deadline
+      end
+
+      # @return [::IO] readable end of the wakeup pipe (creates the pipe lazily)
+      def read_io
+        ensure_pipe
+        @read_io
+      end
+
+      # @return [::IO] writable end used internally to signal readiness
+      def write_io
+        ensure_pipe
+        @write_io
+      end
+
+      # @return [Boolean] +true+ after {#close}
+      def closed?
+        @io_mutex.synchronize { @closed }
+      end
+
+      # Arms a background timer that invokes {#cancel!} with +:timeout+ when the
+      # deadline elapses.
+      #
+      # @param deadline [Deadline, Numeric, Time, nil]
+      # @return [void]
+      # @raise [TIMEx::Error] when the instance was already closed
+      def arm(deadline)
+        raise TIMEx::Error, "Wakeup is single-use; construct a fresh instance" if closed?
+
+        deadline = Deadline.coerce(deadline)
+        return if deadline.infinite?
+
+        ensure_pipe
+        @timer = Thread.new do
+          remaining = deadline.remaining
+          ::Kernel.sleep(remaining) if remaining.positive?
+          fire(reason: :timeout)
+        end
+      end
+
+      # Cancels observers and wakes blocked readers.
+      #
+      # @param reason [Symbol] opaque reason forwarded to {CancellationToken#cancel}
+      # @return [Boolean, nil] result of the internal fire sequence
+      def cancel!(reason: :user)
+        fire(reason:)
+      end
+
+      # @return [Boolean] whether {#cancel!} / timeout has fired
+      def fired?
+        @token.cancelled?
+      end
+
+      # Idempotently closes pipe ends and stops the timer thread.
+      #
+      # @return [void]
+      def close
+        @timer&.kill
+        @io_mutex.synchronize do
+          return if @closed
+
+          @read_io.close if @read_io && !@read_io.closed?
+          @write_io.close if @write_io && !@write_io.closed?
+          @closed = true
+        end
+      end
+
+      protected
+
+      # @param deadline [Deadline]
+      # @yieldparam deadline [Deadline]
+      # @return [Object]
+      # @raise [TIMEx::Error] when reused after {#close}
+      def run(deadline)
+        raise TIMEx::Error, "Wakeup is single-use; construct a fresh instance" if closed?
+
+        arm(deadline) unless @timer
+        yield(deadline)
+      ensure
+        close
+      end
+
+      private
+
+      # @return [void]
+      def ensure_pipe
+        @io_mutex.synchronize do
+          raise TIMEx::Error, "Wakeup is single-use; construct a fresh instance" if @closed
+          return if @read_io
+
+          @read_io, @write_io = ::IO.pipe
+        end
+      end
+
+      # @param reason [Symbol]
+      # @return [void]
+      def fire(reason:)
+        return unless @token.cancel(reason:)
+
+        # Kill the sleeping timer if we were the first to win the race so the
+        # thread doesn't dangle in `Kernel.sleep` and write to a closed pipe.
+        if @timer && reason != :timeout && @timer.alive?
+          begin
+            @timer.kill
+          rescue StandardError
+            nil
+          end
+        end
+
+        return unless @write_io
+
+        begin
+          @write_io.write_nonblock("!")
+        rescue StandardError
+          nil
+        end
+      end
+
+    end
+  end
+end
+
+TIMEx::Registry.register(:wakeup, TIMEx::Strategies::Wakeup)

data/lib/timex/telemetry/adapters.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module TIMEx
+  module Telemetry
+    # Concrete {Telemetry} backends. All adapters receive symbol/string event names
+    # and a mutable +payload+ hash for a single logical operation.
+    #
+    # @see Telemetry.instrument
+    # @see Telemetry.emit
+    module Adapters
+
+      # No-op base type documenting the adapter protocol.
+      class Base
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def start(event:, payload:); end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def finish(event:, payload:); end
+
+        # Default one-shot implementation pairing {#start} and {#finish}.
+        #
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def emit(event:, payload:)
+          start(event:, payload:)
+          finish(event:, payload:)
+        end
+
+      end
+
+      # Sentinel adapter used when nothing is configured.
+      class Null < Base; end
+
+      # Emits a single structured log line per {#finish} with a conservative key allowlist.
+      class Logger < Base
+
+        # Keys considered safe to log by default. Application-supplied data
+        # like `headers` or block arguments are excluded to avoid leaking
+        # secrets/PII through structured logs. `origin` is whitelisted
+        # because {Deadline.from_header} enforces `ORIGIN_PATTERN` so the
+        # value can only be `[A-Za-z0-9_.-]+`. Pass `extra_keys:` to include
+        # additional whitelisted keys.
+        DEFAULT_SAFE_KEYS = %i[event strategy outcome deadline_ms elapsed_ms error_class
+                               soft_ms grace_ms estimate_ms budget_ms
+                               soft_timeout hard_timeout depth skew_ms origin
+                               reason].freeze
+
+        # @param logger [#info] logger receiving +#info+ calls
+        # @param extra_keys [Array<Symbol, String>] additional payload keys to include
+        def initialize(logger, extra_keys: [])
+          super()
+          @logger    = logger
+          @safe_keys = (DEFAULT_SAFE_KEYS + Array(extra_keys).map(&:to_sym)).uniq.freeze
+        end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def finish(event:, payload:)
+          @logger.info("[timex] #{event} #{filtered(payload).inspect}")
+        end
+
+        private
+
+        # @param payload [Hash{Symbol => Object}]
+        # @return [Hash{Symbol => Object}]
+        def filtered(payload)
+          payload.each_with_object({}) do |(k, v), acc|
+            acc[k] = v if @safe_keys.include?(k)
+          end
+        end
+
+      end
+
+      # Bridges TIMEx events to +ActiveSupport::Notifications+.
+      class ActiveSupportNotifications < Base
+
+        EVENT_PREFIX = "timex."
+
+        def initialize
+          super
+          require "active_support/notifications"
+        end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def start(event:, payload:)
+          instrumenter = ::ActiveSupport::Notifications.instrumenter
+          payload[:__asn_token] = instrumenter.start("#{EVENT_PREFIX}#{event}", payload)
+        end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def finish(event:, payload:)
+          token = payload.delete(:__asn_token)
+          return unless token
+
+          ::ActiveSupport::Notifications.instrumenter.finish_with_state(token, "#{EVENT_PREFIX}#{event}", payload)
+        end
+
+      end
+
+      # Bridges TIMEx spans to OpenTelemetry when the gem is available.
+      class OpenTelemetry < Base
+
+        ATTRIBUTE_TYPES = [String, Symbol, Numeric, TrueClass, FalseClass, NilClass].freeze
+
+        def initialize
+          super
+          require "opentelemetry/api"
+        end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def start(event:, payload:)
+          tracer = ::OpenTelemetry.tracer_provider.tracer("timex")
+          payload[:__otel_span] = tracer.start_span(
+            event,
+            attributes: coerce_attributes(payload)
+          )
+        end
+
+        # @param event [Symbol, String]
+        # @param payload [Hash{Symbol => Object}]
+        # @return [void]
+        def finish(event:, payload:)
+          span = payload.delete(:__otel_span)
+          return unless span
+
+          span.set_attribute("timex.elapsed_ms", payload[:elapsed_ms]) if payload[:elapsed_ms] && span.respond_to?(:set_attribute)
+
+          if span.respond_to?(:status=)
+            case payload[:outcome]
+            when :timeout
+              span.status = ::OpenTelemetry::Trace::Status.error("timeout")
+            when :error
+              span.status = ::OpenTelemetry::Trace::Status.error(payload[:error_class].to_s)
+            end
+          end
+
+          span.finish
+        end
+
+        private
+
+        # Drops keys with nested or non-OTel-supported values rather than
+        # lossy `to_s`-ifying everything.
+        #
+        # @param payload [Hash{Symbol => Object}]
+        # @return [Hash{String => Object}]
+        def coerce_attributes(payload)
+          payload.each_with_object({}) do |(k, v), acc|
+            next if k.to_s.start_with?("__")
+            next unless ATTRIBUTE_TYPES.any? { |t| v.is_a?(t) }
+
+            acc[k.to_s] = v.is_a?(Symbol) ? v.to_s : v
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/timex/telemetry.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Lightweight instrumentation facade for strategies, composers, and internal
+  # events (deadline skew, cancellation observer errors, etc.).
+  #
+  # Resolution order for {#adapter}: explicit {Telemetry.adapter=} assignment,
+  # then {Configuration#telemetry_adapter}, then {Adapters::Null}.
+  #
+  # @see Telemetry::Adapters
+  # @see Configuration#telemetry_adapter=
+  module Telemetry
+
+    @adapter = nil
+    @null_adapter = nil
+    @strict = false
+
+    extend self
+
+    # Resolves the active adapter on each access so runtime config changes apply.
+    #
+    # @return [#emit, #start, #finish] concrete adapter instance
+    def adapter
+      return @adapter if @adapter
+
+      TIMEx.config.telemetry_adapter || (@null_adapter ||= Adapters::Null.new)
+    end
+
+    # Forces a specific adapter (overrides {Configuration#telemetry_adapter} until cleared).
+    #
+    # @param value [#emit, #start, #finish, nil]
+    # @return [#emit, #start, #finish, nil]
+    def adapter=(value)
+      @adapter = value
+    end
+
+    # When +true+, adapter errors propagate instead of being swallowed by {#instrument} / {#emit}.
+    #
+    # @return [Boolean]
+    attr_accessor :strict
+
+    # Clears memoized adapter state and resets {#strict} to +false+.
+    #
+    # @return [void]
+    def reset!
+      @adapter = nil
+      @null_adapter = nil
+      @strict = false
+    end
+
+    # @return [Boolean] +true+ when the resolved adapter is {Adapters::Null}
+    #
+    # @note Lets hot paths skip kwarg-heavy instrumentation when telemetry is disabled.
+    def null_adapter?
+      adapter.is_a?(Adapters::Null)
+    end
+
+    # Emits a one-shot event (no span pairing).
+    #
+    # @param event [Symbol, String] logical event name
+    # @param payload [Hash{Symbol => Object}] structured attributes
+    # @return [void]
+    def emit(event:, **payload)
+      a = adapter
+      return if a.is_a?(Adapters::Null)
+
+      safely { a.emit(event:, payload:) }
+    end
+
+    # Wraps a block with +start+ / +finish+ callbacks and elapsed timing in +payload+.
+    #
+    # @param event [Symbol, String] logical event name
+    # @param base_payload [Hash{Symbol => Object}] initial payload (mutated; see @note)
+    # @yieldparam payload [Hash{Symbol => Object}] same object passed to the adapter
+    # @return [Object] the block's return value
+    #
+    # @note Mutates +base_payload+ in place to avoid per-call +dup+ on the hot path.
+    def instrument(event:, **base_payload)
+      a = adapter
+      return yield(base_payload) if a.is_a?(Adapters::Null)
+
+      # `base_payload` is a fresh hash from the kwarg splat at the call site;
+      # the caller can't observe our mutations, so we skip the defensive dup
+      # to save an allocation per instrumented call.
+      payload = base_payload
+      started_ns = Clock.monotonic_ns
+      safely { a.start(event:, payload:) }
+      begin
+        result = yield(payload)
+        payload[:outcome] ||= :ok
+        result
+      rescue StandardError, Expired => e
+        payload[:outcome] ||= e.is_a?(Expired) ? :timeout : :error
+        payload[:error_class] = e.class.name unless e.is_a?(Expired)
+        raise
+      end
+    ensure
+      if started_ns
+        payload[:elapsed_ms] = (Clock.monotonic_ns - started_ns) / 1_000_000.0
+        safely { a.finish(event:, payload:) }
+      end
+    end
+
+    private
+
+    # @yield adapter callback
+    # @return [Object, nil]
+    def safely
+      yield
+    rescue StandardError
+      raise if @strict
+
+      nil
+    end
+
+  end
+end
+
+require_relative "telemetry/adapters"

data/lib/timex/test/virtual_clock.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Test helpers for controlling TIMEx time without real sleeps.
+  #
+  # Installs a {Clock::VirtualClock} on the current thread and exposes helpers to
+  # advance it from nested code.
+  #
+  # @see Clock::VirtualClock
+  module Test
+
+    extend self
+
+    # Installs a {Clock::VirtualClock} for the block and yields it for manual control.
+    #
+    # @param start_ns [Integer] initial monotonic nanoseconds for the virtual clock
+    # @yieldparam clock [Clock::VirtualClock] the installed virtual clock
+    # @return [Object] the block's return value
+    #
+    # @note Also sets +:timex_test_clock+ so {.advance} can find the active clock
+    #   without threading the object through call sites.
+    def with_virtual_clock(start_ns: 0)
+      previous_clock = Thread.current.thread_variable_get(:timex_clock)
+      previous_test_clock = Thread.current.thread_variable_get(:timex_test_clock)
+      clock = Clock::VirtualClock.new(monotonic_ns: start_ns)
+      Thread.current.thread_variable_set(:timex_clock, clock)
+      Thread.current.thread_variable_set(:timex_test_clock, clock)
+      yield clock
+    ensure
+      Thread.current.thread_variable_set(:timex_clock, previous_clock)
+      Thread.current.thread_variable_set(:timex_test_clock, previous_test_clock)
+    end
+
+    # Advances the active {Clock::VirtualClock} by +seconds+.
+    #
+    # @param seconds [Numeric] delta in seconds
+    # @return [Clock::VirtualClock] the advanced clock
+    # @raise [RuntimeError] when called outside {.with_virtual_clock}
+    def advance(seconds)
+      clock = Thread.current.thread_variable_get(:timex_test_clock) ||
+              raise("call inside TIMEx::Test.with_virtual_clock { ... }")
+      clock.advance(seconds)
+    end
+
+    # @see .with_virtual_clock
+    def freeze_time(&)
+      with_virtual_clock(&)
+    end
+
+  end
+end

data/lib/timex/timeout_handling.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Shared +on_timeout:+ dispatcher included by strategies and composers.
+  #
+  # Centralizes semantics for +:raise+, +:raise_standard+, +:return_nil+,
+  # +:result+, and custom +Proc+ handlers so layers cannot drift.
+  #
+  # @see ON_TIMEOUT_SYMBOLS
+  # @see Expired
+  # @see Result.timeout
+  module TimeoutHandling
+
+    private
+
+    # Dispatches an {Expired} according to +on_timeout+.
+    #
+    # @param on_timeout [Symbol, Proc] mode or custom handler
+    # @param expired [Expired] the deadline exception
+    # @return [Object, nil] handler return value; may raise
+    # @raise [Expired] when +on_timeout == :raise+
+    # @raise [TimeoutError] when +on_timeout == :raise_standard+
+    # @raise [ArgumentError] when +on_timeout+ is unknown
+    def handle_timeout(on_timeout, expired)
+      case on_timeout
+      when :raise then raise expired
+      when :raise_standard then raise TimeoutError.from(expired)
+      when :return_nil then nil
+      when :result then Result.timeout(strategy: self.class.name_symbol, expired:)
+      when Proc then on_timeout.call(expired)
+      else
+        raise ArgumentError,
+          "unknown on_timeout: #{on_timeout.inspect} " \
+          "(expected one of #{ON_TIMEOUT_SYMBOLS.inspect}, or a Proc)"
+      end
+    end
+
+  end
+end

data/lib/timex/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TIMEx
+
+  # Gem version. Bumped on release; mirrored in the gemspec.
+  VERSION = "0.1.0"
+
+end

data/lib/timex.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module TIMEx
+
+  Error = Class.new(StandardError)
+  ConfigurationError = Class.new(Error)
+  StrategyNotFoundError = Class.new(Error)
+
+  extend self
+
+  # Primary entrypoint: runs +block+ under +deadline_or_seconds+ using the resolved strategy.
+  #
+  # @param deadline_or_seconds [Deadline, Numeric, Time, nil] budget or deadline
+  # @param strategy [Symbol, #call, nil] registered key, callable, or +nil+ for default
+  # @param auto_check [Boolean, nil] +nil+ uses {Configuration#auto_check_default}
+  # @param on_timeout [Symbol, Proc, nil] +nil+ uses {Configuration#default_on_timeout}
+  # @param opts [Hash{Symbol => Object}] forwarded to the strategy +#call+
+  # @yieldparam deadline [Deadline] coerced deadline passed to the inner block
+  # @return [Object] strategy/composer result (including timeout handler results)
+  # @raise [ArgumentError] when no block is given
+  def call(deadline_or_seconds, strategy: nil, auto_check: nil, on_timeout: nil, **opts, &block)
+    raise ArgumentError, "block required" unless block
+
+    deadline = Deadline.coerce(deadline_or_seconds)
+    strategy = Registry.resolve_for_call(strategy)
+    cfg = config
+    on_timeout ||= cfg.default_on_timeout
+    auto_check = cfg.auto_check_default if auto_check.nil?
+    runner =
+      if auto_check
+        ->(d) { TIMEx::AutoCheck.run(d) { yield(d) } }
+      else
+        block
+      end
+
+    strategy.call(
+      deadline:,
+      on_timeout:,
+      **opts,
+      &runner
+    )
+  end
+  alias deadline call
+
+end
+
+require_relative "timex/version"
+require_relative "timex/on_timeout"
+require_relative "timex/named_component"
+require_relative "timex/expired"
+require_relative "timex/configuration"
+require_relative "timex/clock"
+require_relative "timex/telemetry"
+require_relative "timex/deadline"
+require_relative "timex/result"
+require_relative "timex/cancellation_token"
+require_relative "timex/registry"
+require_relative "timex/timeout_handling"
+require_relative "timex/strategies/base"
+require_relative "timex/strategies/cooperative"
+require_relative "timex/strategies/io"
+require_relative "timex/strategies/unsafe"
+require_relative "timex/strategies/wakeup"
+require_relative "timex/strategies/closeable"
+require_relative "timex/strategies/subprocess"
+require_relative "timex/strategies/ractor"
+require_relative "timex/composers/base"
+require_relative "timex/composers/two_phase"
+require_relative "timex/composers/hedged"
+require_relative "timex/composers/adaptive"
+require_relative "timex/auto_check"
+require_relative "timex/propagation/http_header"
+require_relative "timex/propagation/rack_middleware"
+require_relative "timex/test/virtual_clock"
+
+require_relative "generators/timex/install_generator" if defined?(Rails::Generators)
+
+# Rails integration is opt-in via the install generator initializer; a Railtie
+# hook is not loaded from this file to keep the core gem free of Rails deps.