diff --git a/.changeset/driver-ws-hosts.md b/.changeset/driver-ws-hosts.md new file mode 100644 index 000000000..5a652e992 --- /dev/null +++ b/.changeset/driver-ws-hosts.md @@ -0,0 +1,7 @@ +--- +"ftw": patch +--- + +A cloud driver can name the WebSocket hosts it streams from in its `DRIVER` table as `ws_hosts`, the way it names `http_hosts`. When the driver's config already grants HTTP, FTW grants the WebSocket for those hosts, so a saved driver needs no `capabilities.websocket` entry; hosts the config lists are kept. A driver without HTTP gets no network access this way. + +Opening a WebSocket now gives up after 5 s instead of 15 s, ends at once when the driver call is cancelled (a stand-down or a stop), and names the HTTP status when the server refuses the upgrade. The driver's poll and its commands wait for that dial. diff --git a/go/internal/drivers/catalog.go b/go/internal/drivers/catalog.go index 0a27882bb..516c136cf 100644 --- a/go/internal/drivers/catalog.go +++ b/go/internal/drivers/catalog.go @@ -32,6 +32,7 @@ type CatalogEntry struct { Protocols []string `json:"protocols,omitempty"` // mqtt / modbus / http Capabilities []string `json:"capabilities,omitempty"` // meter / pv / battery HTTPHosts []string `json:"http_hosts,omitempty"` + WSHosts []string `json:"ws_hosts,omitempty"` Description string `json:"description,omitempty"` Homepage string `json:"homepage,omitempty"` ConnectionDefaults map[string]any `json:"connection_defaults,omitempty"` @@ -220,6 +221,7 @@ func parseCatalogEntry(path string) (CatalogEntry, error) { e.Protocols = pickList(block, "protocols") e.Capabilities = pickList(block, "capabilities") e.HTTPHosts = pickList(block, "http_hosts") + e.WSHosts = pickList(block, "ws_hosts") e.ConnectionDefaults = pickKVBlock(block, "connection_defaults") e.ReadOnly, e.ReadOnlyDeclared = pickOptionalBool(block, "read_only") e.VerificationStatus = normalizeVerificationStatus(pickString(block, "verification_status")) diff --git a/go/internal/drivers/host.go b/go/internal/drivers/host.go index 7cb794148..ee5609a55 100644 --- a/go/internal/drivers/host.go +++ b/go/internal/drivers/host.go @@ -1,6 +1,7 @@ package drivers import ( + "context" "encoding/json" "errors" "fmt" @@ -61,7 +62,10 @@ type SerialCap interface { // implementation's background goroutine buffers inbound frames so // PopMessages is non-blocking. type WSCap interface { - Open(url string, headers map[string]string) error + // Open dials until ctx ends or the dial times out. The Lua binding + // passes the driver call's context, so a default or a stop can cancel + // a dial that holds the poll. + Open(ctx context.Context, url string, headers map[string]string) error Send(text string) error PopMessages() []string IsOpen() bool diff --git a/go/internal/drivers/lua.go b/go/internal/drivers/lua.go index 7c4ca7a9a..8e83c6715 100644 --- a/go/internal/drivers/lua.go +++ b/go/internal/drivers/lua.go @@ -1485,7 +1485,7 @@ func registerHost(L *lua.LState, env *HostEnv) { } }) } - if err := env.WS.Open(url, headers); err != nil { + if err := env.WS.Open(luaCallContext(L), url, headers); err != nil { L.Push(lua.LNil) L.Push(lua.LString(err.Error())) return 2 diff --git a/go/internal/drivers/registry.go b/go/internal/drivers/registry.go index 0d5b11e92..5b2769d16 100644 --- a/go/internal/drivers/registry.go +++ b/go/internal/drivers/registry.go @@ -678,10 +678,33 @@ func (r *Registry) add(ctx context.Context, cfg config.Driver, startupDefault bo if cfg.Capabilities.AllowUnverifiedLocal { env.WithAllowUnverifiedLocal() } + // A cloud driver that streams from a fixed vendor host declares it in + // DRIVER.ws_hosts, as it declares http_hosts. For a driver whose config + // already grants HTTP, the declaration grants the WebSocket for those + // hosts, so a saved config needs no capabilities.websocket entry. A + // driver without HTTP gets no network access from a file edit. Hosts + // come only from the Lua driver's own declaration and are merged into + // any the config lists. + var wsHosts []string if cfg.Capabilities.WebSocket != nil { + wsHosts = append(wsHosts, cfg.Capabilities.WebSocket.AllowedHosts...) + } + declaredWS := false + if entry, err := ParseCatalogFile(cfg.Lua); err == nil && cfg.Capabilities.HTTP != nil { + for _, h := range entry.WSHosts { + h = strings.TrimSpace(h) + if h != "" { + declaredWS = true + if !slices.Contains(wsHosts, h) { + wsHosts = append(wsHosts, h) + } + } + } + } + if cfg.Capabilities.WebSocket != nil || declaredWS { env.WithWS(NewGorillaWS(cfg.Name, cfg.Capabilities.AllowUnverifiedLocal)) - if hosts := cfg.Capabilities.WebSocket.AllowedHosts; len(hosts) > 0 { - env.WithWSAllowedHosts(hosts) + if len(wsHosts) > 0 { + env.WithWSAllowedHosts(wsHosts) } } if cfg.Capabilities.TCP != nil { diff --git a/go/internal/drivers/registry_allowlist_test.go b/go/internal/drivers/registry_allowlist_test.go index 1c7ae01b7..1ec203b60 100644 --- a/go/internal/drivers/registry_allowlist_test.go +++ b/go/internal/drivers/registry_allowlist_test.go @@ -235,3 +235,104 @@ function driver_poll() return 60000 end }) } } + +// A cloud driver that streams from a vendor host declares it in +// DRIVER.ws_hosts. For a driver whose config grants HTTP, the declaration +// grants the WebSocket for those hosts, so a saved config without +// capabilities.websocket still streams. Hosts a config lists are kept, an +// any-host entry narrows to the declared hosts as for http_hosts, and a +// driver without HTTP, or one that declares nothing, gets no WebSocket. +func TestRegistryGrantsWebSocketFromDriverMetadata(t *testing.T) { + dir := t.TempDir() + write := func(name, src string) string { + path := filepath.Join(dir, name) + if err := os.WriteFile(path, []byte(src), 0600); err != nil { + t.Fatal(err) + } + return path + } + const initCheck = ` +function driver_init(config) + local ok, err = host.ws_open("wss://not-declared.invalid/hub") + if config and config.expect == "none" then + assert(ok == nil and err == "ws: capability not granted", + "got a WebSocket it should not have: " .. tostring(err)) + else + assert(ok == nil and err and err:find("not in allowed_hosts", 1, true), + "driver-declared WebSocket allowlist was not installed: " .. tostring(err)) + end +end +function driver_poll() return 60000 end +` + declaring := write("stream.lua", `DRIVER = { + id = "stream", + name = "Stream", + protocols = { "http" }, + capabilities = { "ev" }, + http_hosts = { "api.example.test" }, + ws_hosts = { "streams.example.test", " streams.example.test " }, +}`+initCheck) + silent := write("rest.lua", `DRIVER = { + id = "rest", + name = "Rest", + protocols = { "http" }, + capabilities = { "ev" }, + http_hosts = { "api.example.test" }, +}`+initCheck) + + httpOnly := config.Capabilities{HTTP: &config.HTTPCapability{}} + for _, tc := range []struct { + name string + lua string + caps config.Capabilities + probe bool + want []string // nil: no WebSocket capability + }{ + {name: "declared", lua: declaring, caps: httpOnly, want: []string{"streams.example.test"}}, + {name: "declared probe", lua: declaring, caps: httpOnly, probe: true, want: []string{"streams.example.test"}}, + {name: "declared and configured", lua: declaring, + caps: config.Capabilities{HTTP: &config.HTTPCapability{}, + WebSocket: &config.WSCapability{AllowedHosts: []string{"other.example.test"}}}, + want: []string{"other.example.test", "streams.example.test"}}, + {name: "declared and any host configured", lua: declaring, + caps: config.Capabilities{HTTP: &config.HTTPCapability{}, WebSocket: &config.WSCapability{}}, + want: []string{"streams.example.test"}}, + {name: "declared without HTTP", lua: declaring, caps: config.Capabilities{Standalone: true}}, + {name: "not declared", lua: silent, caps: httpOnly}, + } { + t.Run(tc.name, func(t *testing.T) { + r := NewRegistry(telemetry.NewStore()) + cfg := config.Driver{Name: "ws-" + tc.name, Lua: tc.lua, Capabilities: tc.caps} + if tc.want == nil { + cfg.Config = map[string]any{"expect": "none"} + } + add, stop := r.Add, r.Remove + if tc.probe { + add, stop = r.AddProbe, r.RemoveProbe + } + if err := add(context.Background(), cfg); err != nil { + t.Fatalf("add: %v", err) + } + t.Cleanup(func() { stop(cfg.Name) }) + + r.mu.Lock() + rd := r.rec[cfg.Name] + r.mu.Unlock() + if rd == nil { + t.Fatal("driver was not registered") + } + if tc.want == nil { + if rd.env.WS != nil { + t.Fatal("got a WebSocket it should not have") + } + return + } + if rd.env.WS == nil { + t.Fatal("DRIVER.ws_hosts did not grant a WebSocket") + } + if !reflect.DeepEqual(rd.env.WSAllowedHosts, tc.want) { + t.Fatalf("WSAllowedHosts = %v, want %v", rd.env.WSAllowedHosts, tc.want) + } + }) + } +} diff --git a/go/internal/drivers/tibber_test.go b/go/internal/drivers/tibber_test.go index e2a816e3b..15820efcc 100644 --- a/go/internal/drivers/tibber_test.go +++ b/go/internal/drivers/tibber_test.go @@ -23,7 +23,7 @@ type fakeWS struct { dials []string } -func (f *fakeWS) Open(url string, headers map[string]string) error { +func (f *fakeWS) Open(_ context.Context, url string, headers map[string]string) error { f.mu.Lock() defer f.mu.Unlock() f.open = true diff --git a/go/internal/drivers/ws_cap.go b/go/internal/drivers/ws_cap.go index 54eb8499b..86d84fca4 100644 --- a/go/internal/drivers/ws_cap.go +++ b/go/internal/drivers/ws_cap.go @@ -1,7 +1,9 @@ package drivers import ( + "context" "fmt" + "net" net_http "net/http" net_url "net/url" "strings" @@ -45,9 +47,15 @@ func NewGorillaWS(driverName string, allowUnverifiedLocal ...bool) WSCap { return &gorillaWS{driverName: driverName, allowUnverifiedLocal: allow} } +// wsDialTimeout bounds Open: the TCP dial, TLS and the upgrade. Open runs +// inside driver_poll, and the driver's commands wait for the poll, so a hung +// server must not hold a charger's current cut for long. A healthy cloud +// endpoint answers in well under a second. +const wsDialTimeout = 5 * time.Second + func newGorillaWSDialer(allowUnverifiedLocal bool, proxy func(*net_http.Request) (*net_url.URL, error)) websocket.Dialer { dialer := *websocket.DefaultDialer - dialer.HandshakeTimeout = 15 * time.Second + dialer.HandshakeTimeout = wsDialTimeout if proxy == nil { proxy = dialer.Proxy } @@ -62,7 +70,7 @@ func newGorillaWSDialer(allowUnverifiedLocal bool, proxy func(*net_http.Request) // `Sec-WebSocket-Protocol: graphql-transport-ws`, for instance). Calling // Open on an already-open cap is a no-op so a driver that re-runs // driver_init doesn't double-dial. -func (g *gorillaWS) Open(url string, headers map[string]string) error { +func (g *gorillaWS) Open(ctx context.Context, url string, headers map[string]string) error { g.mu.Lock() if g.open { g.mu.Unlock() @@ -94,9 +102,48 @@ func (g *gorillaWS) Open(url string, headers map[string]string) error { if len(subprotocols) > 0 { dialer.Subprotocols = subprotocols } + // gorilla stops the TCP dial and TLS when ctx ends, but bounds the + // upgrade reply only by HandshakeTimeout. Ending ctx also ends that wait: + // the raw connection's deadline moves to now. On plain ws:// a cancel in + // the first microseconds can still be lost to gorilla setting its own + // deadline; that dial then ends at the timeout. + var rawMu sync.Mutex + var raw net.Conn + dial := dialer.NetDialContext + dialer.NetDialContext = func(dctx context.Context, network, addr string) (net.Conn, error) { + c, err := dial(dctx, network, addr) + if err == nil { + rawMu.Lock() + raw = c + rawMu.Unlock() + } + return c, err + } + stopWatch := context.AfterFunc(ctx, func() { + rawMu.Lock() + defer rawMu.Unlock() + if raw != nil { + _ = raw.SetDeadline(time.Now()) + } + }) // EnableCompression default is true on DefaultDialer; leave it. - conn, _, err := dialer.Dial(url, hdr) + conn, resp, err := dialer.DialContext(ctx, url, hdr) + if !stopWatch() && err == nil { + // ctx ended as the dial finished, so the deadline may already have + // moved on the new connection. A cancelled call opens nothing. + conn.Close() + return fmt.Errorf("ws dial: %w", ctx.Err()) + } if err != nil { + if ctxErr := ctx.Err(); ctxErr != nil { + return fmt.Errorf("ws dial: %w", ctxErr) + } + // A refused upgrade says only "bad handshake"; the status tells a + // driver whether its token, its path or the server is wrong. The + // body stays out: it may echo what the driver sent. + if resp != nil { + return fmt.Errorf("ws dial: %w (HTTP %d)", err, resp.StatusCode) + } return fmt.Errorf("ws dial: %w", err) } // Set a generous read deadline. Tibber's graphql-transport-ws diff --git a/go/internal/drivers/ws_cap_test.go b/go/internal/drivers/ws_cap_test.go new file mode 100644 index 000000000..9d35c8958 --- /dev/null +++ b/go/internal/drivers/ws_cap_test.go @@ -0,0 +1,108 @@ +package drivers + +import ( + "context" + "errors" + "net" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" +) + +// silentServer accepts connections and never answers. +func silentServer(t *testing.T) string { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + var mu sync.Mutex + var held []net.Conn + go func() { + for { + c, err := ln.Accept() + if err != nil { + return + } + mu.Lock() + held = append(held, c) + mu.Unlock() + } + }() + t.Cleanup(func() { + ln.Close() + mu.Lock() + defer mu.Unlock() + for _, c := range held { + c.Close() + } + }) + return "ws://" + ln.Addr().String() + "/hub" +} + +// A server that accepts the connection and never answers the upgrade holds +// Open for the dial timeout and no longer: Open runs inside driver_poll, and +// the driver's commands wait for the poll. +func TestGorillaWSOpenGivesUpOnASilentServer(t *testing.T) { + t.Parallel() + url := silentServer(t) + ws := NewGorillaWS("silent") + start := time.Now() + err := ws.Open(context.Background(), url, nil) + took := time.Since(start) + if err == nil { + ws.Close() + t.Fatal("Open succeeded against a server that never answered") + } + if took < wsDialTimeout-time.Second || took > wsDialTimeout+2*time.Second { + t.Fatalf("Open gave up after %v, want about %v: %v", took, wsDialTimeout, err) + } + if ws.IsOpen() { + t.Fatal("a failed Open left the capability open") + } +} + +// A default or a stop cancels the driver call's context; a dial in that call +// ends with it instead of running out the timeout. +func TestGorillaWSOpenEndsWithItsContext(t *testing.T) { + t.Parallel() + url := silentServer(t) + ctx, cancel := context.WithCancel(context.Background()) + time.AfterFunc(100*time.Millisecond, cancel) + start := time.Now() + err := NewGorillaWS("cancelled").Open(ctx, url, nil) + if err == nil { + t.Fatal("Open succeeded after its context ended") + } + if took := time.Since(start); took > time.Second { + t.Fatalf("Open ran %v after its context ended", took) + } + if !errors.Is(err, context.Canceled) { + t.Fatalf("a cancelled dial reported %v, not the cancel", err) + } +} + +// A refused upgrade names its HTTP status, so a driver can tell a bad token +// from a wrong path, and never the body, which may echo what it sent. +func TestGorillaWSOpenNamesTheRefusedStatus(t *testing.T) { + t.Parallel() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("WWW-Authenticate", "Bearer") + http.Error(w, "token secret-echo rejected", http.StatusUnauthorized) + })) + t.Cleanup(srv.Close) + err := NewGorillaWS("refused").Open(context.Background(), + "ws"+strings.TrimPrefix(srv.URL, "http")+"/hub", map[string]string{"Authorization": "Bearer secret-echo"}) + if err == nil { + t.Fatal("Open succeeded against a refusing server") + } + if !strings.Contains(err.Error(), "HTTP 401") { + t.Fatalf("error does not name the status: %v", err) + } + if strings.Contains(err.Error(), "secret-echo") { + t.Fatalf("error carries the response body: %v", err) + } +}