Documentation
¶
Index ¶
- Constants
- Variables
- func ConfigureHTTPTransport()
- func GetExprEnv(pl platforms.Platform, cfg *config.Instance, st *state.State, ...) zapscript.ArgExprEnv
- func GetLauncherIDs(pl platforms.Platform, cfg *config.Instance) []string
- func HasSensitiveScript(text string) bool
- func IsControlCommand(cmdName string) bool
- func IsMediaDisruptingCommand(cmdName string) bool
- func IsMediaLaunchingCommand(cmdName string) bool
- func IsPlaylistCommand(cmdName string) bool
- func IsValidCommand(cmdName string) bool
- func ParseAdvArgs[T any](pl platforms.Platform, env *platforms.CmdEnv, dest *T) error
- func PreWarmZapLinkHosts(db *database.Database, checkInternet func(int) bool)
- func PreWarmZapLinkHostsContext(ctx context.Context, db *database.Database, ...)
- func PressGamepadSequence(pl platforms.Platform, args []string, interKeyDelay time.Duration) error
- func PressKeyboardSequence(pl platforms.Platform, args []string, interKeyDelay time.Duration) error
- func RedactScript(text string) string
- func RedactToken(text, data string) (redactedText, redactedData string)
- func RunCommand(serviceCtx context.Context, pl platforms.Platform, cfg *config.Instance, ...) (platforms.CmdResult, error)
- func RunControlScript(ctx context.Context, pl platforms.Platform, cfg *config.Instance, ...) error
- type ArgPlaylist
- type ArgPlaylistItem
- type RunCommandOptions
- type WellKnown
Constants ¶
const ( MIMEZaparooZapScript = "application/vnd.zaparoo.zapscript" WellKnownPath = "/.well-known/zaparoo" HeaderZaparooOS = "Zaparoo-OS" HeaderZaparooArch = "Zaparoo-Arch" HeaderZaparooPlatform = "Zaparoo-Platform" )
const ExecuteTimeout = 2 * time.Second
ExecuteTimeout is the maximum duration for execute commands.
const RedactedPlaceholder = "[redacted]"
RedactedPlaceholder replaces a bearer credential in text that is logged, stored, or returned to API clients.
Variables ¶
var ( ErrArgCount = errors.New("invalid number of arguments") ErrRequiredArgs = errors.New("arguments are required") ErrRemoteSource = errors.New("cannot run from remote source") ErrFileNotFound = errors.New("file not found") ErrNoHistory = errors.New("no play history available") // ErrInvalidScript wraps a ZapScript parse failure. ErrInvalidScript = errors.New("invalid ZapScript") // ErrUnknownCommand is returned for a command name with no handler. ErrUnknownCommand = errors.New("unknown command") // ErrCommandBlocked is returned for a command denied by configuration. ErrCommandBlocked = errors.New("command blocked") // ErrExecuteNotAllowed is returned when a command line is denied by the // allow_execute config. ErrExecuteNotAllowed = errors.New("execute not allowed") )
var ( ErrNoActiveMedia = errors.New("no active media") ErrNoLauncher = errors.New("no launcher associated with active media") ErrNoControlCapabilities = errors.New("no control capabilities") )
var ( ErrInputNotAllowed = errors.New("input key not allowed") ErrInputBlocked = errors.New("input key blocked") )
var ( // ErrExtendSourceNotReader is returned when an extension is attempted // from anywhere but a physical reader. ErrExtendSourceNotReader = errors.New("playtime extensions can only be granted by scanning a card") // ErrExtendNotAlone is returned when an extension shares a script with // other commands. ErrExtendNotAlone = errors.New("playtime.extend must be the only command on a token") // ErrExtendProfileMissing is returned when the authorizing profile // argument is absent. ErrExtendProfileMissing = errors.New("playtime.extend requires a profile argument") )
var AcceptedMimeTypes = []string{ MIMEZaparooZapScript, }
var ErrControlCommandNotAllowed = errors.New("command not allowed in control context")
var ErrHTTPNotAllowed = errors.New("HTTP URL not allowed")
var ErrNoPlaylistActive = errors.New("no playlist active")
ErrNoPlaylistActive is returned by playlist control commands when no playlist is active for the requested slot. This is an expected user condition (firing a playlist command with nothing playing), so callers log it at Warn, not Error.
var ErrWellKnownNotFound = errors.New("well-known endpoint not found")
ErrWellKnownNotFound is returned when the .well-known/zaparoo endpoint returns 404, indicating the host does not support Zaparoo.
Functions ¶
func ConfigureHTTPTransport ¶ added in v2.11.0
func ConfigureHTTPTransport()
ConfigureHTTPTransport applies the process TLS root configuration to ZapLink's custom timeout transport.
func GetExprEnv ¶ added in v2.10.0
func GetExprEnv( pl platforms.Platform, cfg *config.Instance, st *state.State, scanned *zapscript.ExprEnvScanned, launching *zapscript.ExprEnvLaunching, ) zapscript.ArgExprEnv
func GetLauncherIDs ¶ added in v2.17.0
GetLauncherIDs extracts launcher IDs from the platform for validation context.
func HasSensitiveScript ¶ added in v2.17.0
HasSensitiveScript reports whether text involves a bearer credential, so callers can also drop adjacent raw copies such as a token's data payload.
This keys off the command rather than the value: a token whose text has already been redacted may still have an unredacted raw payload beside it. Text that cannot be parsed is treated as sensitive, since an unreadable script cannot be shown to be free of credentials.
func IsControlCommand ¶ added in v2.10.0
IsControlCommand returns true if the command is the control command. The control command is blocked in control context to prevent recursion where a control's Script invokes another control command.
func IsMediaDisruptingCommand ¶ added in v2.11.0
IsMediaDisruptingCommand returns true if the command would change or stop the currently playing media. Used by launch guard to decide whether a token should be staged for confirmation.
func IsMediaLaunchingCommand ¶ added in v2.7.0
IsMediaLaunchingCommand returns true if the command launches media and should be subject to playtime limits.
func IsPlaylistCommand ¶ added in v2.10.0
IsPlaylistCommand returns true if the command is a playlist command. Playlist commands require a PlaylistController and are not safe in control context.
func IsValidCommand ¶ added in v2.9.0
IsValidCommand returns true if the command name is a valid ZapScript command.
func ParseAdvArgs ¶ added in v2.8.0
ParseAdvArgs parses and validates advanced arguments for a command. Returns an error if parsing or validation fails.
func PreWarmZapLinkHosts ¶ added in v2.8.0
PreWarmZapLinkHosts pre-warms the DNS and TLS cache for known zaplink hosts. This is called during startup to reduce latency on first zaplink access. It makes HEAD requests to /.well-known/zaparoo for each supported base URL.
func PreWarmZapLinkHostsContext ¶ added in v2.11.0
func PressGamepadSequence ¶ added in v2.10.0
PressGamepadSequence is shared between ZapScript commands and API handlers. interKeyDelay sets the gap between button presses; pass 0 to use the default.
func PressKeyboardSequence ¶ added in v2.10.0
PressKeyboardSequence is shared between ZapScript commands and API handlers. interKeyDelay sets the gap between consecutive key presses; pass 0 to use the default (100 ms). If the platform implements keyboardSequencer, the full args slice is handed off; otherwise falls back to pressing each key individually.
func RedactScript ¶ added in v2.17.0
RedactScript removes bearer credentials from ZapScript text while leaving everything else readable, so logs and history stay useful for diagnosis. A profile card keeps its command name; an extension card additionally keeps its amount, which is the part worth auditing.
Credential values are replaced in the original text rather than the script being re-rendered from the parse tree, so traits, spacing and any command this function does not know about survive untouched.
It fails closed. Text that cannot be parsed, or whose credentials survive the replacement, is replaced wholesale.
func RedactToken ¶ added in v2.17.0
RedactToken returns a copy of a token safe to log, store, or return to API clients. The raw data payload is dropped entirely for sensitive tokens: it is an unparsed copy of the same content, so it cannot be redacted in place.
func RunCommand ¶
func RunCommand( serviceCtx context.Context, pl platforms.Platform, cfg *config.Instance, plsc playlists.PlaylistController, token tokens.Token, cmd zapscript.Command, totalCmds int, currentIndex int, db *database.Database, opts RunCommandOptions, exprEnv *zapscript.ArgExprEnv, ) (platforms.CmdResult, error)
RunCommand parses and runs a single ZapScript command.
func RunControlScript ¶ added in v2.10.0
func RunControlScript( ctx context.Context, pl platforms.Platform, cfg *config.Instance, db *database.Database, script string, exprEnv *gozapscript.ArgExprEnv, ) error
RunControlScript parses and executes a zapscript string in control context. All commands are validated before any are executed to prevent partial execution. The exprEnv is passed directly to each command instead of building from state.
Types ¶
type ArgPlaylist ¶
type ArgPlaylist struct {
ID string `json:"id"`
Name string `json:"name"`
Items []ArgPlaylistItem `json:"items"`
}
type ArgPlaylistItem ¶
type RunCommandOptions ¶ added in v2.16.0
type RunCommandOptions struct {
WaitForMediaReady func(context.Context) error
AcquireMediaLaunch func() (platforms.MediaLaunchAccess, error)
BeforeExit func()
PlaybackManager audio.PlaybackManager
UI *uievents.Service
LauncherManager *state.LauncherManager
}
RunCommandOptions groups optional services used by specific command types.
type WellKnown ¶
type WellKnown struct {
Trusted []string `json:"trusted,omitempty"`
ZapScript int `json:"zapscript"`
Auth int `json:"auth,omitempty"`
}
func FetchWellKnown ¶ added in v2.10.0
FetchWellKnown fetches and parses the .well-known/zaparoo file from a base URL. Returns ErrWellKnownNotFound if the host returned 404.
Source Files
Directories