feat(plugins): add SubsonicAPI CallRaw, with support for raw=true binary response for host functions (#4982)

* feat: implement raw binary framing for host function responses Signed-off-by: Deluan <deluan@navidrome.org> * feat: add CallRaw method for Subsonic API to handle binary responses Signed-off-by: Deluan <deluan@navidrome.org> * test: add tests for raw=true methods and binary framing generation Signed-off-by: Deluan <deluan@navidrome.org> * fix: improve error message for malformed raw responses to indicate incomplete header Signed-off-by: Deluan <deluan@navidrome.org> * fix: add wasm_import_module attribute for raw methods and improve content-type handling Signed-off-by: Deluan <deluan@navidrome.org> --------- Signed-off-by: Deluan <deluan@navidrome.org>
2026-02-04 15:48:08 -05:00
parent 19ea338bed
commit e8863ed147
23 changed files with 1223 additions and 40 deletions
@@ -8,10 +8,13 @@
 # main __init__.py file. Copy the needed functions from this file into your plugin.

 from dataclasses import dataclass
-from typing import Any
+from typing import Any{{- if .Service.HasRawMethods}}, Tuple{{end}}

 import extism
 import json
+{{- if .Service.HasRawMethods}}
+import struct
+{{- end}}


 class HostFunctionError(Exception):
@@ -29,7 +32,7 @@ def _{{exportName .}}(offset: int) -> int:
 {{- end}}
 {{- /* Generate dataclasses for multi-value returns */ -}}
 {{range .Service.Methods}}
-{{- if .NeedsResultClass}}
+{{- if and .NeedsResultClass (not .Raw)}}


@dataclass
@@ -44,7 +47,7 @@ class {{pythonResultType .}}:
 {{range .Service.Methods}}


-def {{pythonFunc .}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.PythonName}}: {{$p.PythonType}}{{end}}){{if .NeedsResultClass}} -> {{pythonResultType .}}{{else if .HasReturns}} -> {{(index .Returns 0).PythonType}}{{else}} -> None{{end}}:
+def {{pythonFunc .}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.PythonName}}: {{$p.PythonType}}{{end}}){{if .Raw}} -> Tuple[str, bytes]{{else if .NeedsResultClass}} -> {{pythonResultType .}}{{else if .HasReturns}} -> {{(index .Returns 0).PythonType}}{{else}} -> None{{end}}:
    """{{if .Doc}}{{.Doc}}{{else}}Call the {{exportName .}} host function.{{end}}
 {{- if .HasParams}}

@@ -53,7 +56,11 @@ def {{pythonFunc .}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.PythonNam
        {{.PythonName}}: {{.PythonType}} parameter.
 {{- end}}
 {{- end}}
-{{- if .HasReturns}}
+{{- if .Raw}}
+
+    Returns:
+        Tuple of (content_type, data) with the raw binary response.
+{{- else if .HasReturns}}

    Returns:
 {{- if .NeedsResultClass}}
@@ -79,6 +86,24 @@ def {{pythonFunc .}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.PythonNam
    request_mem = extism.memory.alloc(request_bytes)
    response_offset = _{{exportName .}}(request_mem.offset)
    response_mem = extism.memory.find(response_offset)
+{{- if .Raw}}
+    response_bytes = response_mem.bytes()
+
+    if len(response_bytes) == 0:
+        raise HostFunctionError("empty response from host")
+    if response_bytes[0] == 0x01:
+        raise HostFunctionError(response_bytes[1:].decode("utf-8"))
+    if response_bytes[0] != 0x00:
+        raise HostFunctionError("unknown response status")
+    if len(response_bytes) < 5:
+        raise HostFunctionError("malformed raw response: incomplete header")
+    ct_len = struct.unpack(">I", response_bytes[1:5])[0]
+    if len(response_bytes) < 5 + ct_len:
+        raise HostFunctionError("malformed raw response: content-type overflow")
+    content_type = response_bytes[5:5 + ct_len].decode("utf-8")
+    data = response_bytes[5 + ct_len:]
+    return content_type, data
+{{- else}}
    response = json.loads(extism.memory.string(response_mem))
 {{if .HasError}}
    if response.get("error"):
@@ -94,3 +119,4 @@ def {{pythonFunc .}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.PythonNam
    return response.get("{{(index .Returns 0).JSONName}}"{{pythonDefault (index .Returns 0)}})
 {{- end}}
 {{- end}}
+{{- end}}