finalizers 0.0.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 822593a5b0219e62e989781c398b5f943763df9ca62bbb284096294a78eab3f9
-  data.tar.gz: 6fbce423173fbaf892d25c737527b15bc476a00d99f4d741c3dac6929143459d
+  metadata.gz: 02dec5224fb743376e9f9af2f17a522512a728dc1b80e55d002b01a81784649f
+  data.tar.gz: 231c643d2047c478961ff7679b04fd60d6372954ed3ca6491eaa0cefe0b03911
 SHA512:
-  metadata.gz: dd753926bcd218a6e497c6b00215c49289e73d5120742edd6d7c8bd2328e715cf4f759d50a76053036ce137e8ab1dd0b3512a9dc164e324e879116a27dc9ada7
-  data.tar.gz: 1c8e5e4fa69fddf9f1105669370ed959bf716a39d09da2ae425cb4ff20a2593bb49e8bc3f6b6ccb585e86ea35e6016b07575930a96ba0325669cdd71c9b3e8b5
+  metadata.gz: 583b9dd07abcf74ff42b431a5ffd85233d5ebbe337af5d9ecaef5c7043ec74786b1642ed8ce2260cb189a8aabd1faf3d247e83de2012fefb8a0e711060366a78
+  data.tar.gz: 8beeefa591f84c3672750133935279add71e40d01b34c93862bf51d03cd8d56a140862fb018ace9fea808254ac11b252cbbe6d1172b3b711643859c70cb4b095

data/{MIT-LICENSE → LICENSE.txt}

@@ -1,4 +1,4 @@
-Copyright thomas morgan
+Copyright 2023 thomas morgan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,28 +1,177 @@
 # Finalizers
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+Add finalizers to your ActiveRecord models. Useful for cleaning up child dependencies in the database as well as associated external resources (APIs, etc).
 
-## Installation
-Add this line to your application's Gemfile:
+* Finalizers and the eventual `destroy` run in background jobs, keeping controllers quick and responsive
+* Finalizers may cleanup other database records, remote APIs, or anything else relevant
+* Finalizers may also confirm any arbitrary dependency, making them extremly flexible
+* Quickly define database-based dependencies with `erase_dependents`
+* Supports cascading deletes
+* Replaces `has_many ... dependent: :async`
+* Background jobs are fully retryable, easily handling delays in satisfying finalizer dependencies and checks
+* Dynamically determine when models shouldn't be deleted at all using `erasable?`
+* Easily check if erasable and delete (erase) in controllers with `safe_erase`
+
+
+
+## Basics and Usage
+
+Each model used with Finalizers requires a `state` string field.
+
+Finalizers is also aware and accommodative of `state_at` (when `state` was last changed) and `delete_at` (for scheduling a future delete), but expects those to be implemented separately.
+
+A quick heads up: Finalizers depends on `rescue_like_a_pro` which changes how `retry_on` and `discard_on` are processed for *all* ActiveJob children. `rescue_like_a_pro` changes ActiveJob to handle exceptions based on specificity instead of last defintion, which most will find more intuitive. For basic usage, likely nothing will change. For advanced exception handling, it may warrant a review of your Job classes (which can often be simplified as a result).
+
+
+#### Installation
+
+As always, add to your Gemfile and run `bundle install` (or however you like to do such things):
 
 ```ruby
 gem "finalizers"
 ```
 
-And then execute:
 ```bash
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install finalizers
+
+#### Models
+
+Add the required `state` field using a migration. It just needs to be a simple string long enough to hold `"deleted"` and any other values you wish to you.
+
+Then, add `include Finalizers::Model` to the model and define an `erasable?` method.
+
+To automatically cascade erase operations onto child classes (ie: `has_one` or `has_many`), use `erase_dependents`.
+
+To add custom finalizers, use `add_finalizer`.
+
+---
+
+Finalizers add new `erase` and `erase!` methods to your model. You should generally use these instead of `destroy`.
+
+`destroy` and `destroy!` continue to exist and will still destroy immediately, without running finalizers or handling dependent records. To prevent accidentally calling them and thus bypassing your finalizers, the `:force` argument must be added: `destroy(force: true)`. This is often still useful in tests.
+
+For controllers and all other 'normal' actions, use `erase`, `erase!`, or `safe_erase`. `safe_erase` is designed especially for controllers. See below.
+
+```ruby
+class Vehicle < ApplicationRecord
+  # Must have `state` attribute
+  # May have `state_at` attribute. If present, will be updated when `state` is updated.
+  # May have `delete_at` attribute. If present, will be cleared when `erase` is called.
+  include Finalizers::Model
+
+  add_finalizer :delete_from_remote
+    # In addition to ensuring dependents are destroyed (see erase_dependents below),
+    # additional work can be required to complete before this record is destroyed.
+    # This is especially useful for cleaning up data in another system, but isn't
+    # limited to that.
+    # See `#delete_from_remote` below for more discussion.
+  add_finalizer do
+    # alternate syntax to define work inline if preferred
+    raise RetryJobError, "#{self.class.name} #{id} still running" if running?
+  end
+
+  has_many :wheels
+    # Hint: to further protect against accidental use of #destroy (and bypassing your
+    # finalizers), add a foreign key restriction to your schema and then add
+    # `:restrict_with_exception` to the has_many definition:
+    #   has_many :wheels, dependent: :restrict_with_exception
+  erase_dependents :wheels
+    # This does 2 things:
+    # a) When Vehicle is erased (state := 'deleted'), causes all child Wheels to be
+    #   erased too. (And, if Wheel has_one :tire, this will cascade as well.)
+    # b) Adds a finalizer to verify that the associated children are destroyed
+    #   before proceeding. That means that children will always have access to the
+    #   parent while performing their own finalization.
+    # Note: any dependent classes here must also include Finalizers::Model.
+
+  def erasable?
+    true     # Allow `safe_erase` to proceed
+    # false  # Prevent `safe_erase` from proceeding
+  end
+  # This only affects `safe_erase`. Using `erase` or `erase~` will work regardless.
+  # Returning false is particularly useful if an object shouldn't be allowed to be
+  # erased because it's in use, is a global object, etc.
+
+  # Finalizer callback, as configured above.
+  def delete_from_remote
+    # If another finalizer fails (including erase_dependents), this finalizer may be
+    # called more than once so it should be idempotent.
+    # You may use (and update) a tracking field (`remote_uuid` here), or may simply
+    # repeat the operation.
+    if remote_uuid
+      RemoteService.delete id: remote_uuid
+      update_columns remote_uuid: nil
+    end
+
+    # Exceptions will cause the finalizer to fail and be retried, so they should
+    # usually be passed through. You can raise RetryJobError if another exception
+    # isn't already in play.
+  end
+
+end
 ```
 
+
+#### Controllers
+
+In `SomeController#destroy`, use `safe_erase` instead of `destroy`. `safe_erase` returns a boolean and will add an error message when false, so it allows making `#destroy` work like `#update`. Optionally, you may erase via `#update` by setting `@model.state = 'deleted'`.
+
+```ruby
+def destroy
+  if @model.safe_erase
+    render @model, notice: 'Resource deleted.'
+  else
+    render 'errors', locals: {obj: @model}, status: 422
+      # however you normally render errors
+  end
+end
+```
+
+
+#### Error reporting
+
+Finalizers uses `RetryJobError` internally to help manage flow. It is recommended to exclude it from any exception reporting tool (Honeybadger, Sentry, etc).
+
+
+
+## Advanced usage
+
+#### Overriding the default EraserJob
+
+Just create your own version of the job in your app. Zeitwerk should prefer the app's version over the gem's.
+
+Be sure to keep the existing signature for `perform`:
+```ruby
+  def perform(obj)
+  end
+```
+
+#### Extending the default EraserJob
+
+Like overriding, create your own version of the job and require the original job before reopening it:
+```ruby
+require "#{Finalizers::Engine.root}/app/jobs/eraser_job"
+class EraserJob
+  # add extensions here
+end
+```
+
+
+
+## History and Compatibility
+
+Extracted from production code.
+
+Tested w/Rails 7.x and GoodJob 3.x.
+
+
+
 ## Contributing
-Contribution directions go here.
+Pull requests welcomed. If unsure whether a proposed addition is in scope, feel free to open an Issue for discussion (not required though).
+
+
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -6,3 +6,14 @@ load "rails/tasks/engine.rake"
 load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
+
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/jobs/eraser_job.rb

@@ -0,0 +1,15 @@
+class EraserJob < Finalizers::ApplicationJob
+  queue_with_priority 10
+
+  retry_on Exception, wait: 20.seconds, jitter: 15.seconds, attempts: :unlimited, priority: 20
+
+  def perform(obj)
+    if obj.state == 'deleted'
+      obj.finalize_and_destroy!
+    end
+  rescue RetryJobError => ex
+    logger.warn "#{ex.message} (attempt=#{executions})"
+    raise
+  end
+
+end

data/app/jobs/finalizers/application_job.rb

@@ -0,0 +1,11 @@
+module Finalizers
+  class ApplicationJob < ActiveJob::Base
+
+    # Automatically retry jobs that encountered a deadlock
+    retry_on ActiveRecord::Deadlocked, wait: 10.seconds, attempts: :unlimited, jitter: 3.seconds
+
+    # Most jobs are safe to ignore if the underlying records are no longer available
+    discard_on ActiveJob::DeserializationError
+
+  end
+end

data/app/jobs/retry_job_error.rb

@@ -0,0 +1,2 @@
+class RetryJobError < RuntimeError
+end

data/app/models/finalizers/model.rb

@@ -0,0 +1,192 @@
+# usage:
+# class Book  # mongoid or activerecord
+#   include Concerns::Finalizers
+#   has_many :editions
+#     # may add dependent: :restrict_with_exception to help ensure proper operation
+#     # of erase/finalization. similarly, may still use dependent: :destroy to
+#     # bypass erase/finalization system, but this is discouraged except perhaps in
+#     # tests [and delete() may be a better choice yet].
+#   erase_dependents :editions  # replaces  dependent: :destroy  in has_many/etc
+#     # this should be used for dependents that themselves should also erase in the
+#     # background (and optionally define finalizers of their own).
+#     # will delay erasing the present object until finalizers for dependents have
+#     # completed.
+#
+#   add_finalizer :do_something
+#   add_finalizer do
+#     do_something_else || throw(:abort)
+#     # alt: on error,  raise RetryJobError  instead
+#   end
+# end
+# b = Book.create
+# b.erase # alt: b.update state: 'deleted'
+# b.state # => 'deleted'
+# b.editions.first.state # => 'deleted
+#
+# the background job will then run finalizers for each Book and Edition being erased.
+# like Rails' standard callbacks, if a finalizer fails, `throw(:abort)`,
+# `raise RetryJobError, 'specific message'`, or raise any other exception.
+# RetryJobError and throw(:abort) are excluded from sentry exception notifications.
+# other exceptions will pass through as normal.
+#
+# requires a `state` field on the model.
+# will call before/after destroy hooks when the object is finally destroyed, after
+# completing finalizers.
+#
+# finalizers only run after verifying that dependent objects have been erased (as
+# instructed by calling `erase_dependents`). this means that parent objects are not
+# finalized or destroyed until all children are gone. this ensures child objects
+# still have access to a functioning (undestroyed) parent to complete their own
+# finalizers.
+# the lifecycle looks like this:
+#   check dependents for not-yet-finalized objects
+#   run finalizers
+#   run before_destroy callbacks
+#   destroy self
+#   run after_destroy callbacks
+#
+# finalizers should be idempotent as they may run more than once in the event of a
+# failure and subsequent retry. they may persist changes to the model to help manage
+# idempotence.
+#
+# note that erase() simply updates :state and will execute normal save and update
+# callbacks.
+# like destroy(), erase() does not run validations. to conditionally trigger an
+# erase, use update(state: 'deleted') instead, which will not bypass validations.
+
+
+module Finalizers::Model
+  extend ActiveSupport::Concern
+
+  included do
+    define_model_callbacks :finalize, only: [:before]
+    class << self
+      alias_method :add_finalizer, :before_finalize
+    end
+
+    after_save do
+      if state == 'deleted' && state_previously_was != 'deleted'
+        EraserJob.perform_later self
+      end
+    end
+
+    scope :not_deleted, ->{ where.not(state: 'deleted') }
+  end
+
+
+  module ClassMethods
+
+    # if child models don't include Finalizers::Model, but are self-deleting (perhaps they
+    # represent an in-progress work task and are deleted when finished), then use
+    # wait_for_no_dependents to defer destroying the current model until the children are gone.
+    # if they are not self-deleting, use standard options like dependent: :destroy or :delete_all.
+    # finally, if children do include Finalizers::Model, use erase_dependents instead.
+    def wait_for_no_dependents(*assoc_list, erase_if_found: false)
+      add_finalizer prepend: true do
+        assoc_list.each do |assoc|
+          proxy = send(assoc)
+          # has_many's :dependent checks use .size, so match that here
+          #   .size uses the cache_counter column, if available, else queries the db
+          if proxy.respond_to?(:size)
+            count = proxy.size
+            _perform_erase_dependents assoc if erase_if_found && count > 0 && proxy.not_deleted.any?
+          elsif proxy
+            count = 1
+            _perform_erase_dependents assoc if erase_if_found && !proxy.deleted?
+          else
+            count = 0
+          end
+          if count > 0
+            raise RetryJobError, "#{self.class.name} #{id} still has #{count} dependent #{assoc}"
+          end
+        end
+      end
+    end
+
+    # if child models include Finalizers::Model, then use erase_dependents to perform a cascading
+    # erase. use this instead of has_many or has_one's depdendent: :destroy (etc).
+    def erase_dependents(*assoc_list)
+      wait_for_no_dependents(*assoc_list, erase_if_found: true)
+      before_update do
+        if state == 'deleted' && state_was != 'deleted'
+          assoc_list.each do |assoc|
+            _perform_erase_dependents assoc
+          end
+        end
+      end
+    end
+
+  end
+
+
+  def deleted? ; state=='deleted' ; end
+
+  def destroy(force: false)
+    raise 'Called destroy() directly instead of using erase()' unless force
+    super()
+  end
+  def destroy!(force: false)
+    raise 'Called destroy!() directly instead of using erase!()' unless force
+    destroy(force: true) || _raise_record_not_destroyed
+  end
+
+  # should run callbacks, but not validations
+  # intent is to parallel destroy()'s behavior
+  def erase
+    self.state     = 'deleted'
+    self.state_at  = Time.current if respond_to?(:state_at=) && state_changed?
+    self.delete_at = nil if respond_to?(:delete_at=)
+    save validate: false
+  end
+  def erase!
+    self.state     = 'deleted'
+    self.state_at  = Time.current if respond_to?(:state_at=) && state_changed?
+    self.delete_at = nil if respond_to?(:delete_at=)
+    save! validate: false
+  end
+
+  # must define on model
+  # def erasable?
+  #   ...
+  # end
+
+  def safe_erase
+    if erasable?
+      erase
+    else
+      errors.add :base, "#{self.class.model_name.human} in use"
+      false
+    end
+  end
+
+
+  # called by EraserJob
+  # may call directly for testing
+  def finalize_and_destroy!
+    # finalizers execute outside of the destroy transaction (and callback sequence).
+    # this intentionally allows finalizers to do whatever action and /persist/ that finalized state
+    #   so if a later finalizer aborts, the previous ones don't have to repeat themselves.
+    # finalizers should still be idempotent though, as a finalizer could re-run due to an error
+    #   persisting that state, server failure, etc.
+    run_callbacks :finalize do
+      destroy force: true
+    end
+    raise RetryJobError, "#{self.class.name} #{id} finalizers did not complete" unless destroyed?
+    self
+  end
+
+
+  private
+
+  def _perform_erase_dependents(assoc)
+    # both activerecord and mongoid use non-! variants for their :dependent
+    # implementations, silently ignoring failures. match that behavior here.
+    proxy = send(assoc)
+    if proxy.respond_to?(:each)
+      proxy.not_deleted.each(&:erase)
+    elsif proxy
+      proxy.erase unless proxy.deleted?
+    end
+  end
+
+end

data/lib/finalizers/version.rb

@@ -1,3 +1,3 @@
 module Finalizers
-  VERSION = "0.0.1"
+  VERSION = '0.5.0'
 end

data/lib/finalizers.rb

@@ -1,6 +1,6 @@
-require "finalizers/version"
-require "finalizers/engine"
-
 module Finalizers
-  # Your code goes here...
+end
+
+%w(engine version).each do |f|
+  require "finalizers/#{f}"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finalizers
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.5.0
 platform: ruby
 authors:
 - thomas morgan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-15 00:00:00.000000000 Z
+date: 2023-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,34 +16,54 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
-description: Finalizers.
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rescue_like_a_pro
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: Adds finalizers to ActiveRecord models to clean up both database child
+  dependencies and external resources (APIs, etc). Finalizers run in background jobs
+  and are fully retryable.
 email:
 - tm@iprog.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- MIT-LICENSE
+- LICENSE.txt
 - README.md
 - Rakefile
-- app/assets/config/finalizers_manifest.js
-- config/routes.rb
+- app/jobs/eraser_job.rb
+- app/jobs/finalizers/application_job.rb
+- app/jobs/retry_job_error.rb
+- app/models/finalizers/model.rb
 - lib/finalizers.rb
 - lib/finalizers/engine.rb
 - lib/finalizers/version.rb
 - lib/tasks/finalizers_tasks.rake
-homepage:
+homepage: https://github.com/zarqman/finalizers
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/zarqman/finalizers
+  source_code_uri: https://github.com/zarqman/finalizers
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -62,5 +82,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Finalizers
+summary: Adds finalizers to ActiveRecord models
 test_files: []

data/config/routes.rb

@@ -1,2 +0,0 @@
-Rails.application.routes.draw do
-end