faye-redis-ng 1.0.2 → 1.1.1

package/AUTOMATION.md

@@ -1,256 +0,0 @@
-# Automation Setup Complete! 🤖
-
-## ✅ What's Been Set Up
-
-Your repository now has **fully automated publishing** via GitHub Actions!
-
-### 📁 New Files Created
-
-```
-.github/
-├── workflows/
-│   ├── ci.yml          # Run tests on every push/PR
-│   └── publish.yml     # Auto-publish on git tags
-├── SETUP.md           # Detailed setup instructions
-└── RELEASE.md         # Quick release guide
-```
-
-### 🔄 Automated Workflows
-
-#### 1. CI Workflow (Continuous Integration)
-
-**Triggers**: Every push to main/master/develop branches, and all PRs
-
-**What it does**:
-- ✅ Tests with Node.js 22
-- ✅ Spins up Redis service
-- ✅ Runs syntax checks
-- ✅ Runs integration tests
-- ✅ Verifies package can be built
-
-**Status**: Check at https://github.com/YOUR-USERNAME/faye-redis-ng/actions
-
-#### 2. Publish Workflow (Auto-Deploy)
-
-**Triggers**: When you push a version tag (e.g., `v1.0.1`)
-
-**What it does**:
-1. ✅ Verifies tag matches package.json version
-2. ✅ Runs all tests
-3. ✅ Publishes to npm with provenance
-4. ✅ Extracts changelog for this version
-5. ✅ Creates GitHub Release
-6. ✅ Uploads package tarball
-
-**Status**: Automatic on tag push
-
-## 🚀 How to Use (3 Steps!)
-
-### Step 1: One-Time Setup (5 minutes) - Trusted Publishing
-
-This project uses **Trusted Publishing (OIDC)** - the modern, secure way to publish to npm. No tokens needed!
-
-#### A. First Publish (Manual, Once)
-
-```bash
-# Login to npm
-npm login
-
-# Publish first version manually
-npm publish --access public
-```
-
-#### B. Configure Trusted Publishing on npm
-
-1. Go to https://www.npmjs.com/package/faye-redis-ng
-2. Click **Settings** → **Publishing access**
-3. Click **Add trusted publisher**
-4. Fill in:
-   - Provider: **GitHub Actions**
-   - Repository owner: **YOUR-GITHUB-USERNAME**
-   - Repository name: **faye-redis-ng**
-   - Workflow name: **publish.yml**
-5. Click **Add**
-
-**Done!** No tokens, no secrets, fully automated and secure.
-
-### Step 2: Make Changes
-
-Work on your code as usual:
-
-```bash
-git add .
-git commit -m "Fix bug in client reconnection"
-```
-
-### Step 3: Release!
-
-When ready to publish:
-
-```bash
-# For bug fixes (1.0.1 → 1.0.2)
-npm version patch -m "Fix: description"
-
-# For new features (1.0.1 → 1.1.0)
-npm version minor -m "Feature: description"
-
-# For breaking changes (1.0.1 → 2.0.0)
-npm version major -m "Breaking: description"
-
-# Push everything
-git push origin master --follow-tags
-```
-
-**That's it!** GitHub Actions takes over and:
-- Runs all tests
-- Publishes to npm
-- Creates GitHub Release
-- Posts success notification
-
-## 📊 Monitoring
-
-### Check CI Status
-
-Every push shows status:
-- ✅ Green check = All tests passed
-- ❌ Red X = Tests failed
-- 🟡 Yellow = Running
-
-View details: https://github.com/YOUR-USERNAME/faye-redis-ng/actions
-
-### Check Published Version
-
-After releasing:
-1. **npm**: https://www.npmjs.com/package/faye-redis-ng
-2. **GitHub Releases**: https://github.com/YOUR-USERNAME/faye-redis-ng/releases
-
-## 🎯 Example: First Release (v1.0.1)
-
-```bash
-# 1. Ensure everything is committed
-git status  # Should be clean
-
-# 2. Create release
-git tag v1.0.1
-git push origin master
-git push origin v1.0.1
-
-# 3. Watch automation (optional)
-# Go to: https://github.com/YOUR-USERNAME/faye-redis-ng/actions
-# Watch the "Publish to npm" workflow run
-
-# 4. Verify (after 1-2 minutes)
-npm view faye-redis-ng
-# Should show version 1.0.1
-```
-
-## 🔒 Security Features
-
-Your automation includes:
-
-- ✅ **Trusted Publishing (OIDC)**: No tokens to manage or leak
-- ✅ **npm Provenance**: Cryptographic proof of where package was built
-- ✅ **Zero Secrets**: GitHub authenticates directly with npm
-- ✅ **Version Verification**: Prevents publishing wrong versions
-- ✅ **Automated Testing**: Every release is tested first
-- ✅ **Minimal Permissions**: Only specific workflow can publish
-
-## 📋 Quick Reference
-
-### Common Commands
-
-```bash
-# Check CI status locally
-npm test
-
-# Preview what will be published
-npm pack --dry-run
-
-# Create patch release
-npm version patch && git push origin master --follow-tags
-
-# Create minor release
-npm version minor && git push origin master --follow-tags
-
-# Create major release
-npm version major && git push origin master --follow-tags
-```
-
-### Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| Workflow didn't trigger | Check tag starts with `v` (v1.0.1) |
-| npm publish 403 error | Verify trusted publisher configured on npm |
-| Tests failed | Fix tests, push new commit, re-tag |
-| Version already exists | Bump version again |
-| First publish fails | Do manual `npm publish` first, then configure trusted publishing |
-
-## 📚 Documentation
-
-- **Full Setup Guide**: `.github/SETUP.md`
-- **Quick Release**: `.github/RELEASE.md`
-- **CI Workflow**: `.github/workflows/ci.yml`
-- **Publish Workflow**: `.github/workflows/publish.yml`
-
-## 🎉 Benefits
-
-**Before automation (manual)**:
-1. Run tests manually
-2. `npm login`
-3. `npm publish`
-4. Create GitHub release manually
-5. Write release notes
-6. Upload files
-7. Hope nothing breaks
-
-**With automation + Trusted Publishing**:
-1. `git push origin v1.0.1`
-2. ☕ Coffee break
-3. ✅ Done!
-
-**No tokens to manage, no secrets to worry about, fully automated!**
-
-## ⚡ Advanced Features
-
-### Branch Protection (Optional)
-
-Protect your main branch:
-1. Settings → Branches → Add rule
-2. Branch name: `master`
-3. Enable: "Require status checks to pass"
-4. Select: "test" and "lint"
-5. Save
-
-Now all PRs must pass tests before merging!
-
-### Auto-versioning (Optional)
-
-Add to `package.json`:
-```json
-{
-  "scripts": {
-    "release:patch": "npm version patch && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:major": "npm version major && git push --follow-tags"
-  }
-}
-```
-
-Then just: `npm run release:patch`
-
-## 🆘 Need Help?
-
-1. Check `.github/SETUP.md` for detailed instructions
-2. Review workflow logs in Actions tab
-3. Verify trusted publisher is configured on npm
-4. Check package.json version matches tag
-5. Ensure first manual publish is done before automation
-
----
-
-**Automation setup by**: Claude Code
-**Date**: January 2026
-**Ready to publish**: YES! 🚀
-
-**Next step**: Follow "Step 1: One-Time Setup" above, then push your first tag!

package/CHANGELOG.md

@@ -1,98 +0,0 @@
-# Changelog
-
-All notable changes to faye-redis-ng 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.1] - 2026-01-07
-
-### Fixed
-- **Critical**: Fixed `clientExists` method parameter order from `(callback, context, clientId)` to `(clientId, callback, context)` to match original faye-redis API
-  - This was causing "Invalid argument type" errors in Redis operations
-  - Also fixed internal call in `publish` method to use correct parameter order
-
-### Changed
-- **Node.js requirement**: Updated from `>=14.0.0` to `>=22.0.0` (LTS)
-  - Now requires Node.js 22 LTS for long-term support and modern features
-
-## [1.0.0] - 2026-01-07
-
-### 🎉 Initial Release of faye-redis-ng
-
-This is the first release of **faye-redis-ng** (Next Generation), a modern fork of the original faye-redis with significant improvements while maintaining 100% backward compatibility.
-
-### Added
-- **Redis v4 support** with modern Promise-based API
-- **Automatic reconnection** with exponential backoff strategy
-  - Retries with delays: 100ms, 200ms, 300ms ... up to 10s
-  - Max 20 retries (~2 minutes) before giving up
-  - Auto re-subscribe to pub/sub channels after reconnection
-- **ES6+ class syntax** replacing prototype-based patterns
-- **Comprehensive error handling** with error event triggers
-- **Connection state tracking** via `_initialized` flag
-- **Modern JavaScript features**: const/let, arrow functions, async/await, spread operators
-- **Better logging** for debugging and monitoring
-- **Integration tests** independent of Faye vendor submodule
-- **Comprehensive documentation**: README, CLAUDE.md, REFACTORING.md, NPM_PUBLISH.md
-
-### Changed
-- **Package name**: `faye-redis` → `faye-redis-ng`
-- **Version**: Starting at 1.0.0 for NG fork
-- **Node.js requirement**: `>=0.4.0` → `>=22.0.0` (LTS)
-- **Redis client**: Upgraded to v4 Promise-based API
-- **Code structure**: Prototype-based → ES6 class
-- **Internal implementation**: Callbacks → async/await
-
-### Improved
-- Production-ready reliability with automatic reconnection
-- Better error messages with contextual information
-- Code maintainability with modern JavaScript patterns
-- Testing with standalone integration test suite
-
-### Fixed
-- Git submodule URL changed from `git://` to `https://`
-- Deprecated `getset` command replaced with modern API
-- Connection loss scenarios now handled gracefully
-
-### Migration from Original faye-redis
-
-**Drop-in replacement** - just update package name:
-
-```bash
-npm uninstall faye-redis
-npm install faye-redis-ng
-```
-
-Change require statement:
-```javascript
-const redis = require('faye-redis-ng');
-```
-
-That's it! No other changes needed.
-
----
-
-## Original faye-redis History
-
-Below is the changelog from the original [faye-redis](https://github.com/faye/faye-redis-node) project by James Coglan.
-
-### 0.2.0 / 2013-10-01
-
-* Trigger the `close` event as required by Faye 1.0
-
-### 0.1.3 / 2013-05-11
-
-* Fix a bug due to a misuse of `this`
-
-### 0.1.2 / 2013-04-28
-
-* Improve garbage collection to avoid leaking Redis memory
-
-### 0.1.1 / 2012-07-15
-
-* Fix an implicit global variable leak (missing semicolon)
-
-### 0.1.0 / 2012-02-26
-
-* Initial release: Redis backend for Faye 0.8

package/CLAUDE.md

@@ -1,134 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-faye-redis is a Redis-based backend engine for the Faye messaging server. It enables distributing a single Faye service across multiple front-end web servers by storing state and routing messages through Redis. The engine implements the Faye engine interface and manages client connections, subscriptions, message queuing, and pub/sub through Redis.
-
-## Development Setup
-
-```bash
-# Initialize git submodules and prepare dependencies (required for first-time setup)
-make prepare
-
-# Install dependencies only
-npm install
-```
-
-The project depends on the Faye library as a git submodule in `vendor/faye`. The Makefile's `prepare` target initializes this submodule, installs Faye's dependencies, and builds Faye before installing this project's dependencies.
-
-**Note**: The codebase has been modernized (January 2026) to use ES6+ syntax and Redis v4 API. Node.js >= 22.0.0 (LTS) is now required.
-
-## Running Tests
-
-```bash
-# Run all tests
-npm test
-# or
-node spec/runner.js
-```
-
-Tests require a Redis server. The test suite:
-- Uses the jstest framework
-- Imports shared engine specs from the Faye submodule (`vendor/faye/spec/javascript/engine_spec`)
-- Tests both regular Redis connections and Unix socket connections
-- Uses password "foobared" for local testing (no password in CI/Travis)
-- Creates unique namespaces per test run using timestamps to avoid conflicts
-
-For local development, Redis should be configured with `requirepass foobared` (see `spec/redis.conf` for reference configuration).
-
-## Architecture
-
-### Core Engine (faye-redis.js)
-
-The Engine is the main class that implements the Faye engine interface:
-
-- **Initialization**: Creates two Redis connections - one for commands (`_redis`) and one for pub/sub subscriptions (`_subscriber`)
-- **Connection Management**: Supports both TCP connections (host/port) and Unix socket connections
-- **Namespace Support**: All Redis keys are prefixed with an optional namespace to allow multiple Faye instances to share one Redis database
-
-### Data Model in Redis
-
-- **Clients**: Stored as sorted set at `{namespace}/clients` with scores as last-ping timestamps (used for garbage collection)
-- **Client Subscriptions**: Set at `{namespace}/clients/{clientId}/channels` containing channel names
-- **Channel Subscribers**: Set at `{namespace}/channels{channelName}` containing client IDs
-- **Message Queues**: List at `{namespace}/clients/{clientId}/messages` containing JSON-serialized messages
-- **Locks**: Keys at `{namespace}/locks/{lockName}` for distributed locking (used by GC)
-- **Pub/Sub Channels**:
-  - `{namespace}/notifications/messages` - notifies when new messages are queued for a client
-  - `{namespace}/notifications/close` - notifies when a client disconnects
-
-### Key Methods
-
-- `createClient()`: Generates unique client ID using server's `generateId()` and stores in Redis sorted set
-- `clientExists()`: Checks if client timestamp is recent (within 1.6 * server timeout)
-- `destroyClient()`: Removes client from all subscribed channels and deletes message queue
-- `ping()`: Updates client's timestamp in sorted set to keep connection alive
-- `subscribe()/unsubscribe()`: Manages client-channel membership in both directions (client's channels and channel's clients)
-- `publish()`: Finds all subscribers to given channels via `SUNION`, queues messages, and sends notifications
-- `emptyQueue()`: Delivers all queued messages for a client and clears the queue
-- `gc()`: Periodically removes stale clients (those not pinged within 2 * server timeout) using distributed lock
-- `_withLock()`: Implements distributed locking using Redis SETNX and GETSET with automatic expiry
-
-### Event Flow
-
-1. **Message Publishing**: Server calls `publish()` → finds subscribers via SUNION → queues message for each subscriber → publishes notification to message channel
-2. **Message Delivery**: Subscriber receives notification → calls `emptyQueue()` → retrieves and delivers messages to client → deletes queue
-3. **Garbage Collection**: Runs every 60 seconds (configurable) → acquires distributed lock → finds stale clients → destroys each one
-
-## Configuration Options
-
-When integrating faye-redis as a Faye engine, these options are available:
-
-- `host`: Redis hostname (default: 'localhost')
-- `port`: Redis port (default: 6379)
-- `password`: Redis password for auth (default: none)
-- `database`: Redis database number (default: 0)
-- `namespace`: Key prefix for isolation (default: '')
-- `socket`: Unix socket path (alternative to host/port)
-- `gc`: Garbage collection interval in seconds (default: 60)
-
-## Testing Notes
-
-- The TRAVIS environment variable disables Unix socket tests in CI
-- Tests create a unique namespace per run to avoid interference between test runs
-- Tests call `flushAll` after completion to clean up Redis (updated to Redis v4 API)
-- Shared behavior specs from Faye ensure engine compatibility
-
-## Modernization Changes (2026)
-
-The codebase has been refactored with the following improvements:
-
-### Code Modernization
-- **ES6 Class Syntax**: Converted from prototype-based to ES6 `class`
-- **const/let**: Replaced all `var` declarations with `const`/`let`
-- **Arrow Functions**: Used where appropriate for cleaner syntax
-- **Async/Await**: Internal Redis operations use async/await while maintaining callback-based external API for Faye compatibility
-- **Template Literals**: Used spread operators and modern JavaScript features
-
-### Dependencies Updated
-- **redis**: Upgraded from unspecified to `^4.7.0` (Promise-based API)
-- **jstest**: Fixed to `^1.0.5`
-- **Node.js**: Minimum version requirement updated from `>=0.4.0` to `>=22.0.0` (LTS)
-- **Git submodules**: Updated from `git://` to `https://` protocol
-
-### Redis v4 API Changes
-The engine now uses Redis v4's Promise-based API:
-- `createClient()` with configuration object instead of positional arguments
-- Methods return Promises (used with async/await internally)
-- Connection requires explicit `.connect()` call
-- Method names updated to camelCase (e.g., `zAdd`, `sMembers`, `rPush`)
-- Deprecated `getSet` replaced with `set(..., { GET: true })`
-- Authentication via config object instead of `.auth()` method
-
-### Backward Compatibility
-The external API remains callback-based to maintain compatibility with Faye. Internal implementation uses async/await for cleaner code while wrapping results in callbacks for the Faye engine interface.
-
-### Reconnection Handling
-The engine includes automatic Redis reconnection handling:
-- **Exponential backoff**: Retries with increasing delays (100ms, 200ms, ... up to 10s)
-- **Max retries**: 20 attempts (~2 minutes) before giving up
-- **Auto re-subscribe**: Pub/sub channels are automatically re-subscribed after reconnection
-- **Error events**: Connection errors are logged and triggered to the Faye server
-- **State tracking**: `_initialized` flag tracks connection readiness

package/CODE_OF_CONDUCT.md

@@ -1,4 +0,0 @@
-# Code of Conduct
-
-All projects under the [Faye](https://github.com/faye) umbrella are covered by
-the [Code of Conduct](https://github.com/faye/code-of-conduct).