Documentation
¶
Index ¶
- Variables
- func AllHandlerNames() []string
- func BuildID(origin PluginOrigin, manifest *Manifest) (string, error)
- func CheckRouterVersion(manifest *Manifest, current string) error
- func CompareVersions(a, b string) (int, error)
- func OptionalHandlerNames() []string
- func QualifiedSourceKey(recordID, name string) string
- type CrashEntry
- type Handler
- type HandlerMeta
- type LogEntry
- type Manifest
- type PluginOrigin
- type PluginRecord
- type PluginVersionSnapshot
- type ProxyPick
- type ProxyResolution
- type Service
- func (s *Service) AuthInitiate(goCtx context.Context, typeKey, flowID string) (*models.AuthFlowResult, error)
- func (s *Service) AuthStep(goCtx context.Context, typeKey, flowID, action string, values map[string]any) (*models.AuthFlowResult, error)
- func (s *Service) Complete(goCtx context.Context, meta HandlerMeta, req *models.ChatCompletionRequest) (*models.ChatCompletionResponse, error)
- func (s *Service) CompletePool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) (*models.ChatCompletionResponse, error)
- func (s *Service) CompleteStream(goCtx context.Context, meta HandlerMeta, req *models.ChatCompletionRequest, ...) error
- func (s *Service) CompleteStreamPool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) error
- func (s *Service) Crashes(pluginID string) []CrashEntry
- func (s *Service) DefaultProxyMode(typeKey string) string
- func (s *Service) Delete(id string) error
- func (s *Service) Embed(goCtx context.Context, meta HandlerMeta, req *models.EmbeddingsRequest) (*models.EmbeddingsResponse, error)
- func (s *Service) EmbedPool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) (*models.EmbeddingsResponse, error)
- func (s *Service) FetchProxies(goCtx context.Context, sourceKey string) ([]models.ProxyCandidate, error)
- func (s *Service) GenerateImage(goCtx context.Context, meta HandlerMeta, req *models.ImageGenerationRequest) (*models.ImageGenerationResponse, error)
- func (s *Service) GenerateImagePool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) (*models.ImageGenerationResponse, error)
- func (s *Service) Get(id string) (*PluginRecord, error)
- func (s *Service) GetModelInfos(goCtx context.Context, typeKey string, cred *models.Credential, ...) ([]models.ModelInfo, error)
- func (s *Service) HasHandler(typeKey, handler string) bool
- func (s *Service) Icon(typeKey string) string
- func (s *Service) Install(source []byte, origin PluginOrigin) (*PluginRecord, error)
- func (s *Service) List() ([]*PluginRecord, error)
- func (s *Service) Logs(pluginID string) []LogEntry
- func (s *Service) Lookup(typeKey string) (*PluginRecord, error)
- func (s *Service) NeedsRefresh(typeKey string, cred *models.Credential) (bool, error)
- func (s *Service) ProxySourceKeys() []string
- func (s *Service) ProxyWhitelist(typeKey string) []string
- func (s *Service) RefreshCredential(goCtx context.Context, typeKey string, cred *models.Credential) (map[string]any, error)
- func (s *Service) Registered() []string
- func (s *Service) Rollback(id string) (*PluginRecord, error)
- func (s *Service) Schema(typeKey, handler string) ([]*models.UINode, error)
- func (s *Service) SetExhaustedStore(e *exhausted.Service)
- func (s *Service) SetLogger(l *slog.Logger)
- func (s *Service) SetOnChanged(fn func(typeKey string))
- func (s *Service) SetProxyResolver(...)
- func (s *Service) SetUsageTracker(t UsageTracker)
- func (s *Service) Speech(goCtx context.Context, meta HandlerMeta, req *models.SpeechRequest) (*models.SpeechResponse, error)
- func (s *Service) SpeechPool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) (*models.SpeechResponse, error)
- func (s *Service) Transcribe(goCtx context.Context, meta HandlerMeta, req *models.TranscriptionRequest) (*models.TranscriptionResponse, error)
- func (s *Service) TranscribePool(ctx context.Context, meta HandlerMeta, creds []*models.Credential, ...) (*models.TranscriptionResponse, error)
- func (s *Service) ValidateCredentials(typeKey string, data map[string]any) (bool, error)
- type UsageTracker
Constants ¶
This section is empty.
Variables ¶
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.
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.
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 ¶
CheckRouterVersion rejects plugins requiring a newer router.
func CompareVersions ¶
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
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 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 ¶
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 ProxyResolution ¶
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 (*Service) AuthInitiate ¶
func (s *Service) AuthInitiate(goCtx context.Context, typeKey, flowID string) (*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) (*models.AuthFlowResult, error)
AuthStep calls auth_step with {action, values}.
func (*Service) Complete ¶
func (s *Service) Complete( goCtx context.Context, meta HandlerMeta, req *models.ChatCompletionRequest, ) (*models.ChatCompletionResponse, error)
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
func (s *Service) CompletePool( ctx context.Context, meta HandlerMeta, creds []*models.Credential, req *models.ChatCompletionRequest, ) (*models.ChatCompletionResponse, error)
CompletePool tries the credential pool in order through the complete handler, at most once per credential.
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, ) error
CompleteStreamPool tries the credential pool in order through the complete_stream handler, at most once per credential.
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
DefaultProxyMode returns the manifest default proxy mode for typeKey. Empty and unknown values mean disabled.
func (*Service) Embed ¶ added in v0.0.5
func (s *Service) Embed( goCtx context.Context, meta HandlerMeta, req *models.EmbeddingsRequest, ) (*models.EmbeddingsResponse, error)
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
func (s *Service) EmbedPool( ctx context.Context, meta HandlerMeta, creds []*models.Credential, req *models.EmbeddingsRequest, ) (*models.EmbeddingsResponse, error)
EmbedPool tries the credential pool in order through the embed handler, at most once per credential.
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
func (s *Service) GenerateImage( goCtx context.Context, meta HandlerMeta, req *models.ImageGenerationRequest, ) (*models.ImageGenerationResponse, error)
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
func (s *Service) GenerateImagePool( ctx context.Context, meta HandlerMeta, creds []*models.Credential, req *models.ImageGenerationRequest, ) (*models.ImageGenerationResponse, error)
GenerateImagePool tries the credential pool in order through the generate_image handler, at most once per credential.
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 ¶
HasHandler reports whether a type key declares a handler.
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) Lookup ¶
func (s *Service) Lookup(typeKey string) (*PluginRecord, error)
Lookup returns the plugin record serving typeKey.
func (*Service) NeedsRefresh ¶
NeedsRefresh calls needs_refresh. Missing handler means not refreshable.
func (*Service) ProxySourceKeys ¶
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
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 ¶
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 ¶
Schema calls config_schema or credential_schema. Missing handler reports ErrHandlerNotFound so the dashboard falls back to raw JSON input.
func (*Service) SetExhaustedStore ¶ added in v0.1.2
SetExhaustedStore wires joint limit-key recording for rate/quota outcomes. Unset (nil) disables marking; attempts still run.
func (*Service) SetOnChanged ¶
SetOnChanged registers a callback fired with every affected type key after install/update/rollback/delete/enable/disable.
func (*Service) SetProxyResolver ¶
func (s *Service) SetProxyResolver(fn func(ctx context.Context, rec *PluginRecord, providerConfig map[string]any) ([]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, error)
SpeechPool tries the credential pool in order through the speech handler, at most once per credential.
func (*Service) Transcribe ¶ added in v0.0.5
func (s *Service) Transcribe( goCtx context.Context, meta HandlerMeta, req *models.TranscriptionRequest, ) (*models.TranscriptionResponse, error)
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
func (s *Service) TranscribePool( ctx context.Context, meta HandlerMeta, creds []*models.Credential, req *models.TranscriptionRequest, ) (*models.TranscriptionResponse, error)
TranscribePool tries the credential pool in order through the transcribe handler, at most once per credential.
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.