session

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()
}

type Decorator func(ctx context.Context, sess MultiSession) (MultiSession, error)

type MultiSession = sessiontypes.MultiSession

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).
	//
	// Whether the session allows anonymous (nil) caller identity is derived
	// internally from identity via ShouldAllowAnonymous.
	//
	// All other behaviour (partial initialisation, bounded concurrency, etc.)
	// is identical to MakeSession.
	MakeSessionWithID(
		ctx context.Context,
		id string,
		identity *auth.Identity,
		backends []*vmcp.Backend,
	) (MultiSession, error)

	// RestoreSession reconstructs a live MultiSession from persisted metadata.
	// It reconnects to the backends whose IDs are listed in storedMetadata under
	// MetadataKeyBackendIDs, rebuilds the routing table, and reapplies the
	// session-binding decorator from the stored identity binding.
	//
	// Use this when the node-local session cache misses — for example after a
	// pod restart or when a request is routed to a different pod. It is more
	// expensive than a cache hit because it opens new backend connections.
	// Because MCP clients cannot be serialised, sticky sessions (session affinity
	// at the load balancer) minimise how often this path is taken.
	//
	// allBackends is the current backend list from the registry; RestoreSession
	// filters it to the subset originally included in this session.
	RestoreSession(
		ctx context.Context,
		id string,
		storedMetadata map[string]string,
		allBackends []*vmcp.Backend,
	) (MultiSession, error)
}

type MultiSessionFactoryOption func(*defaultMultiSessionFactory)