cherryFacade

type ActorPath struct {
	NodeID  string
	ActorID string
	ChildID string
}

type Component struct {
	// contains filtered or unexported fields
}

type IActor interface {
	App() IApplication                                          // the owning Application
	ActorID() string                                            // unique ID within the node
	Path() *ActorPath                                           // parsed "nodeID.actorID" path
	Call(targetPath, funcName string, arg any) int32            // async RPC to another Actor, returns cherryCode status code
	CallWait(targetPath, funcName string, arg, reply any) int32 // sync RPC with reply, returns cherryCode status code
	CallType(nodeType, actorID, funcName string, arg any) int32 // call a random Actor of the given node type, returns cherryCode status code
	PostRemote(m *Message)                                      // fire-and-forget to a remote Actor
	PostLocal(m *Message)                                       // fire-and-forget to a local Actor
	LastAt() int64                                              // last activity timestamp in ms, updated on each message
	Exit()                                                      // stop this Actor; cannot be restarted
}

type IActorChild interface {
	Create(id string, handler IActorHandler) (IActor, error) // create a child Actor on the parent's goroutine
	Get(id string) (IActor, bool)                            // get a child by ID; nil, false if not found
	Remove(id string)                                        // remove and stop a child Actor
	Each(fn func(i IActor))                                  // iterate all children (the callback must not mutate the child set)
	Call(childID, funcName string, arg any)                  // call a handler on a child Actor, returns cherryCode status code
	CallWait(childID, funcName string, arg, reply any) int32 // call a handler on a child and wait for reply, returns cherryCode status code
}

type IActorHandler interface {
	AliasID() string                          // the ID string this Actor is registered under
	OnInit()                                  // called once before the message loop starts; register handlers here
	OnStop()                                  // called once before the goroutine exits; release resources here
	OnLocalReceived(m *Message) (bool, bool)  // returns (handled, needRecycle) — handled=true means the message was processed; needRecycle=true means caller should Recycle the message
	OnRemoteReceived(m *Message) (bool, bool) // returns (handled, needRecycle) — handled=true means the message was processed; needRecycle=true means caller should Recycle the message
	OnFindChild(m *Message) (IActor, bool)    // resolve a child Actor from the message's Target path; returns the child and true if found
}

type IActorSystem interface {
	GetIActor(id string) (IActor, bool)                             // lookup an Actor by ID; nil, false if not found
	CreateActor(id string, handler IActorHandler) (IActor, error)   // create and start a new Actor
	PostRemote(m *Message) bool                                     // fire-and-forget to a remote Actor; returns false if delivery rejected
	PostLocal(m *Message) bool                                      // fire-and-forget to a local Actor; returns false if Actor not found
	PostEvent(data IEventData)                                      // broadcast an event to all subscribers matching data.Name()
	Call(source, target, funcName string, arg any) int32            // async RPC to target actor, returns cherryCode status code
	CallWait(source, target, funcName string, arg, reply any) int32 // sync RPC to target actor with reply, returns cherryCode status code
	CallType(nodeType, actorID, funcName string, arg any) int32     // call a random Actor of the given node type, returns cherryCode status code
	SetLocalInvoke(invoke InvokeFunc)                               // set the low-level dispatch hook for local messages
	SetRemoteInvoke(invoke InvokeFunc)                              // set the low-level dispatch hook for remote messages
	SetCallTimeout(d time.Duration)                                 // set RPC call timeout (default 3s)
	SetArrivalTimeout(t int64)                                      // set message arrival timeout in ms (default 100ms)
	SetExecutionTimeout(t int64)                                    // set handler execution timeout in ms (default 100ms)
}

type IApplication interface {
	INode
	Running() bool                     // whether the application is running
	DieChan() chan bool                // closed when application shuts down
	IsFrontend() bool                  // whether this is a frontend node
	Register(components ...IComponent) // register components (before startup)
	Find(name string) IComponent       // find a component by name
	Remove(name string) IComponent     // remove a component by name
	All() []IComponent                 // list all registered components
	OnShutdown(fn ...func())           // register shutdown hooks (called in registration order)
	Startup()                          // start the application (blocks until shutdown)
	Shutdown()                         // shut down the application
	Serializer() ISerializer           // message serializer
	Discovery() IDiscovery             // node discovery service
	Cluster() ICluster                 // cluster messaging service
	ActorSystem() IActorSystem         // Actor system
}

type ICluster interface {
	Mode() string // cluster transport mode (e.g. "nats")

	// PublishLocal delivers a message to an actor on the local node.
	// The message is NOT serialized — it is passed in-process.
	PublishLocal(nodeID string, msg *Message) error

	// PublishRemote delivers a message to an actor on a remote node.
	// The message is serialized and sent over the cluster transport.
	PublishRemote(nodeID string, msg *Message) error

	// PublishRemoteType delivers a message to a random actor of the given node type.
	// Useful for load-balanced fan-out across a pool of workers.
	PublishRemoteType(nodeType string, msg *Message) error

	// RequestRemote sends a message to a remote actor and blocks until a response
	// is received or the optional timeout expires. Returns the response payload
	// and an error code. If no timeout is specified, a default is used.
	RequestRemote(nodeID string, msg *Message, timeout ...time.Duration) ([]byte, int32)
}

type IClusterComponent interface {
	IComponent
	ICluster
}

type IComponent interface {
	Name() string      // unique name within the Application
	App() IApplication // the owning Application
	IComponentLifecycle
}

type IComponentLifecycle interface {
	Set(app IApplication) // receive the owning Application reference
	Init()                // initialise internal state
	OnAfterInit()         // called after ALL components have been Init'd
	OnBeforeStop()        // called before shutdown begins
	OnStop()              // release resources
}

type IConnector interface {
	IComponent
	Start()                     // begin accepting connections
	Stop()                      // stop the listener and drain pending connections
	OnConnect(fn OnConnectFunc) // register a callback invoked for each new connection
}

type IDiscovery interface {
	Mode() string                                                 // discovery mode name (e.g. "default", "nats", "etcd")
	Map() map[string]IMember                                      // snapshot of all known members keyed by nodeID
	ListByType(nodeType string, filterNodeID ...string) []IMember // members of a given node type, excluding filterNodeID
	Random(nodeType string) (IMember, bool)                       // random member of the given node type; nil, false if none exist
	GetMember(nodeID string) (member IMember, found bool)         // lookup a member by nodeID; nil, false if not found
	UpdateSetting(key, value string)                              // update a single setting on THIS node and sync to other nodes
	UpdateSettings(settings map[string]string)                    // update multiple settings on THIS node and sync to other nodes
	OnAddMember(listener MemberListener)                          // register callback invoked after a member is added
	OnUpdateMember(listener MemberListener)                       // register callback invoked after a member is updated
	OnRemoveMember(listener MemberListener)                       // register callback invoked after a member is removed
}

type IDiscoveryComponent interface {
	IComponent
	IDiscovery
}

type IEventData interface {
	Name() string    // event name used for subscription matching
	UniqueID() int64 // unique ID for deduplication — two events with the same ID are the same occurrence
}

type IMember interface {
	GetNodeID() string              // unique node identifier
	GetNodeType() string            // node type (e.g. "game", "gate", "map")
	GetAddress() string             // RPC address for cross-node communication
	GetSettings() map[string]string // arbitrary key-value metadata for this node
}

type INetParser interface {
	Load(application IApplication)     // register protocol-specific agent Actors
	AddConnector(connector IConnector) // attach a network connector to this parser
	Connectors() []IConnector          // return all attached connectors
}

type INode interface {
	NodeID() string        // globally unique node ID
	NodeType() string      // node type (e.g. "game", "gate", "map")
	Address() string       // public listen address (for frontend nodes)
	RpcAddress() string    // RPC listen address (reserved)
	Settings() ProfileJSON // node settings from profile
	Enabled() bool         // whether this node is enabled
}

type ISerializer interface {
	Marshal(v interface{}) ([]byte, error)      // encode a value into bytes
	Unmarshal(data []byte, v interface{}) error // decode bytes into a value
	Name() string                               // codec name (e.g. "json", "protobuf")
}

type InvokeFunc func(app IApplication, fi *creflect.FuncInfo, m *Message)

type MemberListener func(member IMember)

type Message struct {
	BuildTime int64       // message build time(ms)
	Source    string      // source actor path
	Target    string      // target actor path (node.actor or node.actor.child)
	FuncName  string      // target function name
	Args      interface{} // payload: same-node=decoded object, cross-node=[]byte (pending decode)

	// --- Local only (client->Actor, set by parser) ---
	Session *cproto.Session // client session

	// --- Remote only (Actor->Actor, set by System.Call/CallWait/CallType) ---
	ReqID      string           // NATS request ID (cross-node request-reply)
	Reply      string           // NATS reply subject (non-empty if from cross-node)
	ChanResult chan interface{} // same-node CallWait sync channel
	// contains filtered or unexported fields
}

type OnConnectFunc func(conn net.Conn)

type ProfileJSON interface {
	jsoniter.Any
	GetConfig(path ...any) ProfileJSON
	GetString(path any, defaultVal ...string) string
	GetBool(path any, defaultVal ...bool) bool
	GetInt(path any, defaultVal ...int) int
	GetInt32(path any, defaultVal ...int32) int32
	GetInt64(path any, defaultVal ...int64) int64
	GetUint(path any, defaultVal ...uint) uint
	GetUint32(path any, defaultVal ...uint32) uint32
	GetUint64(path any, defaultVal ...uint64) uint64
	GetFloat32(path any, defaultVal ...float32) float32
	GetFloat64(path any, defaultVal ...float64) float64
	GetDuration(path any, defaultVal ...time.Duration) time.Duration
	Unmarshal(ptrVal any) error
}

type SID = string // session unique id

type UID = int64 // user unique id