track_ballast 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e862c2e25e1e2fcd384d009cefe352c350914732709276274e5013254e58296
-  data.tar.gz: debd71ea18ded7b48e053473fe1cd516bbe82658dcf30407dcfb93437a021193
+  metadata.gz: 4595b4b0cb3973ed3cb28bcdf309fda53718f628b0f8042f319224acf7a30f76
+  data.tar.gz: b76c47871cb4974015cb7d580698296368f10325ad54c36a03736d1cb2f40e10
 SHA512:
-  metadata.gz: '09f2866179582e548cba5e16a5a8afb06942abbe10b891626bb2f1dd1f1d87ba3cce5a1e1d596d8f95bd9b7b8494bad67d45c51d3f0151e30b5b782d6f899048'
-  data.tar.gz: 210396ca3d3d363dc47529d7fe0c3c54f48995c6d21725a26116c741f0b4ded76c61f5e564443ec6a402144fcacb46cf08588d6f1d61e8ffa6c95aba47f2da81
+  metadata.gz: a4494a7b7941ae681e77a0d3c4a12dc31fc49c2a7a60bb5e7d02fafd793de57da2544cc8aca5fdd5982d3195f289e740622f638d91ed334d1e4ed9b948b386b7
+  data.tar.gz: 8e17fdf3a516d75234438f103273bc227e1e45f9b742d635807e4618c22053d6ea276563cfd30215555dbd7cc53ee1a4f98c117f3f6dc46947bac4cf544e31c3

data/.circleci/config.yml

@@ -16,7 +16,11 @@ executors:
         default: 3.2.2
     resource_class: small
     docker:
-    - image: cimg/ruby:<< parameters.ruby-version >>
+      - image: cimg/ruby:<< parameters.ruby-version >>
+        environment:
+          REDIS_URL: redis://localhost:6379
+          BUNDLE_VERSION: 2.5.5
+      - image: cimg/redis:6.2
 
 commands:
   bundle_install:
@@ -70,6 +74,12 @@ commands:
               read -r target_gemname target_version \<<< $( echo "<< parameters.gem-version >>" | sed 's/\(.*\)-\([0-9]\{1,3\}\(\.[0-9]\{1,3\}\)*\)/\1 \2/g')
               gem install $target_gemname -i /tmp/repo --no-document -v $target_version
 
+              # Install sqlite3 2.1.0 if we're using Rails 8
+              if [[ "$target_gemname" = "rails" && "$target_version" =~ ^8\. ]]; then
+                echo "Detected Rails 8.x, installing sqlite3 2.1.0"
+                gem install sqlite3 -i /tmp/repo --no-document -v 2.1.0
+              fi
+
               echo 'Delete any gems matching the newly installed ones from the existing cache'
               for line in $(ls /tmp/repo/cache | grep gem); do
                 read -r gemname version \<<< $( echo $line | sed 's/\(.*\)-\([0-9]\{1,3\}\(\.[0-9]\{1,3\}\)*\)[^0-9\.]*.*.gem/\1 \2/g')
@@ -224,12 +234,10 @@ workflows:
               path: tmp/test-results
         matrix:
           parameters:
-            ruby-version:
-            - '3.0'
-            - '3.1'
-            - '3.2'
-            - '3.3'
-            gem-version:
-            - rails-6.1.7
-            - rails-7.0.8
-            - rails-7.1.3
+            ruby-version: ['3.0', '3.1', '3.2', '3.3']
+            gem-version: ['rails-7.0.8', 'rails-7.1.3', 'rails-8.0.2']
+          exclude:
+            - ruby-version: '3.0'
+              gem-version: 'rails-8.0.2'
+            - ruby-version: '3.1'
+              gem-version: 'rails-8.0.2'

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+## 0.3.0
+
+* Added support for Rails 8
+* Updated ActiveRecord and ActiveSupport dependencies to support Rails 7.0 - 8.x
+
+## 0.2.0
+
+* Added `redis` dependency
+* Added `TrackBallast.redis`
+* Added `StopSignal`
+
 ## 0.1.0
 
 * First external release

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    track_ballast (0.1.0)
-      activerecord (>= 6.1, < 8.0)
-      activesupport (>= 6.1, < 8.0)
+    track_ballast (0.3.0)
+      activerecord (>= 7.0, < 9.0)
+      activesupport (>= 7.0, < 9.0)
+      redis (>= 4.8, < 6.0)
 
 GEM
   remote: https://rubygems.org/
@@ -78,6 +79,10 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
+    redis (5.0.8)
+      redis-client (>= 0.17.0)
+    redis-client (0.19.1)
+      connection_pool
     regexp_parser (2.9.0)
     rexml (3.2.6)
     rspec (3.12.0)
@@ -138,6 +143,7 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -22,6 +22,16 @@ Or install it yourself as:
 
     $ gem install track_ballast
 
+If you wish to use features that rely on Redis, you may set a Redis connection to `TrackBallast.redis`.
+
+For Rails, you may wish to set up TrackBallast using an initializer, though **please note**, the default configuration may be appropriate.  Please see the `TrackBallast.redis` documentation for details.
+
+```ruby
+# config/initializers/track_ballast.rb
+
+TrackBallast.redis = Redis.new(url: ENV["CUSTOM_REDIS_URL"])
+```
+
 ## Usage
 
 Please see [the code](https://github.com/doximity/track_ballast/tree/master/lib/track_ballast) and [documentation](https://www.rubydoc.info/gems/track_ballast) for individual units.
@@ -45,6 +55,18 @@ require "track_ballast/callable"
 
 class MyService
   extend TrackBallast::Callable
+
+  # ...
+end
+```
+
+```ruby
+require "track_ballast/stop_signal"
+
+class MyJob < ApplicationJob
+  extend TrackBallast::StopSignal
+
+  # ...
 end
 ```
 
@@ -62,6 +84,8 @@ Please see [the Milestones on GitHub](https://github.com/doximity/track_ballast/
 
 ## Development
 
+You'll need [Redis](https://redis.io/docs/getting-started/) and [Ruby](https://www.ruby-lang.org/en/downloads/) installed.  Please ensure both are set up before continuing.
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
@@ -74,7 +98,7 @@ find spec -name '*_spec.rb' -exec bundle exec rspec {} \;
 
 ## Contributing
 
-1. See [CONTRIBUTING.md](./CONTRIBUTING.md)
+1. See [CONTRIBUTING.md](https://github.com/doximity/track_ballast/blob/master/CONTRIBUTING.md)
 2. Fork it ( https://github.com/doximity/track_ballast/fork )
 3. Create your feature branch (`git checkout -b my-new-feature`)
 4. Commit your changes (`git commit -am 'Add some feature'`)

data/lib/track_ballast/all.rb

@@ -1,3 +1,4 @@
 require "track_ballast"
 require "track_ballast/callable"
+require "track_ballast/stop_signal"
 require "track_ballast/uuid_management"

data/lib/track_ballast/redis.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "redis"
+require "track_ballast/error"
+
+module TrackBallast
+  # Raised when Redis access is attempted without a configured Redis connection.
+  class NoRedisError < Error; end
+
+  class << self
+    attr_writer :redis
+
+    # Internal Redis connection for +TrackBallast+.
+    #
+    # It defaults to the Redis instance configured by the +REDIS_URL+
+    # environment variable.
+    #
+    # @return [Redis] a Redis connection
+    def redis
+      if @redis
+        @redis
+      elsif ENV["REDIS_URL"]
+        # This will short-circuit to be `@redis` on future runs
+        @redis = Redis.new(url: ENV["REDIS_URL"])
+      else
+        raise NoRedisError, "TrackBallast.redis is not configured"
+      end
+    end
+  end
+end

data/lib/track_ballast/stop_signal.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "track_ballast/redis"
+
+module TrackBallast
+  class StopSignalError < StandardError; end
+
+  # +StopSignal+ is a module that provides a way to stop a process while it is
+  # running.
+  #
+  # It uses Redis to store the stop signal.  Please see +TrackBallast.redis+
+  # for more details.
+  #
+  # When the stop signal is set, the client process will stop the next time the
+  # process manually checks the +stopped?+ method.
+  #
+  # == Usage
+  #
+  # +StopSignal+ can be used via +extend+ or +include+.
+  #
+  # === Extend
+  #
+  # - Extend the module in your class
+  # - Call +stopped?+ to check if the stop signal is set, for example: at the
+  #   beginning of the +perform+ method in a job class.
+  # - If desired, add an implementation of the +stop_signal_key+ method.  This
+  #   can be useful for stopping multiple classes with the same stop signal.  For
+  #   example: multiple related jobs.  The default implementation is to use the
+  #   class name.
+  #
+  # Then, from another process, you can manipulate the stop signal:
+  #
+  # - Call +YourClass.stop!+ to set the stop signal
+  # - Call +YourClass.go!+ to remove the stop signal
+  #
+  # ==== Example
+  #
+  #     class YourJob < ApplicationJob
+  #       extend TrackBallast::StopSignal
+  #
+  #       def perform
+  #         return if self.class.stopped?
+  #
+  #         # Process your job here
+  #       end
+  #
+  #       # Optional:
+  #       #
+  #       #     def self.stop_signal_key
+  #       #       "custom_stop_signal_key:stop"
+  #       #     end
+  #     end
+  #
+  # === Include
+  #
+  # - Include the module in your class
+  # - Call +stopped?+ to check if the stop signal is set, for example: at the
+  #   beginning of the +perform+ method in a job class.
+  # - If desired, add an implementation of the +stop_signal_key+ method.  This
+  #   can tie the stop signal to a specific instance of the class, as shown in
+  #   the example below.
+  #
+  # Then, from another process, you can manipulate the stop signal:
+  #
+  # - Call +your_model_instance.stop!+ to set the stop signal
+  # - Call +your_model_instance.go!+ to remove the stop signal
+  #
+  # ==== Example
+  #
+  #     class YourModel < ApplicationRecord
+  #       include TrackBallast::StopSignal
+  #
+  #       # Optional, but recommended for usage via `include`
+  #       def stop_signal_key
+  #         "#{self.class.name}:#{id}:stop"
+  #       end
+  #     end
+  #
+  #     class YourModelService
+  #       def initialize(your_model_instance)
+  #         @your_model_instance = your_model_instance
+  #       end
+  #
+  #       def call
+  #         return if your_model_instance.stopped?
+  #
+  #         # Process `your_model_instance` here
+  #       end
+  #     end
+  #
+  module StopSignal
+    # Set the stop signal
+    #
+    # @return [Boolean] +true+ if the stop signal was set
+    # @raise [StopSignalError] if an error occurred while setting the stop signal
+    def stop!
+      redis.set(stop_signal_key, true)
+
+      true
+    rescue Redis::CommandError
+      raise StopSignalError
+    end
+
+    # Remove the stop signal
+    #
+    # @return [Boolean] +true+ if the stop signal was removed
+    # @raise [StopSignalError] if an error occurred while removing the stop signal
+    def go!
+      redis.del(stop_signal_key)
+
+      true
+    rescue Redis::CommandError
+      raise StopSignalError
+    end
+
+    # Check if the stop signal is set
+    #
+    # @raise [StopSignalError] if an error occurred while checking the stop signal
+    def stopped?
+      redis.exists(stop_signal_key).positive?
+    rescue Redis::CommandError
+      raise StopSignalError
+    end
+
+    # The key used to store the stop signal.
+    #
+    # It defaults to the class name plus ":stop".
+    #
+    # This can be overridden to provide a custom key as described in the
+    # +StopSignal+ module documentation.
+    #
+    # @return [String] the key used to store the stop signal
+    def stop_signal_key
+      "#{name}:stop"
+    end
+
+    private
+
+    def redis
+      TrackBallast.redis
+    end
+  end
+end

data/lib/track_ballast/version.rb

@@ -1,3 +1,3 @@
 module TrackBallast
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/track_ballast.gemspec

@@ -27,8 +27,9 @@ Gem::Specification.new do |spec|
   spec.executables = []
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord", ">= 6.1", "< 8.0"
-  spec.add_dependency "activesupport", ">= 6.1", "< 8.0"
+  spec.add_dependency "activerecord", ">= 7.0", "< 9.0"
+  spec.add_dependency "activesupport", ">= 7.0", "< 9.0"
+  spec.add_dependency "redis", ">= 4.8", "< 6.0"
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "guard"
   spec.add_development_dependency "guard-rspec"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: track_ballast
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Benjamin Oakes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,40 +16,60 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -215,6 +235,8 @@ files:
 - lib/track_ballast/callable.rb
 - lib/track_ballast/error.rb
 - lib/track_ballast/logger.rb
+- lib/track_ballast/redis.rb
+- lib/track_ballast/stop_signal.rb
 - lib/track_ballast/uuid_management.rb
 - lib/track_ballast/version.rb
 - track_ballast.gemspec