tina4ruby 3.13.104 → 3.13.107

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e628488f2b0de1d7ec0d271cc07562ff66aa22c198adfea5fb2d9f61581987
-  data.tar.gz: 1416a35dac038e0a20befbec32f68d5e2cdd4d160ec440c1c18d40c38a3b2034
+  metadata.gz: ab8e75446e8ed41f28be0078b1f16de1e1c0be39ff83cefea98f2a5cc9a78cc2
+  data.tar.gz: b8d786867f6a37c87bbc0e242a615c7df8962ae8fd188d8bb8c381061ecba319
 SHA512:
-  metadata.gz: 118eb151f7ceab9069f13f2e147a81c9e24468fb97d850acddb0054b15acd6e922369c59a83127a09e09605cf8460b0cc606268911325e63651bbda64c315b36
-  data.tar.gz: 6045f620f3e0b1a6f489cd9215b1c8d52dba5ea3eb4f6db15ee768963a763ac6deb51f84e1809ea10de660cd89ad035a8cca06779f3373796ebf455b324631a2
+  metadata.gz: 7badcea95d972dfbc0171ed400722626d7d6565ff1b9328b1183dcedebe591c2c4fb2510fa67f8851614c4cd866c5b4db021351fdeea1bd016ce639ea1cb185f
+  data.tar.gz: b22a17a9907c81b37f1c22cb2d40e63c77eb62802f9db33ae749a747aa3d5eac5427523b2d5cec0a7ebda2b5d3c62ba88219fd906f0fab62da748a076f4b01e2

data/CHANGELOG.md

@@ -6,6 +6,94 @@ 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.107
+
+Feature: RBAC role and permission guards (parity across all four frameworks).
+`role(...)` / `can(...)` route guards read the cryptographically-verified JWT
+`roles` / `permissions` claims — OR within a guard, AND by stacking guards, with
+granted-side wildcards (`posts.*`, `*`) and a legacy singular `role` claim coerced
+to a list. A guarded route implies auth: no or invalid token → 401, authenticated
+but unauthorised → 403; the handler never runs on a miss. Feature 138 / ADR-0058.
+
+## 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.
+
+### Queue and ORM audit bugs closed
+
+- **`Model.clear_cache()` cascades to `db.cache_clear()`.** Under both
+  `TINA4_AUTO_CACHING=true` and `TINA4_DB_CACHE=true`, a manual `clear_cache()`
+  used to leave the DB-layer cache holding stale rows (PY-06-22).
+- **`Queue.retry()` revives every dead letter.** The no-arg form used a
+  generator inside `any(...)` and short-circuited after the first success.
+  Now materialised so all N dead letters revive (PY-12-04).
+- **`Job.retry()` unlinks the dead-letter file.** Iterating `dead_letters()`
+  and calling `.retry()` on each used to leave the failed directory carrying
+  every revived job, so the next `dead_letters()` call re-reported them
+  (PY-12-05).
+- **MongoDB `retry_job(id)` searches the dead-letter namespace by data.id,
+  deletes the DL doc, and upserts the original back to pending.** The old
+  filter `{_id, self._topic, "failed"}` could never match a dead letter.
+- **MongoDB `purge(status)` returns `deleted_count`, honours every status, and
+  routes dead/failed/dead_letter aliases to the `.dead_letter` namespace.**
+  Previously returned None and only handled `pending` — via `clear()`, which
+  nuked every doc under the topic regardless of status.
+
+### Test-harness fixes
+
+- **SIGTERM port probe checks both interfaces.** The graceful-shutdown test
+  probed only `0.0.0.0`; on macOS with the framework's default `127.0.0.1`
+  listener holding the port, that bind succeeded and the pre-assertion
+  concluded the port was free. Now probes both interfaces.
+- **MySQL connect-timeout assertion parses the reported elapsed via regex**
+  and checks it against the configured bound instead of the outer clock;
+  mysql-connector's post-abort cleanup adds ~0.7s that the two stopwatches
+  legitimately disagreed on.
+- **AI installer tests sandbox `HOME` per-test.** `install_context()` writes
+  the global skills bundle to `Path.home()/.claude/skills` by design; in the
+  test suite that raced other tests and hit stale root-owned files from prior
+  sudo runs. `monkeypatch.setenv("HOME", ...)` redirects the global install
+  to a throwaway dir.
+
+### Developer skills — announce and 💩
+
+- **Announce before you act.** All four framework developer skills now
+  instruct: say what you are about to do in one line before doing it —
+  Plan / Next / Done. Never write more than two files between announcements.
+  Never run a schema migration, install a dependency, or edit the boot file
+  without a preceding "About to:" line.
+- **💩 stale-skill detection.** All four framework developer skills gained
+  `updated_for_version: 3.13.105` in the frontmatter and a self-check that
+  compares this to the latest published skill version at
+  `https://tina4.com/skills/<name>/version` (never against the project's
+  framework version — the framework version is the developer's call). If a
+  newer skill is available, 💩 rides beside 🤖 on every reply plus a one-time
+  update instruction.
+
+### Doc parity
+
+- `Queue.size()`, `Queue.failed()` and `Queue.dead_letters()` gained matching
+  in-source docstrings across Python, PHP, Ruby and Node: `size("failed")` /
+  `size("dead")` / `size("dead_letter")` are aliases for the dead-letter
+  count (== length of `dead_letters()`); `failed()` lists retryable-but-
+  attempted jobs, counted under `size("pending")`, NOT `size("failed")`.
+
 ## 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/rack_app.rb

@@ -1178,6 +1178,9 @@ module Tina4
         identity = sso.is_a?(Hash) ? sso["identity"] : nil
         if identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
           env["tina4.auth_payload"] = identity
+          deny = rbac_forbidden(route, identity)
+          return deny if deny
+
           return nil
         end
         session_token = session.get("token")
@@ -1207,9 +1210,63 @@ module Tina4
         return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
       end
 
+      # ── RBAC guards (Feature 138): authorization AFTER authentication ──
+      # Auth has passed (401 ruled out above). If the route carries role/
+      # permission guards, the verified payload must satisfy them, else 403.
+      deny = rbac_forbidden(route, env["tina4.auth_payload"])
+      return deny if deny
+
       nil
     end
 
+    # Build a 403 Rack tuple when a route's RBAC guards are not satisfied by the
+    # verified payload, else nil. AND across guard groups, OR within a group.
+    # Roles read the `roles` claim (legacy singular `role` coerced); permissions
+    # read `permissions` with granted-side wildcards. Feature 138 / ADR-0058.
+    def self.rbac_forbidden(route, payload)
+      required_roles = route.respond_to?(:roles) ? Array(route.roles) : []
+      required_perms = route.respond_to?(:perms) ? Array(route.perms) : []
+      return nil if required_roles.empty? && required_perms.empty?
+
+      subject = payload.is_a?(Hash) ? payload : {}
+      roles = _rbac_claim_list(subject, "roles", "role")
+      required_roles.each do |group|
+        return _rbac_forbidden_tuple unless group.any? { |r| roles.include?(r) }
+      end
+      perms = _rbac_claim_list(subject, "permissions", nil)
+      required_perms.each do |group|
+        return _rbac_forbidden_tuple unless group.any? { |req| _rbac_perm_granted(perms, req) }
+      end
+      nil
+    end
+
+    def self._rbac_forbidden_tuple
+      [403, { "content-type" => "application/json" }, [JSON.generate({ error: "Forbidden" })]]
+    end
+
+    # Read a claim as a list of strings; coerce a legacy singular string.
+    def self._rbac_claim_list(subject, key, legacy)
+      out = _rbac_coerce_list(subject[key])
+      out = _rbac_coerce_list(subject[legacy]) if out.empty? && legacy
+      out
+    end
+
+    def self._rbac_coerce_list(val)
+      case val
+      when String then val.empty? ? [] : [val]
+      when Array then val.map(&:to_s).reject(&:empty?)
+      else []
+      end
+    end
+
+    # True if any GRANTED permission satisfies the concrete REQUIRED one.
+    # `*` grants everything; `posts.*` grants `posts.<...>` on the dot boundary.
+    def self._rbac_perm_granted(granted, required)
+      granted.any? do |g|
+        g == "*" || g == required || (g.end_with?(".*") && required.start_with?(g[0..-2]))
+      end
+    end
+
     def self._read_rack_body(env)
       # Route through the capped reader so the running per-chunk upload cap is
       # enforced on the form-token / body path too: an over-limit body raises

data/lib/tina4/router.rb

@@ -8,6 +8,9 @@ module Tina4
     attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
                 :path_regex, :param_names, :template
     attr_accessor :auth_required, :cached
+    # RBAC guard groups (Feature 138 / ADR-0058). Each is an array of arrays:
+    # OR within a group, AND across groups (stacking).
+    attr_reader :roles, :perms
 
     def initialize(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
       @method = method.to_s.upcase.freeze
@@ -23,6 +26,8 @@ module Tina4
       # PY-10-02. Call .no_auth on the route to opt out explicitly.
       @auth_required = %w[POST PUT PATCH DELETE].include?(@method)
       @cached = false
+      @roles = []
+      @perms = []
       @param_names = []
       @path_regex = compile_pattern(@path)
       @param_names.freeze
@@ -42,6 +47,31 @@ module Tina4
       self
     end
 
+    # RBAC: require ONE of the named roles (OR). Reads the verified JWT `roles`
+    # claim. Stack .role/.can for AND. Implies auth. Feature 138 / ADR-0058.
+    # Returns self for chaining: Router.get("/admin") { ... }.role("admin")
+    def role(*names)
+      names = names.flatten.map(&:to_s).reject(&:empty?)
+      unless names.empty?
+        @roles << names
+        @auth_required = true
+      end
+      self
+    end
+
+    # RBAC: require ONE of the named permissions (OR). Reads the verified JWT
+    # `permissions` claim; granted-side wildcards (`posts.*`, `*`) satisfy a
+    # concrete requirement. Stack for AND. Implies auth. Feature 138.
+    # Returns self for chaining: Router.delete("/p") { ... }.can("posts.delete")
+    def can(*permissions)
+      permissions = permissions.flatten.map(&:to_s).reject(&:empty?)
+      unless permissions.empty?
+        @perms << permissions
+        @auth_required = true
+      end
+      self
+    end
+
     # Mark this route as cacheable.
     # Returns self for chaining: Router.get("/path") { ... }.cache
     def cache

data/lib/tina4/version.rb

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

metadata

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