tina4ruby 3.13.41 → 3.13.43

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74de2870c01871240bb98d6ceeb66cd5bc5bf05c6e1c4e82d19a198d585d83e6
-  data.tar.gz: 9d548edf025f53d6547216f3a421d9215eb893cfda89131c342910ebc2c820bb
+  metadata.gz: 209245b1743578b21530e31feb670940f068cc911725fff1b2a59ee6d8335e10
+  data.tar.gz: '059d0fde8d4fbc57db9e4aa408d0dd31f71b1c8065d5041258a8a502017ce7ab'
 SHA512:
-  metadata.gz: 3d2db7a1fc7dfcb95848dbc80c4f76664800bd6692a460667f5dfcbb59cb59fcba101737773c4eda4b4731275f735b4ef494164388869ded0849d29bb6de3804
-  data.tar.gz: 49e9c4742313a45ebb610cc5840c1b277915db9b1a5eb3a98dcb5b680a93d336b5b1d846698a9ec9121d2d722c905b8e0261b2532d050d0d7805b27a6c2c5228
+  metadata.gz: 30babc583e40444ec46069088e1af2a94f0485546b585530ccda22cca2a8ba29fafca3464bd08845fd1d9f88e92342533f2c58a82b89f38a517fce607096f905
+  data.tar.gz: 84960f5d44cb50d7ec4d8dd31a6645e10640526aaf6c9f777e81c7376a43290a6027d33d903f45a317f369834eee59518ec9d215d05e8933c820e5d3020ae49e

data/lib/tina4/queue.rb

@@ -305,6 +305,10 @@ module Tina4
         config = resolve_mongo_config
         config[:visibility_timeout] = vt
         config[:max_retries] = max_retries
+        # Thread retry_backoff through so a failed/retried job's available_at is
+        # reset to now (or now + retry_backoff) instead of being stranded for the
+        # full visibility window (Bug B).
+        config[:retry_backoff] = retry_backoff
         Tina4::QueueBackends::MongoBackend.new(config)
       else
         raise ArgumentError, "Unknown queue backend: #{chosen.inspect}. Use 'lite', 'rabbitmq', 'kafka', or 'mongodb'."

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -5,11 +5,16 @@ module Tina4
     class MongoBackend
       # Reservation/visibility + retry policy (settable so a Queue can propagate
       # its own onto a backend instance passed directly — legacy path).
-      attr_accessor :visibility_timeout, :max_retries
+      attr_accessor :visibility_timeout, :max_retries, :retry_backoff
 
       def initialize(options = {})
         require "mongo"
         @max_retries = options[:max_retries] || 3
+        # Seconds to delay a requeued (failed/retried) job before it is eligible
+        # again. Default 0 = available on the very next dequeue, so a fail()'d job
+        # retries immediately (matching the lite backend) instead of waiting out
+        # the visibility window.
+        @retry_backoff = (options[:retry_backoff] || 0).to_f
 
         uri = options[:uri] || ENV["TINA4_MONGO_URI"]
         host = options[:host] || ENV.fetch("TINA4_MONGO_HOST", "localhost")
@@ -134,10 +139,58 @@ module Tina4
         collection.delete_one(_id: message.id)
       end
 
+      # Terminal success — the job is done and removed (mirrors the lite
+      # backend's complete()). Without this, job.complete() was a no-op on
+      # MongoDB and the document stayed "processing" forever.
+      def complete(message)
+        collection.delete_one(_id: message.id)
+      end
+
+      # Record a failed attempt (mirrors the lite backend + the Python Mongo
+      # adapter). Increments attempts; while attempts < max_retries the job is
+      # re-queued to pending (visible again immediately, or after retry_backoff),
+      # otherwise it is dead-lettered. The Queue/Job lifecycle expects fail() to
+      # route the requeue here — previously MongoBackend had no fail(), so
+      # job.fail() degraded to in-memory bookkeeping and never touched Mongo.
+      def fail(job, error = "")
+        job.attempts += 1
+        if job.attempts >= @max_retries
+          collection.find_one_and_update(
+            { _id: job.id },
+            { "$set" => { status: "dead", topic: "#{job.topic}.dead_letter",
+                          error: error, reserved_at: nil } },
+            upsert: true
+          )
+        else
+          requeue_with_error(job, error)
+        end
+      end
+
+      # 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.
+      def retry(job, delay_seconds: 0)
+        job.attempts += 1
+        backoff = delay_seconds.to_f > 0 ? delay_seconds.to_f : @retry_backoff
+        collection.find_one_and_update(
+          { _id: job.id },
+          { "$set" => { status: "pending", error: nil, reserved_at: nil,
+                        available_at: requeue_available_at(backoff) } },
+          upsert: true
+        )
+      end
+
       def requeue(message)
+        # Reset available_at so the requeued job is visible again right away (or
+        # after retry_backoff) and clear reserved_at. dequeue() pushed
+        # available_at out to the reservation expiry; leaving it there stranded a
+        # requeued job for the full visibility window instead of retrying it on
+        # the next pop().
         collection.find_one_and_update(
           { _id: message.id },
-          { "$set" => { status: "pending" }, "$inc" => { attempts: 1 } },
+          { "$set" => { status: "pending", reserved_at: nil,
+                        available_at: requeue_available_at(@retry_backoff) },
+            "$inc" => { attempts: 1 } },
           upsert: true
         )
       end
@@ -172,7 +225,11 @@ module Tina4
       def retry_failed(topic, max_retries: 3)
         result = collection.update_many(
           { topic: topic, status: "failed", attempts: { "$lt" => max_retries } },
-          { "$set" => { status: "pending" } }
+          # Reset available_at so re-queued failed jobs are visible again — they
+          # were reserved with available_at in the future at dequeue. Clear
+          # reserved_at too. (Same Bug B reason as requeue/fail.)
+          { "$set" => { status: "pending", error: nil, reserved_at: nil,
+                        available_at: requeue_available_at(@retry_backoff) } }
         )
         result.modified_count
       end
@@ -183,6 +240,31 @@ module Tina4
 
       private
 
+      # Re-queue a failed job to pending, carrying the failure reason and
+      # resetting available_at (now, or now + retry_backoff) + clearing
+      # reserved_at so the next dequeue picks it up.
+      def requeue_with_error(job, error)
+        collection.find_one_and_update(
+          { _id: job.id },
+          # Persist the incremented attempt count (fail() already did job.attempts
+          # += 1). Without this the doc's attempts stayed at its old value, so the
+          # next dequeue surfaced a stale count, fail()'s attempts >= max_retries
+          # check never tripped, and the job was re-queued forever instead of
+          # dead-lettering.
+          { "$set" => { status: "pending", error: error, reserved_at: nil,
+                        attempts: job.attempts,
+                        available_at: requeue_available_at(@retry_backoff) } },
+          upsert: true
+        )
+      end
+
+      # available_at for a re-queued job: now (immediately retryable) or
+      # now + backoff when a backoff is configured.
+      def requeue_available_at(backoff)
+        b = (backoff || 0).to_f
+        b > 0 ? (Time.now.utc + b) : Time.now.utc
+      end
+
       def collection
         @db[@collection_name]
       end

data/lib/tina4/swagger.rb

@@ -3,23 +3,68 @@ require "json"
 
 module Tina4
   module Swagger
+    # Process-wide registries for security schemes and reusable component
+    # schemas declared programmatically (add_security_scheme / add_schema).
+    # Kept module-level so app bootstrap can register before any generate()
+    # call; reset_registry clears them (tests).
+    @registered_schemes = {}
+    @registered_schemas = {}
+
     class << self
+      # ── Programmatic registries ────────────────────────────────────
+
+      # Register a named OpenAPI security scheme (e.g. an oauth2 scheme with
+      # scopes, or a custom apiKey). Call at app bootstrap, before generate().
+      #
+      #   Tina4::Swagger.add_security_scheme("oauth2", {
+      #     "type" => "oauth2",
+      #     "flows" => { "clientCredentials" => {
+      #       "tokenUrl" => "https://api.example.com/oauth/token",
+      #       "scopes" => { "read:users" => "Read users", "write:users" => "Write users" }
+      #     } }
+      #   })
+      def add_security_scheme(name, definition)
+        @registered_schemes[name.to_s] = definition
+      end
+
+      # Register a reusable component schema, referenceable via
+      # swagger_meta[:request_schema] / [:response_schemas] or a raw $ref.
+      def add_schema(name, schema)
+        @registered_schemas[name.to_s] = schema
+      end
+
+      # Clear the security-scheme and schema registries (test helper).
+      def reset_registry
+        @registered_schemes = {}
+        @registered_schemas = {}
+      end
+
       def generate(routes = [])
         spec = base_spec
         route_list = routes.empty? ? Tina4::Router.routes : routes
         # Accumulators shared across routes: ORM models referenced
-        # (-> components.schemas), tags used (-> top-level tags[]), seen
-        # operationIds (de-dup — OpenAPI requires them unique).
-        ctx = { models: {}, used_tags: [], seen_ids: [] }
+        # (-> components.schemas), registered custom-schema names referenced
+        # by routes, tags used (-> top-level tags[]), seen operationIds
+        # (de-dup — OpenAPI requires them unique).
+        ctx = { models: {}, ref_schemas: [], used_tags: [], seen_ids: [],
+                schemes: spec["components"]["securitySchemes"] }
         route_list.each do |route|
+          next unless included?(route.path)
+
           add_route_to_spec(spec, route, ctx)
         end
 
-        unless ctx[:models].empty?
-          spec["components"]["schemas"] = {}
+        unless ctx[:models].empty? && ctx[:ref_schemas].empty?
+          spec["components"]["schemas"] ||= {}
           ctx[:models].each do |name, klass|
             spec["components"]["schemas"][name] = model_schema(klass)
           end
+          ctx[:ref_schemas].each do |name|
+            next unless @registered_schemas.key?(name)
+            next if spec["components"]["schemas"].key?(name)
+
+            spec["components"]["schemas"][name] = @registered_schemas[name]
+          end
         end
         spec["tags"] = ctx[:used_tags].map { |t| { "name" => t } } unless ctx[:used_tags].empty?
 
@@ -63,22 +108,88 @@ module Tina4
         end
 
         {
-          "openapi" => "3.0.3",
+          "openapi" => resolve_openapi_version(ENV["TINA4_SWAGGER_OPENAPI"]),
           "info" => info,
           "servers" => servers,
           "paths" => {},
           "components" => {
-            "securitySchemes" => {
-              "bearerAuth" => {
-                "type" => "http",
-                "scheme" => "bearer",
-                "bearerFormat" => "JWT"
-              }
-            }
+            "securitySchemes" => security_schemes
           }
         }
       end
 
+      # OpenAPI version — default 3.0.3 for broad tool compatibility; opt in to
+      # 3.1.0 via TINA4_SWAGGER_OPENAPI=3.1 (the schemas this generator emits
+      # are valid in both dialects).
+      def resolve_openapi_version(val)
+        v = val.to_s.strip
+        return "3.0.3" if v.empty?
+        return "3.1.0" if %w[3.1 3.1.0].include?(v)
+        return "3.0.3" if %w[3.0 3.0.3].include?(v)
+
+        v # honour an explicit full version verbatim
+      end
+
+      # Resolve components.securitySchemes from defaults + env + registry.
+      def security_schemes
+        schemes = {
+          "bearerAuth" => {
+            "type" => "http",
+            "scheme" => "bearer",
+            # Default bearer format (the built-in bearerAuth scheme). JWT unless an
+            # API uses opaque tokens / API keys as the bearer (e.g. sk_live_...).
+            "bearerFormat" => ENV["TINA4_SWAGGER_BEARER_FORMAT"] || "JWT"
+          }
+        }
+
+        # Optional apiKey scheme — emitted as "apiKeyAuth" when a header/query
+        # name is configured (e.g. X-Api-Key).
+        api_key_name = ENV["TINA4_SWAGGER_API_KEY_NAME"]
+        if api_key_name && !api_key_name.empty?
+          api_key_in = ENV["TINA4_SWAGGER_API_KEY_IN"] || "header"
+          api_key_in = "header" unless %w[header query cookie].include?(api_key_in)
+          schemes["apiKeyAuth"] = {
+            "type" => "apiKey",
+            "name" => api_key_name,
+            "in" => api_key_in
+          }
+        end
+
+        # Registered schemes win (let an app override bearerAuth or add oauth2).
+        @registered_schemes.each { |name, defn| schemes[name] = defn }
+        schemes
+      end
+
+      # Which scheme secured routes use by default when no per-route security
+      # is declared.
+      def default_scheme
+        scheme = ENV["TINA4_SWAGGER_DEFAULT_SCHEME"]
+        scheme && !scheme.empty? ? scheme : "bearerAuth"
+      end
+
+      # Path filtering. Framework internals (/swagger, /__dev) are ALWAYS
+      # excluded; then TINA4_SWAGGER_INCLUDE (allow-list) / _EXCLUDE apply.
+      def included?(raw_path)
+        ["/swagger", "/__dev"].each do |internal|
+          return false if raw_path == internal || raw_path.start_with?("#{internal}/")
+        end
+
+        includes = csv(ENV["TINA4_SWAGGER_INCLUDE"])
+        unless includes.empty?
+          matched = includes.any? { |p| raw_path == p || raw_path.start_with?(p) }
+          return false unless matched
+        end
+
+        excludes = csv(ENV["TINA4_SWAGGER_EXCLUDE"])
+        return false if excludes.any? { |p| raw_path == p || raw_path.start_with?(p) }
+
+        true
+      end
+
+      def csv(val)
+        val.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
       # servers[] — TINA4_SWAGGER_SERVERS (comma-separated) for a multi-server
       # list, else SWAGGER_DEV_URL, else the relative "/" default.
       def servers
@@ -124,31 +235,135 @@ module Tina4
           "description" => meta[:description] || "",
           "tags" => tags,
           "parameters" => build_parameters(route),
-          "responses" => meta[:responses] || model_or_default_responses(ref, meta[:model_list])
+          "responses" => build_responses(meta, ref, ctx)
         }
 
         operation["deprecated"] = true if meta[:deprecated]
 
-        if route.auth_handler
-          operation["security"] = [{ "bearerAuth" => [] }]
-        end
+        security = resolve_security(meta, route, ctx[:schemes])
+        operation["security"] = security unless security.nil?
 
         if %w[post put patch].include?(method)
-          operation["requestBody"] = build_request_body(method, meta, ref)
+          operation["requestBody"] = build_request_body(method, meta, ref, ctx)
         end
 
         spec["paths"][path][method] = operation
       end
 
-      def build_request_body(_method, meta, ref)
+      # Auth — explicit per-route security wins (an explicit "public"/[] = no
+      # security); otherwise a secured route gets the default scheme. Returns
+      # nil when the route declares nothing and is not secured (omit the key).
+      def resolve_security(meta, route, schemes)
+        if meta.key?(:security)
+          reqs = normalize_security(meta[:security], meta[:scopes])
+          return reqs.empty? ? [] : sanitize_security(reqs, schemes)
+        end
+
+        return sanitize_security([{ default_scheme => [] }], schemes) if route.auth_handler
+
+        nil
+      end
+
+      # Normalize swagger_meta[:security] to an OpenAPI security-requirement list.
+      #
+      #   security: "oauth2", scopes: ["read"]   -> [{"oauth2" => ["read"]}]
+      #   security: { "bearerAuth" => [] }        -> [{"bearerAuth" => []}]   (AND within one map)
+      #   security: [{"oauth2"=>["read"]}, {...}] -> verbatim (OR across maps)
+      #   security: "public" / []                 -> [] (explicitly no auth)
+      def normalize_security(value, scopes)
+        scope_list = Array(scopes).map(&:to_s)
+        if value.nil? || value == [] || (value.is_a?(String) && %w[public none].include?(value))
+          return []
+        end
+
+        case value
+        when String
+          [{ value => scope_list }]
+        when Hash
+          [value.each_with_object({}) { |(k, v), h| h[k.to_s] = Array(v).map(&:to_s) }]
+        when Array
+          value.map { |req| req.each_with_object({}) { |(k, v), h| h[k.to_s] = Array(v).map(&:to_s) } }
+        else
+          []
+        end
+      end
+
+      # Keep a security-requirement list spec-valid: scopes are allowed only on
+      # oauth2/openIdConnect schemes; everything else gets an empty array
+      # (OpenAPI requires that for http/apiKey).
+      def sanitize_security(reqs, schemes)
+        scope_ok = %w[oauth2 openIdConnect]
+        reqs.map do |req|
+          req.each_with_object({}) do |(name, scopes), clean|
+            stype = (schemes[name] || {})["type"]
+            clean[name] = scope_ok.include?(stype) ? Array(scopes) : []
+          end
+        end
+      end
+
+      def build_request_body(_method, meta, ref, ctx)
         return meta[:request_body] if meta[:request_body]
 
+        # Registered custom request schema ($ref) wins over the ORM-model ref.
+        if (req_schema = meta[:request_schema])
+          name, content_type = request_schema_parts(req_schema)
+          ctx[:ref_schemas] << name unless ctx[:ref_schemas].include?(name)
+          content = { "schema" => { "$ref" => "#/components/schemas/#{name}" } }
+          content["example"] = meta[:example] if meta[:example]
+          return { "content" => { content_type => content } }
+        end
+
         schema = ref ? { "$ref" => ref } : { "type" => "object" }
         content = { "schema" => schema }
         content["example"] = meta[:example] if meta[:example]
         { "content" => { "application/json" => content } }
       end
 
+      # swagger_meta[:request_schema] accepts "Name" or { name:, content_type: }.
+      def request_schema_parts(req_schema)
+        if req_schema.is_a?(Hash)
+          [(req_schema[:name] || req_schema["name"]).to_s,
+           (req_schema[:content_type] || req_schema["content_type"] || "application/json").to_s]
+        else
+          [req_schema.to_s, "application/json"]
+        end
+      end
+
+      def build_responses(meta, ref, ctx)
+        return meta[:responses] if meta[:responses]
+
+        responses = model_or_default_responses(ref, meta[:model_list])
+
+        # Registered response schemas ($ref) — explicit and authoritative.
+        if (resp_schemas = meta[:response_schemas])
+          resp_schemas.each do |status, spec|
+            name, is_list = response_schema_parts(spec)
+            ctx[:ref_schemas] << name unless ctx[:ref_schemas].include?(name)
+            sref = "#/components/schemas/#{name}"
+            schema = is_list ? { "type" => "array", "items" => { "$ref" => sref } } : { "$ref" => sref }
+            responses[status.to_s] = {
+              "description" => status.to_s.start_with?("2") ? "Successful response" : "Response",
+              "content" => { "application/json" => { "schema" => schema } }
+            }
+          end
+        end
+
+        responses
+      end
+
+      # A response-schema entry is "Name", { name:, list: } or [name, is_list].
+      def response_schema_parts(spec)
+        case spec
+        when Hash
+          [(spec[:name] || spec["name"]).to_s,
+           !!(spec[:list] || spec["list"] || spec[:is_list] || spec["is_list"])]
+        when Array
+          [spec[0].to_s, !!spec[1]]
+        else
+          [spec.to_s, false]
+        end
+      end
+
       def model_or_default_responses(ref, model_list)
         return default_responses unless ref
 

data/lib/tina4/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.41
+  version: 3.13.43
 platform: ruby
 authors:
 - Tina4 Team