postburner 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b21ae5985bd9458b91095fe9a40370c6efe0a2d1903be46b47a0785dc6e0f73
-  data.tar.gz: e7e3989d2805bc64815f6b586ba8e594b11963a7330e0d012a7671928b55576d
+  metadata.gz: 6faa3078340ee2bc8d90e931ee1db203114e32ff69b288ec69340e8b86a987cd
+  data.tar.gz: 0a2ddf78a320e9b01c26a0e3fbd3158b78d37a89bca04a5fdd8c64b70eada1a7
 SHA512:
-  metadata.gz: af927556728f74e306075633a45851a51c4f26faa44f1c54901aa2c7a6f176e494b2c220d2040239e49c458a5cdc6c2e4ae19fd9d35548de1a2028f2a24c074a
-  data.tar.gz: 22d1b312e5b44a21b9035ecaf6a732aa6bac2100244144ed1084bf1f1d83f170df1f378f262fabdc1c8ec2edf26c2c97d4cfd94b006c27992a5871261f09bb4d
+  metadata.gz: 5253309eb7aff502623040d49e923faff7c91df6aac407ec7a4e306a8317b1363db43a4b0408eb20fbdad6ee017ad68489480ac50d7e2ac68a612a1337488457
+  data.tar.gz: 49d0253fe3ecde9cfd4de8b48a2ce95997245bea4310f7c751ccca3685fea8a42b29310a8058f222031ee8aa91f6ec61f990ec5c330157e39853c95830236cfa

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.4.0 - 2021-10-12
+
+### Added
+- Change Job logging to persisted in perform.
+- Update mailer job to use #with and support serializations.
+
 ## v0.3.3 - 2021-06-15
 
 ### Fixed

data/README.md

@@ -1,29 +1,15 @@
 # Postburner
-An ActiveRecord layer on top of Backburner for inspecting and auditing the
-queue, especially for delayed jobs. It isn't meant to be fast, but safe.
+An ActiveRecord layer on top of [Backburner](https://github.com/nesquena/backburner) for inspecting and auditing the
+queue, especially for delayed jobs. It isn't meant to be outperform other queues, but be safe (and inspectable).
 
-It is meant to be complementary to Backburner. Use Backburner as the default
+It is meant to be complementary to [Backburner](https://github.com/nesquena/backburner). Use Backburner as the default
 ActiveJob processor for mailers, active storage, and the like. Use a
-`Postburner::Job` for things that you want to track.
+`Postburner::Job` for things that you want to track. See [Comparison to Backburner](#comparison-to-backburner) for more.
 
-Comes with a mountable interface that can be password protected with whatever
-authentication you use in your project.
-
-Also meant to be a replacement/upgrade for [Que](https://github.com/que-rb/que).
-If you need something faster, but backed with ACID compliance, check out Que.
-There are some additional features in Postburner such as retained jobs
-after processing, stats, per job logging, etc.
-
-Compared to plain [Backburner](https://github.com/nesquena/backburner),
-Postburner adds:
-- Database Jobs for inspection, linking, auditing, removal (and deletion)
-- Direct access to associated [Beanstalk](https://beanstalkd.github.io/) (via [beaneater](https://github.com/beanstalkd/beaneater))
-- Job Statistics (lag, attempts, logs, tracked errors)
-- Convenience methods to clear tubes, stats, and connections for Beanstalk.
-
-Otherwise, Postburner tries to be a super simple layer on `Backburner::Queue`
-and `ActiveRecord`. Every tool with either of those are avilabel in
-`Postburner::Job`s.
+Postburner meant to be a replacement/upgrade for [Que](https://github.com/que-rb/que).
+If you need something faster, check out Que - we love it! Postburner is built for a slightly different purpose: to be
+simple, safe, and inspectable. All of which Que has (or can be added), but are included by default with some architecture
+differences. See [Comparison to Que](#comparison-to-que) for more.
 
 ## Usage
 
@@ -33,51 +19,240 @@ class RunDonation < Postburner::Job
   queue_priority 0 # 0 is highest priority
   queue_max_job_retries 0 # don't retry
 
-  def process(args)
+  def perform(args)
     # do long tasks here
     # also have access to self.args
   end
 end
 
-RunDonation.create!(args: {donation_id: 123}).queue!
+# RunDonation#create! is the `ActiveRecord` method, so it returns a model,
+# you can manipulate, add columns to the table to, reference with foreign
+# keys, etc.
+job = RunDonation.create!(args: {donation_id: 123})
+# NOTE Make sure use use an after_commit or after_save_commit, etc to avoid
+#      any race conditions of Postburner trying to process before a required
+#      database mutation is commited.
+job.queue!
 => {:status=>"INSERTED", :id=>"1139"}
+
+# queue for later with `:at`
 RunDonation.create!(args: {donation_id: 123}).queue! at: Time.zone.now + 2.days
 => {:status=>"INSERTED", :id=>"1140"}
 
-# `delay` takes priority over `at`
+# queue for later with `:delay`
+#
+# `:delay` takes priority over `:at`takes priority over `:at` because the
+# beanstalkd protocol uses uses `delay`
 RunDonation.create!(args: {donation_id: 123}).queue! delay: 1.hour
 => {:status=>"INSERTED", :id=>"1141"}
 ```
 
+### [Beaneater](https://github.com/beanstalkd/beaneater) and [beanstalkd](https://raw.githubusercontent.com/beanstalkd/beanstalkd/master/doc/protocol.txt) attributes and methods
+```ruby
+# get the beanstalkd job id
+job.bkid
+=> 1104
+
+# get the beaneater job, call any beaneater methods on this object
+job.beanstalk_job
+
+# get the beanstald stats
+job.beanstalk_job.stats
+
+# kick the beanstalk job
+job.kick!
+
+# delete beankstalkd job, retain the job model
+job.delete!
+
+# delete beankstalkd job, retain the job model, but set `removed_at` on model.
+job.remove!
+
+# or simply remove the model, which will clean up the beanstalkd job in a before_destroy hook
+job.destroy # OR job.destroy!
+
+# get a cached Backburner connection and inspect it (or even use it directly)
+c = Postburner.connection
+c.beanstalk.tubes.to_a
+c.beanstalk.tubes.to_a.map{|t| c.tubes[t.name].peek(:buried)}
+c.beanstalk.tubes['ss.development.caching'].stats
+c.beanstalk.tubes['ss.development.caching'].peek(:buried).kick
+c.beanstalk.tubes['ss.development.caching'].kick(3)
+c.close
+
+# automatically close
+Postburner.connected do |connection|
+  # do stuff with connection
+end
+```
+
+Read about the [beanstalkd protocol](https://raw.githubusercontent.com/beanstalkd/beanstalkd/master/doc/protocol.txt).
+
+### Basic model fields
+```ruby
+# ActiveRecord primary key
+job.id
+
+# int id of the beankstalkd job
+job.bkid
+
+# string uuid
+job.sid
+
+# ActiveRecord STI job subtype
+job.type
+
+# jsonb arguments for use in job
+job.args
+
+# time job should run - not intended to be changed
+# TODO run_at should be readonly after create
+job.run_at
+```
+
+### Job statistics
+```ruby
+# when job was inserted into beankstalkd
+job.queued_at
+
+# last time attempted
+job.attempting_at
+
+# last time processing started
+job.processing_at
+
+# when completed
+job.processed_at
+
+# when removed, may be nil
+job.removed_at
+
+# lag in ms from run_at/queued_at to attempting_at
+job.lag
+
+# duration of processing in ms
+job.duration
+
+# number of attempts
+job.attempt_count
+
+# number of errors (length of errata)
+job.error_count
+
+# number of log entries (length of logs)
+job.log_count
+
+# array of attempting_at times
+job.attempts
+
+# array of errors
+job.errata
+
+# array of log messages
+job.logs
+```
+
+### Job logging and exceptions
+
+Optionally, you can:
+1. Add log messages to the job during processing to `logs`
+1. Add log your own exceptions to `errata`
+
+```ruby
+class RunDonation < Postburner::Job
+  queue 'critical'
+  queue_priority 0 # 0 is highest priority
+  queue_max_job_retries 0 # don't retry
+
+  def perform(args)
+    # log at task, defaults to `:info`, but `:debug`, `:warning`, `:error`
+    log "Log bad condition...", level: :error
+
+    begin
+      # danger
+    rescue Exception => e
+      log_exception e
+    end
+  end
+end
+```
+
+### Optionally, mount the engine
+
+```ruby
+mount Postburner::Engine => "/postburner"
+
+# mount only for development inspection
+mount Postburner::Engine => "/postburner" if Rails.env.development?
+```
+
+[Open the controller](https://guides.rubyonrails.org/engines.html#overriding-models-and-controllers)
+to add your own authentication or changes - or just create your own routes, controllers, and views.
+
+[Override the views](https://guides.rubyonrails.org/engines.html#overriding-views) to make them
+prettier - or follow the suggestion above and use your own.
+
 ## Installation
 
+First [install beanstalkd](https://beanstalkd.github.io/download.html). On Debian-based systems, that goes like this:
+```bash
+sudo apt-get install beanstalkd
+```
+
+Then add to your Gemfile.
 ```ruby
-# in Gemfile
 gem 'postburner'
 ```
 
+Install...
 ```bash
 $ bundle
+```
 
+After bundling, install the migration.
+```
 # install migration, possible to edit and add attributes or indexes as needed.
 $ bundle exec rails g postburner:install
 ```
 
-Add a `config/initializers/backburner.rb` with option found [here](https://github.com/nesquena/backburner#configuration).
+Inspect `XXX_create_postburner_jobs.rb`. (The template is [here](-/blob/master/lib/generators/postburner/install/templates/migrations/create_postburner_jobs.rb.erb)).The required attributes are in there, but add more if you would like to use them,
+or do it in a separate migration. By default, several indexes are added 
 
-Set `Backburner` for `ActiveJob`
+Because `Postburner` is built on `Backburner`, add a `config/initializers/backburner.rb` with option found [here](https://github.com/nesquena/backburner#configuration).
+```ruby
+Backburner.configure do |config|
+  config.beanstalk_url       = "beanstalk://127.0.0.1"
+  config.tube_namespace      = "some.app.production"
+  config.namespace_separator = "."
+  config.on_error            = lambda { |e| puts e }
+  config.max_job_retries     = 3 # default 0 retries
+  config.retry_delay         = 2 # default 5 seconds
+  config.retry_delay_proc    = lambda { |min_retry_delay, num_retries| min_retry_delay + (num_retries ** 3) }
+  config.default_priority    = 65536
+  config.respond_timeout     = 120
+  config.default_worker      = Backburner::Workers::Simple
+  config.logger              = Logger.new(STDOUT)
+  config.primary_queue       = "backburner-jobs"
+  config.priority_labels     = { :custom => 50, :useless => 1000 }
+  config.reserve_timeout     = nil
+  config.job_serializer_proc = lambda { |body| JSON.dump(body) }
+  config.job_parser_proc     = lambda { |body| JSON.parse(body) }
+end
+```
+
+Finally, set `Backburner` for `ActiveJob`
 ```
 # config/application.rb
 config.active_job.queue_adapter = :backburner
 ```
 
 Postburner may later provide an adapter, but we recommend using `Postburner::Job` classes
-directyly.
+directly.
 
 Add jobs to `app/jobs/`. There currently is no generator.
+
 ```ruby
 # app/jobs/run_donation.rb
-
 class RunDonation < Postburner::Job
   queue 'critical'
   queue_priority 0 # 0 is highest priority
@@ -88,6 +263,34 @@ class RunDonation < Postburner::Job
     # also have access to self.args
   end
 end
+```
+
+### Comparison to Backburner
+
+Compared to plain [Backburner](https://github.com/nesquena/backburner),
+Postburner adds:
+- Database Jobs for inspection, linking, auditing, removal (and deletion)
+- Direct access to associated [Beanstalk](https://beanstalkd.github.io/) (via [beaneater](https://github.com/beanstalkd/beaneater))
+- Job Statistics (lag, attempts, logs, tracked errors)
+- Convenience methods to clear tubes, stats, and connections for Beanstalk.
+
+Otherwise, Postburner tries to be a super simple layer on `Backburner::Queue`
+and `ActiveRecord`. Every tool with either of those are available in
+`Postburner::Job`s.
+
+Comes with a mountable interface that can be password protected with whatever
+authentication you use in your project.
+
+### Comparison to Que
+
+Postburner meant to be a replacement/upgrade for [Que](https://github.com/que-rb/que).
+However, if you need something faster and backed with ACID compliance, check out Que.  
+
+Postburner has some additional features such as retained jobs after processing,
+stats, per job logging, etc.
+
+Postburner is meant to be simpler than `Que`. Que is incredible, but jobs should
+be simple so the logic and history can be transparent.
 
 ## Contributing
 Submit a pull request. Follow conventions of the project. Be nice.
@@ -102,7 +305,6 @@ Submit a pull request. Follow conventions of the project. Be nice.
 - Job generator
   - Build file in app/jobs
   - Inherit from Postburner::Job
-- Job generator
 - Add before/after/around hooks
 - Add destroy, and remove actions on show page
 - Clear tubes.
@@ -112,5 +314,23 @@ Submit a pull request. Follow conventions of the project. Be nice.
 - Add logging with Job.args in backburner logs
 - MAYBE - ActiveJob adapter
 
+
+### Running in Development
+
+```
+cd test/dummy
+bundle exec backburner
+```
+
+### Releasing
+
+1. `gem bump -v minor -t`
+  Where <minor> can be: major|minor|patch|pre|release or a version number
+2. Edit `CHANGELOG.md` with details from `git log --oneline`
+3. `git commit --amend`
+4. `gem release -k nac -p`
+  Where <nac> is an authorized key with push capabilities.
+
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/postburner/job.rb

@@ -72,11 +72,11 @@ module Postburner
           return
         end
 
-        self.log('START')
+        self.log!('START')
 
         self.perform(args)
 
-        self.log('DONE')
+        self.log!('DONE')
 
         begin
           now = Time.zone.now

data/app/models/postburner/mailer.rb

@@ -1,13 +1,13 @@
 module Postburner
   # Send a mailer, tracked.
   #
-  # Postburner::Mailer.deliver(UserMailer, :welcome, user_id: 1)
-  # Postburner::Mailer.deliver(UserMailer, :welcome, user_id: 1).queue! at: Time.zone.now + 1.day
-  # Postburner::Mailer.deliver(UserMailer, :welcome, user_id: 1).queue! delay: 5.minutes
+  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1)
+  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1).queue! at: Time.zone.now + 1.day
+  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1).queue! delay: 5.minutes
   class Mailer < Job
     #queue 'mailers'
 
-    def self.deliver!(mailer, action)
+    def self.deliver(mailer, action)
       job = self.create!(
         args: {
           mailer: mailer.to_s,
@@ -17,9 +17,32 @@ module Postburner
       job
     end
 
-    def process(args)
-      cls = args['mailer'].constantize
-      cls.send(args['action']).deliver_now
+    # Similar to ActionMailer #with - set the parameters
+    #
+    def with(params={})
+      self.args.merge!(
+        params: ActiveJob::Arguments.serialize(params)
+      )
+      self.save!
+      self
+    end
+
+    # Build the mail but don't send.
+    #
+    def assemble(args=nil)
+      _args = args || self.args
+
+      cls = _args['mailer'].constantize
+
+      mail = cls.
+        with(ActiveJob::Arguments.deserialize(_args['params']).to_h).
+        send(_args['action'])
+
+      mail
+    end
+
+    def perform(args)
+      self.assemble(args).deliver_now
     end
   end
 end

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '0.3.3'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-15 00:00:00.000000000 Z
+date: 2021-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -128,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Postgres backed beanstalkd queue via backburner