William Valentin
162 lines
5.2 KiB
Markdown
162 lines
5.2 KiB
Markdown
# Gmail Push Notifications Revisit — Summary
|
|
|
|
**Date**: 2026-02-13
|
|
**Status**: Planned
|
|
**Implementation Plan**: `2026-02-13-gmail-push-revisit-implementation-plan.md`
|
|
|
|
## Overview
|
|
|
|
Enhance Gmail notification reliability through better deployment pattern support, improved configuration surface, actionable error messages, and comprehensive diagnostics.
|
|
|
|
## Problems Addressed
|
|
|
|
1. **Deployment ambiguity**: No clear guidance on supported patterns (push vs pull vs hybrid)
|
|
2. **GCP setup confusion**: Topic/subscription/IAM relationships not documented
|
|
3. **Network constraints**: Tailscale-only gateways cannot receive push webhooks
|
|
4. **Poor error messages**: Failures lack actionable guidance
|
|
5. **Config gaps**: No explicit disable, no pull subscription support
|
|
6. **Diagnostics gap**: Doctor doesn't validate Pub/Sub setup
|
|
|
|
## Solution
|
|
|
|
### Supported Deployment Patterns
|
|
|
|
| Pattern | Config | Network | Reliability |
|
|
|---------|--------|---------|-------------|
|
|
| **Push only** | `pubsub_topic` | Public IP or Tailscale funnel | High (when reachable) |
|
|
| **Pull only** | `pubsub_subscription_id` | Any | High |
|
|
| **Hybrid** ⭐ | Both | Any | Highest |
|
|
| **Polling only** | Neither | Any | Medium (5min latency) |
|
|
|
|
### New Config Fields
|
|
|
|
```yaml
|
|
automation:
|
|
gmail:
|
|
# Push notifications (watch API)
|
|
pubsub_topic: projects/<project>/topics/gmail-push
|
|
disable_push: false # Explicit disable
|
|
|
|
# Pull subscription (new)
|
|
pubsub_subscription_id: projects/<project>/subscriptions/gmail-pull
|
|
pubsub_pull_interval: "60s"
|
|
pubsub_max_messages: 10
|
|
|
|
# History API fallback
|
|
poll_interval: "300s"
|
|
```
|
|
|
|
### Enhanced Doctor Check
|
|
|
|
```bash
|
|
$ flynn doctor
|
|
✓ Gmail configured (push + pull + poll-fallback → telegram/123456789)
|
|
⚠ Gmail configured (push + poll-fallback ⚠️ push requires public endpoint or Tailscale funnel)
|
|
✓ Gmail configured (poll → telegram/123456789)
|
|
```
|
|
|
|
### Improved Error Messages
|
|
|
|
**Before**:
|
|
```
|
|
GmailWatcher: Watch setup failed (will use polling only) — Invalid topicName
|
|
```
|
|
|
|
**After**:
|
|
```
|
|
GmailWatcher: Watch setup failed (push disabled) — Invalid topicName
|
|
Tip: Set automation.gmail.pubsub_topic to "projects/your-project/topics/gmail-push"
|
|
Ensure the topic exists in GCP and the subscription is configured to POST to /gmail/push
|
|
Or set automation.gmail.pubsub_subscription_id for pull-based mode (no webhook required)
|
|
```
|
|
|
|
## Files Modified
|
|
|
|
### Core (4 files)
|
|
- `src/config/schema.ts` — Add new fields
|
|
- `src/automation/gmail.ts` — Add pull support, error hints
|
|
- `src/cli/doctor.ts` — Enhanced validation
|
|
- `package.json` — Add `@google-cloud/pubsub`
|
|
|
|
### Docs (3 files)
|
|
- `README.md` — Rewrite Gmail section
|
|
- `config/default.yaml` — Update examples
|
|
- `docs/plans/state.json` — Mark completed
|
|
|
|
### Tests (2 files)
|
|
- `src/automation/gmail.test.ts` — +7 test cases
|
|
- `src/cli/doctor.test.ts` — +5 test cases
|
|
|
|
## Implementation Checklist
|
|
|
|
- [ ] Add config schema fields (`pubsub_subscription_id`, `pubsub_pull_interval`, `pubsub_max_messages`, `disable_push`)
|
|
- [ ] Implement `setupPullSubscription()` method
|
|
- [ ] Implement `pullSubscriptionMessages()` method
|
|
- [ ] Implement `buildWatchErrorHint()` method
|
|
- [ ] Update `connect()` to handle `disable_push` and call pull setup
|
|
- [ ] Update `disconnect()` to clear pull timer
|
|
- [ ] Enhance `checkGmail` doctor check with mode detection
|
|
- [ ] Add `@google-cloud/pubsub` dependency
|
|
- [ ] Write unit tests for pull mode
|
|
- [ ] Write unit tests for `disable_push`
|
|
- [ ] Write unit tests for error hints
|
|
- [ ] Write doctor check tests
|
|
- [ ] Update README Gmail section
|
|
- [ ] Update `config/default.yaml` example
|
|
- [ ] Manual integration testing (4 modes)
|
|
- [ ] Update `state.json`
|
|
|
|
## Test Plan
|
|
|
|
### Unit Tests (12 new tests)
|
|
- Pull subscription setup (full path)
|
|
- Pull subscription setup (shorthand with project_id)
|
|
- Skip pull when not configured
|
|
- Invalid subscription path warning
|
|
- `disable_push` skips watch setup
|
|
- `disable_push` logs message
|
|
- Error hints (Invalid topicName)
|
|
- Error hints (Permission denied)
|
|
- Error hints (Not found)
|
|
- Connection logging shows modes
|
|
- Doctor: push mode detection
|
|
- Doctor: pull mode detection
|
|
- Doctor: hybrid mode detection
|
|
- Doctor: Tailscale reachability warning
|
|
|
|
### Integration Tests (Manual)
|
|
- [ ] Push only deployment
|
|
- [ ] Pull only deployment
|
|
- [ ] Hybrid deployment
|
|
- [ ] Polling only deployment
|
|
- [ ] Disable push with topic set
|
|
- [ ] Doctor check output for each mode
|
|
- [ ] Error message hints for common failures
|
|
- [ ] Tailscale warning validation
|
|
|
|
## Recommended Default
|
|
|
|
**Hybrid mode** (push + pull + polling):
|
|
- Push: ~Real-time when endpoint is reachable
|
|
- Pull: 60s latency, always works
|
|
- Poll: 300s latency, final fallback
|
|
|
|
## Estimated Effort
|
|
|
|
**Total**: 1-2 days
|
|
- Implementation: 4-6 hours
|
|
- Testing: 2-4 hours
|
|
- Documentation: 2-3 hours
|
|
|
|
## Breaking Changes
|
|
|
|
**None** — existing `pubsub_topic`-only configs continue to work.
|
|
|
|
## Benefits
|
|
|
|
1. ✅ **Clarity**: Explicit deployment patterns with setup instructions
|
|
2. ✅ **Flexibility**: Pull mode supports private deployments (no inbound connections)
|
|
3. ✅ **Reliability**: Hybrid mode ensures delivery across all network configs
|
|
4. ✅ **Debuggability**: Error hints + doctor checks catch misconfigurations
|
|
5. ✅ **Documentation**: Comprehensive README with GCP setup, troubleshooting
|