faye-redis-ng 1.0.1

package/NPM_PUBLISH.md

@@ -0,0 +1,358 @@
+# NPM Publishing Guide for faye-redis-ng
+
+This guide will help you publish `faye-redis-ng` to npm.
+
+## 🤖 Automated Publishing with Trusted Publishing (Recommended)
+
+This project uses **GitHub Actions** with **Trusted Publishing (OIDC)** - the modern, secure way to publish to npm. No tokens needed!
+
+### 🔒 Why Trusted Publishing?
+
+**Traditional method** ❌:
+- Create npm token
+- Store in GitHub Secrets
+- Risk of token leakage
+- Manual token rotation
+
+**Trusted Publishing** ✅:
+- Zero tokens to manage
+- GitHub authenticates directly with npm
+- More secure (OIDC protocol)
+- Recommended by npm
+
+### Quick Start
+
+**Step 1**: First manual publish (once)
+```bash
+npm login
+npm publish --access public
+```
+
+**Step 2**: Configure on npm
+1. Go to https://www.npmjs.com/package/faye-redis-ng/settings
+2. Publishing access → Add trusted publisher
+3. Provider: **GitHub Actions**
+4. Repository: **YOUR-USERNAME/faye-redis-ng**
+5. Workflow: **publish.yml**
+
+**Step 3**: Push tags
+```bash
+git tag v1.0.1 && git push origin v1.0.1
+```
+
+**Done!** 🎉 Fully automated, zero secrets.
+
+**See `.github/SETUP.md` for detailed setup instructions.**
+
+---
+
+## 📦 Manual Publishing (Alternative)
+
+If you prefer manual control or need to publish without automation:
+
+## Pre-Publishing Checklist
+
+### 1. Verify Package Information
+
+- ✅ Package name: `faye-redis-ng`
+- ✅ Version: `1.0.0` (starting fresh for NG version)
+- ✅ Description updated
+- ✅ Keywords added for discoverability
+- ✅ License: MIT (same as original)
+- ✅ Repository URL (update when you create your fork)
+
+### 2. Prepare Your Repository
+
+**Important**: Update the repository URL in `package.json` to point to YOUR fork:
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR-USERNAME/faye-redis-ng.git"
+  },
+  "homepage": "https://github.com/YOUR-USERNAME/faye-redis-ng",
+  "bugs": "https://github.com/YOUR-USERNAME/faye-redis-ng/issues"
+}
+```
+
+### 3. Files to Include/Exclude
+
+Create or update `.npmignore`:
+
+```
+# Development files
+spec/
+vendor/
+test-*.js
+.git/
+.gitmodules
+*.rdb
+
+# Documentation (keep these)
+!README.md
+!CLAUDE.md
+!REFACTORING.md
+!CHANGELOG.md
+!LICENSE
+```
+
+Or use `files` field in package.json (recommended):
+
+```json
+{
+  "files": [
+    "faye-redis.js",
+    "README.md",
+    "CLAUDE.md",
+    "REFACTORING.md",
+    "LICENSE"
+  ]
+}
+```
+
+### 4. Create Essential Files
+
+**LICENSE** (if not exists):
+```
+MIT License
+
+Copyright (c) 2011-2013 James Coglan (original faye-redis)
+Copyright (c) 2026-present Community Contributors (faye-redis-ng)
+
+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.
+```
+
+**CHANGELOG.md**:
+```markdown
+# Changelog
+
+All notable changes to faye-redis-ng will be documented in this file.
+
+## [1.0.0] - 2026-01-07
+
+### Added
+- Initial release of faye-redis-ng (Next Generation fork)
+- Redis v4 support with Promise-based API
+- Automatic reconnection with exponential backoff
+- ES6+ class syntax and modern JavaScript features
+- Comprehensive error handling and logging
+- Auto re-subscribe after reconnection
+- Better documentation and examples
+
+### Changed
+- Upgraded from callback-based to async/await internally
+- Updated from prototype-based to ES6 class
+- Node.js requirement: >=14.0.0 (was >=0.4.0)
+- All Redis commands updated to v4 API
+
+### Improved
+- Production-ready reconnection handling
+- Better error messages and debugging
+- Updated dependencies to latest versions
+- Modernized codebase while maintaining backward compatibility
+
+### Migration
+- Drop-in replacement for original faye-redis
+- No breaking changes to public API
+- Simply replace `require('faye-redis')` with `require('faye-redis-ng')`
+
+## Original faye-redis
+
+This project is a modernized fork of [faye-redis](https://github.com/faye/faye-redis-node) by James Coglan.
+```
+
+## Publishing Steps
+
+### Step 1: Create npm Account (if you don't have one)
+
+```bash
+npm adduser
+# or
+npm login
+```
+
+### Step 2: Test Package Locally
+
+```bash
+# Test installation locally
+npm pack
+
+# This creates faye-redis-ng-1.0.0.tgz
+# Test it in another project:
+cd /path/to/test-project
+npm install /path/to/faye-redis-ng-1.0.0.tgz
+```
+
+### Step 3: Verify Package Contents
+
+```bash
+# Check what will be published
+npm publish --dry-run
+
+# Review the output carefully
+```
+
+### Step 4: Run Final Checks
+
+```bash
+# Lint package.json
+npm install -g npm-package-json-lint
+npmPkgJsonLint .
+
+# Or manually verify:
+# - All dependencies are correct versions
+# - No sensitive information in any files
+# - README is complete
+# - Version number is correct
+```
+
+### Step 5: Publish to npm
+
+```bash
+# Publish to npm (public)
+npm publish --access public
+
+# If you want to test first, publish to a scoped package:
+# npm publish --access public --tag beta
+```
+
+### Step 6: Verify Publication
+
+```bash
+# Check on npm
+npm view faye-redis-ng
+
+# Install and test
+npm install faye-redis-ng
+```
+
+## Post-Publishing
+
+### 1. Create Git Tag
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+### 2. Create GitHub Release
+
+Go to your GitHub repository and create a release:
+- Tag: `v1.0.0`
+- Title: `v1.0.0 - Initial Release`
+- Description: Copy from CHANGELOG.md
+
+### 3. Update Documentation
+
+- Add badges to README.md with actual npm package link
+- Update homepage URL if needed
+
+### 4. Announce
+
+Consider announcing on:
+- Twitter/X
+- Reddit (r/node, r/javascript)
+- Hacker News
+- Dev.to
+
+## Version Management
+
+### Semantic Versioning
+
+Follow [semver](https://semver.org/):
+
+- **MAJOR**: Breaking changes (2.0.0)
+- **MINOR**: New features, backward compatible (1.1.0)
+- **PATCH**: Bug fixes, backward compatible (1.0.1)
+
+### Publishing Updates
+
+```bash
+# For patches (bug fixes)
+npm version patch
+npm publish
+
+# For minor (new features)
+npm version minor
+npm publish
+
+# For major (breaking changes)
+npm version major
+npm publish
+```
+
+## Troubleshooting
+
+### Package Name Already Taken
+
+If `faye-redis-ng` is taken, consider:
+- `@yourscope/faye-redis-ng`
+- `faye-redis-modern`
+- `faye-redis-v4`
+- `faye-redis-next`
+
+### Can't Publish
+
+Common issues:
+1. **Not logged in**: Run `npm login`
+2. **Name conflict**: Choose different name
+3. **Version exists**: Bump version with `npm version patch`
+4. **Email not verified**: Check npm email verification
+
+## Security
+
+### Before Publishing
+
+- ✅ No API keys or secrets in code
+- ✅ No .env files included
+- ✅ Dependencies are from trusted sources
+- ✅ Run `npm audit` and fix vulnerabilities
+
+```bash
+npm audit
+npm audit fix
+```
+
+### After Publishing
+
+Set up:
+- GitHub security alerts
+- Dependabot
+- npm 2FA for publishing
+
+## Maintenance
+
+### Keeping Updated
+
+1. Monitor dependencies: `npm outdated`
+2. Update dependencies regularly
+3. Test before publishing updates
+4. Keep CHANGELOG.md updated
+5. Respond to issues and PRs
+
+## Questions?
+
+- npm documentation: https://docs.npmjs.com/
+- Semantic versioning: https://semver.org/
+- Package.json docs: https://docs.npmjs.com/cli/v10/configuring-npm/package-json
+
+---
+
+**Good luck with your first publish! 🚀**

package/README.md

@@ -0,0 +1,215 @@
+# faye-redis-ng
+
+[![npm version](https://badge.fury.io/js/faye-redis-ng.svg)](https://www.npmjs.com/package/faye-redis-ng)
+[![Node.js Version](https://img.shields.io/node/v/faye-redis-ng.svg)](https://nodejs.org)
+[![CI](https://github.com/YOUR-USERNAME/faye-redis-ng/workflows/CI/badge.svg)](https://github.com/YOUR-USERNAME/faye-redis-ng/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Next Generation** Redis backend engine for [Faye](http://faye.jcoglan.com) - A modern, maintained fork with Redis v4 support, ES6+ syntax, and automatic reconnection.
+
+## 🎉 What's New in NG (Next Generation)
+
+This is a modernized fork of the original [faye-redis](https://github.com/faye/faye-redis-node) with significant improvements:
+
+### ✨ Key Improvements
+
+- ✅ **Redis v4 Support** - Uses modern Promise-based Redis client API
+- ✅ **ES6+ Syntax** - Modern JavaScript with classes, async/await, const/let
+- ✅ **Auto-Reconnection** - Automatic Redis reconnection with exponential backoff
+- ✅ **Better Error Handling** - Comprehensive error logging and event triggers
+- ✅ **Node.js 22 LTS** - Updated for latest LTS Node.js version
+- ✅ **Zero Breaking Changes** - Drop-in replacement for original faye-redis
+
+### 🔄 Why This Fork?
+
+The original `faye-redis` hasn't been updated since 2015 and uses deprecated dependencies. This fork brings it up to modern standards while maintaining 100% backward compatibility.
+
+## Installation
+
+```bash
+npm install faye-redis-ng
+```
+
+## Usage
+
+This is a **drop-in replacement** for the original `faye-redis`. Simply change the require statement:
+
+```js
+// Before (old faye-redis)
+const redis = require('faye-redis');
+
+// After (faye-redis-ng)
+const redis = require('faye-redis-ng');
+```
+
+Complete example:
+
+```js
+const faye = require('faye');
+const redis = require('faye-redis-ng');
+const http = require('http');
+
+const server = http.createServer();
+
+const bayeux = new faye.NodeAdapter({
+  mount: '/',
+  timeout: 25,
+  engine: {
+    type: redis,
+    host: 'redis.example.com',
+    port: 6379,
+    password: 'your-password', // optional
+    namespace: 'faye',         // optional
+    database: 0                // optional
+  }
+});
+
+bayeux.attach(server);
+server.listen(8000);
+```
+
+## Configuration Options
+
+All original configuration options are supported:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | String | `'localhost'` | Redis server hostname |
+| `port` | Number | `6379` | Redis server port |
+| `password` | String | `undefined` | Redis password (if `requirepass` is set) |
+| `database` | Number | `0` | Redis database number |
+| `namespace` | String | `''` | Prefix for all Redis keys (allows multiple Faye instances) |
+| `socket` | String | `undefined` | Unix socket path (alternative to host/port) |
+| `gc` | Number | `60` | Garbage collection interval in seconds |
+
+## New Features
+
+### Automatic Reconnection
+
+The NG version includes production-ready reconnection handling:
+
+- **Exponential backoff**: 100ms, 200ms, 300ms ... up to 10s
+- **Max retries**: 20 attempts (~2 minutes) before giving up
+- **Auto re-subscribe**: Pub/sub channels automatically re-subscribed after reconnection
+- **State tracking**: Operations pause during reconnection and resume when ready
+
+Example reconnection logs:
+```
+Redis reconnecting in 100ms (attempt 1)
+Redis reconnecting in 200ms (attempt 2)
+...
+Redis subscriber ready
+Redis client ready
+```
+
+### Better Error Handling
+
+All connection errors are logged and trigger events to your Faye server:
+
+```js
+bayeux.bind('error', function(error) {
+  console.error('Redis error:', error);
+});
+```
+
+## Migrating from faye-redis
+
+**No code changes required!** Just update your package.json:
+
+```bash
+npm uninstall faye-redis
+npm install faye-redis-ng
+```
+
+Update your require statement and you're done:
+
+```js
+const redis = require('faye-redis-ng');
+```
+
+## Requirements
+
+- **Node.js**: >= 22.0.0 (LTS)
+- **Redis**: >= 2.8.0 (tested with Redis 6.x and 7.x)
+- **Faye**: >= 1.0.0
+
+## Architecture
+
+This engine implements the Faye engine interface and uses Redis for:
+
+- **Client storage**: Sorted set with last-ping timestamps
+- **Subscriptions**: Sets tracking client-channel relationships
+- **Message queues**: Lists storing queued messages per client
+- **Pub/Sub**: Channels for message notifications and client disconnections
+- **Distributed locking**: For garbage collection coordination
+
+See [CLAUDE.md](./CLAUDE.md) for detailed architecture documentation.
+
+## Development
+
+```bash
+# Install dependencies (includes Faye submodule)
+make prepare
+
+# Run tests (requires Redis server running)
+npm test
+
+# Or run integration tests
+node test-integration.js
+```
+
+## Testing
+
+The test suite requires a running Redis server. For local development:
+
+```bash
+# Start Redis with password
+redis-server --requirepass foobared
+
+# Run tests
+npm test
+```
+
+## Changes from Original
+
+See [REFACTORING.md](./REFACTORING.md) for complete details on modernization changes.
+
+**Summary**:
+- Upgraded from callback-based Redis to Promise-based Redis v4
+- Converted from prototype-based to ES6 class syntax
+- Added automatic reconnection with exponential backoff
+- Modern JavaScript: const/let, arrow functions, async/await
+- Improved error handling and logging
+- Updated all dependencies to current versions
+
+## Credits
+
+- **Original Author**: [James Coglan](http://jcoglan.com/) - Created the original faye-redis
+- **This Fork**: Modernized and maintained by the community
+
+## License
+
+MIT License - Same as the original faye-redis
+
+## Contributing
+
+Contributions are welcome! This is a community-maintained fork. Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Submit a pull request
+
+## Related Projects
+
+- [Faye](http://faye.jcoglan.com/) - Simple pub/sub messaging for the web
+- [Redis](https://redis.io/) - In-memory data structure store
+
+## Support
+
+- **Issues**: [GitHub Issues](http://github.com/faye/faye-redis-node/issues)
+- **Original Project**: [faye-redis](https://github.com/faye/faye-redis-node)
+
+---
+
+**Made with ❤️ by the community** | Keeping faye-redis modern and maintained