feishu-websocket-stability

Feishu Websocket Stability

Use this skill when Hermes runs in Feishu websocket mode and you need predictable startup and reconnect behavior.

Quick start

1. Confirm the adapter is running in connection_mode=websocket.
2. Ensure only one local Hermes gateway instance uses a given Feishu app_id.
3. Tune reconnect jitter/interval via Feishu platform extra config.
4. If the SDK resets its own websocket settings during startup, reapply runtime overrides after _configure(...).
5. Add ping tuning only when you have an actual idle-connection problem.
6. Back all changes with focused gateway tests.

Core lessons from real usage

1. Guard against duplicate local websocket clients

Feishu websocket mode should behave like a single-owner resource per app.

Problem pattern:

• two local Hermes gateway processes start with the same Feishu app_id
• both try to consume the same websocket stream
• behavior becomes ambiguous or unstable

Fix pattern:

• acquire a scoped local lock keyed by the Feishu app_id
• if acquisition fails, stop startup immediately
• surface a clear fatal error that includes the owning PID when available

Recommended behavior:

• fail fast
• mark the error as non-retryable until the competing process is stopped

2. Make reconnect timing configurable

The official Feishu SDK defaults are conservative.

Real effect:

• first reconnect may wait with large jitter
• later reconnects can be spaced far apart
• production recovery after a transient network flap can feel unnecessarily slow

Expose config values under platforms.feishu.extra:

platforms:
  feishu:
    extra:
      ws_reconnect_nonce: 0
      ws_reconnect_interval: 3

Guideline:

• ws_reconnect_nonce: non-negative integer
• ws_reconnect_interval: positive integer
• invalid values should fall back to SDK defaults instead of crashing startup

3. Runtime websocket overrides must survive SDK reconfiguration

A subtle failure mode:

• you set local reconnect or ping values
• the Feishu SDK later calls its own _configure(...)
• your custom values get overwritten
• reconnect tuning appears ignored even though config parsing worked