backend

type ChangeKind ¶ added in v0.41.0

type ChangeKind string

ChangeKind identifies which capability class a backend reported changed via ListChangedSink. Using a typed constant (rather than a bare string) means a typo is a compile error at the producer and consumer instead of a silent no-op.

const (
	// KindTools is reported when a backend emits notifications/tools/list_changed.
	KindTools ChangeKind = "tools"

	// KindResources is reported when a backend emits
	// notifications/resources/list_changed. Per MCP 2025-11-25 there is no
	// separate wire method for resource TEMPLATE changes, so this kind also
	// covers a resync of the backend's resource templates (see
	// resyncSessionResources in pkg/vmcp/server).
	KindResources ChangeKind = "resources"

	// KindPrompts is reported when a backend emits
	// notifications/prompts/list_changed.
	KindPrompts ChangeKind = "prompts"
)

type ListChangedSink ¶ added in v0.41.0

type ListChangedSink func(ctx context.Context, backendWorkloadID string, kind ChangeKind)

ListChangedSink is invoked when a persistent backend connection observes a notification this package consumes asynchronously (outside any in-flight call): notifications/tools/list_changed (kind=KindTools), notifications/resources/list_changed (kind=KindResources, which also covers resource templates — MCP 2025-11-25 has no separate wire method for those), and notifications/prompts/list_changed (kind=KindPrompts).

The sink is invoked on the mcpcompat client's receive-loop goroutine (see Client.dispatch in toolhive-core), so implementations MUST be non-blocking: they must hand the work off (e.g. set a dirty flag / signal a worker) and return immediately. A sink that does real work (network I/O, cache purges) inline stalls that backend's entire notification delivery and lets a misbehaving backend amplify one notification into unbounded work. The ctx passed here is only for the hand-off; long-lived resync work must run under a caller-owned, cancellable context, not this one.

type Session ¶

type Session interface {
	// CallTool invokes toolName on the backend.
	// arguments contains the tool input parameters.
	// meta contains protocol-level metadata (_meta) forwarded from the client.
	CallTool(
		ctx context.Context,
		toolName string,
		arguments map[string]any,
		meta map[string]any,
	) (*vmcp.ToolCallResult, error)

	// ReadResource retrieves the resource identified by uri from the backend.
	ReadResource(ctx context.Context, uri string) (*vmcp.ResourceReadResult, error)

	// GetPrompt retrieves the named prompt from the backend.
	// arguments contains the prompt input parameters.
	GetPrompt(
		ctx context.Context,
		name string,
		arguments map[string]any,
	) (*vmcp.PromptGetResult, error)

	// Close releases all resources held by this session. Implementations must
	// be idempotent: calling Close multiple times returns nil.
	Close() error

	// SessionID returns the backend-assigned session ID (if any).
	// Returns "" if the backend did not assign a session ID.
	SessionID() string
}

Session abstracts a persistent, initialised MCP connection to a single backend server. It is created once per backend during session creation and reused for the lifetime of the parent MultiSession.

Each Session is bound to exactly one backend at creation time — callers do not need to pass a routing target to individual method calls.

Caller validation happens at the MultiSession level, not here. These methods perform the actual I/O operations without authentication checks.

Implementations must be safe for concurrent use.