track_ballast 0.1.0 → 0.2.0.beta1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6e862c2e25e1e2fcd384d009cefe352c350914732709276274e5013254e58296
4
- data.tar.gz: debd71ea18ded7b48e053473fe1cd516bbe82658dcf30407dcfb93437a021193
3
+ metadata.gz: 4eb3bf0aa7b712fdc33b3f4a83f0f17cbb9fc27105a0fb24922a16472dc22714
4
+ data.tar.gz: d6d476f287c14698835dd9836c54da4b0727ca0cdf57804867b3c4e7939f1a9d
5
5
  SHA512:
6
- metadata.gz: '09f2866179582e548cba5e16a5a8afb06942abbe10b891626bb2f1dd1f1d87ba3cce5a1e1d596d8f95bd9b7b8494bad67d45c51d3f0151e30b5b782d6f899048'
7
- data.tar.gz: 210396ca3d3d363dc47529d7fe0c3c54f48995c6d21725a26116c741f0b4ded76c61f5e564443ec6a402144fcacb46cf08588d6f1d61e8ffa6c95aba47f2da81
6
+ metadata.gz: ba22a6eb00e3e32385c3b88c579efde2cc708fbf1dcfcbaf730a5b529fee9ee3031bbc2b0bc5768057e7d8f03f2e9568a0e779f0e50771a1b41a816d531b30d6
7
+ data.tar.gz: 62c28dd2b2ee403e90b2a03d5cd1263a2126cb4359c5b78531bd61912dc4faa66760f1c1d9dc9bdfbe6ae8e4e17fef61fdf385a6bcfbffa20d833ccc1ae1dfec
data/.circleci/config.yml CHANGED
@@ -16,7 +16,11 @@ executors:
16
16
  default: 3.2.2
17
17
  resource_class: small
18
18
  docker:
19
- - image: cimg/ruby:<< parameters.ruby-version >>
19
+ - image: cimg/ruby:<< parameters.ruby-version >>
20
+ environment:
21
+ REDIS_URL: redis://localhost:6379
22
+ BUNDLE_VERSION: 2.5.5
23
+ - image: cimg/redis:6.2
20
24
 
21
25
  commands:
22
26
  bundle_install:
data/CHANGELOG.md CHANGED
@@ -1,6 +1,12 @@
1
1
  Changelog
2
2
  =========
3
3
 
4
+ ## 0.2.0
5
+
6
+ * Added `redis` dependency
7
+ * Added `TrackBallast.redis`
8
+ * Added `StopSignal`
9
+
4
10
  ## 0.1.0
5
11
 
6
12
  * First external release
data/Gemfile.lock CHANGED
@@ -1,9 +1,10 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- track_ballast (0.1.0)
4
+ track_ballast (0.2.0.beta1)
5
5
  activerecord (>= 6.1, < 8.0)
6
6
  activesupport (>= 6.1, < 8.0)
7
+ redis (>= 4.8, < 6.0)
7
8
 
8
9
  GEM
9
10
  remote: https://rubygems.org/
@@ -78,6 +79,10 @@ GEM
78
79
  rb-fsevent (0.11.2)
79
80
  rb-inotify (0.10.1)
80
81
  ffi (~> 1.0)
82
+ redis (5.0.8)
83
+ redis-client (>= 0.17.0)
84
+ redis-client (0.19.1)
85
+ connection_pool
81
86
  regexp_parser (2.9.0)
82
87
  rexml (3.2.6)
83
88
  rspec (3.12.0)
data/README.md CHANGED
@@ -22,6 +22,16 @@ Or install it yourself as:
22
22
 
23
23
  $ gem install track_ballast
24
24
 
25
+ If you wish to use features that rely on Redis, you may set a Redis connection to `TrackBallast.redis`.
26
+
27
+ 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.
28
+
29
+ ```ruby
30
+ # config/initializers/track_ballast.rb
31
+
32
+ TrackBallast.redis = Redis.new(url: ENV["CUSTOM_REDIS_URL"])
33
+ ```
34
+
25
35
  ## Usage
26
36
 
27
37
  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"
45
55
 
46
56
  class MyService
47
57
  extend TrackBallast::Callable
58
+
59
+ # ...
60
+ end
61
+ ```
62
+
63
+ ```ruby
64
+ require "track_ballast/stop_signal"
65
+
66
+ class MyJob < ApplicationJob
67
+ extend TrackBallast::StopSignal
68
+
69
+ # ...
48
70
  end
49
71
  ```
50
72
 
@@ -62,6 +84,8 @@ Please see [the Milestones on GitHub](https://github.com/doximity/track_ballast/
62
84
 
63
85
  ## Development
64
86
 
87
+ 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.
88
+
65
89
  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.
66
90
 
67
91
  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).
@@ -1,3 +1,4 @@
1
1
  require "track_ballast"
2
2
  require "track_ballast/callable"
3
+ require "track_ballast/stop_signal"
3
4
  require "track_ballast/uuid_management"
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "redis"
4
+ require "track_ballast/error"
5
+
6
+ module TrackBallast
7
+ # Raised when Redis access is attempted without a configured Redis connection.
8
+ class NoRedisError < Error; end
9
+
10
+ class << self
11
+ attr_writer :redis
12
+
13
+ # Internal Redis connection for +TrackBallast+.
14
+ #
15
+ # It defaults to the Redis instance configured by the +REDIS_URL+
16
+ # environment variable.
17
+ #
18
+ # @return [Redis] a Redis connection
19
+ def redis
20
+ if @redis
21
+ @redis
22
+ elsif ENV["REDIS_URL"]
23
+ # This will short-circuit to be `@redis` on future runs
24
+ @redis = Redis.new(url: ENV["REDIS_URL"])
25
+ else
26
+ raise NoRedisError, "TrackBallast.redis is not configured"
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,143 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "track_ballast/redis"
4
+
5
+ module TrackBallast
6
+ class StopSignalError < StandardError; end
7
+
8
+ # +StopSignal+ is a module that provides a way to stop a process while it is
9
+ # running.
10
+ #
11
+ # It uses Redis to store the stop signal. Please see +TrackBallast.redis+
12
+ # for more details.
13
+ #
14
+ # When the stop signal is set, the client process will stop the next time the
15
+ # process manually checks the +stopped?+ method.
16
+ #
17
+ # == Usage
18
+ #
19
+ # +StopSignal+ can be used via +extend+ or +include+.
20
+ #
21
+ # === Extend
22
+ #
23
+ # - Extend the module in your class
24
+ # - Call +stopped?+ to check if the stop signal is set, for example: at the
25
+ # beginning of the +perform+ method in a job class.
26
+ # - If desired, add an implementation of the +stop_signal_key+ method. This
27
+ # can be useful for stopping multiple classes with the same stop signal. For
28
+ # example: multiple related jobs. The default implementation is to use the
29
+ # class name.
30
+ #
31
+ # Then, from another process, you can manipulate the stop signal:
32
+ #
33
+ # - Call +YourClass.stop!+ to set the stop signal
34
+ # - Call +YourClass.go!+ to remove the stop signal
35
+ #
36
+ # ==== Example
37
+ #
38
+ # class YourJob < ApplicationJob
39
+ # extend TrackBallast::StopSignal
40
+ #
41
+ # def perform
42
+ # return if self.class.stopped?
43
+ #
44
+ # # Process your job here
45
+ # end
46
+ #
47
+ # # Optional:
48
+ # #
49
+ # # def self.stop_signal_key
50
+ # # "custom_stop_signal_key:stop"
51
+ # # end
52
+ # end
53
+ #
54
+ # === Include
55
+ #
56
+ # - Include the module in your class
57
+ # - Call +stopped?+ to check if the stop signal is set, for example: at the
58
+ # beginning of the +perform+ method in a job class.
59
+ # - If desired, add an implementation of the +stop_signal_key+ method. This
60
+ # can tie the stop signal to a specific instance of the class, as shown in
61
+ # the example below.
62
+ #
63
+ # Then, from another process, you can manipulate the stop signal:
64
+ #
65
+ # - Call +your_model_instance.stop!+ to set the stop signal
66
+ # - Call +your_model_instance.go!+ to remove the stop signal
67
+ #
68
+ # ==== Example
69
+ #
70
+ # class YourModel < ApplicationRecord
71
+ # include TrackBallast::StopSignal
72
+ #
73
+ # # Optional, but recommended for usage via `include`
74
+ # def stop_signal_key
75
+ # "#{self.class.name}:#{id}:stop"
76
+ # end
77
+ # end
78
+ #
79
+ # class YourModelService
80
+ # def initialize(your_model_instance)
81
+ # @your_model_instance = your_model_instance
82
+ # end
83
+ #
84
+ # def call
85
+ # return if your_model_instance.stopped?
86
+ #
87
+ # # Process `your_model_instance` here
88
+ # end
89
+ # end
90
+ #
91
+ module StopSignal
92
+ # Set the stop signal
93
+ #
94
+ # @return [Boolean] +true+ if the stop signal was set
95
+ # @raise [StopSignalError] if an error occurred while setting the stop signal
96
+ def stop!
97
+ redis.set(stop_signal_key, true)
98
+
99
+ true
100
+ rescue Redis::CommandError
101
+ raise StopSignalError
102
+ end
103
+
104
+ # Remove the stop signal
105
+ #
106
+ # @return [Boolean] +true+ if the stop signal was removed
107
+ # @raise [StopSignalError] if an error occurred while removing the stop signal
108
+ def go!
109
+ redis.del(stop_signal_key)
110
+
111
+ true
112
+ rescue Redis::CommandError
113
+ raise StopSignalError
114
+ end
115
+
116
+ # Check if the stop signal is set
117
+ #
118
+ # @raise [StopSignalError] if an error occurred while checking the stop signal
119
+ def stopped?
120
+ redis.exists(stop_signal_key).positive?
121
+ rescue Redis::CommandError
122
+ raise StopSignalError
123
+ end
124
+
125
+ # The key used to store the stop signal.
126
+ #
127
+ # It defaults to the class name plus ":stop".
128
+ #
129
+ # This can be overridden to provide a custom key as described in the
130
+ # +StopSignal+ module documentation.
131
+ #
132
+ # @return [String] the key used to store the stop signal
133
+ def stop_signal_key
134
+ "#{name}:stop"
135
+ end
136
+
137
+ private
138
+
139
+ def redis
140
+ TrackBallast.redis
141
+ end
142
+ end
143
+ end
@@ -1,3 +1,3 @@
1
1
  module TrackBallast
2
- VERSION = "0.1.0"
2
+ VERSION = "0.2.0.beta1"
3
3
  end
@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
29
29
 
30
30
  spec.add_dependency "activerecord", ">= 6.1", "< 8.0"
31
31
  spec.add_dependency "activesupport", ">= 6.1", "< 8.0"
32
+ spec.add_dependency "redis", ">= 4.8", "< 6.0"
32
33
  spec.add_development_dependency "bundler"
33
34
  spec.add_development_dependency "guard"
34
35
  spec.add_development_dependency "guard-rspec"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: track_ballast
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.0.beta1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Benjamin Oakes
@@ -50,6 +50,26 @@ dependencies:
50
50
  - - "<"
51
51
  - !ruby/object:Gem::Version
52
52
  version: '8.0'
53
+ - !ruby/object:Gem::Dependency
54
+ name: redis
55
+ requirement: !ruby/object:Gem::Requirement
56
+ requirements:
57
+ - - ">="
58
+ - !ruby/object:Gem::Version
59
+ version: '4.8'
60
+ - - "<"
61
+ - !ruby/object:Gem::Version
62
+ version: '6.0'
63
+ type: :runtime
64
+ prerelease: false
65
+ version_requirements: !ruby/object:Gem::Requirement
66
+ requirements:
67
+ - - ">="
68
+ - !ruby/object:Gem::Version
69
+ version: '4.8'
70
+ - - "<"
71
+ - !ruby/object:Gem::Version
72
+ version: '6.0'
53
73
  - !ruby/object:Gem::Dependency
54
74
  name: bundler
55
75
  requirement: !ruby/object:Gem::Requirement
@@ -215,6 +235,8 @@ files:
215
235
  - lib/track_ballast/callable.rb
216
236
  - lib/track_ballast/error.rb
217
237
  - lib/track_ballast/logger.rb
238
+ - lib/track_ballast/redis.rb
239
+ - lib/track_ballast/stop_signal.rb
218
240
  - lib/track_ballast/uuid_management.rb
219
241
  - lib/track_ballast/version.rb
220
242
  - track_ballast.gemspec
@@ -236,9 +258,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
236
258
  version: 3.0.0
237
259
  required_rubygems_version: !ruby/object:Gem::Requirement
238
260
  requirements:
239
- - - ">="
261
+ - - ">"
240
262
  - !ruby/object:Gem::Version
241
- version: '0'
263
+ version: 1.3.1
242
264
  requirements: []
243
265
  rubygems_version: 3.4.10
244
266
  signing_key: