Documentation
¶
Overview ¶
Package zapface serves the browser-facing ZAP RPC plane over WebSocket.
Two transports, ONE dispatch path. Native in-cluster peers reach cloud's procedures over the ZAP transport (TCP/QUIC). Browsers — which cannot open a raw socket — reach the SAME /v1 handlers over a WebSocket carrying binary ZAP frames. There is no second copy of any business logic here: every call is replayed as an in-process *http.Request through the existing Fiber app (adaptor.FiberApp), so the same controllers, middleware, auth filters, and /v1 {status,msg,data} envelope back both transports.
Wire contract (matches @zap-proto/web + github.com/zap-proto/go/rpc exactly):
- One WebSocket BINARY message == one ZAP router envelope. No extra length prefix (WS frames already carry message boundaries). Text frames are a protocol violation and close the socket (1003).
- The outer envelope is github.com/zap-proto/go/rpc: a request decodes via rpc.ParseRequest into rpc.Call{Method,PromiseID,Target,Cap,Payload}; the reply is rpc.BuildResponse(status, promiseID, body). These are byte-for-byte identical to the TS runtime's buildRequest/parseResponse, so a frame built by console's @zap-proto/web is decoded here and our reply is decoded there.
- The INNER request payload (rpc.Call.Payload) is console's ZapRequest struct: { method @0 :Text, payload @8 :Text } (fixed size 16). `method` is the /v1 endpoint name (e.g. "get-providers"); `payload` is a SuperJSON string of the call arguments (” for none).
- The INNER reply body is console's ZapReply struct: { ok @0 :Bool, status @4 :UInt32, result @8 :Text, errorJson @16 :Text } (fixed size 24). `result` is a SuperJSON string of the /v1 `data`; `errorJson` is a JSON error envelope when ok == false.
The inner struct offsets/sizes live ONLY here — the single source of truth mirroring console/src/lib/zap/transport.ts.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
Handler returns the zip.Handler mounted at /zap. It mints the per-connection auth slot from the upgrade request (fail-closed: 401 with no credential), upgrades to a native Fiber WebSocket (wsx), then bridges each binary ZAP frame to the /v1 dispatch via rpc.ParseRequest -> dispatch -> rpc.BuildResponse.
WebSocket is served Fiber-natively (fasthttp/websocket via zip/wsx), NOT through a net/http adaptor — fasthttp's synthetic ResponseWriter cannot be hijacked, so an adaptor-based upgrade 404s.
Types ¶
type Options ¶
type Options struct {
// OriginPatterns is informational here; the WS upgrade allows all origins
// (zip is multi-tenant — auth, not Origin, is the gate) and the per-call
// /v1 filter does the authoritative check. Kept for symmetry/logging.
OriginPatterns []string
// MaxMessage caps one inbound WS message in bytes. Default 4 MiB.
MaxMessage int
// Logger for connection/dispatch diagnostics.
Logger luxlog.Logger
}
Options configure the ZAP WebSocket face.
Source Files