luaplugin

package
v0.3.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultHealthCooldown = 5 * time.Minute
	MinHealthCooldown     = time.Minute
	MaxHealthCooldown     = 24 * time.Hour
)

Health-check cooldown bounds for the healthcheck_cooldown registration value. Absent means DefaultHealthCooldown.

Variables

View Source
var (
	// ErrUnsupportedLuaType marks functions, userdata and threads.
	ErrUnsupportedLuaType = errors.New("luaplugin: unsupported lua value type")
	// ErrNonStringKey marks tables keyed by non-strings in object position.
	ErrNonStringKey = errors.New("luaplugin: non-string table key")
	// ErrMixedTable marks tables mixing array and object parts.
	ErrMixedTable = errors.New("luaplugin: mixed array/object table")
	// ErrSparseArray marks array tables with holes in 1..n.
	ErrSparseArray = errors.New("luaplugin: sparse array table")
)

Conversion sentinels: Lua values that cannot cross into JSON.

View Source
var ErrHandlerNotFound = errors.New("luaplugin: handler not declared")

ErrHandlerNotFound is returned when a plugin does not declare the requested handler. Callers apply the fixed fallback behavior per handler.

View Source
var ErrTypeKeyConflict = errors.New("luaplugin: type key already registered by another plugin")

ErrTypeKeyConflict is returned when installing a plugin whose type key is already served by a different plugin. The registry is a single source of truth: one type key maps to exactly one plugin.

View Source
var PluginAPIVersion = version.Version{Major: 1, Minor: 0}

PluginAPIVersion is the plugin API contract served by this router. Format x.y: x breaks, y extends without breaking.

Functions

func AllHandlerNames added in v0.1.2

func AllHandlerNames() []string

AllHandlerNames lists every handler slot, required first.

func BuildID

func BuildID(origin PluginOrigin, manifest *Manifest) (string, error)

BuildID derives the composite plugin ID from origin and manifest. Repo installs use the file basename: <repo>/<author>/<basename>. Manual uploads use: manual/<author>/<slug-of-plugin-name>.

func CheckPluginAPI added in v0.3.8

func CheckPluginAPI(manifest *Manifest) error

CheckPluginAPI compares the plugin @plugin_api major against the served contract. Minor is informational only. Missing tag reports no_api_version.

func CompareVersions

func CompareVersions(a, b string) (int, error)

CompareVersions compares two MAJOR.MINOR.PATCH versions. Returns -1, 0 or 1 when a is older, equal or newer than b.

func OptionalHandlerNames added in v0.1.2

func OptionalHandlerNames() []string

OptionalHandlerNames lists every non-required handler slot.

func ParseStorageKey added in v0.3.7

func ParseStorageKey(raw string) (pluginID, scope, key string, ok bool)

ParseStorageKey splits a storage key into plugin ID, scope and key. It reports false when the key was not built by storageKey, so callers (e.g. database inspection) never reimplement the separator.

func QualifiedSourceKey added in v0.1.2

func QualifiedSourceKey(recordID, name string) string

QualifiedSourceKey names one plugin's proxy-list source globally: <recordID>/<declared>. Declared names are unique per plugin but not across plugins, so the bare name cannot serve as an identity.

Types

type APICompatError added in v0.3.8

type APICompatError struct {
	Reason    string
	RouterAPI version.Version
	PluginAPI version.Version
}

APICompatError reports a plugin API mismatch with a machine-readable Reason for the dashboard toast: "too_new", "too_old", "no_api_version".

func (*APICompatError) Error added in v0.3.8

func (e *APICompatError) Error() string

type CrashEntry

type CrashEntry struct {
	At      time.Time `json:"at"`
	TypeKey string    `json:"type_key"`
	Cause   string    `json:"cause"`
}

CrashEntry is one recorded PluginInternalError.

type Handler added in v0.1.2

type Handler string

Handler names a Lua-callable function slot of llm_router.register. Static schema tables (credential_schema, config_schema, settings_schema, proxy_schema) and colocated job specs are not handlers: they are validated at install, never invoked.

const (
	HandlerCompleteStream      Handler = "complete_stream"
	HandlerTranscribe          Handler = "transcribe"
	HandlerSpeech              Handler = "speech"
	HandlerGenerateImage       Handler = "generate_image"
	HandlerEmbed               Handler = "embed"
	HandlerModerate            Handler = "moderate"
	HandlerGenerateVideo       Handler = "generate_video"
	HandlerPollVideo           Handler = "poll_video"
	HandlerVideoContent        Handler = "video_content"
	HandlerValidateCredentials Handler = "validate_credentials"
	HandlerGetModelInfos       Handler = "get_model_infos"
	HandlerCheckHealth         Handler = "check_health"
	HandlerAuthInitiate        Handler = "auth_initiate"
	HandlerAuthStep            Handler = "auth_step"
)

Optional handlers: declared per type, validated as functions when present.

const HandlerComplete Handler = "complete"

Required handler: every registered type serves it.

type HandlerMeta added in v0.1.2

type HandlerMeta struct {
	ProviderID         string
	TypeKey            string
	Credential         *models.Credential
	Model              models.ModelId
	ProviderConfig     map[string]any
	AllowedCredentials []string
	// contains filtered or unexported fields
}

HandlerMeta carries request identity into handler calls: which provider instance and type serve the request, which model was requested, the provider config, and the token allow-list of credential IDs the plugin may use. A nil allow-list means unrestricted (admin probes); virtual fan-out recomputes it per member from the token snapshot in ctx.

type HealthStatus added in v0.3.8

type HealthStatus string

HealthStatus is the verdict of a check_health handler call.

const (
	HealthHealthy   HealthStatus = "healthy"
	HealthUnhealthy HealthStatus = "unhealthy"
	HealthUnknown   HealthStatus = "unknown"
)

Health verdicts: healthy keeps the credential, unhealthy disables it, unknown (and any handler failure) changes nothing.

type HealthTrigger added in v0.3.8

type HealthTrigger interface {
	SuspectFailed(pluginID, typeKey, credentialID string)
}

HealthTrigger receives failed attempt identities for detached health-check dispatch. Implemented by the healthcheck service; kept as an interface here so the call direction never cycles.

type JobSpec added in v0.3.8

type JobSpec struct {
	IntervalSeconds int64 `json:"interval_seconds"`
	RunOnStartup    bool  `json:"run_on_startup"`
	TimeoutMs       int   `json:"timeout_ms"`
}

JobSpec is the validated schedule of one colocated plugin job.

type LogEntry

type LogEntry struct {
	At      time.Time `json:"at"`
	Message string    `json:"message"`
}

LogEntry is one print() line captured from a plugin.

type Manifest

type Manifest struct {
	Plugin      string
	Author      string
	Version     string
	PluginAPI   string
	Description string
	License     string
	AllowHosts  []string
	// Unsafe is true when the plugin requests a wildcard allow_host.
	Unsafe bool
}

Manifest is the parsed "--- @tag value" header of a plugin file.

func ParseManifest

func ParseManifest(source []byte) (*Manifest, error)

ParseManifest parses the leading "---" header block. The header is the contiguous run of "---"-prefixed lines at the very start of the file.

type PluginOrigin

type PluginOrigin struct {
	RepoID string `json:"repo_id"`
	Path   string `json:"path"`
	Manual bool   `json:"manual"`
}

PluginOrigin describes where a plugin was installed from.

type PluginRecord

type PluginRecord struct {
	ID          string   `json:"id"`
	DisplayName string   `json:"display_name"`
	Author      string   `json:"author"`
	Version     string   `json:"version"`
	PluginAPI   string   `json:"plugin_api_version"`
	Description string   `json:"description"`
	License     string   `json:"license"`
	AllowHosts  []string `json:"allow_hosts"`
	Unsafe      bool     `json:"unsafe"`
	// ProxySourceKeys lists registered proxy-list feeds in this plugin.
	ProxySourceKeys []string `json:"proxy_source_keys,omitempty"`
	// ModelSpecs holds per-type pinned model rows from the registration
	// model_specs table, merged over discovered rows in GetModelInfos.
	ModelSpecs map[string]map[string]models.ModelInfo `json:"model_specs,omitempty"`
	// HealthCooldown holds per-type healthcheck_cooldown values in seconds
	// from the registration table. Absent means DefaultHealthCooldown.
	HealthCooldown map[string]int64 `json:"health_cooldown,omitempty"`
	// Schemas holds per-type static UI tables: credential_schema,
	// config_schema, settings_schema, proxy_schema. A missing table means
	// the surface stays hidden.
	Schemas map[string]map[string][]*models.UINode `json:"schemas,omitempty"`
	// Jobs holds per-type colocated job schedules. Function bodies live in
	// plugin source and load fresh on every run.
	Jobs        map[string]map[string]JobSpec `json:"jobs,omitempty"`
	TypeKeys    []string                      `json:"type_keys"`
	Handlers    map[string][]string           `json:"handlers"`
	Icons       map[string]string             `json:"icons"`
	Source      []byte                        `json:"source"`
	History     []PluginVersionSnapshot       `json:"history"`
	Origin      PluginOrigin                  `json:"origin"`
	InstalledAt time.Time                     `json:"installed_at"`
	UpdatedAt   time.Time                     `json:"updated_at"`
}

PluginRecord is the stored plugin row in BucketPlugins.

type PluginVersionSnapshot

type PluginVersionSnapshot struct {
	Version         string                                 `json:"version"`
	Source          []byte                                 `json:"source"`
	TypeKeys        []string                               `json:"type_keys"`
	Handlers        map[string][]string                    `json:"handlers"`
	Icons           map[string]string                      `json:"icons"`
	ModelSpecs      map[string]map[string]models.ModelInfo `json:"model_specs,omitempty"`
	HealthCooldown  map[string]int64                       `json:"health_cooldown,omitempty"`
	ProxySourceKeys []string                               `json:"proxy_source_keys,omitempty"`
	Schemas         map[string]map[string][]*models.UINode `json:"schemas,omitempty"`
	Jobs            map[string]map[string]JobSpec          `json:"jobs,omitempty"`
}

PluginVersionSnapshot is one rollback entry.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service owns the plugin lifecycle, the type key registry and handler calls.

func New

func New(database *db.DB, logger *slog.Logger) (*Service, error)

New loads all enabled plugins into the in-memory registry.

func (*Service) AuthInitiate

func (s *Service) AuthInitiate(goCtx context.Context, typeKey, flowID string, providerConfig map[string]any) (*models.AuthFlowResult, error)

AuthInitiate calls auth_initiate. Missing handler reports ErrHandlerNotFound so the dashboard uses the single-step credential_schema form.

func (*Service) AuthStep

func (s *Service) AuthStep(goCtx context.Context, typeKey, flowID, action string, values map[string]any, providerConfig map[string]any) (*models.AuthFlowResult, error)

AuthStep calls auth_step with {action, values}.

func (*Service) CheckHealth added in v0.3.8

func (s *Service) CheckHealth(goCtx context.Context, typeKey string, cred *models.Credential) (HealthStatus, string, error)

CheckHealth invokes the check_health handler for one credential and returns its verdict. Missing handler reports ErrHandlerNotFound (the type never health-checks). Invalid verdict shapes become PluginInternalError and change nothing: only an explicit "unhealthy" may disable.

func (*Service) Complete

Complete invokes the complete handler and validates the response shape. Proxy retries belong to the higher-level retry engine: one handler call uses one ordered pick list, and transport failover stays inside it.

func (*Service) CompleteRouted added in v0.2.0

CompleteRouted is Complete plus the redacted proxy host:port of the call ("" = direct).

func (*Service) CompleteStream

func (s *Service) CompleteStream(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.ChatCompletionRequest,
	w io.Writer,
) error

CompleteStream invokes complete_stream with an emit callback. When the plugin does not declare complete_stream, the stream is emulated with a single chunk produced by complete plus [DONE].

func (*Service) CompleteStreamRouted added in v0.2.0

func (s *Service) CompleteStreamRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.ChatCompletionRequest,
	w io.Writer,
) (string, error)

CompleteStreamRouted is CompleteStream plus the redacted proxy host:port of the call ("" = direct).

func (*Service) Crashes

func (s *Service) Crashes(pluginID string) []CrashEntry

Crashes returns recent recorded crashes for a plugin, never nil.

func (*Service) CredentialsEnabled added in v0.3.8

func (s *Service) CredentialsEnabled(typeKey string) bool

CredentialsEnabled reports whether a type key serves credentials: a credential_schema table or an auth_initiate handler is present.

func (*Service) Delete

func (s *Service) Delete(id string) error

Delete removes a plugin and its storage entries.

func (*Service) Embed added in v0.0.5

Embed invokes the embed handler. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) EmbedRouted added in v0.2.0

func (s *Service) EmbedRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.EmbeddingsRequest,
) (*models.EmbeddingsResponse, string, error)

EmbedRouted is Embed plus the redacted proxy host:port of the call ("" = direct).

func (*Service) FetchProxies

func (s *Service) FetchProxies(goCtx context.Context, sourceKey string) ([]proxypool.Candidate, error)

FetchProxies invokes the fetch_proxies handler of a proxy source plugin. sourceKey is qualified; the owning record is resolved exactly, and the routed call uses the declared name the plugin registered.

func (*Service) GenerateImage added in v0.0.5

GenerateImage invokes the generate_image handler. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) GenerateImageRouted added in v0.2.0

func (s *Service) GenerateImageRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.ImageGenerationRequest,
) (*models.ImageGenerationResponse, string, error)

GenerateImageRouted is GenerateImage plus the redacted proxy host:port of the call ("" = direct).

func (*Service) Get

func (s *Service) Get(id string) (*PluginRecord, error)

Get returns a plugin record by composite ID.

func (*Service) GetModelInfos

func (s *Service) GetModelInfos(
	goCtx context.Context,
	providerID string,
	typeKey string,
	providerConfig map[string]any,
) ([]models.ModelInfo, error)

GetModelInfos calls get_model_infos with the provider config in ctx. The plugin selects its own credential for discovery from the provider's scope: providerID threads into the call so credentials.list() sees the provider's rows. Missing handler reports ErrHandlerNotFound so callers apply the fixed fallback.

func (*Service) HasHandler

func (s *Service) HasHandler(typeKey, handler string) bool

HasHandler reports whether a type key declares a handler.

func (*Service) HealthCooldown added in v0.3.8

func (s *Service) HealthCooldown(typeKey string) time.Duration

HealthCooldown resolves the health-check cooldown for one type key: the per-type registration value when present, DefaultHealthCooldown otherwise. Unknown types fall back to the default: a struggling store never blocks traffic.

func (*Service) Icon

func (s *Service) Icon(typeKey string) string

Icon returns the icon declared by a type key, or empty when none.

func (*Service) Install

func (s *Service) Install(source []byte, origin PluginOrigin) (*PluginRecord, error)

Install validates source and stores it as a new or updated plugin. An update pushes the previous version onto History for rollback.

func (*Service) Jobs added in v0.3.8

func (s *Service) Jobs(typeKey string) map[string]JobSpec

Jobs returns the stored job schedules for a type key, or nil.

func (*Service) List

func (s *Service) List() ([]*PluginRecord, error)

List returns all installed plugin records.

func (*Service) Logs

func (s *Service) Logs(pluginID string) []LogEntry

Logs returns recent print() lines for a plugin, never nil.

func (*Service) Lookup

func (s *Service) Lookup(typeKey string) (*PluginRecord, error)

Lookup returns the plugin record serving typeKey.

func (*Service) Moderate added in v0.3.8

Moderate invokes the moderate handler. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) ModerateRouted added in v0.3.8

func (s *Service) ModerateRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.ModerationRequest,
) (*models.ModerationResponse, string, error)

ModerateRouted is Moderate plus the redacted proxy host:port of the call ("" = direct).

func (*Service) PollVideo added in v0.3.8

func (s *Service) PollVideo(
	goCtx context.Context,
	meta HandlerMeta,
	model models.ModelId,
	upstreamJobID string,
) (*models.VideoGenerationResponse, error)

PollVideo invokes the poll_video handler for one upstream job ID.

func (*Service) PollVideoRouted added in v0.3.8

func (s *Service) PollVideoRouted(
	goCtx context.Context,
	meta HandlerMeta,
	model models.ModelId,
	upstreamJobID string,
) (*models.VideoGenerationResponse, string, error)

PollVideoRouted is PollVideo plus the redacted proxy host:port of the call ("" = direct).

func (*Service) ProxiesEnabled added in v0.3.8

func (s *Service) ProxiesEnabled(typeKey string) bool

ProxiesEnabled reports whether a type key serves proxy settings: a proxy_schema table is present (empty tables enable defaults).

func (*Service) ProxySourceKeys

func (s *Service) ProxySourceKeys() ([]string, error)

ProxySourceKeys lists proxy-list sources registered by installed plugins, one qualified key per (record, declared name), first-seen order.

func (*Service) Registered

func (s *Service) Registered() []string

Registered returns all enabled type keys, sorted.

func (*Service) Rollback

func (s *Service) Rollback(id string) (*PluginRecord, error)

Rollback restores the most recent previous version. The rolled-back-from version is pushed back onto History, so rollback toggles forward again.

func (*Service) RunJob added in v0.3.8

func (s *Service) RunJob(goCtx context.Context, typeKey, name, reason, providerID string, providerConfig map[string]any) error

RunJob invokes the colocated run function of one job spec. Reason is one of "tick", "startup" or "manual". The job owns its iteration: list credentials, refresh what is stale, persist through credentials.update.

func (*Service) Schema

func (s *Service) Schema(typeKey, kind string) ([]*models.UINode, error)

Schema serves static UI tables from the stored record: credential_schema, config_schema, settings_schema or proxy_schema. Missing tables report ErrHandlerNotFound so callers hide the surface instead of rendering it.

func (*Service) Schemas added in v0.3.8

func (s *Service) Schemas(typeKey string) map[string][]*models.UINode

Schemas returns the stored static UI tables for a type key, or nil when the plugin declares none.

func (*Service) SetCredentialAccess added in v0.3.8

func (s *Service) SetCredentialAccess(
	list func(providerID string) ([]*models.Credential, error),
	get func(id string) (*models.Credential, error),
	update func(id string, data map[string]any) error,
)

SetCredentialAccess wires credential list/get (request and job contexts) and update (job contexts only) for plugins.

func (*Service) SetCredentialLifecycle added in v0.3.8

func (s *Service) SetCredentialLifecycle(
	disable func(id string, reason string) error,
	enable func(id string) error,
	automationOn func(providerID string) bool,
)

SetCredentialLifecycle wires plugin disable/enable writes plus the automation-switch gate for the shared disabled state.

func (*Service) SetCredentialParks added in v0.3.8

func (s *Service) SetCredentialParks(
	park func(id string, ttl time.Duration, reason string) error,
	unpark func(id string) error,
	parked func(id string) (*models.ParkEntry, error),
)

SetCredentialParks wires the unified cooldown park store for plugins.

func (*Service) SetHealthTrigger added in v0.3.8

func (s *Service) SetHealthTrigger(t HealthTrigger)

SetHealthTrigger wires detached health-check dispatch for failed attempts that carry a credential identity.

func (*Service) SetLogger

func (s *Service) SetLogger(l *slog.Logger)

SetLogger wires structured logging.

func (*Service) SetMarkDead added in v0.3.8

func (s *Service) SetMarkDead(f func(url, reason string) bool)

SetMarkDead wires proxy exclusion for structural TLS faults observed by the plugin HTTP client.

func (*Service) SetOnChanged

func (s *Service) SetOnChanged(fn func(typeKey string))

SetOnChanged registers a callback fired with every affected type key after install/update/rollback/delete/enable/disable.

func (*Service) SetProxyQuery added in v0.3.8

func (s *Service) SetProxyQuery(f func(pool, country string, limit int) ([]models.ProxyView, error))

SetProxyQuery wires the read-only proxy pool query for plugins.

func (*Service) SetProxyRequire added in v0.3.8

func (s *Service) SetProxyRequire(f func(ctx context.Context, req models.ProxyRequire) (models.ProxyRequireResult, error))

SetProxyRequire wires the demand-driven proxy acquisition for plugins.

func (*Service) Speech added in v0.0.5

func (s *Service) Speech(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.SpeechRequest,
) (*models.SpeechResponse, error)

Speech invokes the speech handler. The plugin returns {audio_b64, format}: the JSON return path cannot carry raw bytes, so audio crosses the boundary base64-encoded. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) SpeechRouted added in v0.2.0

func (s *Service) SpeechRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.SpeechRequest,
) (*models.SpeechResponse, string, error)

SpeechRouted is Speech plus the redacted proxy host:port of the call ("" = direct).

func (*Service) SubmitVideo added in v0.3.8

SubmitVideo invokes the generate_video handler. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) SubmitVideoRouted added in v0.3.8

SubmitVideoRouted is SubmitVideo plus the redacted proxy host:port of the call ("" = direct).

func (*Service) Transcribe added in v0.0.5

Transcribe invokes the transcribe handler. A missing handler reports ErrHandlerNotFound so the router maps it to a clean "endpoint not supported" error.

func (*Service) TranscribeRouted added in v0.2.0

func (s *Service) TranscribeRouted(
	goCtx context.Context,
	meta HandlerMeta,
	req *models.TranscriptionRequest,
) (*models.TranscriptionResponse, string, error)

TranscribeRouted is Transcribe plus the redacted proxy host:port of the call ("" = direct).

func (*Service) ValidateCredentials

func (s *Service) ValidateCredentials(typeKey string, data map[string]any) (bool, error)

ValidateCredentials calls validate_credentials. Missing handler accepts any data. Returns valid=false with a ProviderError on rejection.

func (*Service) VideoContent added in v0.3.8

func (s *Service) VideoContent(
	goCtx context.Context,
	meta HandlerMeta,
	model models.ModelId,
	upstreamJobID string,
	index int,
) (*models.VideoContentResponse, error)

VideoContent invokes the video_content handler for one upstream job ID and asset index. Video bytes cross the boundary base64-encoded like speech audio. A missing handler reports ErrHandlerNotFound.

func (*Service) VideoContentRouted added in v0.3.8

func (s *Service) VideoContentRouted(
	goCtx context.Context,
	meta HandlerMeta,
	model models.ModelId,
	upstreamJobID string,
	index int,
) (*models.VideoContentResponse, string, error)

VideoContentRouted is VideoContent plus the redacted proxy host:port of the call ("" = direct).

type StorageKey added in v0.3.8

type StorageKey struct {
	PluginID string
	Scope    string
	Key      string
}

StorageKey identifies one plugin storage entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL