track_ballast 0.1.0.beta6 → 0.2.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eb1bf8026f035355c976bd1d356017c022dfd12ae0c9db32967d17c84ae19ac
-  data.tar.gz: 451487f526462eb61d15d9bd036a6070825b7c733d36b77f6957a40f086e0fa0
+  metadata.gz: 4eb3bf0aa7b712fdc33b3f4a83f0f17cbb9fc27105a0fb24922a16472dc22714
+  data.tar.gz: d6d476f287c14698835dd9836c54da4b0727ca0cdf57804867b3c4e7939f1a9d
 SHA512:
-  metadata.gz: ae6549bbe50faebd1c394f107e43de187029459d7f8afefd67d774a4c190d5ebaa3b5b0d7b8479f836ec7400462674c939927361f7830161a3e60f2aaba0bf89
-  data.tar.gz: 5b187742d7f330fb0405752919270fb20f9067ca62212638260e15f80fb5b146e839c3c41567b26e9d9887d3d03fc42c23f71920a3f1a294335389969b96d50e
+  metadata.gz: ba22a6eb00e3e32385c3b88c579efde2cc708fbf1dcfcbaf730a5b529fee9ee3031bbc2b0bc5768057e7d8f03f2e9568a0e779f0e50771a1b41a816d531b30d6
+  data.tar.gz: 62c28dd2b2ee403e90b2a03d5cd1263a2126cb4359c5b78531bd61912dc4faa66760f1c1d9dc9bdfbe6ae8e4e17fef61fdf385a6bcfbffa20d833ccc1ae1dfec

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:

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+## 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.beta6)
+    track_ballast (0.2.0.beta1)
       activerecord (>= 6.1, < 8.0)
       activesupport (>= 6.1, < 8.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)

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2023 Doximity, Inc.
+Copyright 2024 Doximity, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

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).

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.beta6"
+  VERSION = "0.2.0.beta1"
 end

data/track_ballast.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "activerecord", ">= 6.1", "< 8.0"
   spec.add_dependency "activesupport", ">= 6.1", "< 8.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.beta6
+  version: 0.2.0.beta1
 platform: ruby
 authors:
 - Benjamin Oakes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-01 00:00:00.000000000 Z
+date: 2024-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -50,6 +50,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.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