registry

type Address struct {
	IP   net.IP
	Port int
}

type CreateActorResult struct{}

type EnsureActivationRequest struct {
	Namespace string `json:"namespace"`
	ModuleID  string `json:"module_id"`
	ActorID   string `json:"actor_id"`

	// ExtraReplicas represents the number of additional replicas requested for an actor.
	// It specifies the desired number of replicas, in addition to the primary replica,
	// that should be created during actor activation.
	// The value of ExtraReplicas should be a non-negative integer.
	ExtraReplicas uint64 `json:"extra_replicas"`
	// BlacklistedServerIDs is set if the caller is calling the EnsureActivation method
	// after receiving an error from the server the actor is *supposed* to be activated
	// on that the server has blacklisted the actor. The server may blacklist the actor
	// temporarily due to excessive resource consumption and/or to accomplish balancing
	// requests initiated by the registry. In those scenarios, the caller will provide
	// the ID of the server that the actor was blacklisted on so the registry can keep
	// track of that information and ensure the actor is activated elsewhere / balanced
	// properly.
	BlacklistedServerIDs      []string `json:"blacklisted_server_ids"`
	CachedActivationServerIDs []string `json:"cached_activation_server_ids"`
}

type EnsureActivationResult struct {
	References       []types.ActorReference `json:"references"`
	VersionStamp     int64                  `json:"versionstamp"`
	RegistryServerID string                 `json:"registry_server_id"`
}

type HeartbeatResult struct {
	// VersionStamp associated with the successful heartbeat.
	VersionStamp int64 `json:"version_stamp"`
	// TTL of the successful heartbeat in the same unit as the
	// VerisionStamp.
	HeartbeatTTL int64 `json:"heartbeat_ttl"`
	// ServerVersion is incremented every time a server's heartbeat expires and resumes,
	// guaranteeing the server's ability to identify periods of inactivity/death for correctness purposes.
	ServerVersion int64 `json:"server_version"`
	// MemoryBytesToShed is the number of bytes of memory usage that the registry recommends
	// that the server try to shed for balancing purposes. This value will only ever be > 0
	// when the registry things that rebalancing should occur by requesting that the current
	// server shed some of its load.
	MemoryBytesToShed int64
}

type HeartbeatState struct {
	// NumActivatedActors is the number of actors currently activated on the server.
	NumActivatedActors int `json:"num_activated_actors"`
	// UsedMemory is the amount of memory currently being used by actors on the server.
	UsedMemory int `json:"used_memory"`
	// Address is the address at which the server can be reached.
	Address string `json:"address"`
}

type KVRegistryOptions struct {
	// DisableHighConflictOperations disables operations that
	// would lead to high conflict rates when using KV stores
	// like FoundationDB. In general enabling this feature will
	// not break correctness, but it may degrade the efficiency
	// of features like balancing actors across servers.
	DisableHighConflictOperations bool

	// RebalanceMemoryThreshold is the minimum delta between the memory usage of the
	// minimum and maximum servers before the registry will begin making balancing
	// decisions based on memory usage.
	RebalanceMemoryThreshold int

	// DisableMemoryRebalancing will disable rebalancing actors based on memory
	// usage if set.
	DisableMemoryRebalancing bool

	// MinSuccessiveHeartbeatsBeforeAllowActivations is the minimum number of
	// successive heartbeats the registry must receive from any serverID before
	// it will allow EnsureActivation() calls to succeed for any actor. This is
	// used to prevent a newly instantiated registry from making actor placement
	// decisions before every server has had the opportunity to heartbeat at least
	// once. Without this setting, newly intantiated registries may temporarily
	// assign all new actor activations to a small number of servers in the brief
	// window before its received a heartbeat (and thus is aware of the existence)
	// from all the servers in the cluster.
	MinSuccessiveHeartbeatsBeforeAllowActivations int

	// Logger is a logging instance used for logging messages.
	// If no logger is provided, the default logger from the slog
	// package (slog.Default()) will be used.
	Logger *slog.Logger
}

type ModuleOptions struct {
}

type ModuleStore interface {
	// RegisterModule registers the provided module []byte and options with the
	// provided module ID for subsequent calls to CreateActor().
	RegisterModule(
		ctx context.Context,
		namespace,
		moduleID string,
		moduleBytes []byte,
		opts ModuleOptions,
	) (RegisterModuleResult, error)

	// GetModule gets the bytes and options associated with the provided module.
	GetModule(
		ctx context.Context,
		namespace,
		moduleID string,
	) ([]byte, ModuleOptions, error)
}

type NoOpTransaction struct{}

type RegisterModuleResult struct{}

type Registry interface {
	// Heartbeat updates the "lastHeartbeatedAt" value for the provided server ID. Server's
	// must heartbeat regularly to be considered alive and eligible for hosting actor
	// activations.
	Heartbeat(
		ctx context.Context,
		serverID string,
		state HeartbeatState,
	) (HeartbeatResult, error)

	// EnsureActivation checks the registry to see if the provided actor is already
	// activated, and if so it returns an ActorReference that points to its activated
	// location. Otherwise, the registry will pick a location to activate the actor at
	// and then return an ActorReference that points to the newly selected location.
	//
	// Note that when this method returns it is guaranteed that a location will have
	// been selected for the actor to be activated at, but the actor may not necessarily
	// have been activated. In general, actor activation is handled "lazily" when a
	// location (server) receives its first invocation for an actor ID that it doesn't
	// currently have activated.
	EnsureActivation(
		ctx context.Context,
		req EnsureActivationRequest,
	) (EnsureActivationResult, error)

	// GetVersionStamp() returns a monotonically increasing integer that should increase
	// at a rate of ~ 1 million/s.
	GetVersionStamp(ctx context.Context) (int64, error)

	// Close closes the registry and releases any resources associated (DB connections, etc).
	Close(ctx context.Context) error

	// UnsafeWipeAll wipes the entire registry. Only used for tests. Do not call it anywhere
	// in production code.
	UnsafeWipeAll() error
}