This directory contains the mqttx-persistence skill for configuring session state persistence with Redis or file storage.

mqttx-persistence/
├── SKILL.md                          # Main skill documentation
├── assets/                           # Code templates and examples
│   ├── redis-storage.go.tmpl        # Redis persistence template
│   ├── file-storage.go.tmpl         # File persistence template
│   └── storage-config.yaml.tmpl     # Storage configuration template
├── references/                       # Reference documentation
│   └── storage-comparison.md        # Detailed storage backend comparison
└── scripts/                          # Helper scripts
    └── test-persistence.sh          # Persistence testing script

Core skill file containing:

• When to use this skill
• Prerequisites and setup instructions
• Step-by-step implementation guide
• Code examples for all storage backends
• Common issues and troubleshooting
• Production deployment checklist
• Related skills and references

Complete Redis persistence implementation example featuring:

• Environment-based configuration
• Session manager setup with Redis storage
• Event handling for session lifecycle
• Subscription and publishing examples
• Graceful shutdown handling
• Production-ready patterns

Complete file persistence implementation example featuring:

• Local file storage configuration
• Directory management
• Session state preservation
• Automatic session recovery
• Event monitoring
• Best practices for file-based persistence

Comprehensive configuration template including:

• Memory storage setup
• File storage configuration
• Redis storage configuration (basic and advanced)
• Production examples for different scenarios
• Security best practices
• Monitoring and health check configuration
• Troubleshooting guide

Detailed comparison document covering:

• Quick comparison table of all storage backends
• In-depth analysis of Memory, File, and Redis storage
• Performance metrics and benchmarks
• Use cases and decision matrix
• Migration guides between storage types
• Cost analysis
• Best practices for each backend

Automated test script that:

• Tests file, Redis, and memory storage backends
• Validates session persistence
• Checks storage configuration
• Verifies data integrity
• Provides clear pass/fail results
• Includes helpful diagnostics

1. Read SKILL.md first - It's your starting point
2. Choose your storage backend - Memory, File, or Redis
3. Use appropriate template - Copy from assets/ directory
4. Configure your application - Use storage-config.yaml.tmpl as reference
5. Test persistence - Run test-persistence.sh script
6. Read storage comparison - For detailed decision making

# Use the file storage template
cat assets/file-storage.go.tmpl > my_app.go

# Edit configuration
# Set STORAGE_DIR, MQTT_BROKER, etc.

# Run
go run my_app.go

# Use the Redis storage template
cat assets/redis-storage.go.tmpl > my_app.go

# Set environment variables
export REDIS_ADDR=localhost:6379
export MQTT_BROKER=tcp://localhost:1883

# Run
go run my_app.go

# Test file storage
./scripts/test-persistence.sh file ./test_sessions

# Test Redis storage
./scripts/test-persistence.sh redis localhost:6379

# Test memory storage (no persistence)
./scripts/test-persistence.sh memory

Use mqttx-persistence when you need:

• Distributed systems with multiple instances sharing session state
• Session recovery after unexpected disconnections or restarts
• QoS 1/2 message persistence and guaranteed delivery
• Offline message handling and buffering
• High-availability MQTT deployments
• Production environments requiring session durability
• IoT devices with intermittent connectivity
• Long-running sessions that need to survive process restarts

• mqttx-quickstart - Learn MQTT X basics
• mqttx-tls-security - Secure your persistent sessions
• mqttx-multi-session - Manage multiple persistent sessions
• mqttx-events - Handle session lifecycle events
• mqttx-production - Complete production deployment

• /workspace/examples/redis_storage/main.go - Redis storage example
• /workspace/store.go - File and memory storage implementation
• /workspace/store_redis.go - Redis storage implementation

When updating this skill:

1. Keep SKILL.md as the primary documentation
2. Ensure templates are tested and working
3. Update storage-comparison.md with new features
4. Test scripts should pass on clean environment
5. Follow the structure of other skills

This skill is part of the MQTT X project.