navidrome/plugins/host/scrobbleretriever_gen.go
Kendall Garner b0c6d2e444
feat(plugins): add scrobbles access to PDK (#5795)
* initial scrobble api

* feat: add scrobble retrieval api

* address feedback (1)

* fix spelling

* be explicit about get

* add primary key field, update index, remove rowid references

* use unix timestamp for input and output

* initial api, some testing

* add tests, add count retrieval

* add docs, test for rejected user

* add permission validation for scrobble retriever

* chore(plugins): fix typos in scrobble retriever

Rename newScrobbleRetreverService, and fix FromTImestamp/nonero in the
ScrobbleRetriever doc comments, which generate into the Go and Rust PDKs.
Also corrects two mislabelled test entries.

* fix(plugins): make scrobble pagination order deterministic

Sorting only by submission_time left the order of equal timestamps up to the
query planner, but the cursor skips ties by offset, so an unstable order can
repeat or drop scrobbles between pages. Break ties on scrobbles.id, which the
existing scrobbles_user_time index already yields for free.

Descending is now honoured for every combination of From/To rather than only
when both or neither is set. This changes the default for a lone ToTimestamp
from newest-first to oldest-first.

* refactor(plugins): return the next page's options from GetScrobbles

Paging previously meant reading NextTimestamp and Cursor off the response and
deciding where each belonged: NextTimestamp into FromTimestamp when ascending
or ToTimestamp when descending, and Cursor copied every time, including when 0.
Both are silent data-loss bugs when a plugin gets them wrong.

GetScrobbles now returns the options for the following page, or nil when the
range is exhausted, so a plugin passes the value straight back and repeats.
ScrobbleCursor and ScrobbleList are gone; the query itself is unchanged.

* docs(plugins): warn against setting ScrobbleOptions.Offset manually

The all-ties carry rule assumes Offset counts already-returned rows at the
boundary timestamp, which only holds for the options GetScrobbles returns.
A hand-built From+Offset combination can silently skip scrobbles, so document
the field as managed pagination state instead of a generic skip.

* docs(plugins): document the ScrobbleRetriever host service in the README

Covers the manifest permissions (including the users requirement), the four
host functions, the options/ref field tables, and the pagination loop with
its two gotchas: the host-managed offset and the adjusted range on the
returned next options.

* chore(plugins): regenerate scrobble retriever stub with nil-safe accessors

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
2026-08-08 22:13:29 -04:00

231 lines
7.4 KiB
Go

// Code generated by ndpgen. DO NOT EDIT.
package host
import (
"context"
"encoding/json"
extism "github.com/extism/go-sdk"
)
// ScrobbleRetrieverGetFirstTimestampRequest is the request type for ScrobbleRetriever.GetFirstTimestamp.
type ScrobbleRetrieverGetFirstTimestampRequest struct {
Username string `json:"username"`
}
// ScrobbleRetrieverGetFirstTimestampResponse is the response type for ScrobbleRetriever.GetFirstTimestamp.
type ScrobbleRetrieverGetFirstTimestampResponse struct {
Result *int64 `json:"result,omitempty"`
Error string `json:"error,omitempty"`
}
// ScrobbleRetrieverGetLastTimestampRequest is the request type for ScrobbleRetriever.GetLastTimestamp.
type ScrobbleRetrieverGetLastTimestampRequest struct {
Username string `json:"username"`
}
// ScrobbleRetrieverGetLastTimestampResponse is the response type for ScrobbleRetriever.GetLastTimestamp.
type ScrobbleRetrieverGetLastTimestampResponse struct {
Result *int64 `json:"result,omitempty"`
Error string `json:"error,omitempty"`
}
// ScrobbleRetrieverGetScrobblesRequest is the request type for ScrobbleRetriever.GetScrobbles.
type ScrobbleRetrieverGetScrobblesRequest struct {
Username string `json:"username"`
Options ScrobbleOptions `json:"options"`
}
// ScrobbleRetrieverGetScrobblesResponse is the response type for ScrobbleRetriever.GetScrobbles.
type ScrobbleRetrieverGetScrobblesResponse struct {
Scrobbles []ScrobbleRef `json:"scrobbles,omitempty"`
Next *ScrobbleOptions `json:"next,omitempty"`
Error string `json:"error,omitempty"`
}
// ScrobbleRetrieverGetScrobbleCountRequest is the request type for ScrobbleRetriever.GetScrobbleCount.
type ScrobbleRetrieverGetScrobbleCountRequest struct {
Username string `json:"username"`
Options ScrobbleCountOptions `json:"options"`
}
// ScrobbleRetrieverGetScrobbleCountResponse is the response type for ScrobbleRetriever.GetScrobbleCount.
type ScrobbleRetrieverGetScrobbleCountResponse struct {
Result int64 `json:"result,omitempty"`
Error string `json:"error,omitempty"`
}
// RegisterScrobbleRetrieverHostFunctions registers ScrobbleRetriever service host functions.
// The returned host functions should be added to the plugin's configuration.
func RegisterScrobbleRetrieverHostFunctions(service ScrobbleRetrieverService) []extism.HostFunction {
return []extism.HostFunction{
newScrobbleRetrieverGetFirstTimestampHostFunction(service),
newScrobbleRetrieverGetLastTimestampHostFunction(service),
newScrobbleRetrieverGetScrobblesHostFunction(service),
newScrobbleRetrieverGetScrobbleCountHostFunction(service),
}
}
func newScrobbleRetrieverGetFirstTimestampHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
return extism.NewHostFunctionWithStack(
"scrobbleretriever_getfirsttimestamp",
func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
// Read JSON request from plugin memory
reqBytes, err := p.ReadBytes(stack[0])
if err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
var req ScrobbleRetrieverGetFirstTimestampRequest
if err := json.Unmarshal(reqBytes, &req); err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
// Call the service method
result, svcErr := service.GetFirstTimestamp(ctx, req.Username)
if svcErr != nil {
scrobbleretrieverWriteError(p, stack, svcErr)
return
}
// Write JSON response to plugin memory
resp := ScrobbleRetrieverGetFirstTimestampResponse{
Result: result,
}
scrobbleretrieverWriteResponse(p, stack, resp)
},
[]extism.ValueType{extism.ValueTypePTR},
[]extism.ValueType{extism.ValueTypePTR},
)
}
func newScrobbleRetrieverGetLastTimestampHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
return extism.NewHostFunctionWithStack(
"scrobbleretriever_getlasttimestamp",
func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
// Read JSON request from plugin memory
reqBytes, err := p.ReadBytes(stack[0])
if err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
var req ScrobbleRetrieverGetLastTimestampRequest
if err := json.Unmarshal(reqBytes, &req); err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
// Call the service method
result, svcErr := service.GetLastTimestamp(ctx, req.Username)
if svcErr != nil {
scrobbleretrieverWriteError(p, stack, svcErr)
return
}
// Write JSON response to plugin memory
resp := ScrobbleRetrieverGetLastTimestampResponse{
Result: result,
}
scrobbleretrieverWriteResponse(p, stack, resp)
},
[]extism.ValueType{extism.ValueTypePTR},
[]extism.ValueType{extism.ValueTypePTR},
)
}
func newScrobbleRetrieverGetScrobblesHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
return extism.NewHostFunctionWithStack(
"scrobbleretriever_getscrobbles",
func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
// Read JSON request from plugin memory
reqBytes, err := p.ReadBytes(stack[0])
if err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
var req ScrobbleRetrieverGetScrobblesRequest
if err := json.Unmarshal(reqBytes, &req); err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
// Call the service method
scrobbles, next, svcErr := service.GetScrobbles(ctx, req.Username, req.Options)
if svcErr != nil {
scrobbleretrieverWriteError(p, stack, svcErr)
return
}
// Write JSON response to plugin memory
resp := ScrobbleRetrieverGetScrobblesResponse{
Scrobbles: scrobbles,
Next: next,
}
scrobbleretrieverWriteResponse(p, stack, resp)
},
[]extism.ValueType{extism.ValueTypePTR},
[]extism.ValueType{extism.ValueTypePTR},
)
}
func newScrobbleRetrieverGetScrobbleCountHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
return extism.NewHostFunctionWithStack(
"scrobbleretriever_getscrobblecount",
func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
// Read JSON request from plugin memory
reqBytes, err := p.ReadBytes(stack[0])
if err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
var req ScrobbleRetrieverGetScrobbleCountRequest
if err := json.Unmarshal(reqBytes, &req); err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
// Call the service method
result, svcErr := service.GetScrobbleCount(ctx, req.Username, req.Options)
if svcErr != nil {
scrobbleretrieverWriteError(p, stack, svcErr)
return
}
// Write JSON response to plugin memory
resp := ScrobbleRetrieverGetScrobbleCountResponse{
Result: result,
}
scrobbleretrieverWriteResponse(p, stack, resp)
},
[]extism.ValueType{extism.ValueTypePTR},
[]extism.ValueType{extism.ValueTypePTR},
)
}
// scrobbleretrieverWriteResponse writes a JSON response to plugin memory.
func scrobbleretrieverWriteResponse(p *extism.CurrentPlugin, stack []uint64, resp any) {
respBytes, err := json.Marshal(resp)
if err != nil {
scrobbleretrieverWriteError(p, stack, err)
return
}
respPtr, err := p.WriteBytes(respBytes)
if err != nil {
stack[0] = 0
return
}
stack[0] = respPtr
}
// scrobbleretrieverWriteError writes an error response to plugin memory.
func scrobbleretrieverWriteError(p *extism.CurrentPlugin, stack []uint64, err error) {
errResp := struct {
Error string `json:"error"`
}{Error: err.Error()}
respBytes, _ := json.Marshal(errResp)
respPtr, _ := p.WriteBytes(respBytes)
stack[0] = respPtr
}