Documentation
¶
Overview ¶
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 AuthFields(storage []byte, metadata map[string]any) (map[string]any, error)
- func MapError(err error) *pluginabi.Error
- func NewHostHTTPClient(h Caller, callbackID string) pluginapi.HostHTTPClient
- func RetryAfterSeconds(value string, now time.Time) int
- func ValidateMetadata(m pluginapi.Metadata) error
- type APIKeyAuth
- func (p APIKeyAuth) Identifier() string
- func (p APIKeyAuth) ParseAuth(_ context.Context, req pluginapi.AuthParseRequest) (pluginapi.AuthParseResponse, error)
- func (p APIKeyAuth) PollLogin(context.Context, pluginapi.AuthLoginPollRequest) (pluginapi.AuthLoginPollResponse, error)
- func (p APIKeyAuth) RefreshAuth(_ context.Context, req pluginapi.AuthRefreshRequest) (pluginapi.AuthRefreshResponse, error)
- func (p APIKeyAuth) StartLogin(context.Context, pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
- 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
Constants ¶
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 AuthFields ¶
AuthFields applies the same merge precedence as persisted host auth storage: Metadata overrides StorageJSON. Callers own the returned map.
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 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 ValidateMetadata ¶
ValidateMetadata checks the metadata required by the host and public registry.
Types ¶
type APIKeyAuth ¶
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.
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(context.Context, 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(context.Context, pluginapi.AuthLoginStartRequest) (pluginapi.AuthLoginStartResponse, error)
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
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.
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. 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 9 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 a clone of the standard transport (including normal environment proxy behavior), not a mutable shared http.Client.
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 and usage; unrelated SDK capabilities are rejected instead of silently advertised without dispatch.
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. |