jetstream_bridge 7.1.0 → 7.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 290f604d47d1605f6c2b2abcde100159327a7418b103c0c054b0b92f5e7fbf56
-  data.tar.gz: 485e9cf4070d9671a1994ffbde32ab8ca6e41fbfb7d94d8cf571e2e8ec04cd3b
+  metadata.gz: 45dac84dd11b563f4f5b0b3d52d85722fdb5b7900923d85f7d6cb7af9b0fad95
+  data.tar.gz: a53400f90050c039fa8ac72109a99e3778911200fab983efa6f18549bcf5620f
 SHA512:
-  metadata.gz: a1a17ed6a75d8f9b32de3efbe23da1797824c4e846c0d4d73ee1014d9ea20048367088cfaabd3f9a02179314090741237d21dffc0c618a429a47510597bb1ed8
-  data.tar.gz: f3ae4a9e9b256f4dfa1d1e84a32d66140ae01c52d07f21b8fac7976c61bb76a81cb83a53aae6631af9c0affa81eb24d81b7167ebb18875489e398f7869ebd2d6
+  metadata.gz: 9e1790cb302107920d71736110db8bc19ae08ac111725614bb4221c73daddf4a992fea8c5c9913cc8dfeea7ebb4bcad359d189e691cd6cf45c1e7bb516b708c1
+  data.tar.gz: 60ee52e1c6943c8fb0c95cb7ea7f2b12d18d914fd2f03981134deaf6c5bef95680671d25ed66585914299216e70fc25f924dcf66925da7076687f95e6ee9b29d

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.1.2] - 2026-02-11
+
+### Fixed
+
+- **Skip all JS.API calls when `auto_provision=false`** - `ensure_consumer!` and `auto_create_consumer_on_error` no longer issue `stream_info`, `consumer_info`, or `add_consumer` calls when `auto_provision=false`. This fixes failures in restricted NATS accounts where `$JS.API` permissions are not granted and the stream/consumer are pre-provisioned by an admin.
+
+### Changed
+
+- **Restricted permissions docs** - Added missing `$JS.ACK.{stream}.{consumer}.>` publish permissions to all permission examples. Without this permission, consumers cannot acknowledge messages and they are redelivered until `max_deliver` is exhausted.
+
+## [7.1.1] - 2026-02-02
+
+### Changed
+
+- Fail-fast consumer provisioning: when running in push mode with `auto_provision=false`, the bridge now raises `ConsumerProvisioningError` instead of silently skipping consumer setup, preventing idle workers when the durable is missing.
+- Permission-aware creation: consumer creation now surfaces `ConsumerProvisioningError` on permissions violations (pull or push mode), guiding operators to grant the minimal `$JS.API` rights or pre-provision the durable.
+
+### Added
+
+- New `ConsumerProvisioningError` topology error for clearer operator feedback when consumer setup cannot proceed.
+
 ## [7.1.0] - 2026-02-01
 
 ### Added

data/docs/RESTRICTED_PERMISSIONS.md

@@ -31,7 +31,7 @@ When you cannot modify NATS server permissions, you have **two options**:
 
 - **No JetStream API permissions required** at runtime
 - Messages delivered automatically to a subscription subject
-- Simpler permission model: only needs subscribe permission on delivery subject
+- Simpler permission model: only needs subscribe on delivery subject + publish on `$JS.ACK` for acks
 - Best for restricted permission environments
 
 For both options, you need to:
@@ -82,7 +82,8 @@ end
 # NATS user permissions (e.g., pwas user)
 publish: {
   allow: [
-    "pwas.>",  # Your business subjects only
+    "pwas.>",                                                    # Your business subjects
+    "$JS.ACK.pwas-heavyworth-sync.pwas-workers.>",              # Ack/nak messages (required)
   ]
 }
 subscribe: {
@@ -92,7 +93,7 @@ subscribe: {
 }
 ```
 
-**No `$JS.API.*` or `_INBOX.>` permissions needed!**
+**No `$JS.API.*` or `_INBOX.>` permissions needed!** However, `$JS.ACK` publish permission is required for the consumer to acknowledge messages. Without it, messages will be redelivered until `max_deliver` is exhausted.
 
 ### Provisioning Push Consumers
 
@@ -122,11 +123,11 @@ nats consumer add pwas-heavyworth-sync pwas-workers \
 - Topology: **one shared stream per app pair**, with one durable consumer per app (each filters the opposite direction). Pre-provision via `bundle exec rake jetstream_bridge:provision` or NATS CLI.
 - NATS permissions for runtime creds:
   - **Pull consumers** (default):
-    - publish allow: `">"` (or narrowed to your business subjects) and `$JS.API.CONSUMER.MSG.NEXT.{stream_name}.{app_name}-workers`
-    - subscribe allow: `">"` (or narrowed) and `_INBOX.>` (responses for pull consumers)
+    - publish allow: `{app_name}.>`, `$JS.API.CONSUMER.MSG.NEXT.{stream_name}.{app_name}-workers`, and `$JS.ACK.{stream_name}.{app_name}-workers.>`
+    - subscribe allow: `{destination_app}.>` and `_INBOX.>` (responses for pull consumers)
   - **Push consumers** (recommended for restricted environments):
-    - publish allow: `">"` (or narrowed to your business subjects only - e.g., `pwas.>`)
-    - subscribe allow: `">"` (or narrowed to your business subjects only - e.g., `heavyworth.>`)
+    - publish allow: `{app_name}.>` and `$JS.ACK.{stream_name}.{app_name}-workers.>` (ack/nak)
+    - subscribe allow: `{destination_app}.>` (includes delivery subject)
     - No `$JS.API.*` or `_INBOX.>` permissions needed
 - Health check will only report connectivity (stream info skipped).
 
@@ -643,15 +644,15 @@ end
 
 ```conf
 # pwas user
-publish: { allow: ["pwas.>"] }
+publish: { allow: ["pwas.>", "$JS.ACK.pwas-heavyworth-sync.pwas-workers.>"] }
 subscribe: { allow: ["heavyworth.>"] }
 
 # heavyworth user
-publish: { allow: ["heavyworth.>"] }
+publish: { allow: ["heavyworth.>", "$JS.ACK.pwas-heavyworth-sync.heavyworth-workers.>"] }
 subscribe: { allow: ["pwas.>"] }
 ```
 
-**Note:** With push consumers, no `$JS.API.*` or `_INBOX.>` permissions are required.
+**Note:** With push consumers, no `$JS.API.*` or `_INBOX.>` permissions are required. The `$JS.ACK` permission is needed so the consumer can acknowledge (ack/nak) delivered messages.
 
 ---
 
@@ -664,16 +665,17 @@ If you have any influence over NATS permissions, you have two options:
 Request minimal JetStream API permissions:
 
 ```conf
-# Minimal permissions needed for pull consumer
+# Minimal permissions needed for pull consumer (e.g., pwas user)
 publish: {
   allow: [
-    ">",                                   # Your app subjects (narrow if desired)
-    "$JS.API.CONSUMER.MSG.NEXT.{stream_name}.{app_name}-workers",  # Fetch messages (required)
+    "pwas.>",                                                          # Your app subjects
+    "$JS.API.CONSUMER.MSG.NEXT.pwas-heavyworth-sync.pwas-workers",    # Fetch messages (required)
+    "$JS.ACK.pwas-heavyworth-sync.pwas-workers.>",                    # Ack/nak messages (required)
   ]
 }
 subscribe: {
   allow: [
-    ">",                                   # Your app subjects (narrow if desired)
+    "heavyworth.>",                        # Destination app subjects
     "_INBOX.>",                            # Request-reply responses (required)
   ]
 }
@@ -683,16 +685,16 @@ These are read-only operations and don't allow creating/modifying streams or con
 
 ### Option 2: Push Consumers (Recommended)
 
-Use push consumers with business subject permissions only:
+Use push consumers with business subject permissions plus ack:
 
 ```conf
 # For pwas app
-publish: { allow: ["pwas.>"] }
+publish: { allow: ["pwas.>", "$JS.ACK.pwas-heavyworth-sync.pwas-workers.>"] }
 subscribe: { allow: ["heavyworth.>"] }
 
 # For heavyworth app
-publish: { allow: ["heavyworth.>"] }
+publish: { allow: ["heavyworth.>", "$JS.ACK.pwas-heavyworth-sync.heavyworth-workers.>"] }
 subscribe: { allow: ["pwas.>"] }
 ```
 
-**No `$JS.API.*` or `_INBOX.>` permissions required!** This is the simplest and most restrictive permission model.
+**No `$JS.API.*` or `_INBOX.>` permissions required!** The only extra permission beyond business subjects is `$JS.ACK` for acknowledging messages.

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -450,6 +450,14 @@ module JetstreamBridge
     end
 
     def auto_create_consumer_on_error(_error)
+      unless JetstreamBridge.config.auto_provision
+        Logging.info(
+          "Skipping consumer auto-creation (auto_provision=false) for #{@durable}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        return
+      end
+
       Logging.info(
         "Consumer not found error detected, attempting auto-creation for #{@durable}...",
         tag: 'JetstreamBridge::Consumer'

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -28,13 +28,13 @@ module JetstreamBridge
       @desired_cfg
     end
 
-    # Ensure consumer exists, auto-creating if missing.
-    #
-    # @param force [Boolean] Kept for backward compatibility but no longer used.
-    #   Consumers are always auto-created regardless of this parameter.
+    # Ensure consumer exists; skips all JS.API calls when auto_provision is false.
     def ensure_consumer!(**_options)
-      # Always auto-create consumer if it doesn't exist, regardless of auto_provision setting.
-      # auto_provision only controls stream topology creation, not consumer creation.
+      unless @cfg.auto_provision
+        Logging.info("Skipping consumer validation (auto_provision=false); assuming '#{@durable}' exists.",
+                     tag: 'JetstreamBridge::Consumer')
+        return
+      end
       create_consumer_if_missing!
     end
 
@@ -70,15 +70,18 @@ module JetstreamBridge
       false
     end
 
-    # Create consumer only if it doesn't already exist.
-    #
-    # Fails if the stream doesn't exist - streams must be provisioned separately.
-    #
-    # This is a safer alternative to create_consumer! that won't fail
-    # if the consumer was already created by another process.
-    #
+    # Create consumer only if it doesn't already exist. Fails if stream is missing.
     # @raise [StreamNotFoundError] if the stream doesn't exist
     def create_consumer_if_missing!
+      # In restricted environments (push + auto_provision=false), we still want fail-fast semantics.
+      # Attempt creation and raise a clear error so operators know the consumer must be pre-provisioned
+      # or the account must allow the minimal $JS.API consumer permissions.
+      if skip_consumer_management?
+        raise JetstreamBridge::ConsumerProvisioningError,
+              "Consumer '#{@durable}' not ensured because auto_provision=false and push mode is enabled. " \
+              'Provision the consumer with admin credentials or grant minimal consumer create/info permissions.'
+      end
+
       # First, verify stream exists - fail fast with clear error if not
       unless stream_exists?
         raise StreamNotFoundError,
@@ -103,6 +106,8 @@ module JetstreamBridge
     rescue StreamNotFoundError
       raise
     rescue StandardError => e
+      raise ConsumerProvisioningError, permission_error_message(e) if permission_denied?(e)
+
       # If creation fails due to consumer already existing (race condition), that's OK
       msg = e.message.to_s.downcase
       if msg.include?('already') || msg.include?('exists')
@@ -210,6 +215,21 @@ module JetstreamBridge
       config
     end
 
+    def skip_consumer_management?
+      @cfg.push_consumer? && !@cfg.auto_provision
+    end
+
+    def permission_denied?(error)
+      msg = error.message.to_s.downcase
+      msg.include?('permission') || msg.include?('permissions violation')
+    end
+
+    def permission_error_message(error)
+      "Consumer '#{@durable}' could not be ensured due to permissions: #{error.message}. " \
+        'Grant $JS.API.STREAM.INFO/$JS.API.CONSUMER.INFO/$JS.API.CONSUMER.CREATE for the stream, ' \
+        'or pre-provision the consumer with an admin account.'
+    end
+
     def create_consumer!
       @jts.add_consumer(stream_name, **desired_consumer_cfg)
       Logging.info(

data/lib/jetstream_bridge/errors.rb

@@ -67,6 +67,7 @@ module JetstreamBridge
 
   # Topology errors
   class TopologyError < Error; end
+  class ConsumerProvisioningError < TopologyError; end
   class StreamNotFoundError < TopologyError; end
   class SubjectOverlapError < TopologyError; end
   class StreamCreationFailedError < TopologyError; end

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '7.1.0'
+  VERSION = '7.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 7.1.0
+  version: 7.1.2
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-01 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord