Support Upstash and Vercel KV environment variables for Redis authentication

CHANGES_SUMMARY.md

@@ -0,0 +1,151 @@
+# Summary of Changes - Redis Environment Variable Fix
+
+## Issue Addressed
+User comments #3504737289 and #3504805230 pointed out:
+1. Confusion about which environment variables to use
+2. Non-standard `UPSTASH_REST_API_*` variables were added but aren't provided by any platform
+3. Need to support Vercel KV variables: `KV_REST_API_URL`, `KV_URL`, `REDIS_URL`
+4. Maintain fallback to `./coaia.json` and `~/coaia.json`
+
+## Changes Made
+
+### Code Changes (`coaiapy/coaiamodule.py`)
+
+#### Removed
+- ❌ `UPSTASH_REST_API_URL` support (non-standard, confusing)
+- ❌ `UPSTASH_REST_API_TOKEN` support (non-standard, confusing)
+
+#### Added
+- ✅ `KV_REST_API_URL` support (Vercel KV REST API)
+- ✅ `KV_REST_API_TOKEN` support (Vercel KV REST API)
+- ✅ `KV_URL` support (Vercel connection string parsing)
+- ✅ `REDIS_URL` support (Vercel connection string parsing)
+- ✅ Connection string parsing for `rediss://` format
+
+#### Kept (Already Working)
+- ✅ `UPSTASH_REDIS_REST_URL` (Upstash direct)
+- ✅ `UPSTASH_REDIS_REST_TOKEN` (Upstash direct)
+- ✅ `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` (traditional)
+- ✅ Config file support (`./coaia.json`, `~/coaia.json`)
+- ✅ `--verbose` flag for debugging
+
+### Priority Order (Updated)
+1. **Upstash Direct** - `UPSTASH_REDIS_REST_*`
+2. **Vercel KV REST** - `KV_REST_API_*`
+3. **Vercel Connection Strings** - `KV_URL` or `REDIS_URL`
+4. **Traditional Redis** - `REDIS_HOST`/`REDIS_PASSWORD`
+5. **Config Files** - `./coaia.json` or `~/coaia.json`
+
+### Documentation Changes
+
+#### New Files
+1. **`ENVIRONMENT_VARIABLES_REFERENCE.md`**
+   - Quick reference for all supported variables
+   - Examples for each platform (Upstash, Vercel)
+   - Priority order explanation
+   - Troubleshooting guide
+   - Migration guide
+
+2. **`UPDATE_NOTES.md`**
+   - Explains the correction from non-standard to standard variables
+   - Why the change was needed
+   - Migration instructions
+
+#### Updated Files
+1. **`REDIS_FIX_DOCUMENTATION.md`**
+   - Removed references to `UPSTASH_REST_API_*`
+   - Added Vercel KV variables
+   - Updated examples to show correct variable names
+
+2. **Error Messages in `coaiamodule.py`**
+   - Updated to mention correct variables
+   - Added clearer troubleshooting steps
+
+## Verification
+
+### Tests Performed
+✅ All syntax checks pass
+✅ Help text shows `--verbose` flag
+✅ Code compiles without errors
+✅ Tested all variable formats:
+  - Upstash direct variables
+  - Vercel KV REST API variables
+  - Vercel connection strings (KV_URL, REDIS_URL)
+  - Priority order works correctly
+
+### Platform Compatibility
+
+| Platform | Variables | Status |
+|----------|-----------|--------|
+| Upstash Direct | `UPSTASH_REDIS_REST_*` | ✅ Supported |
+| Vercel KV | `KV_REST_API_*` | ✅ Supported |
+| Vercel KV | `KV_URL`, `REDIS_URL` | ✅ Supported |
+| Traditional Redis | `REDIS_HOST`, etc. | ✅ Supported |
+| Config Files | `coaia.json` | ✅ Supported |
+
+## User Impact
+
+### Before This Fix
+- ❌ Confusing `UPSTASH_REST_API_*` variables that don't match any platform
+- ❌ Vercel KV variables not supported
+- ❌ Users had to manually figure out which variables to use
+
+### After This Fix
+- ✅ Only standard platform-provided variables supported
+- ✅ All Vercel KV variable formats work
+- ✅ Clear documentation showing which variables to use for each platform
+- ✅ Easy to debug with `--verbose` flag
+
+## How Users Should Configure
+
+### Upstash Direct Users
+```bash
+# .env
+UPSTASH_REDIS_REST_URL=https://your-instance.upstash.io
+UPSTASH_REDIS_REST_TOKEN=your_token
+```
+
+### Vercel Users (Option 1: REST API)
+```bash
+# .env (from Vercel dashboard)
+KV_REST_API_URL=https://your-instance.upstash.io
+KV_REST_API_TOKEN=your_token
+```
+
+### Vercel Users (Option 2: Connection String)
+```bash
+# .env (from Vercel dashboard)
+KV_URL=rediss://default:password@host.upstash.io:6379
+```
+
+### Testing
+```bash
+# Verify configuration with verbose mode
+coaia tash TEST_KEY "test" --verbose
+
+# Expected output shows:
+# - Connecting to Redis server:
+#   Host: your-host.upstash.io
+#   Port: 6379
+#   SSL: True
+#   Password: ***word
+#   Status: Connection established successfully
+```
+
+## Commits
+
+1. **7e3f80f** - Fix environment variable naming: Support Vercel KV variables, remove confusing UPSTASH_REST_API_*
+2. **0373dfa** - Add comprehensive environment variables reference and update notes
+
+## Next Steps for Users
+
+1. ✅ Update .env files to use correct variable names for your platform
+2. ✅ Test with `--verbose` flag to verify configuration
+3. ✅ See `ENVIRONMENT_VARIABLES_REFERENCE.md` for complete reference
+4. ✅ See `UPDATE_NOTES.md` for migration guide
+
+## Resolution
+
+Both user comments have been addressed:
+- ✅ #3504737289 - Removed confusing `UPSTASH_REST_API_*` variables
+- ✅ #3504805230 - Added full Vercel KV support, maintained config file fallback

ENVIRONMENT_VARIABLES_REFERENCE.md

@@ -0,0 +1,162 @@
+# Supported Environment Variables - Quick Reference
+
+## Redis/Upstash Connection Variables
+
+### Priority Order (Highest to Lowest)
+
+1. **Upstash Direct (REST API)**
+   ```bash
+   UPSTASH_REDIS_REST_URL=https://your-instance.upstash.io
+   UPSTASH_REDIS_REST_TOKEN=your_token_here
+   ```
+
+2. **Vercel KV (REST API)**
+   ```bash
+   KV_REST_API_URL=https://your-instance.upstash.io
+   KV_REST_API_TOKEN=your_token_here
+   ```
+
+3. **Vercel KV (Connection String)**
+   ```bash
+   KV_URL=rediss://default:your_password@your-host.upstash.io:6379
+   # OR
+   REDIS_URL=rediss://default:your_password@your-host.upstash.io:6379
+   ```
+
+4. **Traditional Redis**
+   ```bash
+   REDIS_HOST=your-host.upstash.io
+   REDIS_PORT=6379
+   REDIS_PASSWORD=your_password
+   REDIS_SSL=true
+   ```
+
+5. **Config Files** (lowest priority)
+   - `./coaia.json` (current directory)
+   - `~/coaia.json` (home directory)
+
+   ```json
+   {
+     "jtaleconf": {
+       "host": "your-host.upstash.io",
+       "port": 6379,
+       "password": "your_password",
+       "ssl": true
+     }
+   }
+   ```
+
+## When to Use Each Format
+
+### Use Upstash Direct Format When:
+- You're using Upstash directly (not through Vercel)
+- You have the Upstash dashboard credentials
+
+### Use Vercel KV Format When:
+- You're deploying on Vercel
+- Vercel automatically sets these variables
+- You're using Vercel's KV storage integration
+
+### Use Config Files When:
+- You want to commit configuration (without secrets)
+- You need project-specific defaults
+- Environment variables aren't available
+
+## Example .env Files
+
+### For Upstash Direct Users
+```bash
+# .env
+UPSTASH_REDIS_REST_URL=https://talented-aardvark-12345.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AaBbCcDdEeFf123456
+```
+
+### For Vercel Users (REST API)
+```bash
+# .env (copied from Vercel dashboard)
+KV_REST_API_URL=https://full-alpaca-12634.upstash.io
+KV_REST_API_TOKEN=AaBbCcDdEeFf123456
+KV_REST_API_READ_ONLY_TOKEN=XxYyZz789012
+```
+
+### For Vercel Users (Connection String)
+```bash
+# .env (copied from Vercel dashboard)
+KV_URL=rediss://default:AaBbCcDdEeFf123456@full-alpaca-12634.upstash.io:6379
+REDIS_URL=rediss://default:AaBbCcDdEeFf123456@full-alpaca-12634.upstash.io:6379
+```
+
+## Testing Your Configuration
+
+```bash
+# Test with verbose mode to see which configuration is being used
+coaia tash TEST_KEY "test value" --verbose
+
+# Expected output:
+# Connecting to Redis server:
+#   Host: your-host.upstash.io
+#   Port: 6379
+#   SSL: True
+#   Password: ***3456
+#   Status: Connection established successfully
+# Key: TEST_KEY  was just saved to memory.
+```
+
+## Troubleshooting
+
+### Wrong Redis Server Being Used?
+Run with `--verbose` to see which host is being connected to:
+```bash
+coaia tash KEY "value" --verbose
+```
+
+Check the priority order - OS environment variables override .env file, which overrides config files.
+
+### "Invalid username-password pair" Error?
+1. Verify your credentials are correct
+2. Check which variables you're setting match your provider:
+   - Upstash direct → Use `UPSTASH_REDIS_REST_*`
+   - Vercel → Use `KV_*` variables
+3. Use `--verbose` to see the masked password and verify it's correct
+
+### Variables Not Being Loaded from .env?
+1. Ensure `.env` file is in your current working directory
+2. Check for typos in variable names
+3. OS environment variables take priority over .env file
+4. Use `--verbose` to confirm which configuration is active
+
+## Migration Guide
+
+### Migrating from Old UPSTASH_REST_API_* Variables
+If you were using the non-standard `UPSTASH_REST_API_*` variables, update to standard names:
+
+**Old (no longer supported):**
+```bash
+UPSTASH_REST_API_URL=...
+UPSTASH_REST_API_TOKEN=...
+```
+
+**New (choose based on your provider):**
+```bash
+# For Upstash direct:
+UPSTASH_REDIS_REST_URL=...
+UPSTASH_REDIS_REST_TOKEN=...
+
+# For Vercel KV:
+KV_REST_API_URL=...
+KV_REST_API_TOKEN=...
+```
+
+## Summary Table
+
+| Variable | Provider | Format | Priority |
+|----------|----------|--------|----------|
+| `UPSTASH_REDIS_REST_URL` | Upstash | HTTPS | 1 (Highest) |
+| `UPSTASH_REDIS_REST_TOKEN` | Upstash | Token | 1 |
+| `KV_REST_API_URL` | Vercel | HTTPS | 2 |
+| `KV_REST_API_TOKEN` | Vercel | Token | 2 |
+| `KV_URL` | Vercel | Connection String | 3 |
+| `REDIS_URL` | Vercel | Connection String | 3 |
+| `REDIS_HOST` | Generic | Hostname | 4 |
+| `REDIS_PASSWORD` | Generic | Password | 4 |
+| Config files | Any | JSON | 5 (Lowest) |