session

Documentation

Overview

Package session provides vMCP session management types and utilities, including the AdmissionQueue used to coordinate concurrent session access.

Index

• Constants
• Variables
• type AdmissionQueue
• type MultiSession
• type MultiSessionFactory
  • func NewSessionFactory(registry vmcpauth.OutgoingAuthRegistry, opts ...MultiSessionFactoryOption) MultiSessionFactory
• type MultiSessionFactoryOption
  • func WithAggregator(agg aggregator.Aggregator) MultiSessionFactoryOption
  • func WithBackendInitTimeout(d time.Duration) MultiSessionFactoryOption
  • func WithHMACSecret(secret []byte) MultiSessionFactoryOption
  • func WithMaxBackendInitConcurrency(n int) MultiSessionFactoryOption

Constants

const (

	// MetadataKeyIdentitySubject is the transport-session metadata key that
	// holds the subject claim of the authenticated caller (identity.Subject).
	// Set at session creation; empty for anonymous callers.
	MetadataKeyIdentitySubject = "vmcp.identity.subject"

	// MetadataKeyBackendIDs is the transport-session metadata key that holds
	// a comma-separated, sorted list of successfully-connected backend IDs.
	// The key is omitted entirely when no backends connected.
	MetadataKeyBackendIDs = "vmcp.backend.ids"
)

const (
	// MetadataKeyTokenHash is the session metadata key that holds the HMAC-SHA256
	// hash of the bearer token used to create the session. For authenticated sessions
	// this is hex(HMAC-SHA256(bearerToken)). For anonymous sessions this is the empty
	// string sentinel. The raw token is never stored — only the hash.
	//
	// Re-exported from types package for convenience.
	MetadataKeyTokenHash = sessiontypes.MetadataKeyTokenHash

	// MetadataKeyTokenSalt is the session metadata key that holds the hex-encoded
	// random salt used for HMAC-SHA256 token hashing. Omitted for anonymous sessions.
	//
	// Re-exported from types package for convenience.
	MetadataKeyTokenSalt = sessiontypes.MetadataKeyTokenSalt
)

Variables

var (
	// ErrSessionClosed is returned when an operation is attempted on a closed session.
	ErrSessionClosed = errors.New("session is closed")

	// ErrToolNotFound is returned when the requested tool is not in the routing table.
	ErrToolNotFound = errors.New("tool not found in session routing table")

	// ErrResourceNotFound is returned when the requested resource is not in the routing table.
	ErrResourceNotFound = errors.New("resource not found in session routing table")

	// ErrPromptNotFound is returned when the requested prompt is not in the routing table.
	ErrPromptNotFound = errors.New("prompt not found in session routing table")

	// ErrNoBackendClient is returned when the routing table references a backend
	// that has no entry in the connections map. This indicates an internal
	// invariant violation: under normal operation MakeSession always populates
	// both maps together, so this error should never be seen at runtime.
	ErrNoBackendClient = errors.New("no client available for backend")
)

Sentinel errors returned by defaultMultiSession methods.

Types

type AdmissionQueue

type AdmissionQueue interface {
	// TryAdmit attempts to admit a request. If the queue is open, it returns
	// (true, done) where done must be called when the request completes.
	// If the queue is already closed, it returns (false, nil).
	TryAdmit() (bool, func())

	// CloseAndDrain closes the queue so that subsequent TryAdmit calls return
	// false, then blocks until all currently-admitted requests have called
	// their done function. Idempotent.
	CloseAndDrain()
}

AdmissionQueue controls admission of concurrent requests to a shared resource that can be closed. Once closed, no further requests are admitted and CloseAndDrain blocks until all previously-admitted requests complete.

type MultiSession

type MultiSession = sessiontypes.MultiSession

MultiSession is an alias for sessiontypes.MultiSession, re-exported here for backward compatibility and convenience.

type MultiSessionFactory

type MultiSessionFactory interface {
	// MakeSessionWithID creates a new MultiSession with a specific session ID.
	// This is used by SessionManager to create sessions using the SDK-assigned ID
	// rather than generating a new UUID internally.
	//
	// The id parameter must be non-empty and should be a valid MCP session ID
	// (visible ASCII characters, 0x21 to 0x7E per the MCP specification).
	//
	// The allowAnonymous parameter controls whether the session allows nil caller
	// identity. If false, all session method calls must provide a valid caller
	// that matches the session creator's identity.
	//
	// All other behaviour (partial initialisation, bounded concurrency, etc.)
	// is identical to MakeSession.
	MakeSessionWithID(
		ctx context.Context,
		id string,
		identity *auth.Identity,
		allowAnonymous bool,
		backends []*vmcp.Backend,
	) (MultiSession, error)
}

MultiSessionFactory creates new MultiSessions for connecting clients.

func NewSessionFactory

func NewSessionFactory(registry vmcpauth.OutgoingAuthRegistry, opts ...MultiSessionFactoryOption) MultiSessionFactory

NewSessionFactory creates a MultiSessionFactory that connects to backends over HTTP using the given outgoing auth registry.

type MultiSessionFactoryOption

type MultiSessionFactoryOption func(*defaultMultiSessionFactory)

MultiSessionFactoryOption configures a defaultMultiSessionFactory.

func WithAggregator

func WithAggregator(agg aggregator.Aggregator) MultiSessionFactoryOption

WithAggregator configures the factory to apply per-backend tool overrides, conflict resolution, and advertising filters when building sessions. If not set, raw backend tool names are used unchanged.

func WithBackendInitTimeout

func WithBackendInitTimeout(d time.Duration) MultiSessionFactoryOption

WithBackendInitTimeout sets the per-backend timeout during MakeSession. Defaults to 30 s.

func WithHMACSecret

func WithHMACSecret(secret []byte) MultiSessionFactoryOption

WithHMACSecret sets the server-managed secret used for HMAC-SHA256 token hashing. The secret should be 32+ bytes and loaded from secure configuration (e.g., environment variable, secret management system).

The secret is defensively copied to prevent external modification after assignment. Empty or nil secrets are rejected (function is a no-op) to prevent accidental security downgrades.

If not set, a default insecure secret is used (NOT RECOMMENDED for production).

func WithMaxBackendInitConcurrency

func WithMaxBackendInitConcurrency(n int) MultiSessionFactoryOption

WithMaxBackendInitConcurrency sets the maximum number of backends that are initialised concurrently during MakeSession. Defaults to 10.