luaplugin

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

This section is empty.

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.

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 CheckRouterVersion

func CheckRouterVersion(manifest *Manifest, current string) error

CheckRouterVersion rejects plugins requiring a newer router.

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 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 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 slot of llm_router.register. The two handler inventories (registration-time validation in sandbox.go and install-time discovery in service.go) both derive from these lists.

const (
	HandlerCompleteStream      Handler = "complete_stream"
	HandlerTranscribe          Handler = "transcribe"
	HandlerSpeech              Handler = "speech"
	HandlerGenerateImage       Handler = "generate_image"
	HandlerEmbed               Handler = "embed"
	HandlerValidateCredentials Handler = "validate_credentials"
	HandlerGetModelInfos       Handler = "get_model_infos"
	HandlerClassifyError       Handler = "classify_error"
	HandlerNeedsRefresh        Handler = "needs_refresh"
	HandlerRefreshCredential   Handler = "refresh_credential"
	HandlerConfigSchema        Handler = "config_schema"
	HandlerCredentialSchema    Handler = "credential_schema"
	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
}

HandlerMeta carries request identity into handler calls: which provider instance and type serve the request, which credential attempt runs, which model was requested, and the provider config. Threaded from the router through the pool into every handler invocation, so identity never has to be re-derived from scattered arguments.

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
	RouterVersion string
	Description   string
	License       string
	AllowHosts    []string
	// Unsafe is true when the plugin requests a wildcard allow_host.
	Unsafe bool
	// ProxyLocations is the whitelist of ISO country codes the upstream
	// expects requests to originate from. Empty allows any location.
	ProxyLocations []string
	// ProxyDefaultOption is the default proxy mode for providers registered
	// from this plugin: disabled, auto or manual. Empty means disabled.
	ProxyDefaultOption string
	// ProxySource marks this plugin as a proxy-list source with a
	// fetch_proxies handler instead of a provider backend.
	ProxySource 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"`
	RouterVersion string   `json:"router_version"`
	Description   string   `json:"description"`
	License       string   `json:"license"`
	AllowHosts    []string `json:"allow_hosts"`
	Unsafe        bool     `json:"unsafe"`
	// ProxyLocations and ProxyDefaultOption mirror the manifest proxy tags.
	ProxyLocations []string `json:"proxy_locations,omitempty"`
	// ProxyDefaultOption is the default proxy mode for providers registered
	// from this plugin. Empty means disabled.
	ProxyDefaultOption string `json:"proxy_default_option,omitempty"`
	// ProxySourceKeys lists registered proxy-list sources in this plugin.
	ProxySourceKeys []string                `json:"proxy_source_keys,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"`
	ProxySourceKeys []string            `json:"proxy_source_keys,omitempty"`
}

PluginVersionSnapshot is one rollback entry.

type ProxyPick added in v0.0.7

type ProxyPick struct {
	ID     string
	URL    string
	Region string
}

ProxyPick is one ordered proxy candidate for a plugin call.

type ProxyResolution

type ProxyResolution struct {
	ProxyID  string
	ProxyURL string
}

ProxyResolution is the resolver result for one plugin call.

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) 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) CompletePool added in v0.0.6

CompletePool tries the credential pool in order through the complete handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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) CompleteStreamPool added in v0.0.6

func (s *Service) CompleteStreamPool(
	ctx context.Context,
	meta HandlerMeta,
	creds []*models.Credential,
	req *models.ChatCompletionRequest,
	w io.Writer,
) (string, error)

CompleteStreamPool tries the credential pool in order through the complete_stream handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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) DefaultProxyMode added in v0.0.7

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

DefaultProxyMode returns the manifest default proxy mode for typeKey. Empty and unknown values mean disabled.

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) EmbedPool added in v0.0.6

EmbedPool tries the credential pool in order through the embed handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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) ([]models.ProxyCandidate, 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) GenerateImagePool added in v0.0.6

GenerateImagePool tries the credential pool in order through the generate_image handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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,
	typeKey string,
	cred *models.Credential,
	providerConfig map[string]any,
) ([]models.ModelInfo, error)

GetModelInfos calls get_model_infos. 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) 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) 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) NeedsRefresh

func (s *Service) NeedsRefresh(typeKey string, cred *models.Credential) (bool, error)

NeedsRefresh calls needs_refresh. Missing handler means not refreshable.

func (*Service) ProxySourceKeys

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

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

func (*Service) ProxyWhitelist added in v0.0.7

func (s *Service) ProxyWhitelist(typeKey string) []string

ProxyWhitelist returns the manifest location whitelist for typeKey. Empty means any location is allowed.

func (*Service) RefreshCredential

func (s *Service) RefreshCredential(
	goCtx context.Context,
	typeKey string,
	cred *models.Credential,
) (map[string]any, error)

RefreshCredential calls refresh_credential and returns the new data map. Missing handler reports ErrHandlerNotFound (not refreshable).

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) Schema

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

Schema calls config_schema or credential_schema. Missing handler reports ErrHandlerNotFound so the dashboard falls back to raw JSON input.

func (*Service) SetCredentialDisabler added in v0.2.0

func (s *Service) SetCredentialDisabler(f func(credentialID, reason string))

SetCredentialDisabler wires per-attempt credential auto-disable for auth/payment_required outcomes. Unset (nil) disables it.

func (*Service) SetDumpDir added in v0.2.0

func (s *Service) SetDumpDir(dir string)

SetDumpDir wires the directory for full upstream-body spill files in debug mode. Empty disables spilling.

func (*Service) SetExhaustedStore added in v0.1.2

func (s *Service) SetExhaustedStore(e *exhausted.Service)

SetExhaustedStore wires joint limit-key recording for rate/quota/ model_unavailable outcomes. Unset (nil) disables marking; attempts still run.

func (*Service) SetGeoBanStore added in v0.2.0

func (s *Service) SetGeoBanStore(g interface {
	Mark(plugin, provider, proxy, reason string) error
})

SetGeoBanStore wires indefinite geo-flag recording for geo outcomes. Unset (nil) disables flagging; attempts still run.

func (*Service) SetLogger

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

SetLogger wires structured logging.

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) SetProviderDisabler added in v0.2.0

func (s *Service) SetProviderDisabler(f func(providerID, reason string))

SetProviderDisabler wires per-attempt provider auto-disable for structural_fault outcomes. Unset (nil) disables it.

func (*Service) SetProxyResolver

func (s *Service) SetProxyResolver(fn func(ctx context.Context, rec *PluginRecord, providerConfig map[string]any, known exhausted.Segments) ([]ProxyPick, error))

SetProxyResolver wires pool-based proxy selection for plugin HTTP calls. Resolution is lazy per request; a non-nil error fails the request loudly (manual mode with no usable proxy pooled, settled pool with none).

func (*Service) SetUsageTracker added in v0.0.6

func (s *Service) SetUsageTracker(t UsageTracker)

SetUsageTracker wires per-credential usage accounting for pool calls. Unset (nil) disables accounting; attempts still run.

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) SpeechPool added in v0.0.6

func (s *Service) SpeechPool(
	ctx context.Context,
	meta HandlerMeta,
	creds []*models.Credential,
	req *models.SpeechRequest,
) (*models.SpeechResponse, string, error)

SpeechPool tries the credential pool in order through the speech handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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) 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) TranscribePool added in v0.0.6

TranscribePool tries the credential pool in order through the transcribe handler, at most once per credential. It returns the redacted proxy host:port of the winning or last attempt ("" = direct).

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.

type UsageTracker added in v0.0.6

type UsageTracker = pool.UsageTracker

UsageTracker records per-credential outcomes. It is implemented by the credential pool service and injected via SetUsageTracker, keeping this package free of import cycles.

Jump to

Keyboard shortcuts

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