tina4ruby 3.13.104 → 3.13.105

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e628488f2b0de1d7ec0d271cc07562ff66aa22c198adfea5fb2d9f61581987
-  data.tar.gz: 1416a35dac038e0a20befbec32f68d5e2cdd4d160ec440c1c18d40c38a3b2034
+  metadata.gz: 4ab6d7ce15da93e814204665a8690be0cc2ac58dc1152fa75f050b91fcb0c4f0
+  data.tar.gz: 35fc27eb9d71c17a0049d983d34ed6c1584e014338192e5ace087e5e2bec0746
 SHA512:
-  metadata.gz: 118eb151f7ceab9069f13f2e147a81c9e24468fb97d850acddb0054b15acd6e922369c59a83127a09e09605cf8460b0cc606268911325e63651bbda64c315b36
-  data.tar.gz: 6045f620f3e0b1a6f489cd9215b1c8d52dba5ea3eb4f6db15ee768963a763ac6deb51f84e1809ea10de660cd89ad035a8cca06779f3373796ebf455b324631a2
+  metadata.gz: f2e66595ddcf7eca7d498428149ca38a83caf4871d8d5e29e31ef9d72f7f38f2ed9c3afe638ba2891bf9ffda5b00dbbf54883ddc704bf06787f9f06060b0603b
+  data.tar.gz: c45ab7892609d2be7e0b3dc432a8d54bef9dd8281e3594198b9fa93e9170ceeb60372624c69d49978884ef596cb7ff35eeb720216c4d240a176e372ffa33d803

data/CHANGELOG.md

@@ -6,6 +6,26 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.105
+
+Bug release. Route inspection stops touching the app; Firebird's migration
+ledger tolerates whatever case the driver hands back; PHP loses a colon-in-
+filename that broke Windows checkouts.
+
+### Route inspection scans, never boots
+
+- `tina4 routes` now walks canonical route files and never executes the
+  application entrypoint or starts the server. Feature 115 / ADR-0058.
+- Fixes the case where `tina4 routes --override` would boot the app on the
+  same port and kill whatever process was already holding it (tina4-python
+  issue #104).
+
+### Firebird migration ledger is case-agnostic
+
+- `tina4_migration` reads and writes work regardless of the case the
+  Firebird driver returns for the `migration_name` column.
+- Uses the atomic sequence table pattern already in place for other engines.
+
 ## 3.13.103
 
 ### Metrics reports what it can prove

data/lib/tina4/cli.rb

@@ -1013,8 +1013,8 @@ module Tina4
 
     def cmd_routes(_argv = nil)
       require_relative "../tina4"
-      Tina4.initialize!(Dir.pwd)
-      load_routes(Dir.pwd)
+      Tina4::Env.load_env(Dir.pwd)
+      load_routes(Dir.pwd, entrypoints: false)
 
       puts "\nRegistered Routes:"
       puts "-" * 60
@@ -2959,7 +2959,7 @@ module Tina4
 
     # ── shared helpers ────────────────────────────────────────────────────
 
-    def load_routes(root_dir)
+    def load_routes(root_dir, entrypoints: true)
       route_dirs = %w[src/routes routes src/api api src/orm orm]
       route_dirs.each do |dir|
         route_dir = File.join(root_dir, dir)
@@ -2967,7 +2967,10 @@ module Tina4
         Dir.glob(File.join(route_dir, "**/*.rb")).sort.each { |f| load f }
       end
 
-      # Also load app.rb if it exists
+      return unless entrypoints
+
+      # Runtime and console boot load the application entrypoint. Inspection
+      # commands opt out so they can never start a server or take over a port.
       app_file = File.join(root_dir, "app.rb")
       load app_file if File.exist?(app_file)
 

data/lib/tina4/orm.rb

@@ -480,13 +480,25 @@ module Tina4
 
       # Invalidate every cached query that touches this model's table.
       #
-      # Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that
-      # reads this table is busted too (it carries this table's tag), while a
-      # query that never touches this table is left intact. Called after every
-      # ORM write (save/delete/force_delete/restore) so a read-after-write never
-      # serves a stale/deleted row (CACHE-DEC-01).
+      # Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+      # this table is busted too because it carries this table's tag; a query
+      # that never touches this table is left intact), then cascaded to the
+      # DB layer on this model's bound connection so an out-of-band write /
+      # deliberate refresh / race-with-another-process cannot leave stale rows
+      # in db.fetch's persistent cache. Called after every ORM write
+      # (save/delete/force_delete/restore) so a read-after-write never serves
+      # a stale/deleted row (CACHE-DEC-01). 3.13.105 (parity port of PY-06-22)
+      # added the DB-layer cascade — previously the two cache layers disagreed
+      # under TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
       def clear_cache
         query_cache.clear_tag(table_name.to_s.downcase)
+        begin
+          get_db.cache_clear
+        rescue StandardError
+          # A resolvable DB is not guaranteed at every clear_cache call site
+          # (module-import time in odd bootstraps, tests that mutate bindings);
+          # never let a cache-clear crash a save/delete.
+        end
         nil
       end
 

data/lib/tina4/queue.rb

@@ -171,7 +171,14 @@ module Tina4
       @backend.close
     end
 
-    # Get jobs that failed but are still eligible for retry (under max_retries).
+    # Get jobs that failed at least once but are still being retried
+    # (0 < attempts < max_retries). These live in the pending queue under
+    # the auto-retry lifecycle (fail() re-queues them with an incremented
+    # attempts count and a retry_backoff delay) so pop() picks them up
+    # again. They are NOT counted by size("failed") — that alias counts
+    # the dead-letter store, matching dead_letters(). To include retryable-
+    # failed jobs in a total, use size("pending"). Terminal failures are
+    # returned by dead_letters().
     def failed # -> list[dict]
       refuse_operation!("failed()") unless @backend.respond_to?(:failed)
       @backend.failed(@topic, max_retries: @max_retries)
@@ -179,13 +186,24 @@ module Tina4
 
     # Retry a specific failed job by ID, or all dead-letter jobs if no id given.
     # Returns true if re-queued.
+    #
+    # The no-arg branch is materialised by the backend (LiteBackend#retry_job
+    # iterates every dead-letter file with .each, MongoBackend materialises
+    # find(...).to_a before iterating) — no generator inside any() /
+    # short-circuit reduce can silently leave dead letters behind (parity port
+    # of PY-12-04, 3.13.105).
     def retry(job_id = nil, delay_seconds: 0) # -> bool
       refuse_operation!("retry()") unless @backend.respond_to?(:retry_job)
       @backend.retry_job(@topic, job_id: job_id, delay_seconds: delay_seconds)
     end
 
-    # Get dead letter jobs — messages that exceeded max retries.
-    # Pass max_retries to override the queue's default.
+    # Get jobs that exceeded max_retries — terminal failures.
+    #
+    # Same set counted by size("failed") / size("dead") / size("dead_letter")
+    # (three aliases for the dead-letter store). To LIST retryable-but-
+    # attempted jobs (attempts > 0 AND attempts < max_retries) that are still
+    # being auto-retried, use failed() — those live in the pending queue and
+    # are NOT dead letters. Pass max_retries to override the queue's default.
     def dead_letters(max_retries: nil) # -> list[dict]
       refuse_operation!("dead_letters()") unless @backend.respond_to?(:dead_letters)
       @backend.dead_letters(@topic, max_retries: max_retries || @max_retries)
@@ -328,9 +346,21 @@ module Tina4
       attach(@backend.find_by_id(topic || @topic, id))
     end
 
-    # Get the number of messages by status.
-    # status: "pending" (default) counts pending messages in the topic queue.
-    # status: "failed" or "dead" counts messages in the dead_letter directory.
+    # Count jobs by status.
+    #
+    # "pending" counts jobs waiting to be popped — INCLUDES retryable-but-
+    # attempted ones, because they live in the pending queue under the
+    # auto-retry lifecycle (see failed()).
+    # "reserved" counts jobs a consumer has popped but not yet
+    # completed/failed (in-flight against the visibility timeout).
+    # "completed" counts jobs the consumer has finished successfully
+    # (0 on the lite/file backend which deletes on complete; backends that
+    # track completion expose completed_count).
+    # "failed", "dead", "dead_letter" are ALIASES that all count the
+    # dead-letter store — jobs whose attempts >= max_retries and that have
+    # given up. Use dead_letters() to list them. Retryable-but-attempted
+    # jobs are NOT counted by size("failed"); use failed() to list them or
+    # size("pending") to include them in a total.
     def size(status: "pending")
       case status.to_s
       when "pending"

data/lib/tina4/queue_backends/lite_backend.rb

@@ -164,9 +164,26 @@ module Tina4
 
       # Explicit re-queue requested by the caller (job.retry()). Always
       # re-enqueues regardless of the retry limit — a manual override, distinct
-      # from the automatic fail() path. Increments attempts, clears the error.
+      # from the automatic fail() path. Cleans up BOTH the reservation record
+      # and any dead-letter file for this id, so a caller who iterates
+      # dead_letters and calls job.retry on each doesn't leave the dead-letter
+      # directory carrying duplicates (3.13.105, parity port of PY-12-05).
+      # Aligns with retry_job(id) which had always unlinked the dead-letter
+      # file — two spellings of the same intent that previously diverged.
+      # Increments attempts, clears the error.
       def retry(job, delay_seconds: 0)
         clear_reservation(job.topic, job.id)
+        # Drop any dead-letter file for this id BEFORE the re-queue: if this
+        # job came from dead_letters it lives in @dead_letter_dir and would
+        # otherwise stay on disk while a fresh pending file appears in
+        # topic_path, so the next dead_letters call reports the job again
+        # and a consumer processes it twice.
+        begin
+          File.unlink(job_file(@dead_letter_dir, job.id))
+        rescue Errno::ENOENT
+          # No dead-letter file for this id (manual .retry on a live job) —
+          # nothing to clean up.
+        end
         job.attempts += 1
         requeue_job(job, delay_seconds: delay_seconds, error: nil)
       end

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -291,8 +291,19 @@ module Tina4
                   .map { |doc| job_from_doc(doc) }
       end
 
+      # Delete every doc in this queue whose status matches.
+      #
+      # 3.13.105 (parity port): route the dead-letter statuses ("dead",
+      # "failed", "dead_letter") to the ".dead_letter" topic namespace where
+      # they actually live — pre-fix, purge("dead") delete_many'd on
+      # {topic: topic, status: "dead"}, matching zero docs and silently
+      # returning 0 while the dead letters sat untouched in the sibling
+      # namespace. Every path scopes by status so a purge never nukes docs it
+      # was not asked to remove, and every path returns deleted_count so a
+      # caller can log/assert what was purged.
       def purge(topic, status)
-        result = collection.delete_many(topic: topic, status: status.to_s)
+        namespace = dead_status?(status) ? "#{topic}.dead_letter" : topic
+        result = collection.delete_many(topic: namespace, status: status.to_s)
         result.deleted_count
       end
 
@@ -326,20 +337,31 @@ module Tina4
         result.modified_count
       end
 
-      # Move ONE dead-lettered job back to its main topic as pending.
-      # Returns true when a job was revived, false when the id was not found.
+      # Move dead-lettered jobs back to their main topic as pending.
+      #
+      # With +job_id+, revives that ONE dead letter and returns true when
+      # found (false otherwise). With no id, iterates every dead letter for
+      # the topic and revives ALL — materialised into an array before
+      # reducing, so a truthy first result never short-circuits away the
+      # rest (the class of bug the parity port of PY-12-04 pins). Ruby's
+      # dead-letter model stores the SAME document with topic flipped to
+      # "<topic>.dead_letter", so reviving is the reverse in-place update:
+      # flip the topic back, reset status/available_at/error. Mirrors
+      # LiteBackend#retry_job.
       def retry_job(topic, job_id: nil, delay_seconds: 0)
         filter = { topic: "#{topic}.dead_letter", status: "dead" }
         filter[:_id] = job_id if job_id
-        doc = collection.find(filter).first
-        return false unless doc
+        docs = collection.find(filter).to_a
+        return false if docs.empty?
 
         available = delay_seconds.to_f > 0 ? (Time.now.utc + delay_seconds.to_f) : Time.now.utc
-        collection.update_one(
-          { _id: doc["_id"] },
-          { "$set" => { topic: topic, status: "pending", error: nil,
-                        reserved_at: nil, available_at: available } }
-        )
+        docs.each do |doc|
+          collection.update_one(
+            { _id: doc["_id"] },
+            { "$set" => { topic: topic, status: "pending", error: nil,
+                          reserved_at: nil, available_at: available } }
+          )
+        end
         true
       end
 
@@ -358,6 +380,12 @@ module Tina4
 
       private
 
+      DEAD_STATES = %w[failed dead dead_letter].freeze
+
+      def dead_status?(status)
+        DEAD_STATES.include?(status.to_s)
+      end
+
       # A stored document as a plain Hash with string keys, CARRYING attempts
       # and error.
       #

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.104"
+  VERSION = "3.13.105"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.104
+  version: 3.13.105
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack