pgbus 0.0.1

data/.claude/commands/security.md

@@ -0,0 +1,122 @@
+---
+description: "Reviews code for security vulnerabilities. Use when auditing PGMQ operations, connection handling, SQL injection risks, or dashboard authentication."
+model: claude-opus-4-6
+argument-hint: "code, feature, or area to review for security"
+---
+
+# Security Specialist
+
+You are the **Security review and vulnerability audit specialist** for pgbus.
+
+## Trigger Contexts
+
+Use this skill when:
+- Auditing PGMQ SQL operations for injection risks
+- Reviewing connection pool handling
+- Checking for race conditions in message processing
+- Reviewing deserialization of job arguments / event payloads
+- Auditing the dashboard web UI
+- Reviewing worker process management
+
+## Key Security Concerns for This Gem
+
+### SQL Injection via Queue Names
+
+```ruby
+# BAD: Unsanitized queue name in SQL
+connection.execute("SELECT * FROM pgmq.q_#{queue_name}")
+
+# GOOD: Sanitize queue names
+def sanitize_name(name)
+  name.gsub(/[^a-zA-Z0-9_]/, "")
+end
+```
+
+PGMQ queue names are interpolated into SQL identifiers. The `Client` validates names, but any new code touching queue names must sanitize.
+
+### Connection Pool Safety
+
+- pgmq-ruby uses `connection_pool` gem for thread-safe pooling
+- Never hold a connection across async boundaries
+- `TransactionalClient` pins a single connection -- ensure it's not leaked
+- When using `-> { ActiveRecord::Base.connection.raw_connection }`, connection lifecycle is Rails-managed
+
+### Message Deserialization
+
+```ruby
+# BAD: Unsafe deserialization
+Marshal.load(message.message)
+
+# GOOD: JSON only
+JSON.parse(message.message)
+```
+
+- All payloads are JSONB -- stick to JSON.parse
+- ActiveJob's `deserialize` handles GlobalID resolution -- trust it but validate
+- Event payloads with `_global_id` call `GlobalID::Locator.locate` -- ensure objects exist
+
+### Dashboard Authentication
+
+- `web_auth` block receives the raw request -- must be configured by the host app
+- Default is `nil` (allow all) -- document this clearly
+- Dashboard inherits from `ActionController::Base` (isolated from host app)
+- Never expose raw PGMQ internals without sanitization
+- Filter sensitive job arguments in the UI
+
+### Worker Process Security
+
+- Supervisor forks child processes -- signal handling must be correct
+- Worker recycling kills processes -- ensure graceful cleanup
+- Heartbeat writes to DB -- validate process ownership
+- Memory measurement uses `ps` / `/proc` -- no shell injection risk (pid is numeric)
+
+### Visibility Timeout / Message Safety
+
+- Messages become visible again after VT expires -- idempotency is critical
+- `read_ct` tracks redeliveries -- DLQ routing must be reliable
+- `FOR UPDATE SKIP LOCKED` prevents double-processing -- verify all read paths use it
+- Archive vs delete: archived messages are queryable, deleted are gone
+
+## Verification Checklist
+
+- [ ] No SQL injection via queue names
+- [ ] All PGMQ operations go through Client (sanitized)
+- [ ] Connection pool properly managed
+- [ ] No unsafe deserialization (JSON only)
+- [ ] Dashboard auth is configurable and documented
+- [ ] Worker signals handled correctly
+- [ ] No secrets in logs or error messages
+- [ ] Idempotency enforced for event handlers
+
+## Security Tools
+
+```bash
+# Static analysis
+bundle exec rubocop
+
+# Check for known vulnerabilities in dependencies
+bundle audit check --update
+
+# Review queue name handling
+grep -r "pgmq\.q_\|pgmq\.a_" lib/
+```
+
+## Common Mistakes to Avoid
+
+| Wrong | Right |
+|-------|-------|
+| String interpolation in SQL | Parameterized queries or sanitized identifiers |
+| Marshal.load on payloads | JSON.parse only |
+| Global PGMQ client without pool | Connection pool with thread safety |
+| Default-open dashboard | Require explicit auth configuration |
+| Swallowing worker errors | Log and track via failed_events table |
+| Infinite visibility timeout | Always set reasonable VT with DLQ fallback |
+
+## Handoff
+
+When complete, summarize:
+- Vulnerabilities found (with severity)
+- Remediation steps
+- Tests to add
+
+Now, focus on security review for the current task.

data/.claude/commands/tdd.md

@@ -0,0 +1,148 @@
+---
+description: "Use when implementing any feature or fixing any bug -- enforces RED-GREEN-REFACTOR: write failing test first, implement minimum code to pass, then refactor."
+---
+
+# TDD Command
+
+Enforce test-driven development methodology with RED -> GREEN -> REFACTOR cycle.
+
+## The TDD Cycle
+
+```text
+RED -> GREEN -> REFACTOR -> REPEAT
+
+RED:      Write a failing test (test MUST fail first)
+GREEN:    Write MINIMAL code to pass (nothing more)
+REFACTOR: Improve code while keeping tests green
+REPEAT:   Next feature/scenario
+```
+
+## When to Use
+
+- Implementing new features
+- Adding new queue types or event handlers
+- Fixing bugs (write test that reproduces bug FIRST)
+- Refactoring existing code
+- Modifying the ActiveJob adapter
+- Changing worker/process behavior
+- Adding dashboard endpoints
+
+## Workflow
+
+### Step 1: Write Failing Tests (RED)
+
+```ruby
+# spec/pgbus/example_spec.rb
+RSpec.describe Pgbus::NewFeature do
+  describe "#process" do
+    context "when message is valid" do
+      it "processes successfully" do
+        expect(subject.process(message)).to eq(:success)
+      end
+    end
+
+    context "when max retries exceeded" do
+      it "routes to dead letter queue" do
+        expect(subject.process(stale_message)).to eq(:dead_lettered)
+      end
+    end
+  end
+end
+```
+
+### Step 2: Run Tests - Verify FAIL
+
+```bash
+bundle exec rspec spec/pgbus/example_spec.rb
+
+FAIL - NotImplementedError / Expected behavior not met
+```
+
+**Tests MUST fail before implementing.** This confirms:
+- Tests are actually running
+- Tests are testing the right thing
+- Implementation doesn't already exist
+
+### Step 3: Implement Minimal Code (GREEN)
+
+Write the minimum code to make the test pass.
+
+### Step 4: Run Tests - Verify PASS
+
+```bash
+bundle exec rspec spec/pgbus/example_spec.rb
+
+N examples, 0 failures
+```
+
+### Step 5: Refactor (IMPROVE)
+
+Improve code while keeping tests green:
+- Extract methods to reduce complexity
+- Improve naming
+- Reduce duplication
+- Ensure thread safety
+
+### Step 6: Run Full Suite
+
+```bash
+bundle exec rspec
+```
+
+## Coverage Requirements
+
+| Code Type | Minimum Coverage |
+|-----------|------------------|
+| All code | 80% |
+| ActiveJob adapter | 100% |
+| Event bus (handler, registry) | 100% |
+| Process model (worker, supervisor) | 100% |
+| Client (PGMQ wrapper) | 100% |
+| Web::DataSource | 100% |
+| Configuration | 100% |
+
+## Test Types to Include
+
+### Unit Tests (Configuration, Event, Serializer)
+- Happy path scenarios
+- Edge cases (nil values, empty queues, expired VT)
+- Error conditions
+
+### Integration Tests (Client, Adapter, Worker)
+- ActiveJob enqueue/execute lifecycle
+- Worker claim-process-archive flow
+- Dead letter queue routing
+- Event publish/subscribe round-trip
+
+### Web Tests (DataSource, Authentication)
+- DataSource with mocked PGMQ client
+- Authentication block allow/deny
+- Helper formatting
+
+## Best Practices
+
+**DO:**
+- Write the test FIRST, before any implementation
+- Run tests and verify they FAIL before implementing
+- Write MINIMAL code to make tests pass
+- Refactor only after tests are green
+- Mock PGMQ client in unit tests (avoid DB dependency)
+- Test worker recycling thresholds explicitly
+
+**DON'T:**
+- Write implementation before tests
+- Skip running tests after each change
+- Write too much code at once
+- Ignore failing tests
+- Test implementation details (test behavior)
+- Skip testing error paths
+
+## Checklist
+
+- [ ] Tests written BEFORE implementation
+- [ ] Tests fail initially (RED phase verified)
+- [ ] Minimal code written to pass (GREEN)
+- [ ] Code refactored with tests still passing
+- [ ] Coverage meets requirements (80%+)
+- [ ] All edge cases covered
+- [ ] Backwards compatibility maintained

data/.claude/rules/agents.md

@@ -0,0 +1,49 @@
+# Agent Orchestration Rules
+
+## Available Agents
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| Explore | Codebase exploration | Finding files, understanding patterns |
+| Plan | Implementation planning | Complex features, architectural decisions |
+| general-purpose | Multi-step tasks | Research, complex searches |
+
+## Immediate Agent Usage
+
+Use agents PROACTIVELY without waiting for user prompt:
+
+1. **Complex feature requests** -> Use Plan agent first
+2. **Codebase exploration** -> Use Explore agent
+3. **Multi-file searches** -> Use Explore agent (not direct Glob/Grep)
+4. **Architectural decisions** -> Use Plan agent
+
+## Parallel Execution
+
+**ALWAYS** use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch multiple agents simultaneously:
+1. Agent 1: Explore client/adapter patterns
+2. Agent 2: Check event bus patterns
+3. Agent 3: Review test coverage
+
+# BAD: Sequential when unnecessary
+First explore, wait, then check patterns, wait, then review...
+```
+
+## When to Use Explore Agent
+
+Use the Explore agent (subagent_type=Explore) instead of direct Glob/Grep when:
+- Open-ended codebase exploration
+- Searching for patterns across client, adapter, event bus, and process layers
+- Answering questions about codebase structure
+- Finding related implementations across modules
+
+## When NOT to Use Agents
+
+Use direct tools when:
+- Reading a specific known file path
+- Simple pattern match in known location
+- Single-file edits
+- Running specific commands

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

@@ -0,0 +1,91 @@
+# 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

@@ -0,0 +1,56 @@
+# 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

@@ -0,0 +1,73 @@
+# 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

@@ -0,0 +1,67 @@
+# 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/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-30
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,80 @@
+# 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

@@ -0,0 +1,10 @@
+# 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").