Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/lua-http-put.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"ftw": patch
---

Lua drivers can now send `host.http_put(url, body, headers)`. It has the same
safety gates as `host.http_patch`: it needs `capabilities.http.allow_write`,
stays inside `allowed_hosts`, refuses redirects and cannot write during a
fingerprint probe. Some device APIs, such as the sonnenBatterie JSON API v2,
accept settings only through PUT. No existing driver changes behaviour.
12 changes: 7 additions & 5 deletions docs/writing-a-driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ current host API and the source of truth for it. Today it registers:
| Decoding | `decode_string`, `decode_i16`, `decode_i32_be`, `decode_i32_le`, `decode_u32_be`, `decode_u32_le` |
| Modbus | `modbus_read`, `write`, `write_registers` (canonical); `modbus_write`, `modbus_write_multi` (legacy aliases) |
| MQTT | `mqtt_pub`, `mqtt_sub`, `mqtt_publish`, `mqtt_subscribe`, `mqtt_messages` |
| HTTP | `http_get`, `http_post`, `http_patch`, `http_request`, `http_cookies_clear` |
| HTTP | `http_get`, `http_post`, `http_patch`, `http_put`, `http_request`, `http_cookies_clear` |
| WebSocket | `ws_open`, `ws_send`, `ws_messages`, `ws_is_open`, `ws_close` |
| Raw TCP | `tcp_open`, `tcp_recv`, `tcp_close`, `tcp_is_open` |
| Serial | `serial_read` |
Expand All @@ -56,9 +56,11 @@ reads `W` and `SoC_nom_fract` when `w` and `soc` are absent; when both are
present the lowercase key wins. Both spellings are correct — prefer the
canonical one in a new driver.

`http_patch` is the mutating verb and is gated twice: the plain `http` grant is
not enough, it also needs `capabilities.http.allow_write`. It refuses to follow
redirects, because Go re-issues a redirected `PATCH` as a body-less GET and a
`http_patch` and `http_put` are the mutating verbs and are gated twice: the
plain `http` grant is not enough, they also need
`capabilities.http.allow_write`. Both send `Content-Type: application/json`
unless the driver passes its own header. They refuse to follow redirects,
because Go re-issues a redirected `PATCH` or `PUT` as a body-less GET and a
device write that never landed would otherwise report success.

`http_request{method, url, headers, body}` is for a driver that has to sign in
Expand Down Expand Up @@ -139,7 +141,7 @@ may omit the default hook because Core cannot dispatch commands to them.

`driver_fingerprint(target)` is an optional passive setup probe. It must never
reconfigure the device. The host denies mutating verbs (`modbus_write`,
`mqtt_pub`, `http_post`, `http_patch`, and POST through `http_request`) for that VM, including bundled drivers
`mqtt_pub`, `http_post`, `http_patch`, `http_put`, and POST through `http_request`) for that VM, including bundled drivers
that may otherwise write.

Call `host.set_make` and `host.set_sn` as soon as stable identity is known.
Expand Down
14 changes: 7 additions & 7 deletions go/internal/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -1070,13 +1070,13 @@ type HTTPCapability struct {
// for this driver only; when empty, standard verification against the
// system roots applies (unchanged for every existing HTTP driver).
TLSPinSHA256 string `yaml:"tls_pin_sha256,omitempty" json:"tls_pin_sha256,omitempty"`
// AllowWrite grants host.http_patch — the verb REST device APIs use for
// state-changing writes — as a separate, explicit operator decision, the
// HTTP twin of a read-only Modbus driver versus one allowed to write
// registers. Scope is exactly http_patch: http_get stays a read and
// http_post stays under the plain HTTP grant (existing drivers POST to
// query-style APIs), so granting HTTP for telemetry never implicitly
// grants the ability to mutate a device. Default off.
// AllowWrite grants host.http_patch and host.http_put — the verbs REST
// device APIs use for state-changing writes — as a separate, explicit
// operator decision, the HTTP twin of a read-only Modbus driver versus
// one allowed to write registers. Scope is exactly those verbs: http_get
// stays a read and http_post stays under the plain HTTP grant (existing
// drivers POST to query-style APIs), so granting HTTP for telemetry never
// implicitly grants the ability to mutate a device. Default off.
AllowWrite bool `yaml:"allow_write,omitempty" json:"allow_write,omitempty"`
}

Expand Down
12 changes: 6 additions & 6 deletions go/internal/drivers/host.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,10 +104,10 @@ type HostEnv struct {
// verification (unchanged default for all existing HTTP drivers).
// Populated from driver config `capabilities.http.tls_pin_sha256`.
HTTPTLSPinSHA256 string
// HTTPAllowWrite gates host.http_patch, and only http_patch —
// http_get stays a read and http_post stays under the plain HTTP
// capability (existing drivers POST to query-style APIs). http_patch
// returns an error string unless this is set, so granting HTTP for
// HTTPAllowWrite gates host.http_patch and host.http_put, and only
// those — http_get stays a read and http_post stays under the plain
// HTTP capability (existing drivers POST to query-style APIs). Both
// return an error string unless this is set, so granting HTTP for
// telemetry never implicitly grants device mutation. Populated from
// driver config `capabilities.http.allow_write`.
HTTPAllowWrite bool
Expand Down Expand Up @@ -449,8 +449,8 @@ func (h *HostEnv) WithSerial(s SerialCap) *HostEnv { h.Serial = s; return h }
// WithHTTP enables the HTTP capability.
func (h *HostEnv) WithHTTP() *HostEnv { h.HTTP = true; return h }

// WithHTTPAllowWrite grants the mutating HTTP verb host.http_patch. Scoped
// to http_patch only; http_get/http_post are unaffected. See
// WithHTTPAllowWrite grants the mutating HTTP verbs host.http_patch and
// host.http_put; http_get/http_post are unaffected. See
// HostEnv.HTTPAllowWrite.
func (h *HostEnv) WithHTTPAllowWrite() *HostEnv { h.HTTPAllowWrite = true; return h }

Expand Down
130 changes: 70 additions & 60 deletions go/internal/drivers/lua.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
// host.mqtt_sub / mqtt_subscribe, host.mqtt_pub / mqtt_publish, host.mqtt_messages
// host.modbus_read, host.modbus_write / write, host.modbus_write_multi / write_registers
// host.serial_read, host.aes_gcm_decrypt, host.json_decode, host.json_encode
// host.http_get, host.http_post, host.http_patch
// host.http_get, host.http_post, host.http_patch, host.http_put
// host.ws_open, host.ws_send, host.ws_messages, host.ws_is_open, host.ws_close
// host.tcp_open, host.tcp_recv, host.tcp_is_open, host.tcp_close
//
Expand Down Expand Up @@ -1216,12 +1216,12 @@ func registerHost(L *lua.LState, env *HostEnv) {
if len(via) >= 10 {
return fmt.Errorf("stopped after 10 redirects")
}
// A redirected PATCH is unsafe: Go re-issues 301/302/303 as a
// body-less GET, so the device write silently never lands while the
// call still reports success. Refuse it — a write must reach the
// host it was checked against, or fail loudly.
if len(via) > 0 && via[0].Method == "PATCH" {
return fmt.Errorf("redirect not followed for PATCH (a redirected write cannot be verified)")
// A redirected PATCH or PUT is unsafe: Go re-issues 301/302/303 as
// a body-less GET, so the device write silently never lands while
// the call still reports success. Refuse it — a write must reach
// the host it was checked against, or fail loudly.
if len(via) > 0 && (via[0].Method == "PATCH" || via[0].Method == "PUT") {
return fmt.Errorf("redirect not followed for %s (a redirected write cannot be verified)", via[0].Method)
}
// The managed read-only OAuth exception authorizes one exact path.
// A 307/308 must not carry its POST body to a device write endpoint.
Expand Down Expand Up @@ -1402,60 +1402,70 @@ func registerHost(L *lua.LState, env *HostEnv) {
// grant, so granting HTTP for telemetry never implicitly grants the ability
// to mutate a device. Same allowlist, TLS pinning and 1MB response cap as
// the other verbs.
host.RawSetString("http_patch", L.NewFunction(func(L *lua.LState) int {
if !env.HTTP {
L.Push(lua.LNil)
L.Push(lua.LString("http: capability not granted"))
return 2
}
if !env.HTTPAllowWrite {
L.Push(lua.LNil)
L.Push(lua.LString("http: write not granted (set capabilities.http.allow_write)"))
return 2
}
if err := env.allowWrite("http.patch"); err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
url := L.CheckString(1)
if ok, reason := hostAllowed(url); !ok {
L.Push(lua.LNil)
L.Push(lua.LString("http: " + reason))
return 2
}
payload := L.CheckString(2)
// Keep the same ordering rule as POST: the registry actor must not send
// a default while this older mutating request can still finish normally.
req, err := net_http.NewRequest("PATCH", url, strings.NewReader(payload))
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
req.Header.Set("Content-Type", "application/json")
applyHeaders(req, L, 3)
resp, err := httpClient.Do(req)
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
defer resp.Body.Close()
body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
if resp.StatusCode >= 400 {
L.Push(lua.LNil)
L.Push(lua.LString(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(body))))
return 2
//
// host.http_put(url, body, headers?) is the same write under PUT, for
// device APIs that replace a resource instead of patching it (the
// sonnenBatterie JSON API v2 /configurations endpoint). It shares the
// allow_write gate and every other rule with http_patch.
httpWrite := func(method string) lua.LGFunction {
permission := "http." + strings.ToLower(method)
return func(L *lua.LState) int {
if !env.HTTP {
L.Push(lua.LNil)
L.Push(lua.LString("http: capability not granted"))
return 2
}
if !env.HTTPAllowWrite {
L.Push(lua.LNil)
L.Push(lua.LString("http: write not granted (set capabilities.http.allow_write)"))
return 2
}
if err := env.allowWrite(permission); err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
url := L.CheckString(1)
if ok, reason := hostAllowed(url); !ok {
L.Push(lua.LNil)
L.Push(lua.LString("http: " + reason))
return 2
}
payload := L.CheckString(2)
// Keep the same ordering rule as POST: the registry actor must not send
// a default while this older mutating request can still finish normally.
req, err := net_http.NewRequest(method, url, strings.NewReader(payload))
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
req.Header.Set("Content-Type", "application/json")
applyHeaders(req, L, 3)
resp, err := httpClient.Do(req)
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
defer resp.Body.Close()
body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if err != nil {
L.Push(lua.LNil)
L.Push(lua.LString(err.Error()))
return 2
}
if resp.StatusCode >= 400 {
L.Push(lua.LNil)
L.Push(lua.LString(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(body))))
return 2
}
L.Push(lua.LString(string(body)))
return 1
}
L.Push(lua.LString(string(body)))
return 1
}))
}
host.RawSetString("http_patch", L.NewFunction(httpWrite("PATCH")))
host.RawSetString("http_put", L.NewFunction(httpWrite("PUT")))

registerHTTPRequest(L, host, env, httpClient, hostAllowed)

Expand Down
9 changes: 8 additions & 1 deletion go/internal/drivers/lua_http_patch_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,18 @@ import (
// runHTTPDriverWithEnv. The specific denial gate is surfaced as a metric so
// tests can assert WHICH gate fired, not just that something failed.
func runPatchDriver(t *testing.T, env *HostEnv, targetURL string) (ok bool, deniedBy string) {
t.Helper()
return runHTTPWriteDriver(t, env, "http_patch", targetURL)
}

// runHTTPWriteDriver runs the same one-shot driver through any mutating
// verb (host.http_patch or host.http_put).
func runHTTPWriteDriver(t *testing.T, env *HostEnv, fn, targetURL string) (ok bool, deniedBy string) {
t.Helper()
src := `
function driver_init() end
function driver_poll()
local body, err = host.http_patch("` + targetURL + `",
local body, err = host.` + fn + `("` + targetURL + `",
'[{"variableId":5202,"integerValue":3000}]',
{ Authorization = "Basic dTpw" })
if err then
Expand Down
Loading