**Goal:** Replace polling-based Bitable sync with event-driven (push) notifications from Feishu to Bugger.
---
## TL;DR
⚠️ **Conditionally feasible.** The best approach is a **WebSocket Long Connection** to Feishu's event platform, which does NOT require a public-facing server. A `feishu-connector` service can maintain this connection, listen for `drive.file.bitable_record_changed_v1` events, and notify the Bugger macOS app to refresh.
**Critical caveat:** Feishu only allows the Bitable **owner or manager** to subscribe to events (§7.1). For editor/viewer users, the connector cannot subscribe — Bugger falls back to polling for those Bitables. This is a **progressive enhancement** on top of polling, not a replacement.
**Phase 0 (before any code):** Verify the subscribe permission boundary with Bugger's target user roles. If all target users are editors only, pivot to improved polling (§8.2).
---
## 1. Current State (Bugger)
Bugger currently polls Feishu's Bitable REST API:
```
Bugger (macOS) ──[Timer: every N min]──▶ GET /bitable/v1/apps/{appToken}/tables/{tableId}/records
│
▼
Feishu Cloud
```
**Pain points:**
- Latency up to the poll interval (default 5 min)
- Wasted API calls when nothing changed
- Timer-based, no real-time awareness
**Existing Bugger Feishu integration:**
- OAuth 2.0 with `user_access_token` + `refresh_token`
- `tenant_access_token` obtained via `app_id` + `app_secret`
- `FeishuAuthService` already handles both token types
- `FeishuService` already handles Bitable record fetching
---
## 2. Feishu Event Subscription Options
Feishu provides **three** mechanisms to receive Bitable change events:
### Option A: WebSocket Long Connection (⭐ Recommended)
The raw `bitable_record_changed_v1` event includes full `before_value` / `after_value` for every changed field. For a large Bitable record, this can be several KB — enough to exceed `DistributedNotificationCenter`'s ~2 KB payload limit.
**Feishu does NOT support server-side field filtering** on the event subscription — the entire changed record is always delivered. However, the connector can filter client-side before notifying Bugger:
```
Feishu ──[full event]──▶ Connector ──[filtered: only changed fields]──▶ Bugger
```
**Filtering strategies (client-side, in `BitableEventHandler`):**
| Strategy | What Bugger Receives | Payload Reduction |
| **Assignee-only** | Only `action_list` entries where the changed field is the assignee/person column | ~90%+ for typical records |
| **Field whitelist** | Only `action_list` entries matching a configured set of field names/IDs | Configurable |
| **Change summary** | `{table_id, record_id, revision, changed_fields: ["Assignee"]}` — no before/after values | ~95%+, fits easily in DNC |
| **Wake-up signal only** | `{table_id, revision}` — Bugger does a full re-fetch | Minimal (~100 bytes), simplest |
**Recommendation:** Start with the **wake-up signal only** approach. It's the simplest, safest for DNC payload limits, and Bugger already knows how to fetch records. The connector just needs to say "table X changed, go fetch." This avoids the entire payload-size concern and keeps the notification channel trivial.
---
## 4. WebSocket Long Connection Protocol Details
### 4.1 Protobuf Frame Format (`pbbp2.proto`)
```protobuf
message PbFrame {
int32 method = 1; // 0 = CONTROL, 1 = DATA
bytes payload = 2; // JSON string for DATA frames
map<string,string> headers = 3; // message_id, seq, sum, etc.
}
```
### 4.2 Connection Lifecycle
```
1. Obtain tenant_access_token
POST /open-apis/auth/v3/tenant_access_token/internal
Server sends ping_interval. Client must send CONTROL frames at that interval.
```
### 4.3 Fragment Reassembly
Large events may be split across multiple PbFrames. Headers provide:
- `message_id` — groups fragments of the same logical message
- `sum` — total fragment count
- `seq` — 0-indexed fragment number
Client must buffer and reassemble by `message_id`.
### 4.4 Deduplication
Platform uses at-least-once delivery. Use `header.event_id` for idempotency.
---
## 5. Architecture Proposal: feishu-connector
### 5.1 High-Level Design
**Key architectural principle: Polling is the primary path; push is a progressive enhancement.** The connector provides real-time notifications only for Bitables where the user has owner/manager permissions (§7.1). For all others, the existing `PollerService` remains the sole refresh mechanism. Bugger operates in a per-Bitable mixed mode.
**Recommendation: DistributedNotificationCenter with wake-up-signal pattern.**
The connector sends a minimal payload — just `{table_id, revision}` (~100 bytes) — and Bugger does a full re-fetch. This eliminates the payload-size concern entirely (§3.1). The signal is idempotent and loss-tolerant since Bugger's `PollerService` runs as a periodic fallback.
**Fallback:** If DNC proves unreliable in practice, switch to **localhost HTTP** on a fixed port. The wake-up-signal approach keeps the payload tiny regardless of transport.
The connector can **reuse the same credentials** (app_id, app_secret from Info.plist) and obtain its own `tenant_access_token`. Alternatively, Bugger can share its token via Keychain (same access group).
### 5.5 Fallback Strategy
The connector handles **event loss gracefully**:
```
Event received ──▶ Notify Bugger ──▶ Bugger.fetchNow()
│
If connector disconnects: │
→ Bugger's PollerService continues │
as periodic fallback │
│
When connector reconnects: │
→ Full re-fetch to catch missed │
events │
```
Bugger's existing `PollerService` should remain as a fallback (e.g., every 15–30 min) to catch any events missed during connector downtime.
---
## 6. Implementation Complexity Assessment
### 6.1 Swift Protobuf Implementation
Feishu's WebSocket uses a custom binary protocol (`pbbp2.proto`). In Swift:
| Option | Effort | Risk |
|--------|--------|------|
| **SwiftProtobuf (Apple)** | Medium | Official, well-maintained. Need `.proto` → Swift codegen |
| **Manual binary encode/decode** | High | Error-prone, but avoids dependency |
| **Use `Codable` + manual frame parsing** | Medium | Protobuf wire format is straightforward for this simple schema |
The `PbFrame` schema is simple enough (3 fields: int32, bytes, map) that a manual binary encoder/decoder (~200 lines) may be viable and avoids a Protobuf dependency.
| **Subscribe requires doc owner/manager** | 🔴 Critical | **Showstopper.** The subscribing user must be the Bitable owner or have manager permissions. If Bugger's user is a collaborator/editor only, the WebSocket approach is non-viable for that Bitable. See §7.1 for deep-dive and alternatives. |
| **No official Swift SDK** | Medium | Protocol is documented; implement manually. PbFrame schema is simple. |
| **Protobuf complexity** | Low | Use Apple's SwiftProtobuf, or hand-roll ~150 lines for the simple schema. |
| **WebSocket disconnects** | Medium | Auto-reconnect with exponential backoff. Bugger's PollerService is fallback. |
| **Event loss during disconnect** | Medium | On reconnect, trigger full re-fetch. PollerService runs as periodic safety net. |
| **Feishu API changes** | Low | Protocol is stable. Event schema versioned (`schema: "2.0"`). |
| **App must be "published"** | Medium | Feishu requires app version publication before it can subscribe to events. Acceptable for internal tool, but adds setup friction. |
| **macOS sandboxing** | Medium | If the connector ships inside Bugger's app bundle, the sandbox may block outbound WebSocket connections. Requires `com.apple.security.network.client` entitlement. If distributed outside the App Store (direct download), sandboxing may not apply. See §7.2. |
| Viewer / Commenter | ❌ No | ❌ Must fall back to polling |
**What Bugger can do about it:**
1. **Detect at setup time.** When the user configures a Bitable in Bugger, call the subscribe API. If it returns a permission error, log it clearly and fall back to polling for that Bitable. Don't silently fail.
2. **Per-Bitable mode.** Bugger can support a mixed mode — WebSocket push for Bitables where the user is owner/manager, polling for others. The connector subscribes only to eligible Bitables.
3. **User-facing guidance.** If subscription fails, Bugger should tell the user exactly what's needed: *"To enable real-time sync, ask the Bitable owner to grant you manager permissions, or ask them to install Bugger and set up the connector."*
4. **Polling remains the universal fallback.** Even with the connector, Bugger's `PollerService` is the baseline that works for all permission levels. The connector is a progressive enhancement, not a replacement.
**Verdict:** This doesn't kill the project — it scopes it. The connector is a **best-effort push layer** on top of polling, not a replacement for it. The architecture must treat polling as the primary path and push as an optimization available to owner/manager users.
### 7.2 macOS Sandboxing Considerations
If `feishu-connector` is distributed as part of Bugger's app bundle (vs. a standalone CLI):
| **App Store distribution** | ✅ Mandatory | Needs `com.apple.security.network.client` entitlement (outbound only — granted by default in most templates) |
Outbound WebSocket (client-initiated) is the least restricted network operation — this entitlement is included in Xcode's default sandbox template. It should not be a blocker.
**If the connector also listens on localhost** (for the localhost HTTP fallback), it additionally needs:
```xml
<key>com.apple.security.network.server</key>
<true/>
```
**Recommendation:** Distribute the connector as a LaunchAgent daemon (via `.plist` in `~/Library/LaunchAgents/`), not embedded in the app bundle. This avoids sandboxing entirely and is the standard pattern for macOS background services. If it must ship inside the bundle, add the network client entitlement explicitly.
---
## 8. Alternatives Considered
### 8.1 Go/Python Sidecar
Run the Feishu WebSocket client in Go or Python (using official SDK), notifying Bugger via localhost HTTP.
| Pros | Cons |
|------|------|
| Official SDK support | Two runtimes to manage |
| Less protocol risk | Distribution complexity |
| Faster to prototype | User must install Go/Python runtime |
Verdict: Viable fallback if pure Swift proves too difficult.
### 8.2 Improve Polling Instead
Shorten poll interval + use conditional requests (ETags / If-Modified-Since).
| Pros | Cons |
|------|------|
| Zero new infrastructure | Still polling |
| Immediate improvement | Feishu Bitable API may not support conditional requests |
| No Feishu platform config needed | Higher API call volume |
Verdict: Quick win, but doesn't solve the fundamental problem. Feishu Bitable List Records API does not support ETags.
### 8.3 Bitable Automation + ngrok
Use Bitable's built-in Automation to send HTTP requests to an ngrok tunnel → local server.
| Pros | Cons |
|------|------|
| Zero code for Feishu integration | ngrok dependency |
| Simple to configure | ngrok URL changes on restart |
| | Fragile for a long-running tool |
Verdict: Good for prototyping, not for production.
---
## 9. Recommendation
### Build `feishu-connector` as a Swift CLI/daemon with per-Bitable eligibility
**Guiding principle:** The connector is a **best-effort push layer** on top of polling — not a replacement. Polling remains the universal fallback for all Bitables. The connector accelerates refresh for Bitables where the user has owner/manager permissions.
1. Using Bugger's existing auth, call `POST /drive/v1/files/{file_token}/subscribe` for a test Bitable
2. Verify the user role required (owner vs. manager vs. editor)
3. If the test user (editor role) gets 403, confirm the permission boundary
4. **Go/no-go:** If none of Bugger's target users are Bitable owners/managers, the WebSocket approach is non-viable — pivot to improved polling (§8.2) or Bitable Automation + ngrok (§8.3)
If the full Swift implementation is too heavy upfront, prototype with Python (`lark-oapi` SDK, ~50 lines) + localhost HTTP notification → Bugger. **Note:** The Python SDK handles Protobuf frames internally; use it for validation, then port to Swift once the approach is confirmed viable. See Appendix A for caveats about the spike code.
> ⚠️ **Caveat:** This is a quick validation spike only. It uses text-mode WebSocket (sends/receives JSON strings) for rapid prototyping. The **production Feishu WebSocket uses binary Protobuf frames** (`pbbp2.proto`), not JSON text frames. The real Swift implementation must handle binary frame encoding/decoding, fragment reassembly, and CONTROL vs DATA frame routing. Do not use this prototype as the basis for production code.
For quick validation before full Swift implementation:
```python
# DISCLAIMER: Spike only — uses text WebSocket for fast prototyping.
# Production must use binary Protobuf frames per §4.1.
**Conclusion:** Building a Swift-native `feishu-connector` daemon using WebSocket long connection is feasible with ~970 lines of Swift code for the connector and ~260 lines of changes in Bugger, with no third-party dependencies. The approach provides real-time push notifications for Bitables where the user is owner/manager, while polling remains the universal fallback. **Prerequisite:** Verify the subscribe permission boundary (Phase 0) before committing to implementation.
tigerenwork