Gateway Stability Patch

Reusable overlay toolkit for stabilizing gateway WebSocket handshakes. Rule-based patches with apply/check/rollback CLI.

可复用的 Gateway 稳定性 overlay 工具。基于规则的补丁系统，支持 apply/check/rollback 工作流。

---

gateway-stability-patch is a public, reusable overlay toolkit that turns a live gateway runtime stability hotfix into a documented, repeatable workflow.

It focuses on one goal: reduce gateway crashes or false outage symptoms caused by local loopback handshake races, connect-challenge timeout drift, and retryable pre-connect closes.

This repository does not ship the target gateway runtime or patched vendor bundles. It ships:

• patch rules
• overlay maintenance scripts
• integrity checks
• rollback helpers
• bilingual documentation

What It Changes

For the supported gateway runtime build, the patch set adds or extends:

• configurable gateway handshake timeout
• configurable connect-challenge timeout
• bounded retry for retryable local-loopback pre-connect failures
• broader local fallback handling in the devices CLI for loopback 1000/1006/no-reason and timeout cases

Supported Version

Configured in src/gateway_stability_patch/patch_set.py as SUPPORTED_RUNTIME_VERSION.

The project is intentionally version-strict. If the detected runtime version does not match, the CLI refuses to patch unless you explicitly pass --allow-unsupported-version.

Why Overlay Instead Of Editing Runtime Files By Hand

• It is repeatable.
• It creates backups automatically.
• It writes a manifest with file hashes.
• It gives you a stable apply -> check -> rollback workflow.
• It survives future maintenance better than one-off manual edits.

Project Layout

gateway-stability-patch/
├── docs/
├── examples/
├── src/gateway_stability_patch/
├── tests/
├── LICENSE
├── README.md
└── README.zh-CN.md

Quick Start

1. Install or run locally

python3 -m pip install .

Or run directly from the source tree:

PYTHONPATH=src python3 -m gateway_stability_patch describe

2. Apply the overlay

gateway-stability apply \
  --install-root /path/to/gateway/runtime \
  --overlay-root ~/.gateway-stability/overlays/gateway-stability \
  --env-file ~/.gateway-stability/.env

3. Verify

gateway-stability check \
  --install-root /path/to/gateway/runtime \
  --overlay-root ~/.gateway-stability/overlays/gateway-stability \
  --env-file ~/.gateway-stability/.env

4. Roll back if needed

gateway-stability rollback \
  --install-root /path/to/gateway/runtime \
  --overlay-root ~/.gateway-stability/overlays/gateway-stability \
  --env-file ~/.gateway-stability/.env

Managed Environment Variables

The tool ensures these values exist in the chosen env file:

GW_STABILITY_HANDSHAKE_TIMEOUT_MS=8000
GW_STABILITY_CONNECT_CHALLENGE_TIMEOUT_MS=6000
GW_STABILITY_PRECONNECT_RETRY_ATTEMPTS=3
GW_STABILITY_PRECONNECT_RETRY_MIN_DELAY_MS=250
GW_STABILITY_PRECONNECT_RETRY_MAX_DELAY_MS=1500
GW_STABILITY_PRECONNECT_RETRY_BACKOFF=2

An example file lives at examples/gateway-stability.env.example.

Commands

• gateway-stability describe
• gateway-stability apply
• gateway-stability check
• gateway-stability rollback

Documentation

• Usage guide: docs/usage.en.md
• Chinese usage guide: docs/usage.zh-CN.md
• Development guide: docs/development.en.md
• Chinese development guide: docs/development.zh-CN.md
• Publishing guide: docs/publishing.en.md
• Chinese publishing guide: docs/publishing.zh-CN.md
• Contribution policy: CONTRIBUTING.md

Safety Notes

• Always back up the target machine before testing on a new runtime version.
• This project only supports a known runtime release by default.
• Do not publish private .env files, backup directories, or host-local overlay trees.
• Re-run check after every runtime upgrade because upstream files may change.

License

MIT. See LICENSE.