connector

type Ctx ¶

type Ctx struct {

	// HTTP is the shared client every connector should use for outbound
	// calls. Connectors MUST build requests with
	//
	//	http.NewRequestWithContext(c.Context(), method, url, body)
	//
	// (NOT plain http.NewRequest) so the request inherits the call's
	// deadline. Without that, the MCP transport's per-call timeout
	// (sseExecuteTimeout in internal/mcp) and client-disconnect
	// cancellations cannot abort an in-flight upstream request — the
	// goroutine would leak until the upstream eventually responds on
	// its own, accumulating one such goroutine per stuck call.
	HTTP *http.Client
	// contains filtered or unexported fields
}

Ctx is the per-call handle wick passes to a connector's ExecuteFunc. It bundles the resolved per-instance credential map, the per-call input arguments from the LLM, an HTTP client, and a context.Context so the call participates in cancellation and deadlines.

Unlike tool.Ctx and job.Ctx, the values in Ctx are NOT looked up via a global config service keyed on Owner+Key. A connector instance has its own row of credential values, materialized into c.configs at dispatch time, so reads stay O(1) and don't touch the configs table.

Construction is internal to wick — modules receive a ready-made *Ctx from the MCP dispatch layer (and, later, from the panel-test handler).

func NewCtx(ctx context.Context, instanceID string, configs, input map[string]string, httpClient *http.Client, progress ProgressReporter, masker Masker) *Ctx

func (c *Ctx) Cfg(key string) string

func (c *Ctx) CfgBool(key string) bool

func (c *Ctx) CfgInt(key string) int

func (c *Ctx) Context() context.Context

func (c *Ctx) Input(key string) string

func (c *Ctx) InputBool(key string) bool

func (c *Ctx) InputInt(key string) int

func (c *Ctx) InstanceID() string

func (c *Ctx) Mask(data string, values []string) string

func (c *Ctx) MaskIgnoreCase(data string, values []string) string

func (c *Ctx) ReportProgress(progress, total int, message string)

type ExecuteFunc ¶

type ExecuteFunc func(c *Ctx) (any, error)

ExecuteFunc is the per-operation handler signature. It receives a *Ctx carrying the resolved per-instance credential map, the per-call input arguments from the LLM, and a configured *http.Client. The returned value is JSON-marshaled into the MCP tools/call result — return a typed struct or slice for a stable, ramping shape rather than the raw upstream payload.

type HealthCheckFunc ¶ added in v0.10.0

type HealthCheckFunc func(c *Ctx) ([]OpHealth, error)

HealthCheckFunc verifies that the configured credentials carry the upstream permissions every operation needs. The framework calls it from the admin UI's "Check Permissions" button. Implementations should make one cheap probe call (e.g. Slack's auth.test) and project the granted permissions against each operation's requirements.

type Masker ¶ added in v0.6.0

type Masker interface {
	Mask(data string, values []string, caseInsensitive bool) string
}

Masker is the narrow slice of the encrypted-fields service connectors use to mask dynamic sensitive values they pull from upstream APIs. The framework provides an implementation pre-bound to the calling user's per-user key; connectors never see the user UUID directly.

caseInsensitive selects between exact-match (false, default) and case-folded matching (true) — useful when a connector's keyword list should match "Admin" and "admin" alike. The token returned is derived from the keyword's configured form, so decrypt yields the configured spelling regardless of which case variant was masked.

type Meta ¶

type Meta struct {
	Key         string
	Name        string
	Description string
	Icon        string
	// Fixed marks this connector as single-instance. Wick auto-seeds one
	// row on first boot, the admin UI hides the "Add new instance"
	// button, and connectors.Repo.Create rejects a second insert with
	// ErrFixedInstanceViolation. Useful when the connector wraps a
	// single in-process resource (e.g. wickmanager) or an external
	// service that can only have one configuration.
	//
	// Default false = many instances allowed (existing behaviour).
	Fixed bool
	// DefaultTags is the list of tags wick auto-attaches to each newly
	// seeded row for this connector at boot. Tags are reused across
	// connectors via the central tags package; admins can add or remove
	// links from the admin UI without redeploy. Existing rows are
	// untouched on subsequent boots — admin unlinks survive restarts.
	//
	// Convention: every connector should set at least `tags.Connector`
	// so the home page groups it under "Connector". Add module-specific
	// tags (e.g. `tags.System` for built-in maintenance connectors) on
	// top of that.
	DefaultTags []tool.DefaultTag
}

Meta is the static metadata for a connector definition. Key must be a unique slug across every connector; entity.Connector.Key references it (one Meta.Key, many entity rows for multi-instance setups).

Description is shown to the admin in the manager UI. The LLM never sees it directly — it only reads per-operation Description fields surfaced through wick_list / wick_search.

type Module ¶

type Module struct {
	Meta        Meta
	Configs     []entity.Config
	Operations  []Operation
	HealthCheck HealthCheckFunc
	// OAuth is non-nil when this connector supports user OAuth.
	OAuth *OAuthMeta
}

Module is the internal, fully-resolved registration record wick keeps for every connector definition. It is produced by app.RegisterConnector — the Meta, the configs reflected from the typed Creds struct, and the list of operations the connector exposes. Downstream code does not construct Module directly.

HealthCheck is optional. When non-nil, the connector detail page renders a "Check Permissions" button that invokes it and toggles per-operation system_disabled flags based on the report.

OAuth is non-nil when this connector supports user OAuth. The manager UI shows an "OAuth App" section on the list page and a "Connect" button on detail pages automatically — no per-connector handler wiring needed.

type OAuthMeta ¶ added in v0.13.0

type OAuthMeta struct {
	// AuthorizeURL is the OAuth consent redirect URL
	// (e.g. https://slack.com/oauth/v2/authorize).
	AuthorizeURL string
	// Scopes is the space- or comma-separated list of requested scopes
	// (sent as the user_scope param for Slack, scope for standard OAuth2).
	Scopes string
	// DisplayName is shown on the Connect button (e.g. "Slack", "Google").
	DisplayName string
	// Icon is an SVG string or emoji rendered next to the Connect button.
	Icon string
	// GetUserIdentity exchanges a fresh access token for a unique user ID
	// and human-readable display name. Called after the code→token exchange
	// to route the token to the correct connector row.
	GetUserIdentity func(ctx context.Context, accessToken string) (userID, displayName string, err error)
}

OAuthMeta describes how a connector participates in the OAuth 2.0 flow. The generic manager handler uses AuthorizeURL and Scopes to build the consent redirect; GetUserIdentity is called after the token exchange to resolve who the token belongs to.

Set Module.OAuth to a non-nil pointer to opt in. The manager UI will render an "OAuth App" section on the connector list page and a "Connect" button on user-token rows automatically.

type OpHealth ¶ added in v0.10.0

type OpHealth struct {
	Key    string
	OK     bool
	Reason string
}

OpHealth is one entry in the report returned by Module.HealthCheck. OK=true means the configured credential has every upstream permission the operation needs; OK=false means the op should be system-disabled and Reason explains what is missing (e.g. "needs scope: chat:write").

HealthCheck implementations should return one OpHealth per operation the module exposes that can be permission-checked; ops omitted from the report are left untouched (neither system-disabled nor cleared).

type Operation ¶

type Operation struct {
	Key         string
	Name        string
	Description string
	Input       []entity.Config
	Execute     ExecuteFunc
	Destructive bool
	// Docs carries the opt-in self-documentation fields the workflow
	// MCP `workflow_node_detail` op surfaces to AI clients (examples,
	// quirks, templateable fields, pair-with, common pitfalls).
	// Zero-value Docs = current behaviour; populate per op when worth
	// it. See pkg/wickdocs + internal/docs/workflow/24-describe-contract.md.
	wickdocs.Docs
}

Operation is one named action exposed by a connector definition. A single connector can carry many operations: a "github" connector might have list_repos, create_issue, list_issues, add_comment.

Description is the load-bearing field for the LLM — it is shown verbatim in the wick_list / wick_search payload and is the primary signal the model uses to decide whether to call this op. Use action verbs and be specific ("List repositories visible to the authenticated user", not "list").

Destructive marks operations that mutate state in a way that is hard or impossible to undo (delete, force-push, send message, post comment). Wick uses this hint to default the per-instance toggle to off so admins must explicitly opt in, and to surface a warning chip in the admin UI.

func Op[I any](key, name, description string, input I, exec ExecuteFunc, docs wickdocs.Docs) Operation

connector.Op("query", "Query Logs",
    "Search Loki using LogQL.",
    QueryInput{}, queryExec, wickdocs.Docs{})

func OpDestructive[I any](key, name, description string, input I, exec ExecuteFunc, docs wickdocs.Docs) Operation

type ProgressReporter ¶

type ProgressReporter interface {
	Report(progress, total int, message string)
}

ProgressReporter receives incremental progress events emitted by a connector during a long-running call. The MCP layer wires an implementation that pushes JSON-RPC notifications/progress frames over the active SSE response; the JSON transport supplies no reporter and ReportProgress becomes a no-op.

Report MUST NOT block the caller — implementations drop events when the client is slow or has disconnected rather than back-pressuring the connector that emits them.