flynn/docs/plans/2026-02-13-gmail-push-revisit-summary.md

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

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

$ 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