ajdc 0.0.1 → 0.1.0

data/skills/ajdc/references/transactions.md

@@ -0,0 +1,68 @@
+# Transactions and AJ/DC
+
+The run row lives in the app's database (or a separate `durable` database via
+`ActiveJob::Durable.connects_to`). These rules follow from that.
+
+## 1. `perform_later` inside a transaction
+
+- The run row is created in the caller's transaction. The queue message is enqueued after all
+  transactions commit (Rails `enqueue_after_transaction_commit`). A rollback removes the row and
+  sends nothing.
+- So: call `perform_later` inside the same transaction that creates or changes the entity
+  (`with_lock`, `transaction do ... end`). The run and the entity commit or roll back together.
+  This is the outbox pattern without an outbox table.
+- `unique_by` is checked in that transaction too. Concurrent enqueues are decided by the unique
+  index on `[job_class, active_key]`; the loser gets `:skip`, `:reject` or `:replace` semantics.
+- If the run row is in a separate database, the two databases do not share a transaction. Then
+  a rollback of the entity leaves an `enqueued` run whose job will find no entity; guard the
+  first step, or keep runs in the primary database when transactional creation matters.
+
+## 2. `wake_up`, `resume!`, `cancel!` inside a transaction
+
+- Each is one status-guarded `UPDATE` on the run row. It joins the caller's transaction like any
+  other write.
+- The re-enqueue of the parked job happens after all transactions commit. Inside a rolled-back
+  transaction nothing is enqueued and the status update is undone.
+- A guarded update that matches zero rows raises (`NotLive`, `NotResumable`, `NotCancellable`,
+  `NotWaiting`). Re-find the run right before the call; do not use a run loaded minutes earlier.
+- `on_conflict: :replace` is `cancel!` of the live run plus the new run's row in one
+  transaction; a wake of the cancelled run is a no-op.
+
+## 3. Writes the gem makes while the job runs
+
+- Every step boundary and every checkpoint (`step.set!`, `step.advance!`, `step.checkpoint!`) is
+  a committed write to the run and step rows, outside your step's transaction.
+- Do not wrap a whole step body in one long transaction and checkpoint inside it: the
+  checkpoint commits on its own connection state, but your work does not, and a crash leaves the
+  cursor ahead of the data. Commit per item, then checkpoint.
+- Every run-row write is guarded on `status = 'running'`. A `cancel!` from elsewhere makes the
+  next checkpoint raise `ActiveJob::Durable::Cancelled`; the step body stops there.
+- Attribute changes (`self.verdict = ...`) are written with the next checkpoint or step
+  boundary, not immediately.
+
+## 4. Step bodies
+
+- At-least-once per step. Make step bodies idempotent: `find_or_create_by`, `upsert_all`, a
+  guard on a fact column (`return if payout.completed?`).
+- A step that both writes the entity and calls an external service: write the external call's
+  result to the entity in the same step, and check the entity first on re-run.
+- Isolated steps run in separate executions; a shared instance variable does not survive. Set
+  `@record = record` at the top of `perform`, which re-runs on every execution, or use
+  `attribute`.
+
+## 5. Locks
+
+- `with_lock` on the entity plus `perform_later` inside it is fine and recommended for
+  start/cancel pairs (cancel an account: create the cancellation, start the run; reactivate:
+  destroy it, cancel the run).
+- Do not hold an entity lock across a step boundary; the step boundary is a separate write and
+  the job may be re-enqueued between steps.
+- SQLite: one writer. Checkpoints are short writes; keep step bodies' transactions short too, or
+  `limits_concurrency` heavy writers as the app already does.
+
+## 6. Tests
+
+Transactional tests wrap each test in a non-joinable transaction, so an app-level
+`transaction do ... end` still commits its savepoint and `after_all_transactions_commit`
+fires; `perform_later` inside `with_lock` enqueues in tests as in production. Verify with
+`assert_enqueued_jobs`. See `testing.md`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ajdc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -10,33 +10,75 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: combustion
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -75,9 +117,41 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- db/durable_schema.rb
+- lib/active_job/continuable/callbacks.rb
+- lib/active_job/continuable/configurable.rb
+- lib/active_job/continuation/callbacks.rb
+- lib/active_job/continuation/rescue_handlers_first.rb
+- lib/active_job/durable.rb
+- lib/active_job/durable/args_mapper.rb
+- lib/active_job/durable/config.rb
+- lib/active_job/durable/continuation.rb
+- lib/active_job/durable/execution.rb
+- lib/active_job/durable/housekeeping_job.rb
+- lib/active_job/durable/record.rb
+- lib/active_job/durable/run.rb
+- lib/active_job/durable/step.rb
+- lib/active_job/durable/wake_job.rb
 - lib/ajdc.rb
 - lib/ajdc/railtie.rb
 - lib/ajdc/version.rb
+- lib/generators/ajdc/install/USAGE
+- lib/generators/ajdc/install/install_generator.rb
+- lib/generators/ajdc/install/templates/create_active_job_durable_tables.rb.tt
+- lib/generators/ajdc/install/templates/initializer.rb.tt
+- skills/ajdc/SKILL.md
+- skills/ajdc/examples/README.md
+- skills/ajdc/examples/agent-loop.md
+- skills/ajdc/examples/halting.md
+- skills/ajdc/examples/pipeline.md
+- skills/ajdc/examples/signals.md
+- skills/ajdc/examples/timers.md
+- skills/ajdc/examples/uniqueness.md
+- skills/ajdc/references/api.md
+- skills/ajdc/references/decision-guide.md
+- skills/ajdc/references/installation.md
+- skills/ajdc/references/testing.md
+- skills/ajdc/references/transactions.md
 homepage: https://github.com/palkan/ajdc
 licenses:
 - MIT
@@ -88,6 +162,8 @@ metadata:
   homepage_uri: https://github.com/palkan/ajdc
   source_code_uri: https://github.com/palkan/ajdc
   rubygems_mfa_required: 'true'
+  hyperdrive_targets: activejob
+  hyperdrive_artifacts: skill
 rdoc_options: []
 require_paths:
 - lib