noiseonwires/yac-ws-bridge

Purpose and topology

Bridge to Freedom is a multiplexed raw-TCP tunnel using Yandex Cloud (YC) API Gateway WebSockets. A server-side Go adapter reaches a target TCP service; a client-side Go helper or MAUI app exposes a local TCP listener. YC’s serverless function performs authenticated peer discovery, while direct YC WebSocket-management gRPC carries most data.

Executable entry points

• Go adapter: adapter-and-helper/cmd/adapter/main.go

• Go helper: adapter-and-helper/cmd/helper/main.go

• YC Node.js Cloud Function handler: bridge-cloud/index.js

• Cross-platform GUI client: maui-client/MauiProgram.cs, maui-client/MainPage.xaml.cs

• Linux MAUI head: maui-client-linux/Program.cs

Go tunnel core

Both Go binaries share internal packages for configuration, framing, stream lifecycle, upstream WebSocket connectivity, and YC send APIs:

• Configuration and runtime options: adapter-and-helper/internal/config/config.go

• Tunnel frame/wire protocol: adapter-and-helper/internal/protocol/protocol.go

• Multiplexed stream management, FIN/open/data processing, ordering, and write coalescing: adapter-and-helper/internal/streams/streams.go

• Persistent authenticated upstream WebSocket connection and reconnect/ping behavior: adapter-and-helper/internal/upstream/upstream.go

The helper accepts local TCP connections, allocates stream IDs, and emits OPEN/DATA/FIN frames. The adapter receives frames, opens a TCP connection to its configured target, and returns response/data frames. Multiple streams share each peer’s upstream WebSocket session.

YC transport boundary

adapter-and-helper/internal/wsapi/wsapi.go abstracts outbound delivery. adapter-and-helper/internal/wsapi/grpc.go uses YC’s WebSocket-management gRPC wsSend path for direct peer delivery; adapter-and-helper/internal/wsapi/rest.go provides the REST-side integration surface. In normal mode, Cloud Function traffic is control-plane discovery only. In helper relay mode, helper-to-adapter frames instead traverse its upstream WebSocket and the function relays them.

YC limits shape transport behavior: periodic pings preserve WebSocket sessions; frame/message limits motivate coalescing and stream framing; reconnect loops handle Gateway connection churn.

Discovery and recovery control plane

The Cloud Function at bridge-cloud/index.js authenticates adapter and helper HELLO handshakes, associates their Gateway connection IDs, and notifies peers when both are present. bridge-cloud/spec.yaml binds the adapter/helper WebSocket routes to that function through YC API Gateway.

The adapter additionally exposes an authenticated HTTP recovery endpoint containing current adapter/helper connection IDs. The function calls it through HTTP_URL after cold starts or instance changes, allowing discovery state restoration. Endpoint URL, shared token, and route names must align across deployed function, Gateway, and clients.

Native and GUI client boundary

The MAUI client is a functional alternative to the Go helper: maui-client/Services/TunnelService.cs owns local tunnel behavior and maui-client/Services/Protocol.cs implements compatible framing. Platform hosts include Android foreground-service support in maui-client/Platforms/Android/TunnelForegroundService.cs and iOS background-audio support in maui-client/Platforms/iOS/SilentAudioService.cs.

Deployment/runtime configuration

Go 1.21+ builds the adapter/helper module in adapter-and-helper/go.mod; Node.js 18 is the documented YC function runtime, with dependencies in bridge-cloud/package.json; MAUI/.NET builds native client variants. Deployment-critical example configuration lives in adapter-and-helper/adapter.config.yaml and adapter-and-helper/helper.config.yaml. These configure Gateway URLs, shared authentication, TCP listen/target addresses, reconnect/ping policy, coalescing, and relay behavior.