pulse_zero 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc39a93099909f808b4bde3b5cfb4826be34d8feb9c1c71eb5e301e9527b2679
+  data.tar.gz: dba7ce1f61b85c4cef989e84c1b6c3c7354cdcad8eff69572e141a9d39640fef
+SHA512:
+  metadata.gz: 496b91b569c09f96f1aad6844811f73e206a5ccdecaa7c9d02aef428f03386c2c0661a85a0b4e12a67416294794810e0da91c73d42d584b29c1f903a9aa61f6e
+  data.tar.gz: 860817c4a47cc4e66ff484df3ef3f148ac31699bc7d67dd34804f7e0c972617740e4e85dea7773d5ad77270d0a890c333356f79631b023c5e20b68a73f6fe5e7

data/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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).
+
+## [Unreleased]
+
+## [0.3.0] - 2025-01-26
+
+### Changed
+- Moved all frontend library files from `app/frontend/lib/` to `app/frontend/lib/pulse/` subdirectory
+- Updated all import paths in hooks to reference the new location
+- This provides better organization and avoids naming conflicts with other libraries
+
+### Fixed
+- Updated documentation to reflect new import paths
+
+## [0.2.2] - 2025-01-26
+
+### Fixed
+- Fixed WebSocket subscription parameter name in pulse.ts (changed from `signed_stream_name` to `"signed-stream-name"`)
+- This fixes the issue where broadcasts were sent but not received by the frontend
+
+## [0.2.1] - 2025-01-26
+
+### Fixed
+- Fixed "uninitialized constant Pulse" error on Rails startup
+- Generator now properly sets up autoload paths for lib directory
+- Made initializer defensive by checking if Pulse is defined
+- Removed conditional engine loading from pulse.rb template
+- Added setup_autoload_paths step to generator execution flow
+- Fixed ApplicationCable connection to not assume authentication is configured
+- Default connection now accepts all connections with guest identifiers
+
+### Changed
+- ApplicationCable::Connection template now provides safe default that accepts all connections
+- Added comprehensive authentication examples (Devise, Session, JWT) in documentation
+- Generator now warns about authentication configuration requirement
+- Improved documentation with authentication setup section
+
+## [0.2.0] - 2025-01-26
+
+### Changed
+- Complete rewrite of templates to match actual implementation
+- Use `mattr_accessor :config` instead of thread-local variables
+- Use `Pulse.config` for all configuration
+- Match exact broadcast API with keyword arguments
+- BroadcastJob now accepts named parameters (streamables:, event:, payload:, request_id:)
+- ThreadDebouncer uses instance-based approach with `.for(key)`
+- StreamName module uses `extend self` pattern
+- Channel uses hyphenated parameter names ("signed-stream-name")
+- Documentation shows both direct broadcasting and DSL approaches
+
+### Fixed
+- Exact match with production code patterns
+- Proper configuration in initializer using Pulse.config
+- Correct parameter passing to broadcast methods
+
+## [0.1.1] - 2025-01-26
+
+### Fixed
+- Create `app/frontend/types/index.ts` if it doesn't exist instead of failing
+- Prevent duplicate injection of `pulse_request_id` in Current model
+- Prevent duplicate inclusion of `Pulse::RequestIdTracking` in ApplicationController
+
+## [0.1.0] - 2025-01-26
+
+### Added
+- Initial release of Pulse Zero
+- Rails generator for installing real-time broadcasting system
+- Backend components:
+  - Core Pulse module with stream verification
+  - Rails Engine for isolation
+  - Broadcasting system with CRUD events
+  - Model concern with `broadcasts_to` DSL
+  - ActionCable channel for WebSocket subscriptions
+  - Background job for async broadcasting
+  - Request ID tracking for correlation
+- Frontend components (TypeScript):
+  - Subscription manager
+  - Connection monitor with exponential backoff
+  - Recovery strategy for browser tab suspension
+  - Visibility manager for tab focus handling
+  - React hooks: `usePulse` and `useVisibilityRefresh`
+- Comprehensive documentation
+- Test helpers and examples
+
+[Unreleased]: https://github.com/yourusername/pulse_zero/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourusername/pulse_zero/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Pulse Zero Contributors
+
+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,281 @@
+# Pulse Zero
+
+Real-time broadcasting generator for Rails + Inertia.js applications. Generate a complete WebSocket-based real-time system with zero runtime dependencies.
+
+## What is Pulse Zero?
+
+Pulse Zero generates a complete real-time broadcasting system directly into your Rails application. Unlike traditional gems, all code is copied into your project, giving you full ownership and the ability to customize everything.
+
+Features:
+- 🚀 WebSocket broadcasting via ActionCable
+- 🔒 Secure signed streams
+- 📱 Browser tab suspension handling
+- 🔄 Automatic reconnection with exponential backoff
+- 📦 TypeScript support for Inertia + React
+- 🎯 Zero runtime dependencies
+
+## Installation
+
+Add this gem to your application's Gemfile:
+
+```ruby
+group :development do
+  gem 'pulse_zero'
+end
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate pulse_zero:install
+```
+
+## What Gets Generated?
+
+### Backend (Ruby)
+- `lib/pulse/` - Core broadcasting system
+- `app/models/concerns/pulse/broadcastable.rb` - Model broadcasting DSL
+- `app/controllers/concerns/pulse/request_id_tracking.rb` - Request tracking
+- `app/channels/pulse/channel.rb` - WebSocket channel
+- `app/jobs/pulse/broadcast_job.rb` - Async broadcasting
+- `config/initializers/pulse.rb` - Configuration
+
+### Frontend (TypeScript)
+- `app/frontend/lib/pulse.ts` - Subscription manager
+- `app/frontend/lib/pulse-connection.ts` - Connection monitoring
+- `app/frontend/lib/pulse-recovery-strategy.ts` - Recovery logic
+- `app/frontend/lib/pulse-visibility-manager.ts` - Tab visibility handling
+- `app/frontend/hooks/use-pulse.ts` - React subscription hook
+- `app/frontend/hooks/use-visibility-refresh.ts` - Tab refresh hook
+
+## Quick Start
+
+### 1. Enable Broadcasting on a Model
+
+```ruby
+class Post < ApplicationRecord
+  include Pulse::Broadcastable
+  
+  # Broadcast to account-scoped channel
+  broadcasts_to ->(post) { [post.account, "posts"] }
+  
+  # Or broadcast to a simple channel
+  broadcasts "posts"
+end
+```
+
+### 2. Pass Stream Token to Frontend
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Current.account.posts
+    @pulse_stream = Pulse::Streams::StreamName
+      .signed_stream_name([Current.account, "posts"])
+  end
+end
+```
+
+### 3. Subscribe in React Component
+
+```tsx
+import { usePulse } from '@/hooks/use-pulse'
+import { useVisibilityRefresh } from '@/hooks/use-visibility-refresh'
+import { router } from '@inertiajs/react'
+
+export default function Posts({ posts, pulseStream }) {
+  // Handle tab visibility
+  useVisibilityRefresh(30, () => {
+    router.reload({ only: ['posts'] })
+  })
+  
+  // Subscribe to real-time updates
+  usePulse(pulseStream, (message) => {
+    switch (message.event) {
+      case 'created':
+      case 'updated':
+      case 'deleted':
+        router.reload({ only: ['posts'] })
+        break
+    }
+  })
+  
+  return <PostsList posts={posts} />
+}
+```
+
+## Broadcasting Events
+
+Pulse broadcasts four types of events:
+
+### `created` - When a record is created
+```json
+{
+  "event": "created",
+  "payload": { "id": 123, "content": "New post" },
+  "requestId": "uuid-123",
+  "at": 1234567890.123
+}
+```
+
+### `updated` - When a record is updated
+```json
+{
+  "event": "updated",
+  "payload": { "id": 123, "content": "Updated post" },
+  "requestId": "uuid-456",
+  "at": 1234567891.456
+}
+```
+
+### `deleted` - When a record is destroyed
+```json
+{
+  "event": "deleted",
+  "payload": { "id": 123 },
+  "requestId": "uuid-789",
+  "at": 1234567892.789
+}
+```
+
+### `refresh` - Force a full refresh
+```json
+{
+  "event": "refresh",
+  "payload": {},
+  "requestId": "uuid-012",
+  "at": 1234567893.012
+}
+```
+
+## Advanced Usage
+
+### Manual Broadcasting
+
+```ruby
+# Broadcast with custom payload
+post.broadcast_updated_to(
+  [Current.account, "posts"],
+  payload: { id: post.id, featured: true }
+)
+
+# Async broadcasting
+post.broadcast_updated_later_to([Current.account, "posts"])
+```
+
+### Suppress Broadcasts During Bulk Operations
+
+```ruby
+Post.suppressing_pulse_broadcasts do
+  Post.where(account: account).update_all(featured: true)
+end
+
+# Then send one refresh broadcast
+Post.new.broadcast_refresh_to([account, "posts"])
+```
+
+### Custom Serialization
+
+```ruby
+# config/initializers/pulse.rb
+Rails.application.configure do
+  config.pulse.serializer = ->(record) {
+    case record
+    when Post
+      record.as_json(only: [:id, :title, :state])
+    else
+      record.as_json
+    end
+  }
+end
+```
+
+## Configuration
+
+```ruby
+# config/initializers/pulse.rb
+Rails.application.configure do
+  # Debounce window in milliseconds (default: 300)
+  config.pulse.debounce_ms = 300
+  
+  # Background job queue (default: :default)
+  config.pulse.queue_name = :low
+  
+  # Custom serializer
+  config.pulse.serializer = ->(record) { record.as_json }
+end
+```
+
+## Browser Tab Handling
+
+Pulse includes sophisticated handling for browser tab suspension:
+
+- **Quick switches (<30s)**: Just ensures connection is alive
+- **Medium absence (30s-5min)**: Reconnects and syncs data
+- **Long absence (>5min)**: Full page refresh for consistency
+
+Platform-aware thresholds:
+- Desktop Chrome/Firefox: 30 seconds
+- Safari/Mobile: 15 seconds (more aggressive)
+
+## Testing
+
+```ruby
+# In your test files
+test "broadcasts on update" do
+  post = posts(:one)
+  
+  assert_broadcast_on([post.account, "posts"]) do
+    post.update!(title: "New Title")
+  end
+end
+
+# Suppress broadcasts in tests
+Post.suppressing_pulse_broadcasts do
+  # Your test code
+end
+```
+
+## Debugging
+
+Enable debug logging:
+
+```javascript
+// In browser console
+localStorage.setItem('PULSE_DEBUG', 'true')
+```
+
+Check connection health:
+
+```javascript
+import { getPulseMonitorStats } from '@/lib/pulse-connection'
+
+const stats = getPulseMonitorStats()
+console.log(stats)
+```
+
+## Requirements
+
+- Rails 7.0+
+- ActionCable
+- Inertia.js
+- React (Vue/Svelte support coming soon)
+- TypeScript
+
+## Philosophy
+
+Pulse Zero follows the same philosophy as [authentication-zero](https://github.com/lazaronixon/authentication-zero):
+
+- **Own your code**: All code is generated into your project
+- **No runtime dependencies**: The gem is only needed during generation
+- **Customizable**: Modify any generated code to fit your needs
+- **Production-ready**: Includes battle-tested patterns from real applications
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module PulseZero
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def check_prerequisites
+        unless defined?(ActionCable)
+          say "ActionCable is required. Installing...", :yellow
+          generate "action_cable:install"
+        end
+
+        return if File.exist?("app/frontend")
+
+        say "This generator is designed for Inertia.js applications with app/frontend directory", :red
+        exit 1
+      end
+
+      def setup_action_cable
+        # Generate base channel classes if missing
+        unless File.exist?("app/channels/application_cable/connection.rb")
+          template "backend/app/channels/application_cable/connection.rb.tt",
+                   "app/channels/application_cable/connection.rb"
+        end
+
+        unless File.exist?("app/channels/application_cable/channel.rb")
+          template "backend/app/channels/application_cable/channel.rb.tt",
+                   "app/channels/application_cable/channel.rb"
+        end
+
+        # Add route if missing
+        route 'mount ActionCable.server => "/cable"' unless action_cable_route_exists?
+      end
+
+      def copy_backend_files
+        # Core library files
+        template "backend/lib/pulse.rb.tt", "lib/pulse.rb"
+        template "backend/lib/pulse/engine.rb.tt", "lib/pulse/engine.rb"
+        template "backend/lib/pulse/streams/broadcasts.rb.tt", "lib/pulse/streams/broadcasts.rb"
+        template "backend/lib/pulse/streams/stream_name.rb.tt", "lib/pulse/streams/stream_name.rb"
+        template "backend/lib/pulse/thread_debouncer.rb.tt", "lib/pulse/thread_debouncer.rb"
+
+        # Application files
+        template "backend/app/channels/pulse/channel.rb.tt", "app/channels/pulse/channel.rb"
+        template "backend/app/controllers/concerns/pulse/request_id_tracking.rb.tt",
+                 "app/controllers/concerns/pulse/request_id_tracking.rb"
+        template "backend/app/models/concerns/pulse/broadcastable.rb.tt",
+                 "app/models/concerns/pulse/broadcastable.rb"
+        template "backend/app/jobs/pulse/broadcast_job.rb.tt", "app/jobs/pulse/broadcast_job.rb"
+
+        # Configuration
+        template "backend/config/initializers/pulse.rb.tt", "config/initializers/pulse.rb"
+      end
+
+      def copy_frontend_files
+        # TypeScript files in lib/pulse/
+        template "frontend/lib/pulse.ts.tt", "app/frontend/lib/pulse/pulse.ts"
+        template "frontend/lib/pulse-connection.ts.tt", "app/frontend/lib/pulse/pulse-connection.ts"
+        template "frontend/lib/pulse-recovery-strategy.ts.tt", "app/frontend/lib/pulse/pulse-recovery-strategy.ts"
+        template "frontend/lib/pulse-visibility-manager.ts.tt", "app/frontend/lib/pulse/pulse-visibility-manager.ts"
+
+        # React hooks
+        template "frontend/hooks/use-pulse.ts.tt", "app/frontend/hooks/use-pulse.ts"
+        template "frontend/hooks/use-visibility-refresh.ts.tt", "app/frontend/hooks/use-visibility-refresh.ts"
+
+        # Create or append to types/index.ts
+        if File.exist?("app/frontend/types/index.ts")
+          append_to_file "app/frontend/types/index.ts", pulse_types_content
+        else
+          create_file "app/frontend/types/index.ts", pulse_types_content
+        end
+      end
+
+      def setup_current_model
+        if File.exist?("app/models/current.rb")
+          # Check if pulse_request_id is already defined
+          current_content = File.read("app/models/current.rb")
+          unless current_content.include?("pulse_request_id")
+            inject_into_class "app/models/current.rb", "Current" do
+              "  attribute :pulse_request_id\n"
+            end
+          end
+        else
+          template "backend/app/models/current.rb.tt", "app/models/current.rb"
+        end
+      end
+
+      def setup_autoload_paths
+        add_pulse_to_autoload_paths
+      end
+
+      def install_npm_dependencies
+        return unless File.exist?("package.json")
+
+        say "Installing @rails/actioncable...", :green
+        run "npm install @rails/actioncable"
+      end
+
+      def add_pulse_to_autoload_paths
+        # Add lib to autoload paths
+        application_file = "config/application.rb"
+        application_content = File.read(application_file)
+
+        # Add to autoload_lib if not already there
+        return if application_content.include?("config.autoload_lib")
+
+        inject_into_file application_file, after: /class Application < Rails::Application\n/ do
+          <<-RUBY
+    # Autoload lib directory
+    config.autoload_lib(ignore: %w[assets tasks])
+
+          RUBY
+        end
+      end
+
+      def setup_application_controller
+        # Check if already included
+        controller_content = File.read("app/controllers/application_controller.rb")
+        return if controller_content.include?("Pulse::RequestIdTracking")
+
+        inject_into_class "app/controllers/application_controller.rb",
+                          "ApplicationController" do
+          "  include Pulse::RequestIdTracking\n"
+        end
+      end
+
+      def create_documentation
+        template "docs/PULSE_USAGE.md.tt", "docs/PULSE_USAGE.md"
+
+        say "\n✅ Pulse real-time broadcasting has been installed!", :green
+        say "\n⚠️  IMPORTANT: Configure authentication!", :yellow
+        say "The default ApplicationCable connection accepts all connections."
+        say "Edit app/channels/application_cable/connection.rb to add your authentication logic."
+        say "\nNext steps:", :yellow
+        say "1. Configure authentication in app/channels/application_cable/connection.rb"
+        say "2. Read docs/PULSE_USAGE.md for complete setup instructions"
+        say "3. Add 'include Pulse::Broadcastable' to models that need broadcasting"
+        say "4. Use 'usePulse' hook in your React components"
+        say "\nExample:", :blue
+        say <<~EXAMPLE
+          # In your model:
+          class Post < ApplicationRecord
+            include Pulse::Broadcastable
+            broadcasts_to ->(post) { [post.account, "posts"] }
+          end
+
+          # In your controller:
+          @pulse_stream = Pulse::Streams::StreamName.signed_stream_name([Current.account, "posts"])
+
+          # In your React component:
+          usePulse(pulseStream, (message) => {
+            router.reload({ only: ['posts'] })
+          })
+        EXAMPLE
+      end
+
+      private
+
+      def action_cable_route_exists?
+        routes_file = File.read("config/routes.rb")
+        routes_file.include?("ActionCable.server") || routes_file.include?("action_cable")
+      end
+
+      def pulse_types_content
+        <<~TYPES
+
+          // Pulse Types
+          export interface PulseMessage {
+            event: 'created' | 'updated' | 'deleted' | 'refresh'
+            payload: any
+            requestId?: string
+            at: number
+          }
+
+          export interface PulseSubscription {
+            unsubscribe: () => void
+          }
+        TYPES
+      end
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/channels/application_cable/channel.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/channels/application_cable/connection.rb.tt

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = find_verified_user
+    end
+
+    private
+
+    def find_verified_user
+      # Default implementation that accepts all connections
+      # Replace this with your authentication logic
+
+      # Example 1: Allow all connections (development/testing)
+      # Return a simple identifier for the connection
+      "guest_#{SecureRandom.hex(8)}"
+
+      # Example 2: Devise authentication (if using Devise)
+      # if verified_user = env["warden"]&.user
+      #   verified_user
+      # else
+      #   reject_unauthorized_connection
+      # end
+
+      # Example 3: Session-based authentication
+      # if session[:user_id] && verified_user = User.find_by(id: session[:user_id])
+      #   verified_user
+      # else
+      #   reject_unauthorized_connection
+      # end
+
+      # Example 4: JWT token authentication
+      # if verified_user = User.find_by(id: decoded_jwt_user_id)
+      #   verified_user
+      # else
+      #   reject_unauthorized_connection
+      # end
+    end
+
+    # Helper method for JWT authentication (uncomment if needed)
+    # def decoded_jwt_user_id
+    #   token = request.params[:token] || request.headers["Authorization"]&.split(" ")&.last
+    #   return unless token
+    #
+    #   decoded = JWT.decode(token, Rails.application.secret_key_base, true, algorithm: "HS256")
+    #   decoded.first["user_id"]
+    # rescue JWT::DecodeError
+    #   nil
+    # end
+
+    # Helper method for session access (uncomment if needed)
+    # def session
+    #   cookies.encrypted[Rails.application.config.session_options[:key]]
+    # end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/channels/pulse/channel.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Pulse::Channel < ApplicationCable::Channel
+  include Pulse::Streams::StreamName::ClassMethods
+
+  def subscribed
+    signed_name = params["signed-stream-name"]
+    if signed_name && verified_stream_name_from_params
+      # Stream from the signed name (same as what broadcaster uses)
+      stream_from signed_name
+    else
+      reject
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/controllers/concerns/pulse/request_id_tracking.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pulse
+  module RequestIdTracking
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_pulse_request_id
+    end
+
+    private
+
+    def set_pulse_request_id
+      Current.pulse_request_id = request.uuid if defined?(Current) && Current.respond_to?(:pulse_request_id=)
+    end
+  end
+end