Documentation
¶
Overview ¶
Package service is the public API of service plugins: an always-on HTTP handler the host mounts at /x/{key}/* (auth decided per route by the host), optionally acting as a Team remote agent source (remote_source).
A service plugin's main is one call:
func main() { service.ServeService(module) }
Paths seen by the handler are relative to /x/{key}; the host strips the prefix and sets X-Wick-Base to it.
Index ¶
- Constants
- func BaseURL(r *http.Request) string
- func Handler(mod Module, cfg map[string]string) http.Handler
- func Manifest(mod Module) wickplugin.ServiceModule
- func ServeService(mod Module)
- type AutoOff
- type Describer
- type Env
- type Meta
- type Module
- type RemoteCanceler
- type RemoteEvent
- type RemoteInjector
- type RemoteSendResult
- type RemoteSessionFielder
- type RemoteSource
- type RemoteTurn
- type Route
- type SessionField
Constants ¶
const ( Public = wickplugin.AuthPublic Token = wickplugin.AuthToken Session = wickplugin.AuthSession )
Route auth modes (see wickplugin.Auth*).
Variables ¶
This section is empty.
Functions ¶
func BaseURL ¶
BaseURL rebuilds the public URL of the service from a proxied request (X-Forwarded-Proto/Host + X-Wick-Base), e.g. for an A2A agent card.
func Handler ¶
Handler returns the plugin's HTTP handler without serving it — for tests and local harnesses. cfg seeds the config.
func Manifest ¶
func Manifest(mod Module) wickplugin.ServiceModule
Manifest returns the service half of mod's manifest.
func ServeService ¶
func ServeService(mod Module)
ServeService is the entire main() of a service plugin binary. With --dump-manifest it prints the kind=service manifest and exits; otherwise it serves HTTP on $WICK_PLUGIN_SOCKET plus the control service until the host stops it.
Types ¶
type AutoOff ¶
type AutoOff struct {
Supported bool
// Reason tells the admin why the service cannot auto-off, e.g. "polls
// the job queue in the background". Shown when Supported is false.
Reason string
// DefaultIdle is the idle limit; 0 = 15 minutes.
DefaultIdle time.Duration
}
AutoOff is a service's own say on being stopped while idle. wick counts a service idle when no request to /x/{key}/* or the remote RPC is in flight and no remote turn is open; after the idle limit it stops the process (state "sleeping") and starts it again on the next request, which waits for the boot. It is only the default: the wick admin can force auto-off on or off per service.
Set Supported only when nothing has to run without a request coming in: no background worker, poller, scheduler or outbound listener, and any state worth keeping is persisted (files, wick). Webhooks are fine, a webhook request wakes the service — but a sender with a very tight timeout (a few seconds) may time out during a cold start.
type Describer ¶
type Describer interface {
Describe() (name, detail string)
}
Describer optionally names the remote agent in the wizard.
type Env ¶
type Env struct {
// contains filtered or unexported fields
}
Env is what the host hands a running service plugin: its config (pushed over Configure, updated live) and the callback credentials.
func (*Env) Callback ¶
Callback returns wick's base URL and the plugin's scoped token. Send the token as "Authorization: Bearer <token>"; never log it. Both are empty outside wick.
func (*Env) CallbackRequest ¶
func (e *Env) CallbackRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)
CallbackRequest builds a request to wick's REST path (e.g. "/x/-/api/whoami") carrying the callback token.
type Module ¶
type Module struct {
Meta Meta
Routes []Route
Configs []entity.Config
// RemoteConfigs are per-agent fields of a RemoteSource (e.g.
// entity.StructToConfigs(RemoteConfig{})): filled per remote agent in
// the wizard and handed to Send as RemoteTurn.Config. The plugin decides
// the fallback when one is empty, usually to its own Configs.
RemoteConfigs []entity.Config
// CallbackScopes are the wick REST scopes the plugin's callback token
// may use (see Env.Callback).
CallbackScopes []string
// Register mounts the HTTP routes on mux (Go 1.22 patterns).
Register func(mux *http.ServeMux, env *Env)
// RemoteSource, when set, makes the plugin selectable as a Team remote
// agent source ("Plugin" in the Remote agent wizard).
RemoteSource RemoteSource
// AutoOff declares whether wick may stop the service while it is idle
// and wake it on the next request. The zero value never auto-offs.
AutoOff AutoOff
}
Module is one service plugin.
type RemoteCanceler ¶
RemoteCanceler is optionally implemented by a RemoteSource whose remote can stop a running turn on its own side: Cancel is called when the turn is stopped in wick. Without it a stop only ends wick's listening; the remote may keep working.
type RemoteEvent ¶
type RemoteEvent = wickplugin.RemoteEvent
RemoteTurn, RemoteEvent and RemoteSendResult are the wire types of the remote_source RPC (event schema v1).
type RemoteInjector ¶
RemoteInjector is optionally implemented by a RemoteSource whose remote takes a message while a turn still runs: Inject hands text to handle's turn, and the answer flows on that turn's Receive stream. Without it wick queues the message as the next turn.
type RemoteSendResult ¶
type RemoteSendResult = wickplugin.RemoteSendResult
RemoteTurn, RemoteEvent and RemoteSendResult are the wire types of the remote_source RPC (event schema v1).
type RemoteSessionFielder ¶
type RemoteSessionFielder interface {
SessionFields(agentCfg map[string]string) []SessionField
}
RemoteSessionFielder is optionally implemented by a RemoteSource whose new sessions take values before the first message (e.g. a repository and a branch). SessionFields gets the agent's RemoteConfigs values (agentCfg) so defaults can fall back from the agent's config to the plugin's own Configs. The answers arrive on the first RemoteTurn.Options; report the values really used on RemoteSendResult.Options.
type RemoteSource ¶
type RemoteSource interface {
Send(ctx context.Context, turn RemoteTurn) (RemoteSendResult, error)
Receive(ctx context.Context, handle string) (<-chan RemoteEvent, error)
Done(handle string)
}
RemoteSource is what a service plugin implements to act as a Team remote agent: Send a turn, Receive its events (closed after a terminal done/error event), Done to release what Send set up.
type RemoteTurn ¶
type RemoteTurn = wickplugin.RemoteTurn
RemoteTurn, RemoteEvent and RemoteSendResult are the wire types of the remote_source RPC (event schema v1).
type Route ¶
type Route = wickplugin.ServiceRoute
Route is one path prefix under /x/{key} and who may reach it.
type SessionField ¶
type SessionField = wickplugin.SessionField
RemoteTurn, RemoteEvent and RemoteSendResult are the wire types of the remote_source RPC (event schema v1).
Directories
¶
| Path | Synopsis |
|---|---|
|
Package a2aservice turns a plain reply function into an A2A agent served by a service plugin: the agent card at /.well-known/agent.json (and agent-card.json), JSON-RPC message/send and message/stream (SSE) at "/".
|
Package a2aservice turns a plain reply function into an A2A agent served by a service plugin: the agent card at /.well-known/agent.json (and agent-card.json), JSON-RPC message/send and message/stream (SSE) at "/". |