Documentation
¶
Overview ¶
Card helpers keep every provider quota card close to the official provider card style (one short plan chip, one row per real limit window, no group-specific chrome, dollar balances as text or chips, never bars).
The management panel renders plugin cards generically: every summary metric becomes a chip, each group gets a header, and a bucket's Description becomes its row label (the SDK QuotaBucket has no display name). So card code must:
- leave Description empty and put the short row label in Window;
- emit at most MaxCardSummaryChips summary metrics, none repeating a bar;
- format dollar amounts in text with USD (exactly 2 decimals).
Package providerkit implements the CLIProxy provider plugin RPC contract. Provider implementations use the pinned SDK's interfaces directly.
Index ¶
- Constants
- func APIKey(storage []byte, metadata map[string]any) (string, error)
- func AssertModelNamespace(t TestReporter, ns string, models []pluginapi.ModelInfo)
- func AuthFields(storage []byte, metadata map[string]any) (map[string]any, error)
- func AuthProxyURL(storage []byte, metadata map[string]any, hostProxyURL string) string
- func CheckCard(resp pluginapi.QuotaFetchResponse) []string
- func CheckModelNamespace(ns string, models []pluginapi.ModelInfo) error
- func MapError(err error) *pluginabi.Error
- func NewHostHTTPClient(h Caller, callbackID string) pluginapi.HostHTTPClient
- func NewQuotaBucket(window string, remainingFraction float64, resetTime string) pluginapi.QuotaBucket
- func NewQuotaTransport() *http.Transport
- func QuotaProxy(r *http.Request) (*url.URL, error)
- func QuotaWindowLabel(window string) string
- func RetryAfterSeconds(value string, now time.Time) int
- func USD(v float64) string
- func ValidateMetadata(m pluginapi.Metadata) error
- func ValidateModelNamespace(ns string) error
- func WithProxyURL(ctx context.Context, proxyURL string) context.Context
- type APIKeyAuth
- func (p APIKeyAuth) Identifier() string
- func (p APIKeyAuth) ParseAuth(_ context.Context, req pluginapi.AuthParseRequest) (pluginapi.AuthParseResponse, error)
- func (p APIKeyAuth) PollLogin(ctx context.Context, req pluginapi.AuthLoginPollRequest) (pluginapi.AuthLoginPollResponse, error)
- func (p APIKeyAuth) RefreshAuth(_ context.Context, req pluginapi.AuthRefreshRequest) (pluginapi.AuthRefreshResponse, error)
- func (p APIKeyAuth) StartLogin(ctx context.Context, req pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
- type APIKeyLogin
- func (l *APIKeyLogin) HandleManagement(ctx context.Context, req pluginapi.ManagementRequest) (pluginapi.ManagementResponse, error)
- func (l *APIKeyLogin) PollLogin(_ context.Context, req pluginapi.AuthLoginPollRequest) (pluginapi.AuthLoginPollResponse, error)
- func (l *APIKeyLogin) RegisterManagement(_ context.Context, req pluginapi.ManagementRegistrationRequest) (pluginapi.ManagementRegistrationResponse, error)
- func (l *APIKeyLogin) StartLogin(_ context.Context, req pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
- type APIKeyLoginConfig
- type APIKeyLoginField
- type CachedQuota
- func (q *CachedQuota) DescribeQuota(context.Context, pluginapi.QuotaDescribeRequest) (pluginapi.QuotaDescribeResponse, error)
- func (q *CachedQuota) FetchQuota(ctx context.Context, r pluginapi.QuotaFetchRequest) (pluginapi.QuotaFetchResponse, error)
- func (q *CachedQuota) Identifier() string
- func (q *CachedQuota) Invalidate(authID string)
- func (q *CachedQuota) ResetQuota(context.Context, pluginapi.QuotaResetRequest) (pluginapi.QuotaResetResponse, error)
- func (q *CachedQuota) Store(r pluginapi.QuotaFetchRequest, out pluginapi.QuotaFetchResponse) error
- type Caller
- type CallerFunc
- type Definition
- type FetchQuotaFunc
- type Passthrough
- func (p Passthrough) CountTokens(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorResponse, error)
- func (p Passthrough) Execute(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorResponse, error)
- func (p Passthrough) ExecuteStream(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorStreamResponse, error)
- func (p Passthrough) HttpRequest(ctx context.Context, r pluginapi.ExecutorHTTPRequest) (pluginapi.ExecutorHTTPResponse, error)
- func (p Passthrough) Identifier() string
- type QuotaHTTPClient
- type Runtime
- type TestReporter
Constants ¶
const ( CardWindowFiveHour = "5-hour limit" CardWindowWeekly = "Weekly limit" CardWindowMonthly = "Monthly limit" CardWindowDaily = "Daily limit" )
Canonical short row labels for quota windows, matching the official provider cards. Keep Window values short; staging screenshots must confirm multi-window order after relabelling.
const MaxCardSummaryChips = 3
MaxCardSummaryChips bounds the plan-row chip count (plan chip excluded). The panel renders every summary metric as a chip with no limit, so an unbounded summary becomes a wall of chips next to the official cards.
const QuotaCacheTTL = 60 * time.Second
QuotaCacheTTL is the maximum age of a successful per-auth quota observation.
const QuotaHTTPTimeout = 15 * time.Second
QuotaHTTPTimeout bounds the entire quota HTTP exchange, including body reads.
Variables ¶
This section is empty.
Functions ¶
func APIKey ¶
APIKey reads a nonempty api_key using host metadata precedence. It never includes the key or raw storage in an error.
func AssertModelNamespace ¶ added in v0.2.0
func AssertModelNamespace(t TestReporter, ns string, models []pluginapi.ModelInfo)
AssertModelNamespace fails the test if any model id would not be registered under ns.
func AuthFields ¶
AuthFields applies the same merge precedence as persisted host auth storage: Metadata overrides StorageJSON. Callers own the returned map.
func AuthProxyURL ¶ added in v0.2.0
AuthProxyURL resolves the outbound proxy for direct (non-host) requests made on behalf of one auth, with the host's precedence: the auth's proxy_url (metadata overrides storage), then the host's global proxy-url. An empty result means "inherit": the environment proxy settings apply.
func CheckCard ¶ added in v0.2.2
func CheckCard(resp pluginapi.QuotaFetchResponse) []string
CheckCard reports official-card-style violations in a quota response:
- any bucket Description (leave it empty so Window stays the row label);
- any bucket with a blank Window (the row would have no label);
- more than MaxCardSummaryChips summary metrics;
- a summary metric repeating a bar (same or overlapping label text).
An empty return means the card follows the shared style. Plugin quota tests assert on this alongside their exact-shape golden tests.
func CheckModelNamespace ¶ added in v0.2.0
CheckModelNamespace is the reusable conformance check for plugin test suites: it reports an error listing every model id that would not be registered under ns. Call it with every id the plugin can emit (static fallback, discovery fixtures and dynamic refresh paths).
func MapError ¶
MapError preserves explicit, public RPC errors. Unclassified errors are intentionally opaque: transport and parsing errors can contain credentials. Providers must put only safe, user-facing text in pluginabi.Error.Message.
func NewHostHTTPClient ¶
func NewHostHTTPClient(h Caller, callbackID string) pluginapi.HostHTTPClient
NewHostHTTPClient creates a callback-scoped SDK client. Runtime injects this automatically into each request. Never retain it past that request/stream. Cancellation uses the host's operation IDs, not abandoned blocking goroutines.
func NewQuotaBucket ¶ added in v0.2.2
func NewQuotaBucket(window string, remainingFraction float64, resetTime string) pluginapi.QuotaBucket
NewQuotaBucket builds one quota bar row: a canonical window label, the remaining fraction, and the reset time. It never sets Description, so the panel shows the short Window label instead of a sentence. remainingFraction is the fraction remaining in [0, 1] (unclamped; NaN fails host decoding), and resetTime is an RFC 3339 instant or "" when the window has no reset (the panel then shows "-").
func NewQuotaTransport ¶ added in v0.2.0
NewQuotaTransport clones the standard transport with QuotaProxy as its proxy (the WithProxyURL setting, else normal environment proxy behavior). It speaks HTTP/1.1 only: Go reuses a cached HTTP/2 connection by destination before it consults Proxy, so one auth's poll could ride another auth's proxy. HTTP/1.1 connections are pooled per proxy.
func QuotaProxy ¶ added in v0.2.0
QuotaProxy is an http.Transport Proxy function that applies the setting from WithProxyURL and otherwise falls back to the environment. Custom transports should start from NewQuotaTransport rather than set it alone: a transport shared across proxies must not reuse HTTP/2 connections.
func QuotaWindowLabel ¶ added in v0.2.2
Canonical quota card labels.
The plugin QuotaBucket type has no displayName field, so the panel renders each bucket row with the label description ?? window (group displayName is a separate group header). A bucket Description therefore becomes the row label and tooltip while Window is hidden, so long explanations must never be set as Description. Keep bucket labels short and window-style with QuotaWindowLabel and NewQuotaBucket, and put absolute amounts in the label only where they add information (for example, "Weekly key limit · $5.00 of $5.00 left").
Only the listed spellings canonicalize to the CardWindow* constants; anything else (including typos and the empty string) passes through verbatim after trimming, so callers must spell windows deliberately.
func RetryAfterSeconds ¶
RetryAfterSeconds parses HTTP Retry-After seconds or an HTTP date, rounding a future date up. Invalid or past values yield zero. No wall clock is hidden.
func USD ¶ added in v0.2.2
USD formats dollars with exactly 2 decimals, sign first: 25 -> $25.00, -0.02 -> -$0.02. Amounts in bucket text must use this, never a higher-precision debug format; chip currency metrics are formatted panel-side from the numeric value. Non-finite inputs render as $0.00: JSON-decoded amounts are always finite, so this branch is unreachable defense so a card can never show $NaN.
func ValidateMetadata ¶
ValidateMetadata checks the metadata required by the host and public registry.
func ValidateModelNamespace ¶ added in v0.2.0
ValidateModelNamespace reports whether ns is usable as a fixed model namespace: a bare segment such as "synthetic", without the trailing slash.
func WithProxyURL ¶ added in v0.2.0
WithProxyURL attaches a proxy setting to ctx for QuotaHTTPClient requests. It accepts the host's proxy syntax: "" inherits the environment, "direct" or "none" bypasses proxies, otherwise an http, https, socks5 or socks5h URL.
Types ¶
type APIKeyAuth ¶
type APIKeyAuth struct {
Provider string
Validate func(map[string]any) error
Login *APIKeyLogin
}
APIKeyAuth implements the SDK auth provider for API-key-only providers. Validate may validate additional provider-owned fields; its errors are redacted by Runtime unless explicitly represented as public pluginabi.Error values. It is stateless: duplicate-file/account policy belongs to the provider.
Login optionally enables the management-UI login flow: StartLogin serves a login page through the plugin ManagementAPI/resource routes and PollLogin returns the submitted key. A nil Login keeps the historical behavior of rejecting both calls with api_key_only.
func (APIKeyAuth) Identifier ¶
func (p APIKeyAuth) Identifier() string
func (APIKeyAuth) ParseAuth ¶
func (p APIKeyAuth) ParseAuth(_ context.Context, req pluginapi.AuthParseRequest) (pluginapi.AuthParseResponse, error)
func (APIKeyAuth) PollLogin ¶
func (p APIKeyAuth) PollLogin(ctx context.Context, req pluginapi.AuthLoginPollRequest) (pluginapi.AuthLoginPollResponse, error)
func (APIKeyAuth) RefreshAuth ¶
func (p APIKeyAuth) RefreshAuth(_ context.Context, req pluginapi.AuthRefreshRequest) (pluginapi.AuthRefreshResponse, error)
func (APIKeyAuth) StartLogin ¶
func (p APIKeyAuth) StartLogin(ctx context.Context, req pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
type APIKeyLogin ¶ added in v0.2.0
type APIKeyLogin struct {
// contains filtered or unexported fields
}
APIKeyLogin serves one provider's API-key login flow. It implements the StartLogin/PollLogin half of pluginapi.AuthProvider (wired through APIKeyAuth.Login) and the pluginapi.ManagementAPI plus pluginapi.ManagementHandler halves for Capabilities.ManagementAPI.
func NewAPIKeyLogin ¶ added in v0.2.0
func NewAPIKeyLogin(cfg APIKeyLoginConfig) (*APIKeyLogin, error)
NewAPIKeyLogin validates the config. Parse must be non-nil: the submit endpoint only stores keys that pass the provider's own checks.
Wire the result into both APIKeyAuth.Login and the Definition's Capabilities.ManagementAPI: the first serves StartLogin/PollLogin, the second registers the login page and key-submit routes. Setting only one leaves StartLogin failing with login_unavailable.
func (*APIKeyLogin) HandleManagement ¶ added in v0.2.0
func (l *APIKeyLogin) HandleManagement(ctx context.Context, req pluginapi.ManagementRequest) (pluginapi.ManagementResponse, error)
HandleManagement dispatches the declared routes by exact method and full path. Request headers are intentionally ignored: the host forwards management credentials with the request, and the login flow must never read, log, or echo them.
func (*APIKeyLogin) PollLogin ¶ added in v0.2.0
func (l *APIKeyLogin) PollLogin(_ context.Context, req pluginapi.AuthLoginPollRequest) (pluginapi.AuthLoginPollResponse, error)
PollLogin reports pending until the submit endpoint completes the session, then delivers the validated AuthData to exactly one poller. A concurrent second poller gets a credential-free pending (not an error) until the consumed entry expires, so it cannot poison the host login session.
func (*APIKeyLogin) RegisterManagement ¶ added in v0.2.0
func (l *APIKeyLogin) RegisterManagement(_ context.Context, req pluginapi.ManagementRegistrationRequest) (pluginapi.ManagementRegistrationResponse, error)
RegisterManagement captures the host's route bases and declares the login page (resource route) and the key submit endpoint (management route). The submit path is namespaced per provider because management routes share one global namespace across plugins.
func (*APIKeyLogin) StartLogin ¶ added in v0.2.0
func (l *APIKeyLogin) StartLogin(_ context.Context, req pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
StartLogin mints a pending session and returns the login page URL. The URL is root-relative on purpose: the host callback base URL the host passes in is loopback-only, so absolutizing with it would hand the panel a link the operator's browser cannot load. The panel opens the relative URL against its own origin (the host, which serves the panel), so the page loads both locally and remotely. StartLogin fails only when the management routes were never registered, in which case the host keeps its generic error.
type APIKeyLoginConfig ¶ added in v0.2.0
type APIKeyLoginConfig struct {
// Provider is the provider key; it must match the APIKeyAuth provider.
// NewAPIKeyLogin enforces the shell-safe charset (see
// loginProviderPattern).
Provider string
// Parse is the provider's full ParseAuth pipeline, including validation
// and the duplicate-key guard.
Parse func(context.Context, pluginapi.AuthParseRequest) (pluginapi.AuthParseResponse, error)
// Fields documents extra provider-owned auth fields.
Fields []APIKeyLoginField
// SessionTTL bounds a pending login; defaults to 15 minutes.
SessionTTL time.Duration
}
APIKeyLoginConfig wires provider behavior into the login helper.
type APIKeyLoginField ¶ added in v0.2.0
type APIKeyLoginField struct {
// Name is the JSON key accepted by the submit endpoint. NewAPIKeyLogin
// enforces the [A-Za-z0-9_] charset (see loginFieldPattern).
Name string
// Label is the short human-readable name shown on the login page.
Label string
// Description explains the field on the login page.
Description string
// Required rejects submissions that omit the field.
Required bool
}
APIKeyLoginField describes one provider-owned auth field, beyond api_key and label, that the login page documents and the submit endpoint accepts.
type CachedQuota ¶
type CachedQuota struct {
// contains filtered or unexported fields
}
CachedQuota implements a non-resettable SDK quota provider with per-account single-flight fetching, copy isolation, and a 60-second cache. Use Store to incorporate normalized inference response headers by auth identity without another HTTP poll or access to the host's credential context.
func NewCachedQuota ¶
func NewCachedQuota(provider, display string, fetch FetchQuotaFunc) *CachedQuota
NewCachedQuota creates an empty quota cache. The identity and callback are fixed for its lifetime. No background polls or provider requests are started.
func (*CachedQuota) DescribeQuota ¶
func (q *CachedQuota) DescribeQuota(context.Context, pluginapi.QuotaDescribeRequest) (pluginapi.QuotaDescribeResponse, error)
func (*CachedQuota) FetchQuota ¶
func (q *CachedQuota) FetchQuota(ctx context.Context, r pluginapi.QuotaFetchRequest) (pluginapi.QuotaFetchResponse, error)
func (*CachedQuota) Identifier ¶
func (q *CachedQuota) Identifier() string
func (*CachedQuota) Invalidate ¶
func (q *CachedQuota) Invalidate(authID string)
Invalidate discards header observations and all polled credential versions for the given auth ID (or AuthIndex when used instead of AuthID).
func (*CachedQuota) ResetQuota ¶
func (q *CachedQuota) ResetQuota(context.Context, pluginapi.QuotaResetRequest) (pluginapi.QuotaResetResponse, error)
func (*CachedQuota) Store ¶
func (q *CachedQuota) Store(r pluginapi.QuotaFetchRequest, out pluginapi.QuotaFetchResponse) error
Store replaces an auth-identity observation (for example, from a provider quota header). Only AuthID (or AuthIndex when AuthID is absent) and an optional matching Provider are used; credential context is neither needed nor keyed. Fresh observations take precedence over polls, including older in-flight polls. Data is cloned on store and read. Invalidate when reusing an identity for a different credential, or recreate the cache on reconfiguration.
type Caller ¶
Caller is the raw host callback boundary. Results are pluginabi.Envelope JSON. Implementations must support concurrent calls. Do not log request/response data.
type CallerFunc ¶
CallerFunc adapts a callback function to Caller.
type Definition ¶
type Definition struct {
Metadata pluginapi.Metadata
Capabilities pluginapi.Capabilities
// ModelNamespace declares the fixed vendor namespace for every model id
// this plugin registers or serves.
ModelNamespace string
Configure func(context.Context, []byte) error
OnQuiesce func(context.Context) error
OnShutdown func(context.Context) error
}
Definition wires SDK capabilities and lifecycle hooks. Configure receives only this plugin's configuration subtree, on both registration and reconfiguration. Hooks run serially after active calls/streams are canceled and drained. Capabilities and metadata must not be mutated after New. Capability methods must be concurrency-safe and honor context cancellation.
ModelNamespace is the plugin's fixed vendor namespace (a bare segment such as "synthetic"; the kit appends the slash). Any provider that serves models made by another vendor must namespace its model ids so they never clash when the official provider is added later. A definition that registers or serves models (ModelRegistrar or ModelProvider set) must declare it; an empty, missing or malformed namespace is a startup error. Every static, discovered and dynamic model list is filtered through it: ids outside "<namespace>/" (including doubled "<namespace>/<namespace>/…") are dropped with a logged error and never served bare. The host auth-file `prefix` is an outer host clone and does not replace this namespace.
type FetchQuotaFunc ¶
type FetchQuotaFunc func(context.Context, pluginapi.QuotaFetchRequest) (pluginapi.QuotaFetchResponse, error)
FetchQuotaFunc fetches and normalizes one account. Provider-owned protocol parsing stays outside the kit. Errors are never cached; stale data is not silently returned. Honor context cancellation.
type Passthrough ¶
type Passthrough struct {
Provider string
BuildRequest func(context.Context, pluginapi.ExecutorRequest) (pluginapi.HTTPRequest, error)
PrepareHTTP func(context.Context, pluginapi.ExecutorHTTPRequest) (pluginapi.HTTPRequest, error)
ClassifyError func(pluginapi.HTTPResponse) error
TokenCount func(context.Context, pluginapi.ExecutorRequest) (pluginapi.ExecutorResponse, error)
}
Passthrough is a thin executor. BuildRequest selects the provider protocol, endpoint and authentication; it must preserve the host's final business payload (the host already applied payload rules). No protocol translation is done here. ExecuteStream re-frames OpenAI-protocol SSE upstream bytes into one host chunk per data event (see frameStreamChunks) and forwards anything else unchanged: other Content-Types so the host frames them, and non-OpenAI plugin output so translators and native host paths keep complete framed SSE with event names. Callers must not frame again. HttpRequest copies the supplied HTTP request unless PrepareHTTP is provided. Every network operation uses the injected HostHTTPClient; there is no fallback. Provider-specific quota/exhaustion classification belongs in ClassifyError. Hooks are immutable after construction and must support concurrent calls.
func (Passthrough) CountTokens ¶
func (p Passthrough) CountTokens(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorResponse, error)
CountTokens uses TokenCount when supplied. Otherwise it returns an explicitly estimated one-token-per-four-Unicode-codepoints upper-rounded payload count, not a model tokenizer or a billable upstream token-count request.
func (Passthrough) Execute ¶
func (p Passthrough) Execute(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorResponse, error)
func (Passthrough) ExecuteStream ¶
func (p Passthrough) ExecuteStream(ctx context.Context, r pluginapi.ExecutorRequest) (pluginapi.ExecutorStreamResponse, error)
func (Passthrough) HttpRequest ¶
func (p Passthrough) HttpRequest(ctx context.Context, r pluginapi.ExecutorHTTPRequest) (pluginapi.ExecutorHTTPResponse, error)
func (Passthrough) Identifier ¶
func (p Passthrough) Identifier() string
type QuotaHTTPClient ¶
type QuotaHTTPClient struct {
// contains filtered or unexported fields
}
QuotaHTTPClient is a bounded, secret-redacting read-only polling helper. It performs no logging. Errors omit URLs, headers, bodies and transport text. This is deliberately separate from HostHTTPClient: ABI 1 / schema 10 has no no-redirect setting. Executors must always use the host client instead. The transport may implement a provider's deployment proxy policy. Its RoundTrip method must NOT follow redirects itself (the standard transports do not).
func NewQuotaHTTPClient ¶
func NewQuotaHTTPClient(transport http.RoundTripper) *QuotaHTTPClient
NewQuotaHTTPClient sets a 15s timeout, no redirects and a 1MiB response cap. With nil transport it uses NewQuotaTransport.
func (*QuotaHTTPClient) CloseIdleConnections ¶
func (c *QuotaHTTPClient) CloseIdleConnections()
CloseIdleConnections releases pooled polling connections during plugin shutdown.
func (*QuotaHTTPClient) Do ¶
func (c *QuotaHTTPClient) Do(ctx context.Context, r pluginapi.HTTPRequest) (pluginapi.HTTPResponse, error)
Do reads a quota/discovery resource. Only GET is allowed, to keep this helper out of the inference execution path. Successful bodies are returned to the provider parser; callers must never log them or credential-bearing headers.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime owns registration, dispatch and the lifetime of asynchronous work.
func New ¶
func New(d Definition, h Caller) (*Runtime, error)
New validates a definition. The runtime starts inactive until plugin.register. Supported capabilities are auth, models, executor, quota, usage and management; unrelated SDK capabilities are rejected instead of silently advertised without dispatch.
type TestReporter ¶ added in v0.2.0
TestReporter is the subset of testing.T used by AssertModelNamespace, so plugin suites in any harness can use the conformance check.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cabi exports the ABI 1 function table for Go c-shared provider plugins.
|
Package cabi exports the ABI 1 function table for Go c-shared provider plugins. |
|
examples
|
|
|
echo
command
Echo is a mock-upstream-only provider example, not a production integration.
|
Echo is a mock-upstream-only provider example, not a production integration. |