jetstream_bridge 4.5.3 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eda1d1166867a08139af3cb85b6d9aca0765d5444d4a44a37bbb42e8bb519a4f
-  data.tar.gz: 267dba8c88cc5fbff41323ef05b74d3cb6cb9491de38d68b95d2d0fd52a4be03
+  metadata.gz: a1c096b0554cb1a7800a2da1c6ddd39067014bff67169d12d5669159f7253c32
+  data.tar.gz: 5e8ee34b68ad114c72d2e754b8d1985eefe267fe2674e55631f3300dd91438db
 SHA512:
-  metadata.gz: 1614bfc73e26c5e21820a0dab70ff61f61e3d33cbfbe2fec5e60bea44b9b83d377e694ade633e0e495d105bef18ab9d5782911d5f05a8bd3356f8e9cbecf7779
-  data.tar.gz: ab40c30a9f1566cd2bdc7c41a4721b950041052d7365540d517b154bcd34d63cc2daf5dd1042982161a279c8d2940bb7d3df3d536c4a9a796d0abcb907f4a46d
+  metadata.gz: 0bd796f2987bd962f4ea5a871302e2a38ace2027164469c827cdd6e203f722a1a6457aa3dbb003f2095dfb9cef365436ca5cfea8697ec7e59222a631b2768fdf
+  data.tar.gz: a6fc7288fe11ad05d9bd80e853f128fd303cd7d22bf49aff3f0adaa092bec4c8ebcaad63cbf2cb8c1d0ba2ce05e66097483f94b5579b357de67eb877398e1274

data/docs/RESTRICTED_PERMISSIONS.md

@@ -19,7 +19,22 @@ This happens because:
 
 ## Solution Overview
 
-When you cannot modify NATS server permissions, you need to:
+When you cannot modify NATS server permissions, you have **two options**:
+
+### Option 1: Pull Consumers (Default)
+
+- **Requires** permission to publish to `$JS.API.CONSUMER.MSG.NEXT.*`
+- Provides backpressure control and batch fetching
+- Best for high-throughput scenarios
+
+### Option 2: Push Consumers (New)
+
+- **No JetStream API permissions required** at runtime
+- Messages delivered automatically to a subscription subject
+- Simpler permission model: only needs subscribe permission on delivery subject
+- Best for restricted permission environments
+
+For both options, you need to:
 
 0. **Turn off runtime provisioning** so the app never calls `$JS.API.*`:
    - Set `config.auto_provision = false`
@@ -31,13 +46,86 @@ When you cannot modify NATS server permissions, you need to:
 
 ---
 
+## Using Push Consumers (Recommended for Restricted Permissions)
+
+If your NATS user can only publish to specific subjects (e.g., `pwas.*`) and subscribe to specific subjects (e.g., `heavyworth.*`), use **push consumer mode**:
+
+```ruby
+# config/initializers/jetstream_bridge.rb
+JetstreamBridge.configure do |config|
+  config.nats_urls = ENV.fetch("NATS_URLS")
+  config.stream_name = "pwas-heavyworth-sync"
+  config.app_name = "pwas"
+  config.destination_app = "heavyworth"
+  config.auto_provision = false
+
+  # Enable push consumer mode
+  config.consumer_mode = :push
+  # Optional: customize delivery subject (defaults to {destination_subject}.worker)
+  # config.delivery_subject = "heavyworth.sync.pwas.worker"
+
+  config.use_outbox = true
+  config.use_inbox = true
+  config.use_dlq = true
+
+  config.max_deliver = 5
+  config.ack_wait = "30s"
+  config.backoff = %w[1s 5s 15s 30s 60s]
+end
+```
+
+### Required Permissions for Push Consumers
+
+```conf
+# NATS user permissions (e.g., pwas user)
+publish: {
+  allow: [
+    "pwas.>",  # Your business subjects only
+  ]
+}
+subscribe: {
+  allow: [
+    "heavyworth.>",  # Your business subjects (includes delivery subject)
+  ]
+}
+```
+
+**No `$JS.API.*` or `_INBOX.>` permissions needed!**
+
+### Provisioning Push Consumers
+
+When creating the consumer, add `--deliver` to specify the delivery subject:
+
+```bash
+# For pwas app (receives heavyworth -> pwas)
+nats consumer add pwas-heavyworth-sync pwas-workers \
+  --filter "heavyworth.sync.pwas" \
+  --deliver "heavyworth.sync.pwas.worker" \
+  --ack explicit \
+  --deliver all \
+  --max-deliver 5 \
+  --ack-wait 30s \
+  --backoff 1s,5s,15s,30s,60s \
+  --replay instant \
+  --max-pending 25000
+```
+
+**Important:** The delivery subject must match what the app can subscribe to based on its permissions.
+
+---
+
 ## Runtime requirements (least privilege)
 
 - Config: `config.auto_provision = false`, `config.stream_name` set explicitly.
 - 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:
-  - 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)
+  - **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)
+  - **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.>`)
+    - No `$JS.API.*` or `_INBOX.>` permissions needed
 - Health check will only report connectivity (stream info skipped).
 
 ### Topology required
@@ -75,7 +163,7 @@ bundle exec rake jetstream_bridge:provision
 
 This is the easiest way to keep `auto_provision=false` in runtime while still reusing the bridge’s topology logic (subjects, DLQ, overlap guard).
 
-## Option B: Pre-create the Consumer using NATS CLI
+## Option B: Pre-create Consumers using NATS CLI
 
 ### Install NATS CLI
 
@@ -87,7 +175,7 @@ curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh
 brew install nats-io/nats-tools/nats
 ```
 
-### Create the Consumer
+### Create Pull Consumer (Default Mode)
 
 You need to create a durable pull consumer with the exact configuration your app expects. Both apps share a single stream; create one consumer per app (each filters the opposite direction).
 
@@ -97,7 +185,7 @@ You need to create a durable pull consumer with the exact configuration your app
 - **Consumer name**: `{app_name}-workers` (e.g., `pwas-workers`)
 - **Filter subject**: `{destination_app}.sync.{app_name}` (e.g., `heavyworth.sync.pwas`)
 
-**Create consumer command:**
+**Create pull consumer command:**
 
 ```bash
 # Connect using a privileged NATS account
@@ -135,6 +223,35 @@ nats consumer add pwas-heavyworth-sync pwas-workers \
   --max-pending 25000
 ```
 
+### Create Push Consumer (For Restricted Permissions)
+
+Push consumers don't require JetStream API permissions at runtime. Messages are delivered to a subscription subject that the app can subscribe to based on its existing permissions.
+
+**Required values:**
+
+- **Stream name**: `JETSTREAM_STREAM_NAME` (e.g., `pwas-heavyworth-sync`)
+- **Consumer name**: `{app_name}-workers` (e.g., `pwas-workers`)
+- **Filter subject**: `{destination_app}.sync.{app_name}` (e.g., `heavyworth.sync.pwas`)
+- **Delivery subject**: Subject the app can subscribe to (e.g., `heavyworth.sync.pwas.worker`)
+
+**Create push consumer command:**
+
+```bash
+# For pwas app (receives heavyworth -> pwas messages)
+nats consumer add pwas-heavyworth-sync pwas-workers \
+  --filter "heavyworth.sync.pwas" \
+  --deliver "heavyworth.sync.pwas.worker" \
+  --ack explicit \
+  --deliver all \
+  --max-deliver 5 \
+  --ack-wait 30s \
+  --backoff 1s,5s,15s,30s,60s \
+  --replay instant \
+  --max-pending 25000
+```
+
+**Key difference:** The `--deliver` flag specifies where messages are pushed. The app subscribes to this subject directly, without calling `$JS.API.CONSUMER.MSG.NEXT.*`.
+
 **Example using your observed stream (`pwas-heavyworth-sync`) and defaults (shared stream, two consumers):**
 
 ```bash
@@ -451,20 +568,21 @@ Check if the issue is:
 
 ## Example: Production Setup for pwas-api
 
-Based on your logs, here's the exact setup:
+Based on your logs and permission requirements, here's the recommended setup using **push consumers** (no JetStream API permissions needed):
 
 ```bash
-# 1. Provision stream and both consumers (as admin)
+# 1. Provision stream and both push consumers (as admin)
 nats stream add pwas-heavyworth-sync \
   --subjects "pwas.sync.heavyworth" "heavyworth.sync.pwas" "pwas.sync.dlq" "heavyworth.sync.dlq" \
   --retention workqueue \
   --storage file
 
-# Consumer for pwas (receives heavyworth -> pwas)
+# Push consumer for pwas (receives heavyworth -> pwas)
+# Delivers to heavyworth.sync.pwas.worker (pwas can subscribe to heavyworth.*)
 nats consumer add pwas-heavyworth-sync pwas-workers \
   --filter "heavyworth.sync.pwas" \
+  --deliver "heavyworth.sync.pwas.worker" \
   --ack explicit \
-  --pull \
   --deliver all \
   --max-deliver 5 \
   --ack-wait 30s \
@@ -472,11 +590,12 @@ nats consumer add pwas-heavyworth-sync pwas-workers \
   --replay instant \
   --max-pending 25000
 
-# Consumer for heavyworth (receives pwas -> heavyworth)
+# Push consumer for heavyworth (receives pwas -> heavyworth)
+# Delivers to pwas.sync.heavyworth.worker (heavyworth can subscribe to pwas.*)
 nats consumer add pwas-heavyworth-sync heavyworth-workers \
   --filter "pwas.sync.heavyworth" \
+  --deliver "pwas.sync.heavyworth.worker" \
   --ack explicit \
-  --pull \
   --deliver all \
   --max-deliver 5 \
   --ack-wait 30s \
@@ -486,28 +605,69 @@ nats consumer add pwas-heavyworth-sync heavyworth-workers \
 ```
 
 ```ruby
-# 2. Update config/initializers/jetstream_bridge.rb
+# 2. Update config/initializers/jetstream_bridge.rb (pwas app)
 JetstreamBridge.configure do |config|
   config.nats_urls = ENV.fetch("NATS_URLS") # e.g., nats://pwas:***@10.199.12.34:4222
   config.stream_name = "pwas-heavyworth-sync"
   config.app_name = "pwas"
   config.destination_app = "heavyworth"
+  config.auto_provision = false
+
+  # Enable push consumer mode (no JetStream API permissions needed)
+  config.consumer_mode = :push
+  config.delivery_subject = "heavyworth.sync.pwas.worker"
+
+  config.max_deliver = 5
+  config.ack_wait = "30s"
+  config.backoff = %w[1s 5s 15s 30s 60s]
+end
+```
+
+```ruby
+# 3. Update config/initializers/jetstream_bridge.rb (heavyworth app)
+JetstreamBridge.configure do |config|
+  config.nats_urls = ENV.fetch("NATS_URLS") # e.g., nats://heavyworth:***@10.199.12.34:4222
+  config.stream_name = "pwas-heavyworth-sync"
+  config.app_name = "heavyworth"
+  config.destination_app = "pwas"
+  config.auto_provision = false
+
+  # Enable push consumer mode
+  config.consumer_mode = :push
+  config.delivery_subject = "pwas.sync.heavyworth.worker"
+
   config.max_deliver = 5
   config.ack_wait = "30s"
   config.backoff = %w[1s 5s 15s 30s 60s]
 end
 ```
 
-**Note:** Verify your exact stream name and consumer durable (`app_name-workers`) match what was provisioned.
+**NATS Permissions:**
+
+```conf
+# pwas user
+publish: { allow: ["pwas.>"] }
+subscribe: { allow: ["heavyworth.>"] }
+
+# heavyworth user
+publish: { allow: ["heavyworth.>"] }
+subscribe: { allow: ["pwas.>"] }
+```
+
+**Note:** With push consumers, no `$JS.API.*` or `_INBOX.>` permissions are required.
 
 ---
 
-## Alternative: Request Minimal Permissions
+## Summary: Permission Requirements by Consumer Mode
 
-If you have any influence over NATS permissions, request only these minimal subjects:
+If you have any influence over NATS permissions, you have two options:
+
+### Option 1: Pull Consumers (Default)
+
+Request minimal JetStream API permissions:
 
 ```conf
-# Minimal permissions needed for JetStream Bridge consumer
+# Minimal permissions needed for pull consumer
 publish: {
   allow: [
     ">",                                   # Your app subjects (narrow if desired)
@@ -523,3 +683,19 @@ subscribe: {
 ```
 
 These are read-only operations and don't allow creating/modifying streams or consumers.
+
+### Option 2: Push Consumers (Recommended)
+
+Use push consumers with business subject permissions only:
+
+```conf
+# For pwas app
+publish: { allow: ["pwas.>"] }
+subscribe: { allow: ["heavyworth.>"] }
+
+# For heavyworth app
+publish: { allow: ["heavyworth.>"] }
+subscribe: { allow: ["pwas.>"] }
+```
+
+**No `$JS.API.*` or `_INBOX.>` permissions required!** This is the simplest and most restrictive permission model.

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -272,9 +272,30 @@ module JetstreamBridge
     # --- helpers ---
 
     def fetch_messages
+      if JetstreamBridge.config.push_consumer?
+        fetch_messages_push
+      else
+        fetch_messages_pull
+      end
+    end
+
+    def fetch_messages_pull
       @psub.fetch(@batch_size, timeout: FETCH_TIMEOUT_SECS)
     end
 
+    def fetch_messages_push
+      # For push consumers, collect messages from the subscription queue
+      # Push subscriptions don't have a fetch method, so we use next_msg
+      messages = []
+      @batch_size.times do
+        msg = @psub.next_msg(FETCH_TIMEOUT_SECS)
+        messages << msg if msg
+      rescue NATS::Timeout, NATS::IO::Timeout
+        break
+      end
+      messages
+    end
+
     def process_one(msg)
       if @inbox_proc
         @inbox_proc.process(msg) ? 1 : 0

data/lib/jetstream_bridge/consumer/pull_subscription_builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../core/logging'
+require_relative '../errors'
+
+module JetstreamBridge
+  # Builds and shims pull subscriptions without requiring JetStream API permissions.
+  class PullSubscriptionBuilder
+    def initialize(jts, durable, stream_name, filter_subject)
+      @jts = jts
+      @durable = durable
+      @stream_name = stream_name
+      @filter_subject = filter_subject
+    end
+
+    def build(nats_client)
+      prefix = @jts.instance_variable_get(:@prefix) || '$JS.API'
+      deliver = nats_client.new_inbox
+      sub = nats_client.subscribe(deliver)
+      sub.instance_variable_set(:@_jsb_nc, nats_client)
+      sub.instance_variable_set(:@_jsb_deliver, deliver)
+      sub.instance_variable_set(:@_jsb_next_subject, "#{prefix}.CONSUMER.MSG.NEXT.#{@stream_name}.#{@durable}")
+
+      extend_pull_subscription(sub)
+      attach_jsi(sub)
+
+      Logging.info(
+        "Created pull subscription without verification for consumer #{@durable} " \
+        "(stream=#{@stream_name}, filter=#{@filter_subject})",
+        tag: 'JetstreamBridge::Consumer'
+      )
+
+      sub
+    end
+
+    private
+
+    def extend_pull_subscription(sub)
+      pull_mod = begin
+        NATS::JetStream.const_get(:PullSubscription)
+      rescue NameError
+        nil
+      end
+
+      sub.extend(pull_mod) if pull_mod
+      shim_fetch(sub) unless pull_mod
+    end
+
+    def shim_fetch(sub)
+      Logging.warn(
+        'PullSubscription mixin unavailable; using shim fetch implementation',
+        tag: 'JetstreamBridge::Consumer'
+      )
+
+      sub.define_singleton_method(:fetch) do |batch_size, timeout: nil|
+        nc_handle = instance_variable_get(:@_jsb_nc)
+        deliver_subject = instance_variable_get(:@_jsb_deliver)
+        next_subject = instance_variable_get(:@_jsb_next_subject)
+        unless nc_handle && deliver_subject && next_subject
+          raise JetstreamBridge::ConnectionError, 'Missing NATS handles for fetch'
+        end
+
+        expires_ns = ((timeout || 5).to_f * 1_000_000_000).to_i
+        payload = { batch: batch_size, expires: expires_ns }.to_json
+
+        nc_handle.publish(next_subject, payload, deliver_subject)
+        nc_handle.flush
+
+        messages = []
+        batch_size.times do
+          msg = next_msg(timeout || 5)
+          messages << msg if msg
+        rescue NATS::IO::Timeout, NATS::Timeout
+          break
+        end
+        messages
+      end
+    end
+
+    def attach_jsi(sub)
+      js_sub_class = begin
+        NATS::JetStream.const_get(:JS).const_get(:Sub)
+      rescue NameError
+        Struct.new(:js, :stream, :consumer, :nms, keyword_init: true)
+      end
+
+      sub.jsi = js_sub_class.new(
+        js: @jts,
+        stream: @stream_name,
+        consumer: @durable,
+        nms: sub.instance_variable_get(:@_jsb_next_subject)
+      )
+    end
+  end
+end

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -4,6 +4,7 @@ require 'json'
 require_relative '../core/logging'
 require_relative '../core/duration'
 require_relative '../errors'
+require_relative 'pull_subscription_builder'
 
 module JetstreamBridge
   # Encapsulates durable ensure + subscribe for a pull consumer.
@@ -37,10 +38,14 @@ module JetstreamBridge
       create_consumer!
     end
 
-    # Bind a pull subscriber to the existing durable.
+    # Bind a subscriber to the existing durable consumer.
     def subscribe!
-      # Always bypass consumer_info to avoid requiring JetStream API permissions at runtime.
-      subscribe_without_verification!
+      if @cfg.push_consumer?
+        subscribe_push!
+      else
+        # Always bypass consumer_info to avoid requiring JetStream API permissions at runtime.
+        subscribe_without_verification!
+      end
     end
 
     def subscribe_without_verification!
@@ -63,10 +68,39 @@ module JetstreamBridge
             'Unable to create subscription without verification: NATS client not available'
     end
 
+    def subscribe_push!
+      # Push consumers deliver messages directly to a subscription subject
+      # No JetStream API calls needed - just subscribe to the delivery subject
+      nc = resolve_nc
+      delivery_subject = @cfg.push_delivery_subject
+
+      if nc.respond_to?(:subscribe)
+        sub = nc.subscribe(delivery_subject)
+        Logging.info(
+          "Created push subscription for consumer #{@durable} " \
+          "(stream=#{stream_name}, delivery=#{delivery_subject})",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        return sub
+      end
+
+      # Fallback for test environments
+      if @jts.respond_to?(:subscribe)
+        Logging.info(
+          "Using JetStream subscribe fallback for push consumer #{@durable} (stream=#{stream_name})",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        return @jts.subscribe(delivery_subject)
+      end
+
+      raise JetstreamBridge::ConnectionError,
+            'Unable to create push subscription: NATS client not available'
+    end
+
     private
 
     def build_consumer_config(durable, filter_subject)
-      {
+      config = {
         durable_name: durable,
         filter_subject: filter_subject,
         ack_policy: 'explicit',
@@ -76,6 +110,11 @@ module JetstreamBridge
         ack_wait: duration_to_seconds(JetstreamBridge.config.ack_wait),
         backoff: Array(JetstreamBridge.config.backoff).map { |d| duration_to_seconds(d) }
       }
+
+      # Add deliver_subject for push consumers
+      config[:deliver_subject] = @cfg.push_delivery_subject if @cfg.push_consumer?
+
+      config
     end
 
     def create_consumer!
@@ -171,74 +210,8 @@ module JetstreamBridge
     end
 
     def build_pull_subscription(nats_client)
-      prefix = @jts.instance_variable_get(:@prefix) || '$JS.API'
-      deliver = nats_client.new_inbox
-      sub = nats_client.subscribe(deliver)
-      sub.instance_variable_set(:@_jsb_nc, nats_client)
-      sub.instance_variable_set(:@_jsb_deliver, deliver)
-      sub.instance_variable_set(:@_jsb_next_subject, "#{prefix}.CONSUMER.MSG.NEXT.#{stream_name}.#{@durable}")
-
-      extend_pull_subscription(sub)
-      attach_jsi(sub)
-
-      Logging.info(
-        "Created pull subscription without verification for consumer #{@durable} " \
-        "(stream=#{stream_name}, filter=#{filter_subject})",
-        tag: 'JetstreamBridge::Consumer'
-      )
-
-      sub
-    end
-
-    def extend_pull_subscription(sub)
-      pull_mod = begin
-        NATS::JetStream.const_get(:PullSubscription)
-      rescue NameError
-        nil
-      end
-
-      sub.extend(pull_mod) if pull_mod
-      shim_fetch(sub) unless pull_mod
-    end
-
-    def shim_fetch(sub)
-      Logging.warn(
-        'PullSubscription mixin unavailable; using shim fetch implementation',
-        tag: 'JetstreamBridge::Consumer'
-      )
-
-      sub.define_singleton_method(:fetch) do |batch_size, timeout: nil|
-        nc_handle = instance_variable_get(:@_jsb_nc)
-        deliver_subject = instance_variable_get(:@_jsb_deliver)
-        next_subject = instance_variable_get(:@_jsb_next_subject)
-        unless nc_handle && deliver_subject && next_subject
-          raise JetstreamBridge::ConnectionError, 'Missing NATS handles for fetch'
-        end
-
-        expires_ns = ((timeout || 5).to_f * 1_000_000_000).to_i
-        payload = { batch: batch_size, expires: expires_ns }.to_json
-
-        nc_handle.publish(next_subject, payload, deliver_subject)
-        nc_handle.flush
-
-        messages = []
-        batch_size.times do
-          msg = next_msg(timeout || 5)
-          messages << msg if msg
-        rescue NATS::IO::Timeout, NATS::Timeout
-          break
-        end
-        messages
-      end
-    end
-
-    def attach_jsi(sub)
-      sub.jsi = NATS::JetStream::JS::Sub.new(
-        js: @jts,
-        stream: stream_name,
-        consumer: @durable,
-        nms: sub.instance_variable_get(:@_jsb_next_subject)
-      )
+      builder = PullSubscriptionBuilder.new(@jts, @durable, stream_name, filter_subject)
+      builder.build(nats_client)
     end
   end
 end

data/lib/jetstream_bridge/core/config.rb

@@ -100,6 +100,15 @@ module JetstreamBridge
     # Disable for locked-down environments and handle provisioning separately.
     # @return [Boolean]
     attr_accessor :auto_provision
+    # Consumer mode: :pull (default) or :push
+    # Pull consumers require publishing to JetStream API subjects ($JS.API.CONSUMER.MSG.NEXT.*)
+    # Push consumers receive messages automatically on a delivery subject
+    # @return [Symbol]
+    attr_accessor :consumer_mode
+    # Delivery subject for push consumers (optional, defaults to {destination_subject}.worker)
+    # Only used when consumer_mode is :push
+    # @return [String, nil]
+    attr_accessor :delivery_subject
 
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
@@ -124,6 +133,10 @@ module JetstreamBridge
       @connect_retry_delay = 2
       @lazy_connect = false
       @auto_provision = true
+
+      # Consumer mode
+      @consumer_mode = :pull
+      @delivery_subject = nil
     end
 
     # Apply a configuration preset
@@ -184,6 +197,32 @@ module JetstreamBridge
       "#{app_name}-workers"
     end
 
+    # Get the delivery subject for push consumers.
+    #
+    # @return [String] Delivery subject for push consumers
+    # @raise [InvalidSubjectError] If components contain NATS wildcards
+    # @raise [MissingConfigurationError] If required components are empty
+    def push_delivery_subject
+      return delivery_subject if delivery_subject && !delivery_subject.empty?
+
+      # Default: {destination_subject}.worker
+      "#{destination_subject}.worker"
+    end
+
+    # Check if using pull consumer mode.
+    #
+    # @return [Boolean]
+    def pull_consumer?
+      consumer_mode.to_sym == :pull
+    end
+
+    # Check if using push consumer mode.
+    #
+    # @return [Boolean]
+    def push_consumer?
+      consumer_mode.to_sym == :push
+    end
+
     # Validate all configuration settings.
     #
     # Checks that required settings are present and valid. Raises errors
@@ -195,13 +234,10 @@ module JetstreamBridge
     #   config.validate!  # Raises if destination_app is missing
     def validate!
       errors = []
-      errors << 'destination_app is required' if destination_app.to_s.strip.empty?
-      errors << 'nats_urls is required' if nats_urls.to_s.strip.empty?
-      errors << 'stream_name is required' if stream_name.to_s.strip.empty?
-      errors << 'app_name is required' if app_name.to_s.strip.empty?
-      errors << 'max_deliver must be >= 1' if max_deliver.to_i < 1
-      errors << 'backoff must be an array' unless backoff.is_a?(Array)
-      errors << 'backoff must not be empty' if backoff.is_a?(Array) && backoff.empty?
+      validate_required_fields!(errors)
+      validate_numeric_constraints!(errors)
+      validate_backoff!(errors)
+      validate_consumer_mode!(errors)
 
       raise ConfigurationError, "Configuration errors: #{errors.join(', ')}" if errors.any?
 
@@ -226,5 +262,25 @@ module JetstreamBridge
 
       raise InvalidSubjectError, "#{name} exceeds maximum length (255 characters): #{str.length}"
     end
+
+    def validate_required_fields!(errors)
+      errors << 'destination_app is required' if destination_app.to_s.strip.empty?
+      errors << 'nats_urls is required' if nats_urls.to_s.strip.empty?
+      errors << 'stream_name is required' if stream_name.to_s.strip.empty?
+      errors << 'app_name is required' if app_name.to_s.strip.empty?
+    end
+
+    def validate_numeric_constraints!(errors)
+      errors << 'max_deliver must be >= 1' if max_deliver.to_i < 1
+    end
+
+    def validate_backoff!(errors)
+      errors << 'backoff must be an array' unless backoff.is_a?(Array)
+      errors << 'backoff must not be empty' if backoff.is_a?(Array) && backoff.empty?
+    end
+
+    def validate_consumer_mode!(errors)
+      errors << 'consumer_mode must be :pull or :push' unless [:pull, :push].include?(consumer_mode.to_sym)
+    end
   end
 end

data/lib/jetstream_bridge/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 4.5.3
+  version: 4.6.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-26 00:00:00.000000000 Z
+date: 2026-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -141,6 +141,7 @@ files:
 - lib/jetstream_bridge/consumer/inbox/inbox_repository.rb
 - lib/jetstream_bridge/consumer/message_processor.rb
 - lib/jetstream_bridge/consumer/middleware.rb
+- lib/jetstream_bridge/consumer/pull_subscription_builder.rb
 - lib/jetstream_bridge/consumer/subscription_manager.rb
 - lib/jetstream_bridge/core.rb
 - lib/jetstream_bridge/core/bridge_helpers.rb