package edge

// GenInfo is what the edge needs to know about an instance's CURRENT
// generation (zero-downtime spec §7.1, §7.2): the socket that takes new
// connections, the process-wide generation number the cache tags entries
// with, and the build X-Carlos-Version reports.
type GenInfo struct {
	Socket string
	N      uint64
	Build  string
}

// GenSource is the activator's generation view, as the edge sees it. It is
// declared here for the reason Activator is: internal/activator imports
// this package, never the reverse. *activator.Service implements it.
//
// The edge uses it only when GenerationsOn reports true. With it false
// (CARLOS_SWAP unset, the default) every path below is skipped and the edge
// proxies, caches and stamps versions exactly as before.
type GenSource interface {
	// GenerationsOn is the activator's dormant switch, read once when the
	// activator was built.
	GenerationsOn() bool
	// AppSocket names the current generation's socket for traffic. False
	// when the instance has no current generation (asleep, or waking).
	AppSocket(host string) (socket string, ok bool)
	// ServingGen is AppSocket with the generation's number and build.
	ServingGen(host string) (GenInfo, bool)
	// CacheGen is the newest generation that has been current for host in
	// this process, kept after the instance sleeps so a sleeping instance's
	// cached pages still answer. False when no generation of host has ever
	// been current here. It must not take any lock the activator holds
	// while calling into the cache.
	CacheGen(host string) (uint64, bool)
	// OnGenRetired registers fn to be called, synchronously and outside
	// every activator lock, each time a generation stops being current.
	// fn must not block.
	OnGenRetired(fn func(host, socket string))
}