service

package
v1.16.0 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 15 Imported by: 0

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

Route auth modes (see wickplugin.Auth*).

Variables

This section is empty.

Functions

func BaseURL

func BaseURL(r *http.Request) string

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

func Handler(mod Module, cfg map[string]string) http.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

func (e *Env) Callback() (baseURL, token string)

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.

func (*Env) Cfg

func (e *Env) Cfg(k string) string

Cfg returns config value k as last pushed by the host.

func (*Env) Key

func (e *Env) Key() string

Key is the plugin key.

type Meta

type Meta struct {
	Key         string
	Name        string
	Description string
	Icon        string
}

Meta names the service.

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

type RemoteCanceler interface {
	Cancel(ctx context.Context, handle string) error
}

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

type RemoteInjector interface {
	Inject(ctx context.Context, handle, text string) error
}

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 "/".

Jump to

Keyboard shortcuts

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