neeto_ws_pusher 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cdbf8416e76dd84e71fa296bc9a8bc5a9e26020fb06a5adeb9c1472bc726551e
+  data.tar.gz: 3d01eb7c7881386c2688d68c239cc42330f244c9ad48380cb353a713bbd560cf
+SHA512:
+  metadata.gz: 50d4399e5c280ab98998759509a1d8203fcec902cd41b5a3e74dede7949d7444cc0338f1a6baf406109d8abcadd0b9a884d30043c715caff5afd4eb97afe3e2c
+  data.tar.gz: 62dc6c26223b7cd9eda7724126082fc16bcb5bea81bfddfbb478facd7186adefb724b4dce59e1023c8aa1e67334e4bab89a1ff1771152dad5d76b7abecf9dc3a

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+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).
+
+## [1.0.3] - 2025-11-17
+
+### Added
+- Added support for Rails 8.1+
+
+## [1.0.0] - 2025-05-02
+
+### Changed
+- **BREAKING**: Changed API endpoint path from `/neeto-ws/api/v1/ws_auth` to `/ws/auth`
+- **BREAKING**: Simplified controller structure
+- **BREAKING**: Removed nested API/v1 namespacing
+- **BREAKING**: Removed unused concerns (WebSocketAuthentication and ErrorHandling)
+
+## [0.2.0] - 2025-05-02
+
+### Added
+- Added support for Rails 7+
+
+## [0.1.0] - 2025-05-02
+
+### Added
+- Initial release
+- Core client for sending messages to SQS
+- Command-line interface
+- Configuration system for global settings
+- Comprehensive documentation
+

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,212 @@
+# NeetoWsPusher
+
+This gem acts as a client for [neeto-ws-server](https://github.com/bigbinary/neeto-ws-server) to enable real-time communication in your applications. 
+
+## How It Works
+
+1. Your application uses this gem to send messages to specific users
+2. Messages are sent to an AWS SQS queue with user_id and app_name
+3. The neeto-ws-server listens to the queue and retrieves messages
+4. The server uses user_id and app_name to find the matching connected clients
+5. Messages are forwarded only to the intended clients
+6. Clients receive real-time updates in their browser or mobile app
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'neeto_ws_pusher'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+If you're using Rails, run the generator:
+
+```bash
+rails generate neeto_ws_pusher:install
+```
+
+This will:
+- Create an initializer at `config/initializers/neeto_ws_pusher.rb`
+- Mount routes at `/ws` with an authentication endpoint
+- Display instructions for JavaScript client setup
+
+## Configuration
+
+```ruby
+# config/initializers/neeto_ws_pusher.rb
+NeetoWsPusher.configure do |config|
+  # AWS Configuration (REQUIRED)
+  config.queue_url = ENV['AWS_SQS_URL']
+  config.region = ENV['AWS_REGION'] || 'us-east-1'
+  config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  
+  # Default Application Name
+  # This identifier is used when sending messages
+  config.default_app_name = 'your-application-name'
+  
+  # Logging Configuration
+  # Set to false to suppress NeetoWsPusher log messages
+  config.logging_enabled = true
+end
+```
+
+## Authentication
+
+This gem automatically mounts an authentication endpoint at `/ws/auth` in your Rails application. This endpoint authenticates WebSocket connections:
+
+### How Authentication Works
+
+1. Client reads your authentication cookie (typically a Devise cookie) from the browser
+2. Client connects to neeto-ws-server and sends the cookie name and value
+3. The server makes a POST request to your `/ws/auth` endpoint with the cookie
+4. The `/ws/auth` endpoint validates the cookie using your app's authentication system
+5. If successful, it returns `user_id` and `app_name`
+6. The server establishes the WebSocket connection and associates it with this user_id + app_name
+7. All future messages sent to this user_id + app_name will be delivered to this connection
+
+The authentication endpoint requires:
+- `current_user` to be available (typically from Devise)
+- `authenticate_user!` method to verify authentication
+
+This cookie-based approach ensures that only authenticated users can establish WebSocket connections.
+
+## Usage
+
+### Direct Ruby Usage
+
+```ruby
+# Create a client instance
+client = NeetoWsPusher.new
+
+# Send a message to a specific channel
+client.send_message(
+  { event: 'notification', content: 'Hello, World!' },
+  channel: 'notifications'
+)
+
+# Send a message to a specific user
+client.send_message(
+  { event: 'notification', content: 'Hello, World!' },
+  user_id: 'user-123'
+)
+
+# Send a message to a specific user in a channel
+client.send_message(
+  { event: 'notification', content: 'Hello, World!' },
+  user_id: 'user-123',
+  channel: 'notifications'
+)
+```
+
+### Rails Integration
+
+The gem adds a `send_ws_message` method to User models. The generator will attempt to add this automatically, but if needed, you can add it manually:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  include NeetoWsPusher::UserExtension
+  
+  # rest of your model...
+end
+```
+
+Once included, you can use it like this:
+
+```ruby
+# Send a message to a user (uses current_user.id automatically)
+current_user.send_ws_message(
+  { event: 'notification', content: 'You have a new message!' }
+)
+
+# Send a message to a specific channel
+current_user.send_ws_message(
+  { event: 'chat_message', content: 'New chat message' },
+  channel: 'chat-room-1'
+)
+```
+
+## JavaScript Client
+
+### 1. Add the Script to Your Page
+
+```html
+<!-- Include from CDN -->
+<script src="https://cdn.example.com/neeto_ws_pusher.js"></script>
+
+<!-- Or from your local servers -->
+<script src="/assets/neeto_ws_pusher.js"></script>
+```
+
+### 2. Initialize the Client
+
+```javascript
+// Initialize with WebSocket server URL
+const client = new NeetoWsPusher({
+  // Required
+  wsUrl: 'wss://your-websocket-server.com',
+  
+  // Optional with defaults
+  authCookieName: '_neeto_ws_auth',  // Name of auth cookie
+  baseUrl: window.location.origin,   // Base URL for auth endpoint
+  autoConnect: true,                 // Connect automatically
+  debug: false,                      // Show debug logs
+  
+  // Reconnection settings
+  reconnect: {
+    enabled: true,                   // Auto-reconnect on disconnect
+    maxAttempts: 5,                  // Maximum reconnection attempts
+    delayFactor: 1.5,                // Exponential backoff factor
+    maxDelay: 30000,                 // Maximum delay (30 seconds)
+    initialDelay: 1000               // First retry after 1 second
+  }
+});
+
+// Listen for messages
+client.on('message', ({ data }) => {
+  console.log('Received message:', data);
+  
+  // Handle message based on event type
+  if (data.event === 'notification') {
+    showNotification(data.content);
+  }
+});
+
+// Connection status events
+client.on('connect', () => console.log('Connected!'));
+client.on('disconnect', ({ code }) => console.log('Disconnected!', code));
+client.on('error', ({ event }) => console.error('WebSocket error:', event));
+```
+
+## CLI Usage
+
+```bash
+# Set environment variables for AWS credentials
+export AWS_ACCESS_KEY_ID=your-key
+export AWS_SECRET_ACCESS_KEY=your-secret
+export AWS_REGION=us-east-1
+export AWS_SQS_URL=https://sqs.region.amazonaws.com/account/queue
+
+neeto_ws_pusher --user-id user-123 \
+                --app-name my-app \
+                --channel notifications \
+                --message '{"event":"notification","content":"Hello!"}'
+```
+
+### Options
+
+- `--user-id`: Target user ID (required)
+- `--app-name`: Application name
+- `--channel`: Channel name
+- `--message`: JSON message payload (required)
+- `--queue-url`, `--region`, `--access-key-id`, `--secret-access-key`: AWS options
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/javascripts/neeto_ws_pusher.js

@@ -0,0 +1,241 @@
+/**
+ * NeetoWsPusher - WebSocket client for neeto-ws-server
+ */
+class NeetoWsPusher {
+  constructor(config = {}) {
+    this.config = {
+      wsUrl: config.wsUrl,
+      authCookieName: config.authCookieName || '_neeto_ws_auth',
+      channel: config.channel,
+      debug: config.debug || false,
+      autoConnect: config.autoConnect !== false,
+      reconnect: {
+        enabled: config.reconnect?.enabled !== false,
+        maxAttempts: config.reconnect?.maxAttempts || 5,
+        delayFactor: config.reconnect?.delayFactor || 1.5,
+        maxDelay: config.reconnect?.maxDelay || 30000,
+        initialDelay: config.reconnect?.initialDelay || 1000
+      }
+    };
+
+    this.socket = null;
+    this.connected = false;
+    this.reconnectAttempts = 0;
+    this.reconnectTimeout = null;
+    this.skipReconnect = false;
+    this.eventHandlers = {
+      connect: [],
+      disconnect: [],
+      message: [],
+      error: []
+    };
+
+    if (this.config.autoConnect) {
+      this.connect();
+    }
+  }
+
+  debug(...args) {
+    if (this.config.debug) {
+      console.log('[NeetoWsPusher]', ...args);
+    }
+  }
+
+  getMyCookie(cookieName) {
+    return fetch(`/ws/expose_cookie`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        name: cookieName,
+        channel: this.config.channel
+      })
+    })
+      .then(response => response.json())
+      .then(data => {
+        this.debug('Cookie value:', data);
+        return data.value;
+      });
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      if (this.socket) {
+        this.socket.close();
+      }
+
+      this.getMyCookie(this.config.authCookieName)
+        .then(authCookieData => {
+          if (!authCookieData) {
+            const error = new Error('Authentication cookie not found');
+            this._trigger('error', { event: error });
+            reject(error);
+            return;
+          }
+
+          try {
+            const wsUrl = new URL(this.config.wsUrl);
+            wsUrl.searchParams.append('auth_cookie_name', this.config.authCookieName);
+            wsUrl.searchParams.append('auth_cookie_data', authCookieData);
+            wsUrl.searchParams.append('base_url', window.location.origin);
+            wsUrl.searchParams.append('channel', this.config.channel);
+
+            this.socket = new WebSocket(wsUrl.toString());
+
+            this.socket.addEventListener('open', (event) => {
+              this.debug('Connected to channel:', this.config.channel);
+              this.connected = true;
+              this.reconnectAttempts = 0;
+              this._trigger('connect', { event, channel: this.config.channel });
+              resolve(event);
+            });
+
+            this.socket.addEventListener('message', (event) => {
+              let parsedData;
+              try {
+                parsedData = JSON.parse(event.data);
+              } catch (e) {
+                parsedData = event.data;
+              }
+
+              this.debug('Message received:', parsedData);
+              this._trigger('message', { data: parsedData, original: event });
+            });
+
+            this.socket.addEventListener('close', (event) => {
+              this.debug('Disconnected from channel:', this.config.channel);
+              this.connected = false;
+              this._trigger('disconnect', {
+                code: event.code,
+                reason: event.reason,
+                event,
+                channel: this.config.channel
+              });
+
+              if (this.config.reconnect.enabled && !this.reconnectTimeout && !this.skipReconnect) {
+                this.reconnect();
+              }
+
+              if (this.reconnectAttempts === 0) {
+                reject(new Error(`Connection closed: ${event.code}`));
+              }
+              this.skipReconnect = false;
+            });
+
+            this.socket.addEventListener('error', (event) => {
+              this.debug('Error:', event);
+              this._trigger('error', { event, channel: this.config.channel });
+
+              if (this.reconnectAttempts === 0) {
+                reject(new Error('WebSocket connection error'));
+              }
+            });
+          } catch (error) {
+            this._trigger('error', { event: error });
+            reject(error);
+          }
+        })
+        .catch(error => {
+          this._trigger('error', { event: error });
+          reject(error);
+        });
+    });
+  }
+
+  changeChannel(newChannel) {
+    this.debug('Changing channel from', this.config.channel, 'to', newChannel);
+    this.config.channel = newChannel;
+    return this.connect();
+  }
+
+  disconnect() {
+    // Prevent reconnection when disconnecting manually
+    this.skipReconnect = true;
+
+    if (this.socket) {
+      this.socket.close();
+    }
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  getChannel() {
+    return this.config.channel;
+  }
+
+  reconnect() {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.reconnectAttempts >= this.config.reconnect.maxAttempts) {
+      this.debug(`Max reconnect attempts (${this.config.reconnect.maxAttempts}) reached`);
+      return;
+    }
+
+    this.reconnectAttempts++;
+
+    const delay = Math.min(
+      this.config.reconnect.initialDelay * Math.pow(this.config.reconnect.delayFactor, this.reconnectAttempts - 1),
+      this.config.reconnect.maxDelay
+    );
+
+    this.debug(`Reconnecting (attempt ${this.reconnectAttempts}/${this.config.reconnect.maxAttempts}) in ${delay}ms`);
+
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connect().catch(error => {
+        this.debug('Reconnect failed:', error);
+      });
+    }, delay);
+  }
+
+  on(event, callback) {
+    if (!this.eventHandlers[event]) {
+      throw new Error(`Unknown event: ${event}`);
+    }
+
+    this.eventHandlers[event].push(callback);
+
+    return () => {
+      this.off(event, callback);
+    };
+  }
+
+  off(event, callback) {
+    if (!this.eventHandlers[event]) {
+      return;
+    }
+
+    const index = this.eventHandlers[event].indexOf(callback);
+    if (index !== -1) {
+      this.eventHandlers[event].splice(index, 1);
+    }
+  }
+
+  _trigger(event, data = {}) {
+    if (!this.eventHandlers[event]) {
+      return;
+    }
+
+    for (const handler of this.eventHandlers[event]) {
+      try {
+        handler(data);
+      } catch (error) {
+        console.error(`Error in ${event} handler:`, error);
+      }
+    }
+  }
+}
+
+// Make globally available
+window.NeetoWsPusher = NeetoWsPusher;

data/app/controllers/neeto_ws_pusher/cookies_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module NeetoWsPusher
+  class CookiesController < ApplicationController
+    skip_before_action :verify_authenticity_token
+
+    def create
+      name = params[:name]
+      value = request.cookies[name]
+      render json: { value: value }.to_json
+    end
+  end
+end

data/app/controllers/neeto_ws_pusher/ws_auth_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module NeetoWsPusher
+  class WsAuthController < Api::V1::BaseController
+    skip_before_action :verify_authenticity_token, raise: false
+    skip_before_action :authenticate_user_using_x_auth_token, raise: false
+
+    before_action :authenticate_user!
+
+    def create
+      # Extract channel from params, default to 'default' if not provided
+      channel = params[:channel] || "default"
+
+      render json: {
+        "app_name": NeetoWsPusher.configuration.default_app_name,
+        "user_id": current_user.id,
+        "channel": channel
+      }, status: :ok
+    end
+  end
+end

data/bin/neeto_ws_pusher

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+
+require 'neeto_ws_pusher'
+require 'optparse'
+require 'json'
+
+# Parse command line options
+options = {
+  user_id: nil,
+  app_name: nil,
+  message: nil,
+  queue_url: ENV['AWS_SQS_URL'],
+  region: ENV['AWS_REGION'] || 'us-east-1',
+  aws_access_key_id: ENV['AWS_ACCESS_KEY_ID'],
+  aws_secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
+  verbose: false
+}
+
+# Parse command line arguments
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: neeto_ws_pusher [options]"
+  
+  opts.on("-u", "--user-id USER_ID", "User ID (required)") do |user_id|
+    options[:user_id] = user_id
+  end
+  
+  opts.on("-a", "--app-name APP_NAME", "Application name (default: from configuration)") do |app_name|
+    options[:app_name] = app_name
+  end
+  
+  opts.on("-m", "--message MESSAGE", "JSON message to send (required)") do |message|
+    options[:message] = message
+  end
+  
+  opts.on("-c", "--channel CHANNEL", "Channel name (optional)") do |channel|
+    options[:channel] = channel
+  end
+  
+  opts.on("-q", "--queue-url URL", "SQS queue URL (default: ENV['AWS_SQS_URL'])") do |url|
+    options[:queue_url] = url
+  end
+  
+  opts.on("-r", "--region REGION", "AWS region (default: ENV['AWS_REGION'] or 'us-east-1')") do |region|
+    options[:region] = region
+  end
+  
+  opts.on("--access-key-id KEY", "AWS access key ID (default: ENV['AWS_ACCESS_KEY_ID'])") do |key|
+    options[:aws_access_key_id] = key
+  end
+  
+  opts.on("--secret-access-key SECRET", "AWS secret access key (default: ENV['AWS_SECRET_ACCESS_KEY'])") do |secret|
+    options[:aws_secret_access_key] = secret
+  end
+  
+  opts.on("-v", "--verbose", "Enable verbose logging") do
+    options[:verbose] = true
+  end
+  
+  opts.on("-h", "--help", "Display this help message") do
+    puts opts
+    exit
+  end
+end
+
+begin
+  # Parse options
+  parser.parse!
+  
+  # Validate required options
+  missing = []
+  missing << "user_id" unless options[:user_id]
+  missing << "message" unless options[:message]
+  missing << "queue_url or AWS_SQS_URL" unless options[:queue_url]
+  missing << "access_key_id or AWS_ACCESS_KEY_ID" unless options[:aws_access_key_id]
+  missing << "secret_access_key or AWS_SECRET_ACCESS_KEY" unless options[:aws_secret_access_key]
+  
+  if !missing.empty?
+    puts "Error: Missing required options: #{missing.join(', ')}"
+    puts parser
+    exit 1
+  end
+
+  # Parse message if it's a JSON string
+  if options[:message].is_a?(String) && options[:message].strip.start_with?('{')
+    begin
+      options[:message] = JSON.parse(options[:message])
+    rescue JSON::ParserError => e
+      if options[:verbose]
+        puts "Warning: Could not parse message as JSON, using as raw string: #{e.message}"
+      end
+    end
+  end
+  
+  # Initialize client with options
+  client = NeetoWsPusher.new(
+    queue_url: options[:queue_url],
+    region: options[:region],
+    aws_access_key_id: options[:aws_access_key_id],
+    aws_secret_access_key: options[:aws_secret_access_key],
+    verbose: options[:verbose]
+  )
+  
+  # Send message
+  message_id = client.send_message(
+    user_id: options[:user_id],
+    app_name: options[:app_name],
+    message: options[:message],
+    channel: options[:channel]
+  )
+  
+  # Report success
+  puts "\nMessage successfully sent to queue:"
+  puts "- Message ID: #{message_id}"
+  puts "- User ID: #{options[:user_id]}"
+  puts "- App Name: #{options[:app_name] || NeetoWsPusher.configuration.default_app_name}"
+  puts "- Channel: #{options[:channel] || 'none'}"
+  puts "- Message: #{options[:message].is_a?(Hash) ? JSON.pretty_generate(options[:message]) : options[:message]}"
+  puts "- Queue URL: #{options[:queue_url]}"
+  
+  exit 0
+rescue OptionParser::InvalidOption => e
+  puts "Error: #{e.message}"
+  puts parser
+  exit 1
+rescue StandardError => e
+  puts "Error: #{e.message}"
+  puts "For help, run: neeto_ws_pusher --help"
+  exit 1
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+NeetoWsPusher::Engine.routes.draw do
+  resources :ws_auth, only: [:create]
+  resources :cookies, only: [:create], path: "expose_cookie"
+end

data/lib/generators/neeto_ws_pusher/install/install_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module NeetoWsPusher
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs NeetoWsPusher configuration files"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/neeto_ws_pusher.rb"
+      end
+
+      def mount_routes
+        # Use as: nil to prevent route helper name collision with the gem's name
+        route 'mount NeetoWsPusher::Engine => "/ws", as: nil'
+      end
+
+      def show_post_install_message
+        say "\n"
+        say "===============================================================================", :green
+        say "NeetoWsPusher was successfully installed! Next steps:", :green
+        say "===============================================================================", :green
+        say "\n"
+        say "1. Configure AWS credentials in config/initializers/neeto_ws_pusher.rb", :yellow
+        say "   - Set queue_url, region, aws_access_key_id, and aws_secret_access_key"
+        say "   - Recommended: use environment variables for these values"
+        say "\n"
+        say "2. Add the User model extension (optional):", :yellow
+        say "   Add this line to your User model:", :yellow
+        say "   include NeetoWsPusher::UserExtension", :blue
+        say "\n"
+        say "   Example:", :yellow
+        say "   # app/models/user.rb", :blue
+        say "   class User < ApplicationRecord", :blue
+        say "     include NeetoWsPusher::UserExtension", :blue
+        say "     # ...", :blue
+        say "   end", :blue
+        say "\n"
+        say "3. Add the JavaScript client to your pages:", :yellow
+        say "   # From CDN", :blue
+        say "   <script src=\"https://cdn.example.com/neeto_ws_pusher.js\"></script>", :blue
+        say "\n"
+        say "   # Or from your local assets", :blue
+        say "   <script src=\"/assets/neeto_ws_pusher.js\"></script>", :blue
+        say "\n"
+        say "4. Initialize the client:", :yellow
+        say "   const client = new NeetoWsPusher({", :blue
+        say "     wsUrl: 'wss://your-websocket-server.com',", :blue
+        say "     authCookieName: '_your_auth_cookie_name'", :blue
+        say "   });", :blue
+        say "\n"
+        say "   client.on('message', ({ data }) => {", :blue
+        say "     console.log('Message received:', data);", :blue
+        say "   });", :blue
+        say "\n"
+        say "For more information, see: https://github.com/bigbinary/neeto-ws-pusher#readme", :green
+        say "\n"
+      end
+    end
+  end
+end

data/lib/generators/neeto_ws_pusher/install/templates/initializer.rb

@@ -0,0 +1,48 @@
+# NeetoWsPusher Configuration
+# IMPORTANT: AWS credentials MUST be set in environment variables.
+# Make sure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION are set.
+NeetoWsPusher.configure do |config|
+  #=======================================================================
+  # AWS SQS Configuration (REQUIRED)
+  #=======================================================================
+
+  # SQS Queue URL - REQUIRED
+  # This is the URL of your AWS SQS queue that will be used to send WebSocket messages
+  # Format: https://sqs.[region].amazonaws.com/[account-id]/[queue-name]
+  # Should be set via the AWS_SQS_URL environment variable
+  config.queue_url = ENV['AWS_SQS_URL'] # REQUIRED
+
+  # AWS Region (REQUIRED)
+  # The region where your SQS queue is located
+  # Should be set via the AWS_REGION environment variable
+  config.region = ENV['AWS_REGION'] || 'us-east-1'
+
+  # AWS Credentials (REQUIRED)
+  # You MUST set AWS credentials using environment variables:
+  config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID'] # REQUIRED
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY'] # REQUIRED
+
+  #=======================================================================
+  # Application Configuration
+  #=======================================================================
+
+  # Default Application Name
+  # This identifier is used:
+  # 1. In the WebSocket authentication endpoint response
+  # 2. As the default app_name when sending messages via User#send_ws_message
+  #
+  # You should change this to a unique identifier for your application
+  config.default_app_name = 'your-application-name'
+
+  #=======================================================================
+  # Logging Configuration
+  #=======================================================================
+
+  # Enable/Disable gem logging
+  # Set to false to suppress NeetoWsPusher log messages (e.g., User model extension notifications)
+  # Default: true (enabled for backward compatibility)
+  config.logging_enabled = true
+
+  # NOTE: The gem automatically mounts an authentication endpoint at /ws/auth
+  # This endpoint integrates with your application's authentication system
+end

data/lib/neeto_ws_pusher/client.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "aws-sdk-sqs"
+require "json"
+require "logger"
+
+module NeetoWsPusher
+  # Client class for sending messages to WebSocket server via SQS
+  class Client
+    attr_accessor :logger, :sqs_client, :queue_url
+
+    # Initialize a new client
+    #
+    # @param options [Hash] Options for the client
+    # @option options [String] :queue_url SQS queue URL (required unless configured globally)
+    # @option options [String] :region AWS region (defaults to 'us-east-1')
+    # @option options [Logger] :logger Custom logger (defaults to STDOUT)
+    # @option options [Boolean] :verbose Enable verbose logging
+    def initialize(options = {})
+      @options = options
+      setup_logger
+      setup_sqs_client
+    end
+
+    # Send a message to a specific user in an application
+    #
+    # @param message [Hash, String] Message payload (will be converted to JSON if Hash)
+    # @param user_id [String] Target user ID (optional, but either user_id or channel must be provided)
+    # @param channel [String] Channel name (optional, but either user_id or channel must be provided)
+    # @return [String] SQS message ID if successful
+    # @raise [StandardError] If required parameters are missing or if SQS returns an error
+    # @example Send a message to a channel
+    #   client.send_message({ event: 'notification', content: 'Hello!' }, channel: 'notifications')
+    # @example Send a message to a specific user
+    #   client.send_message({ event: 'notification', content: 'Hello!' }, user_id: 'user-123')
+    # @example Send a message to a specific user in a channel
+    #   client.send_message({ event: 'notification', content: 'Hello!' }, user_id: 'user-123', channel: 'notifications')
+    def send_message(message, user_id: nil, channel: nil)
+      validate_parameters(message, user_id, channel)
+
+      message_payload = {
+        app_name: NeetoWsPusher.configuration.default_app_name,
+        message: message.is_a?(String) ? parse_json(message) : message
+      }
+
+      message_payload[:user_id] = user_id if user_id
+      message_payload[:channel] = channel if channel
+
+      @logger.debug("Message payload: #{message_payload}")
+      @logger.info("Sending message to SQS queue")
+
+      response = @sqs_client.send_message(
+        {
+          queue_url: @queue_url,
+          message_body: message_payload.to_json
+        })
+
+      @logger.info("Message successfully queued with ID: #{response.message_id}")
+
+      response.message_id
+    end
+
+    private
+
+      def setup_logger
+        @logger = @options[:logger] || Logger.new($stdout)
+        @logger.formatter = proc { |severity, _, _, msg| "[NeetoWsPusher][#{severity}]: #{msg}\n" }
+        @logger.level = if NeetoWsPusher.configuration.logging_enabled
+          @options[:verbose] ? Logger::DEBUG : Logger::INFO
+                        else
+                          Logger::FATAL
+        end
+      end
+
+      def setup_sqs_client
+        @queue_url = @options[:queue_url] || NeetoWsPusher.configuration.queue_url
+        region = @options[:region] || NeetoWsPusher.configuration.region
+
+        raise Error, "SQS queue URL is required" unless @queue_url
+
+        # Build AWS SDK configuration
+        aws_config = { region: region }
+
+        # Use credentials from configuration if provided
+        config = NeetoWsPusher.configuration
+        if config.aws_access_key_id && config.aws_secret_access_key
+          aws_config[:credentials] = Aws::Credentials.new(
+            config.aws_access_key_id,
+            config.aws_secret_access_key
+          )
+          @logger.debug("Using configured AWS credentials")
+        else
+          @logger.debug("Using default AWS credential provider chain")
+        end
+
+        @sqs_client = Aws::SQS::Client.new(aws_config)
+        @logger.info("Connected to AWS SQS in region: #{region}")
+      end
+
+      def validate_parameters(message, user_id, channel)
+        errors = []
+        errors << "Message is required" unless message
+        errors << "Either user_id or channel must be provided" if user_id.nil? && channel.nil?
+
+        raise Error, errors.join(", ") if errors.any?
+      end
+
+      def parse_json(json_string)
+        JSON.parse(json_string)
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON message: #{e.message}"
+      end
+  end
+end

data/lib/neeto_ws_pusher/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module NeetoWsPusher
+  # Rails engine that handles WebSocket authentication
+  class Engine < ::Rails::Engine
+    isolate_namespace NeetoWsPusher
+
+    # Initialize any authentication callbacks
+    initializer "neeto_ws_pusher.setup_authentication" do |app|
+      # Can be extended to set up authentication integrations
+    end
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.assets false
+      g.helper false
+    end
+
+    # Load JavaScript assets
+    initializer "neeto_ws_pusher.assets" do |app|
+      app.config.assets.paths << root.join("app", "assets", "javascripts")
+      app.config.assets.precompile += %w(neeto_ws_pusher.js)
+    end
+  end
+end

data/lib/neeto_ws_pusher/model_extensions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module NeetoWsPusher
+  # Module to extend User model with WebSocket functionality
+  module UserExtension
+    # Send a WebSocket message to this user
+    #
+    # @param message [Hash, String] The message to send
+    # @param channel [String] Optional channel name
+    # @return [String] Message ID if successful
+    # @example Send a notification
+    #   user.send_ws_message(event: 'notification', content: 'Hello!')
+    # @example Send a notification to a specific channel
+    #   user.send_ws_message({ event: 'notification', content: 'Hello!' }, channel: 'notifications')
+    def send_ws_message(message, channel: nil)
+      # Use the user's ID as the user_id
+      NeetoWsPusher.new.send_message(
+        user_id: id.to_s,
+        app_name: NeetoWsPusher.configuration.default_app_name,
+        message: message,
+        channel: channel
+      )
+    end
+  end
+end

data/lib/neeto_ws_pusher/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails"
+require "neeto_ws_pusher/model_extensions"
+
+module NeetoWsPusher
+  # Rails integration for NeetoWsPusher
+  class Railtie < Rails::Railtie
+    # Automatically extend the User model with WebSocket functionality
+    initializer "neeto_ws_pusher.extend_user_model" do
+      ActiveSupport.on_load(:active_record) do
+        # If User model exists, extend it with WebSocket functionality
+        if defined?(::User)
+          ::User.include(NeetoWsPusher::UserExtension)
+          if NeetoWsPusher.configuration.logging_enabled
+            Rails.logger.info("[NeetoWsPusher][INFO]: Added WebSocket functionality to User model")
+          end
+        elsif NeetoWsPusher.configuration.logging_enabled
+          Rails.logger.warn("[NeetoWsPusher][WARN]: User model not found, WebSocket extensions not applied")
+        end
+      end
+    end
+  end
+end

data/lib/neeto_ws_pusher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NeetoWsPusher
+  VERSION = "1.0.3"
+end

data/lib/neeto_ws_pusher.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "neeto_ws_pusher/version"
+require "neeto_ws_pusher/client"
+
+# Load Rails integration if Rails is defined
+if defined?(Rails)
+  require "neeto_ws_pusher/model_extensions"
+  require "neeto_ws_pusher/engine"
+  require "neeto_ws_pusher/railtie"
+end
+
+# Main module for the NeetoWsPusher gem
+module NeetoWsPusher
+  # Custom error class for NeetoWsPusher errors
+  class Error < StandardError; end
+
+  # Configure the gem with default options
+  def self.configure
+    yield(configuration) if block_given?
+    configuration
+  end
+
+  # Get the current configuration
+  def self.configuration
+    @_configuration ||= Configuration.new
+  end
+
+  # Configuration class for storing default settings
+  class Configuration
+    attr_accessor :queue_url, :region,
+      :aws_access_key_id, :aws_secret_access_key,
+      :default_app_name, :logging_enabled
+
+    def initialize
+      # AWS SQS configuration
+      @queue_url = nil
+      @region = "us-east-1"
+      @aws_access_key_id = nil
+      @aws_secret_access_key = nil
+
+      # WebSocket authentication API configuration
+      @default_app_name = "default" # Default application name
+
+      # Logging configuration
+      @logging_enabled = true
+    end
+  end
+
+  # Helper method to create a new client
+  def self.new(options = {})
+    Client.new(options)
+  end
+end

metadata

@@ -0,0 +1,185 @@
+--- !ruby/object:Gem::Specification
+name: neeto_ws_pusher
+version: !ruby/object:Gem::Version
+  version: 1.0.3
+platform: ruby
+authors:
+- Neeto Engineers
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-sqs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A lightweight Ruby gem for sending messages to WebSocket clients through
+  an AWS SQS queue. Includes Rails integration with WebSocket authentication endpoint
+  and User model extensions.
+email:
+- engineering@neeto.com
+executables:
+- neeto_ws_pusher
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- app/assets/javascripts/neeto_ws_pusher.js
+- app/controllers/neeto_ws_pusher/cookies_controller.rb
+- app/controllers/neeto_ws_pusher/ws_auth_controller.rb
+- bin/neeto_ws_pusher
+- config/routes.rb
+- lib/generators/neeto_ws_pusher/install/install_generator.rb
+- lib/generators/neeto_ws_pusher/install/templates/initializer.rb
+- lib/neeto_ws_pusher.rb
+- lib/neeto_ws_pusher/client.rb
+- lib/neeto_ws_pusher/engine.rb
+- lib/neeto_ws_pusher/model_extensions.rb
+- lib/neeto_ws_pusher/railtie.rb
+- lib/neeto_ws_pusher/version.rb
+homepage: https://github.com/bigbinary/neeto-ws-pusher
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bigbinary/neeto-ws-pusher
+  source_code_uri: https://github.com/bigbinary/neeto-ws-pusher/tree/main
+  changelog_uri: https://github.com/bigbinary/neeto-ws-pusher/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/bigbinary/neeto-ws-pusher/blob/main/README.md
+  bug_tracker_uri: https://github.com/bigbinary/neeto-ws-pusher/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.10
+signing_key:
+specification_version: 4
+summary: Send messages to WebSocket clients via AWS SQS
+test_files: []