pgbus 0.0.1 → 0.1.1

data/.claude/rules/coding-style.md

@@ -1,91 +0,0 @@
-# Coding Style Rules
-
-## File Organization
-
-**MANY SMALL FILES > FEW LARGE FILES**
-
-- High cohesion, low coupling
-- 200-400 lines typical
-- 800 lines maximum per file
-- Extract complex logic to dedicated classes
-- Organize by concern (client, adapter, event_bus, process, web)
-
-## Ruby Style
-
-### Classes & Methods
-
-```ruby
-# Good: Small, focused methods
-def execute(message, queue_name)
-  check_dead_letter(message, queue_name)
-  deserialize_and_run(message)
-  archive(message, queue_name)
-end
-
-# Bad: Giant methods doing everything
-def process_everything
-  # 200 lines of code...
-end
-```
-
-### Error Handling
-
-```ruby
-# Good: Specific error handling
-def execute(message, queue_name)
-  job = deserialize(message)
-  job.perform_now
-  client.archive_message(queue_name, message.msg_id.to_i)
-  :success
-rescue ActiveJob::DeserializationError => e
-  Pgbus.logger.error { "[Pgbus] Deserialization failed: #{e.message}" }
-  :failed
-rescue StandardError => e
-  Pgbus.logger.error { "[Pgbus] Job failed: #{e.message}" }
-  :failed
-end
-
-# Bad: Swallowing errors
-def execute(message, queue_name)
-  deserialize(message).perform_now
-rescue StandardError
-  nil
-end
-```
-
-### PGMQ Operations
-
-```ruby
-# Good: All PGMQ access through Client
-Pgbus.client.send_message(queue, payload)
-Pgbus.client.read_batch(queue, qty: 5)
-
-# Bad: Direct PGMQ calls
-pgmq = PGMQ::Client.new(...)
-pgmq.produce("raw_queue_name", data)
-```
-
-### Thread Safety
-
-```ruby
-# Good: Mutex for shared state
-@mutex.synchronize { @queues_created[name] = true }
-
-# Good: Concurrent primitives
-@pool = Concurrent::FixedThreadPool.new(threads)
-
-# Bad: Unsynchronized shared state
-@queues_created[name] = true  # race condition
-```
-
-## Code Quality Checklist
-
-Before marking work complete:
-- [ ] Code is readable and well-named
-- [ ] Methods are small (<30 lines ideal, <50 max)
-- [ ] Files are focused (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Proper error handling with logging
-- [ ] All PGMQ operations through Client
-- [ ] Thread safety verified for shared state
-- [ ] Rubocop passes

data/.claude/rules/git-workflow.md

@@ -1,56 +0,0 @@
-# Git Workflow Rules
-
-## Commit Messages
-
-Use conventional commits:
-- `feat:` - New feature
-- `fix:` - Bug fix
-- `refactor:` - Code refactoring
-- `perf:` - Performance improvement
-- `docs:` - Documentation only
-- `test:` - Adding/updating tests
-- `chore:` - Maintenance tasks
-- `ci:` - CI/CD changes
-
-Format:
-```
-feat(scope): brief description
-
-Longer explanation if needed. Focus on WHY, not WHAT.
-
-Refs #123
-```
-
-## Branch Naming
-
-- `feature/description` - New features
-- `fix/description` - Bug fixes
-- `refactor/description` - Refactoring
-- `ci/description` - CI changes
-- `chore/description` - Maintenance
-
-## PR Workflow
-
-1. Create branch from `main`
-2. Make focused, atomic commits
-3. Run all validators before pushing
-4. Create PR with description and test plan
-5. Request review
-6. Squash merge when approved
-
-## Pre-Commit Checklist
-
-Run before EVERY commit:
-```bash
-bundle exec rubocop              # Style
-bundle exec rspec <relevant_specs>  # Tests
-```
-
-## Rules
-
-- **NEVER** commit directly to `main`
-- **NEVER** force push to shared branches
-- **ALWAYS** run validators before committing
-- **ALWAYS** write meaningful commit messages
-- Keep commits small and focused
-- One logical change per commit

data/.claude/rules/performance.md

@@ -1,73 +0,0 @@
-# Performance Rules
-
-## Context Window Management
-
-**Critical**: Your context window can shrink significantly with many tools enabled.
-
-Guidelines:
-- Keep under 10 MCPs enabled per project
-- Avoid loading large files unnecessarily
-- Use targeted searches over broad exploration
-
-## PGMQ Performance
-
-### Polling vs LISTEN/NOTIFY
-
-```ruby
-# Good: Use LISTEN/NOTIFY for instant wake-up
-pgmq.enable_notify_insert(queue_name, throttle_interval_ms: 250)
-
-# Polling as fallback only -- not primary mechanism
-sleep(config.polling_interval) # only when LISTEN/NOTIFY unavailable
-```
-
-### Batch Operations
-
-```ruby
-# Good: Batch reads for throughput
-client.read_batch(queue, qty: idle_threads)
-
-# Bad: Single reads in a loop
-idle_threads.times { client.read_message(queue) }
-```
-
-### Connection Pool Sizing
-
-- Pool size should match worker thread count
-- Don't over-provision -- each connection holds PostgreSQL resources
-- Use `-> { ActiveRecord::Base.connection.raw_connection }` in Rails to share the pool
-
-### Queue Table Performance
-
-- PGMQ's `q_` tables use `vt ASC` index for fast reads
-- `FOR UPDATE SKIP LOCKED` prevents contention between workers
-- Archive tables grow unbounded -- consider partitioning for high-volume queues
-- Purge processed events table periodically (idempotency dedup)
-
-## Worker Performance
-
-### Memory Management
-
-```ruby
-# Good: Recycling prevents memory bloat
-max_jobs_per_worker: 10_000
-max_memory_mb: 512
-max_worker_lifetime: 3600
-
-# Bad: Workers running forever without limits
-# (this is solid_queue's problem)
-```
-
-### Thread Pool Sizing
-
-- Match threads to expected concurrency
-- More threads = more PGMQ connections needed
-- Monitor with `pool.queue_length` vs `pool.max_length`
-
-## Performance Checklist
-
-- [ ] LISTEN/NOTIFY enabled for active queues
-- [ ] Batch reads used where possible
-- [ ] Connection pool sized appropriately
-- [ ] Worker recycling configured
-- [ ] No N+1 queries in dashboard DataSource

data/.claude/rules/testing.md

@@ -1,67 +0,0 @@
-# Testing Rules
-
-## TDD Workflow
-
-Follow RED -> GREEN -> REFACTOR:
-
-1. **RED**: Write a failing test first
-2. **GREEN**: Write minimal code to pass
-3. **REFACTOR**: Improve code while keeping tests green
-
-## Coverage Requirements
-
-- **80% minimum** for all code
-- **100% required** for:
-  - ActiveJob adapter (enqueue, execute, DLQ routing)
-  - Event bus (handler, registry, publisher)
-  - Client (PGMQ wrapper)
-  - Configuration
-  - Web::DataSource
-  - Web::Authentication
-
-## Test Type Preference
-
-| Feature involves | Use |
-|-----------------|-----|
-| Configuration / Event / Serializer | Unit spec |
-| Client / PGMQ interaction | Unit spec with mocked PGMQ |
-| ActiveJob adapter | Integration spec |
-| Worker / Supervisor | Unit spec (process behavior) |
-| Dashboard DataSource | Unit spec with mocked client |
-| Dashboard Authentication | Unit spec |
-| Helper formatting | Unit spec |
-
-## RSpec Conventions
-
-```ruby
-# Use let for setup
-let(:config) { Pgbus::Configuration.new }
-
-# Use subject for the thing being tested
-subject(:data_source) { described_class.new(client: mock_client) }
-
-# Use contexts for scenarios
-context "when queue exists" do
-  before { allow(mock_client).to receive(:metrics).and_return(metrics) }
-  it { expect(result).not_to be_nil }
-end
-
-# Use doubles for PGMQ (avoid DB dependency in unit tests)
-let(:mock_client) { double("Pgbus::Client", pgmq: double("pgmq")) }
-```
-
-## PGMQ in Tests
-
-- Mock `Pgbus::Client` in unit tests -- PGMQ requires a real PostgreSQL connection
-- Use doubles for PGMQ message objects (they're `Data.define` value objects)
-- Test configuration without PGMQ connection
-- Integration tests (when added) will need a real PostgreSQL with PGMQ extension
-
-## Test Checklist
-
-- [ ] Tests written BEFORE implementation
-- [ ] All tests pass: `bundle exec rspec`
-- [ ] Coverage meets requirements
-- [ ] No skipped tests without reason
-- [ ] Edge cases covered (nil messages, expired VT, max retries exceeded)
-- [ ] Error paths tested (connection failures, deserialization errors)

data/CLAUDE.md

@@ -1,80 +0,0 @@
-# Pgbus
-
-PostgreSQL-native job processing and event bus for Rails, built on PGMQ.
-
-## Tech Stack
-
-- **Ruby**: >= 3.3 | **Rails**: >= 7.1
-- **Transport**: pgmq-ruby (PGMQ PostgreSQL extension)
-- **Concurrency**: concurrent-ruby
-- **Autoloading**: zeitwerk
-- **Testing**: RSpec
-- **Linting**: RuboCop
-
-## Critical Rules
-
-### Never Do
-1. **NO direct PGMQ calls** — always go through `Pgbus::Client`
-2. **NO hardcoded queue names** — use `config.queue_name()`
-3. **NO raw SQL in dashboard** — use `Web::DataSource`
-4. **NO `Marshal.load`** — JSON serialization only
-5. **NO unsynchronized shared state** — use Mutex or Concurrent primitives
-6. **NO swallowing errors** — log via `Pgbus.logger`, track in `pgbus_failed_events`
-
-### Always Do
-1. **TDD**: Write tests BEFORE implementation
-2. **Worker recycling**: Configure `max_jobs`, `max_memory_mb`, `max_lifetime`
-3. **Dead letter routing**: Check `read_ct` > `max_retries`
-4. **LISTEN/NOTIFY**: Use `enable_notify_insert` for instant wake-up
-5. **Queue prefix**: All queues through `config.queue_name()`
-6. **Visibility timeout**: Always pass `vt:` parameter on reads
-
-## Commands
-
-```bash
-bundle exec rspec          # Run tests
-bundle exec rubocop        # Lint
-bundle exec rake           # Both
-```
-
-## Slash Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/lfg` | Full autonomous workflow: branch → understand → explore → plan → TDD → verify → PR |
-| `/github-review-comments` | Process unresolved PR review comments |
-| `/review-pr` | Review a PR for pattern compliance |
-| `/tdd` | Enforce RED → GREEN → REFACTOR cycle |
-| `/security` | Security audit (PGMQ ops, connections, auth, deserialization) |
-| `/architect` | Coordinate multi-layer development |
-
-## Architecture
-
-```
-Layer 6: Dashboard       app/controllers/pgbus/, app/views/pgbus/
-Layer 5: CLI             lib/pgbus/cli.rb
-Layer 4: Process Model   lib/pgbus/process/ (supervisor, worker, dispatcher, consumer)
-Layer 3: Event Bus       lib/pgbus/event_bus/ (publisher, subscriber, registry, handler)
-Layer 2: ActiveJob       lib/pgbus/active_job/ (adapter, executor)
-Layer 1: Client          lib/pgbus/client.rb (PGMQ wrapper)
-Layer 0: Config          lib/pgbus/configuration.rb, config_loader.rb
-```
-
-## Key Design Decisions
-
-- Worker recycling via `max_jobs_per_worker`, `max_memory_mb`, `max_worker_lifetime` — fixes solid_queue's memory leak problem
-- LISTEN/NOTIFY via PGMQ's `enable_notify_insert` for instant wake-up (polling as fallback only)
-- Dead letter queues: after `max_retries` failed reads (tracked by PGMQ's `read_ct`), move to `_dlq` queue
-- Idempotent events: `pgbus_processed_events` table with (event_id, handler_class) unique index
-- Dashboard via Tailwind CDN + Turbo CDN — zero npm dependency
-
-## Queue Naming
-
-All PGMQ queues are prefixed: `{queue_prefix}_{name}` (default: `pgbus_default`).
-DLQ queues append `_dlq` suffix.
-
-## More Documentation
-
-See `.claude/` directory:
-- `commands/` — Slash command definitions
-- `rules/` — Coding style, git workflow, testing, agents, performance, security

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"pgbus" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["mikael@mhenrixon.com"](mailto:"mikael@mhenrixon.com").

data/bun.lock

@@ -1,18 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "configVersion": 0,
-  "workspaces": {
-    "": {
-      "devDependencies": {
-        "playwright": "^1.50.0",
-      },
-    },
-  },
-  "packages": {
-    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
-
-    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": "cli.js" }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
-
-    "playwright-core": ["playwright-core@1.58.2", "", { "bin": "cli.js" }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
-  }
-}

data/docs/README.md

@@ -1,28 +0,0 @@
-# Pgbus Documentation
-
-## Migration guides
-
-Switching to Pgbus from another job backend? These guides cover what changes, what stays the same, and what to watch out for.
-
-| Guide | Backend | Key differences |
-|-------|---------|-----------------|
-| [Switch from Sidekiq](switch_from_sidekiq.md) | Sidekiq (+ Pro/Enterprise) | Remove Redis, convert native workers to ActiveJob, replace middleware with callbacks |
-| [Switch from SolidQueue](switch_from_solid_queue.md) | SolidQueue | Similar architecture (PostgreSQL + `SKIP LOCKED`), swap config format, gain LISTEN/NOTIFY + worker recycling |
-| [Switch from GoodJob](switch_from_good_job.md) | GoodJob | Both PostgreSQL-native with LISTEN/NOTIFY, swap advisory locks for PGMQ visibility timeouts, gain worker recycling |
-
-## Feature comparison
-
-| Feature | Sidekiq | SolidQueue | GoodJob | Pgbus |
-|---------|---------|------------|---------|-------|
-| Infrastructure | Redis | PostgreSQL | PostgreSQL | PostgreSQL (PGMQ) |
-| ActiveJob adapter | Yes | Yes | Yes | Yes |
-| Bulk enqueue | No | Yes | Yes | Yes |
-| LISTEN/NOTIFY | N/A | No (polling only) | Yes | Yes |
-| Dead letter queues | No (retries only) | No | No | Yes |
-| Worker recycling | No | No | No | Yes |
-| Event bus | No | No | No | Yes |
-| Idempotent events | No | No | No | Yes |
-| Concurrency controls | Enterprise | `limits_concurrency` | `good_job_control_concurrency_with` | `Pgbus::Concurrency` |
-| Recurring/cron jobs | `sidekiq-cron` gem | `config/recurring.yml` | `config.good_job.cron` | Planned |
-| Batches | Pro | No | `GoodJob::Batch` | `Pgbus::Batch` |
-| Web dashboard | `Sidekiq::Web` | Mission Control | `GoodJob::Engine` | `Pgbus::Engine` |