timex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 004cb51ebbe6c5acb07cf3085e0fec11a544a2d6eb29a953ff897b37727051bf
+  data.tar.gz: ead577ccb6e1a5cc28c99619afa6c074bb76f6345340edd4aba4ee5162d81a80
+SHA512:
+  metadata.gz: a05964e1431ce5fc7e1b78a722dcd51cf0beacc746ab8637178d545a57e5e8fcb32d1317330c12f45a62deb40b5ac64ccb0368b893abf6ec7e271f628d762124
+  data.tar.gz: 7d68892730d9a424c0213617be0e06d04bdf25481bb431e545058703b84b2b716092482e030ee5d25d71a3629cb4d35a6fdf2307ed5f66b54b60ee5e3f571635

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - UNRELEASED
+
+### Added
+
+- Init commit

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,4 @@
+Copyright (c) Drexed
+
+CMDx is an Open Source project licensed under the terms of the LGPLv3 license.
+Please see <http://www.gnu.org/licenses/lgpl-3.0.html> for license text.

data/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+  <img src="./src/timex-light-logo.png#gh-light-mode-only" width="200" alt="TIMEx Light Logo">
+  <img src="./src/timex-dark-logo.png#gh-dark-mode-only" width="200" alt="TIMEx Dark Logo">
+
+  ---
+
+  Deadlines, budgets, and cancellation you can reason about in production.
+
+  [Home](https://drexed.github.io/timex) ·
+  [Documentation](https://drexed.github.io/timex/getting_started) ·
+  [Blog](https://drexed.github.io/timex/blog) ·
+  [Changelog](./CHANGELOG.md) ·
+  [Report Bug](https://github.com/drexed/timex/issues) ·
+  [Request Feature](https://github.com/drexed/timex/issues) ·
+  [AI Skills](https://github.com/drexed/timex/blob/main/skills) ·
+  [llms.txt](https://drexed.github.io/timex/llms.txt) ·
+  [llms-full.txt](https://drexed.github.io/timex/llms-full.txt)
+
+  <img alt="Version" src="https://img.shields.io/gem/v/timex">
+  <img alt="Build" src="https://github.com/drexed/timex/actions/workflows/ci.yml/badge.svg">
+  <img alt="License" src="https://img.shields.io/badge/license-LGPL%20v3-blue.svg">
+</div>
+
+# TIMEx
+
+TIMEx is a **deadline engine** for Ruby: one facade runs your code under a `Deadline`, picks an execution strategy (cooperative checks, thread wakeup, IO deadlines, subprocesses, and more), and routes expiry through consistent `on_timeout` semantics—without pulling in a framework.
+
+> [!NOTE]
+> [Documentation](https://drexed.github.io/timex/getting_started/) reflects the latest code on `main`. For version-specific documentation, refer to the `docs/` directory within that version's tag.
+
+## What you get
+
+- **`TIMEx.deadline` / `TIMEx.call`** — single entrypoint with `strategy:`, `on_timeout:`, `auto_check:`, and strategy-specific options
+- **`Deadline`** — monotonic + wall alignment, narrowing (`#min`), skew-aware header encoding (`X-TIMEx-Deadline`)
+- **Strategies** — `:cooperative`, `:unsafe`, `:io`, `:wakeup`, `:subprocess`, `:closeable`, `:ractor` (when `Ractor` is defined), each registered on `TIMEx::Registry`
+- **Composers** — `TwoPhase`, `Hedged`, `Adaptive` for multi-attempt and staged execution
+- **`on_timeout`** — `:raise` (default), `:raise_standard`, `:return_nil`, `:result`, or a custom `Proc` with shared dispatch in `TimeoutHandling`
+- **`Result`** — discriminated `:ok` / `:timeout` / `:error` outcomes when you opt out of raising
+- **Propagation** — `Deadline#to_header` / `Deadline.from_header` plus optional Rack middleware for cross-service budgets
+- **Telemetry & clocks** — pluggable `Telemetry.adapter`, injectable monotonic/wall `Clock`, and `TIMEx::Test::VirtualClock` for tests
+- **Rails (opt-in)** — install generator adds initializer hooks without loading Rails from the core require
+
+See the [feature comparison](https://drexed.github.io/timex/comparison/) for how TIMEx compares to `Timeout.timeout` and other patterns.
+
+## Requirements
+
+- Ruby: MRI 3.3+ or a compatible JRuby/TruffleRuby release
+- Runtime dependencies: none beyond the standard library (no ActiveSupport required)
+
+Rails middleware and generators load only when you opt in after `bundle install`.
+
+## Installation
+
+```sh
+gem install timex
+# - or -
+bundle add timex
+```
+
+## Quick example
+
+### 1. Budget
+
+Pass seconds, a `Deadline`, or `nil` for an infinite budget. The block receives a frozen `Deadline` you can thread through helpers.
+
+```ruby
+deadline = TIMEx::Deadline.in(2.5)
+TIMEx.deadline(deadline) { |d| process!(d) }
+```
+
+### 2. Run
+
+The default `:cooperative` strategy runs your block and performs a final `check!` so CPU-bound work still observes expiry at cooperative points.
+
+```ruby
+TIMEx.deadline(1.0) do |deadline|
+  rows = fetch_rows
+  deadline.check!
+  summarize(rows)
+end
+```
+
+### 3. On expiry
+
+Override per call or via `TIMEx.configure`. Use `:result` when you want a `TIMEx::Result` instead of an exception.
+
+```ruby
+outcome = TIMEx.deadline(0.01, on_timeout: :result, strategy: :unsafe) do
+  sleep 5 # interrupted when the budget is exhausted
+end
+
+outcome.timeout? # => true
+```
+
+### 4. Propagate
+
+Serialize remaining budget into an outbound request so downstream services share the same cap.
+
+```ruby
+req["X-TIMEx-Deadline"] = TIMEx::Deadline.in(3.0).to_header
+# or use TIMEx::Propagation::RackMiddleware on the server (see docs)
+```
+
+Ready to go deeper? Start with [Getting Started](https://drexed.github.io/timex/getting_started/) and [Migrating from stdlib `Timeout`](https://drexed.github.io/timex/migrating_from_stdlib_timeout/).
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/drexed/timex>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [LGPLv3 License](https://www.gnu.org/licenses/lgpl-3.0.html).

data/Rakefile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+desc "Generate YARD API documentation"
+task :yard do
+  require "yard"
+  require "fileutils"
+
+  YARD::CLI::Yardoc.run(*File.readlines(".yardopts", chomp: true).reject(&:empty?))
+
+  api_dir = "docs/api"
+
+  # Remove unwanted files
+  FileUtils.rm_f("#{api_dir}/Timex_.html")
+
+  # Make TIMEx.html the default index
+  FileUtils.cp("#{api_dir}/TIMEx.html", "#{api_dir}/index.html") if File.exist?("#{api_dir}/TIMEx.html")
+end
+
+task default: %i[spec rubocop]

data/lib/generators/timex/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Rails generator namespace is +Timex+ (not +TIMEx+) to follow Rails::Generators
+# naming conventions and avoid constant clashes with the +TIMEx+ library module.
+module Timex
+  # Copies the TIMEx initializer template into the host application.
+  #
+  # @see Rails::Generators::Base
+  class InstallGenerator < Rails::Generators::Base
+
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates TIMEx initializer with global configuration settings"
+
+    # @return [void]
+    def copy_initializer_file
+      copy_file("install.rb", "config/initializers/timex.rb")
+    end
+
+  end
+end

data/lib/generators/timex/templates/install.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+#
+# TIMEx global defaults for this Rails app. Edit and uncomment options as needed.
+# Full reference: https://drexed.github.io/timex/configuration
+
+TIMEx.configure do |c|
+  # ===========================================================================
+  # Default strategy
+  # ===========================================================================
+  # Registry name passed to strategies when +strategy:+ is omitted on
+  # +TIMEx.deadline+ (e.g. +:cooperative+, +:io+, +:unsafe+).
+  #
+  # c.default_strategy = :cooperative
+
+  # ===========================================================================
+  # On timeout
+  # ===========================================================================
+  # +:raise+, +:return_nil+, +:result+, or a +Proc+ invoked with the exception.
+  #
+  # c.default_on_timeout = :raise
+
+  # ===========================================================================
+  # Auto-check (TracePoint)
+  # ===========================================================================
+  # When +true+, +TIMEx.deadline+ behaves like +auto_check: true+ unless overridden
+  # per call. +auto_check_interval+ is VM events between deadline polls.
+  #
+  # c.auto_check_default = false
+  # c.auto_check_interval = 1_000
+
+  # ===========================================================================
+  # Telemetry
+  # ===========================================================================
+  # +nil+ uses the built-in null adapter. In Rails you often wire Logger or
+  # Active Support Notifications — see docs/telemetry.md.
+  #
+  # c.telemetry_adapter = TIMEx::Telemetry::Adapters::Logger.new(Rails.logger)
+  # c.telemetry_adapter = TIMEx::Telemetry::Adapters::ActiveSupportNotifications.new
+
+  # ===========================================================================
+  # Clock
+  # ===========================================================================
+  # Override monotonic/wall time sources (tests, virtual clocks).
+  #
+  # c.clock = nil
+
+  # ===========================================================================
+  # Deadline header skew
+  # ===========================================================================
+  # Milliseconds of tolerated wall-clock drift when parsing propagated headers.
+  #
+  # c.skew_tolerance_ms = 250
+end

data/lib/timex/auto_check.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Best-effort cooperative deadline checks driven by +TracePoint+ (+:line+ and
+  # +:b_return+). Injects periodic {#Deadline#check!} calls without requiring manual
+  # probes inside the block.
+  #
+  # @note +:line+ events are expensive; expect noticeable overhead on tight loops.
+  #   Prefer explicit {#Deadline#check!} for hot paths.
+  #
+  # @note TracePoint does not fire inside C-native methods (+Mutex#synchronize+,
+  #   blocking +IO+, etc.); pair with an IO-aware strategy for those regions.
+  #
+  # @note Only +target_thread:+ is traced; child threads need their own setup or
+  #   explicit deadline checks.
+  #
+  # @see Strategies::Cooperative
+  # @see Configuration#auto_check_interval
+  module AutoCheck
+
+    # Only Ruby-level events: +:line+ already polls between every Ruby
+    # statement, and +:b_return+ adds coverage at block boundaries so we
+    # interrupt promptly between iterations. +:c_return+ was tempting but
+    # fires on every C method return (Hash#[], String#+, …) — the dispatch
+    # cost dwarfs the latency win on any non-trivial loop body.
+    EVENTS = %i[line b_return].freeze
+
+    extend self
+
+    # Runs +block+ with TracePoint-driven deadline checks every +interval+ Ruby events.
+    #
+    # @param deadline [Deadline]
+    # @param interval [Integer] line/block events between checks (from config by default)
+    # @yieldparam deadline [Deadline]
+    # @return [Object] the block's return value
+    # @raise [Expired] when the deadline elapses between checks
+    def run(deadline, interval: TIMEx.config.auto_check_interval)
+      return yield(deadline) if deadline.infinite?
+
+      counter = 0
+      tp = TracePoint.new(*EVENTS) do |_event|
+        counter += 1
+        next unless counter >= interval
+
+        counter = 0
+        next if Thread.current.thread_variable_get(:timex_shielded)
+        next unless deadline.expired?
+
+        tp.disable
+        deadline.check!(strategy: :cooperative)
+      end
+
+      tp.enable(target_thread: Thread.current) do
+        yield(deadline)
+      end
+    end
+
+  end
+end

data/lib/timex/cancellation_token.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Thread-safe manual cancellation signal for long-running or hedged work.
+  #
+  # Observers registered via {#on_cancel} run outside the mutex after the
+  # transition to cancelled; observer exceptions are swallowed and reported
+  # through {Telemetry}.
+  #
+  # @see Telemetry.emit
+  class CancellationToken
+
+    # @return [void]
+    def initialize
+      @mutex = Mutex.new
+      @cancelled = false
+      @reason = nil
+      @observers = []
+    end
+
+    # @return [Boolean] +true+ after {#cancel} succeeds
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    attr_reader :reason
+
+    # Marks the token cancelled and notifies observers (once).
+    #
+    # @param reason [Object, nil] opaque payload passed to observers
+    # @return [Boolean] +true+ when this call performed the transition, +false+ if already cancelled
+    def cancel(reason: nil) # rubocop:disable Naming/PredicateMethod
+      observers_to_notify = nil
+      @mutex.synchronize do
+        return false if @cancelled
+
+        @cancelled = true
+        @reason = reason
+        observers_to_notify = @observers.dup
+      end
+      observers_to_notify.each { |o| safe_call(o, reason) }
+      true
+    end
+
+    # Registers a callback invoked on cancellation (immediately if already cancelled).
+    #
+    # @yield [reason] invoked when cancelled
+    # @yieldparam reason [Object, nil] the reason passed to {#cancel}
+    # @return [self] for chaining
+    def on_cancel(&block)
+      fire_now = false
+      @mutex.synchronize do
+        if @cancelled
+          fire_now = true
+        else
+          @observers << block
+        end
+      end
+      safe_call(block, @reason) if fire_now
+      self
+    end
+
+    private
+
+    # @param observer [Proc, #call]
+    # @param reason [Object, nil]
+    # @return [void]
+    def safe_call(observer, reason)
+      observer.call(reason)
+    rescue StandardError => e
+      # Observers must not break the cancellation chain. Surface the failure
+      # via telemetry so it's debuggable instead of vanishing.
+      begin
+        TIMEx::Telemetry.emit(
+          event: "cancellation.observer_error",
+          error_class: e.class.name
+        )
+      rescue StandardError
+        nil
+      end
+    end
+
+  end
+end

data/lib/timex/clock.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module TIMEx
+  # Thread-scoped clock abstraction for monotonic and wall time in nanoseconds.
+  #
+  # Production code reads {RealClock} unless {TIMEx::Configuration#clock=} or
+  # {TIMEx::Test.with_virtual_clock} overrides the current binding via
+  # +thread_variable_*+ (not fiber-local storage).
+  #
+  # @note Uses +Thread.current.thread_variable_get/set(:timex_clock)+ so every fiber
+  #   in a thread shares one clock context (deadline shielding, {AutoCheck}, tests).
+  #
+  # @see TIMEx::Configuration#clock=
+  # @see TIMEx::Test.with_virtual_clock
+  module Clock
+
+    NS_PER_SECOND = 1_000_000_000
+
+    extend self
+
+    # @return [Integer] monotonic time in nanoseconds from the active clock
+    def monotonic_ns
+      current.monotonic_ns
+    end
+
+    # @return [Integer] wall-clock time in nanoseconds from the active clock
+    def wall_ns
+      current.wall_ns
+    end
+
+    # @return [Float] monotonic time expressed in fractional seconds
+    def now_seconds
+      monotonic_ns / NS_PER_SECOND.to_f
+    end
+
+    # Returns the clock object consulted by {.monotonic_ns} and {.wall_ns}.
+    #
+    # @return [#monotonic_ns, #wall_ns] {RealClock}, {VirtualClock}, or a custom clock
+    def current
+      Thread.current.thread_variable_get(:timex_clock) || TIMEx.config.clock || RealClock
+    end
+
+    # Binds +clock+ for the duration of the block on the current thread.
+    #
+    # @param clock [#monotonic_ns, #wall_ns] clock implementation to install
+    # @yield runs with the thread-local clock swapped
+    # @return [Object] the block's return value
+    def with(clock)
+      previous = Thread.current.thread_variable_get(:timex_clock)
+      Thread.current.thread_variable_set(:timex_clock, clock)
+      yield
+    ensure
+      Thread.current.thread_variable_set(:timex_clock, previous)
+    end
+
+    # Default clock backed by the process monotonic and realtime clocks.
+    module RealClock
+
+      extend self
+
+      # @return [Integer] nanoseconds from +CLOCK_MONOTONIC+
+      def monotonic_ns
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      end
+
+      # @return [Integer] nanoseconds from +CLOCK_REALTIME+
+      def wall_ns
+        Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      end
+
+      # Sleeps the OS scheduler for up to +seconds+ (no-op when non-positive).
+      #
+      # @param seconds [Numeric] duration in seconds
+      # @return [void]
+      def sleep(seconds)
+        Kernel.sleep(seconds) if seconds.positive?
+      end
+
+    end
+
+    # Mutable monotonic/wall pair used in tests to advance time without sleeping.
+    class VirtualClock
+
+      attr_accessor :monotonic_ns, :wall_ns
+
+      # @param monotonic_ns [Integer] starting monotonic nanoseconds
+      # @param wall_ns [Integer] starting wall nanoseconds (defaults to realtime now)
+      def initialize(monotonic_ns: 0, wall_ns: Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond))
+        @monotonic_ns = monotonic_ns
+        @wall_ns = wall_ns
+      end
+
+      # Advances both monotonic and wall by +seconds+ (no sleep).
+      #
+      # @param seconds [Numeric] delta in seconds
+      # @return [self] for chaining
+      def advance(seconds)
+        delta = (seconds * Clock::NS_PER_SECOND).to_i
+        @monotonic_ns += delta
+        @wall_ns += delta
+        self
+      end
+
+      # @param seconds [Numeric] virtual sleep; advances clocks like {.advance}
+      # @return [self] for chaining
+      def sleep(seconds)
+        advance(seconds)
+      end
+
+    end
+
+  end
+end