core

type CID uint64

type CidGenerator interface {
	Generate() CID
}

type Component interface {
	// GetCid 获取组件唯一 ID
	GetCid() CID
	// Bind 与引擎进行绑定
	// 在被引擎接收时调用
	Bind(CID, Global)
	// Prepare 准备
	// 在引擎处于 Preparing 状态时执行
	Prepare(Config)
	// OnEnable 启用组件时激活
	// 组件被启用时调用
	OnEnable()
	// OnDisable 禁用组件时激活
	// 组件被禁用时调用
	OnDisable()
	// Destroy 销毁组件
	// 在组件被废弃时调用，将会销毁该组件的对象
	Destroy()
}

type ComponentPool []Component

type Config interface {
	// IsMap 判别该配置对象是否是一个 ConfigMap
	IsMap() bool
	// IsArray 判别该配置对象是否是一个 ConfigArray
	IsArray() bool
	// IsItem 判别该配置对象是否是一个 ConfigItem
	IsItem() bool

	// LockState 获取锁状态
	LockState() LockLevel
	// IsLock 判别该配置对象是否被加锁
	IsLock() bool
	// IsUnlock 判别该配置对象是否无锁
	IsUnlock() bool
	// CanRead 判断是否可读
	CanRead(LockRef) bool
	// CanWrite 判断是否可写
	CanWrite(LockRef) bool
	// Lock 加锁
	Lock(LockLevel) LockRef
	// Unlock 解锁
	Unlock(LockRef)
	// ChangeLockLevel 变更锁等级
	ChangeLockLevel(LockRef, LockLevel)

	// ToConfigMap 返回该配置对象的 ConfigMap 类型的引用
	ToConfigMap() ConfigMap
	// ToConfigArray  返回该配置对象的 ConfigArray 类型的引用
	ToConfigArray() ConfigArray
	// ToConfigItem  返回该配置对象的 ConfigItem 类型的引用
	ToConfigItem() ConfigItem

	// GetPath 获取从根配置项到当前配置项的路径
	GetPath() ConfigPath
}

type ConfigArray interface {
	Config
	ConfigGroup

	// Get 根据 Index 获取对应的 Config 对象
	Get(int) Config
	// Items 获取该对象下的所有子配置
	Items() []Config
}

type ConfigChanger int

type ConfigGroup interface {
	// GetItem 获取配置项
	GetItem(ConfigPath) ConfigItem
	// GetSubConfig 获取子配置对象
	GetSubConfig(ConfigPath) ConfigGroup
}

type ConfigItem interface {
	// GetName 获取当前配置项的名称
	GetName() string
	// GetValue 获取该配置项的值
	GetValue() interface{}
	// GetType 获取配置项的值的类型
	GetType() reflect.Type
	// GetStr 获取字符串类型的配置项的值
	GetStr() string
	// GetInt 获取整型类型的配置项的值
	GetInt() int
	// GetInt64 获取 64 位整型类型的配置项的值
	GetInt64() int64
	// GetBool 获取布尔类型的配置项的值
	GetBool() bool
	// GetBytes 获取字节数组类型的配置项的值
	GetBytes() []byte
	// Unmarshal 解组
	// 将该配置项解组到指定的对象
	Unmarshal(interface{}) error
}

type ConfigMap interface {
	Config
	ConfigGroup

	// Get 根据 Key 获取对应的 Config 对象
	Get(string) Config
	// GetByPoint 根据注册点获取对应的 Config 对象
	GetByPoint(ConfigRegisterPoint) Config
	// Items 获取该对象下的所有子配置
	Items() map[string]Config
}

type ConfigPath interface {
	// Backward 回退路径
	Backward(int) ConfigPath
	// Append 在该路径后面追加路径
	Append(...interface{}) ConfigPath
	// AppendByKey 在该路径后面追加一个 Key 寻址路径
	AppendByKey(...string) ConfigPath
	// AppendByIndex 在该路径后面追加一个索引寻址路径
	AppendByIndex(...int) ConfigPath
	// AppendByPath 将指定的路径对象的内容全部追加到该路径后面
	AppendByPath(...ConfigPath) ConfigPath
	// AppendByExpr 将一个路径表达式追加到该路径后面
	AppendByExpr(...string) ConfigPath
	// ToExpr 将该对象转换为路径表达式
	ToExpr() string
	// String 将该对象转换为字符串
	// 该方法应该被重写，并且返回结果应该与 ToExpr() 一致
	String() string
}

type ConfigRegisterPoint RegisterPoint

type ConfigWriter interface {
	ConfigItem

	Set(interface{}) error
}

type Content interface {
	// GetType 获取内容类型
	GetType() ContentType
	// Bytes 返回内容的 Byte 数组表现形式
	Bytes() []byte
}

type ContentScheduler interface {
	Scheduler

	// SelectSuitableOutput 选择合适的输出类型
	SelectSuitableOutput(Content, Content, Subject) ContentType
}

type ContentType int

type DialogueListener interface {
	Listener

	// OnReceive 接收对话时执行
	OnReceive()
	// OnBeforeAnswer 回答之前执行
	OnBeforeAnswer()
}

type Engine interface {
	// State 获取引擎的状态
	State() EngineState
	// Global 获取全局唯一共享对象
	Global() Global
	// Init 引擎初始化函数
	// 同步
	// 该方法仅允许引擎处于 Uninitialized 状态时调用
	// 该方法被调用后，引擎会立即进入 Configuring 状态
	// 该方法执行失败时，引擎将进入 Error 状态，且通过 panic 抛出异常
	Init(Global, CidGenerator, ComponentPool)
	// Prepare 准备
	// 异步
	// 该方法仅允许引擎处于 Configuring 状态时调用
	// 该方法执行过程中，引擎将进入 Preparing 状态
	// 该方法执行失败时，若发生了严重异常，引擎将进入 Error 状态；若发生了其他异常，引擎将回到 Configuring 状态
	// 该方法执行完成后，引擎将进入 Ready 状态
	Prepare() error
	// Run 运行
	// 异步
	// 该方法仅允许引擎处于 Ready 状态时调用
	// 该方法执行过程中，引擎将进入 Running 状态
	// 该方法执行失败时，若发生了严重异常，引擎将进入 Error 状态；若发生了其他异常，引擎将进入 Ready 状态
	// 该方法会持续执行，直到调用了 Stop() 方法
	Run()
	// Stop 暂停
	// 异步
	// 该方法仅允许引擎处于 Running 状态时调用
	// 该方法执行过程中，引擎将进入 Stopping 状态
	// 该方法执行失败时，引擎将进入 Error 状态
	// 该方法执行完成后，引擎将进入 Ready 状态
	Stop()
	// Destroy 销毁
	// 异步
	// 该方法仅允许引擎处于 Configuring 或 Ready 状态时调用
	// 该方法执行过程中，引擎将进入 Destroying 状态
	// 该方法执行失败时，引擎将进入 Error 状态
	// 该方法执行完成后，引擎将进入 Destroyed 状态
	Destroy()
	// Error 获取引擎发生的异常
	Error() error
}

type EngineState uint

type ErrorManager interface {
	// Error 接收错误
	Error(error)
}

type Event struct {
}

type Global interface {
	// Debug 是否启用调试模式
	Debug() bool
	// RootConfig 根配置
	RootConfig() ConfigMap
	// ErrorManager 异常管理器
	ErrorManager() ErrorManager
}

type HandleScheduler interface {
	ManagedScheduler

	// Import 导出处理器
	// 优先于 Prepare 之前执行
	Import(...Handler)
	// SelectSuitable 选择合适的处理器
	// 参数
	// Content: 请求的内容
	// Subject: 请求的主体
	// TransformFunction: 内容转换函数
	// 返回值
	// Handler: 合适的处理器
	// ContentType: 合适的内容类型，用于调用处理器
	SelectSuitable(Content, Subject, TransformFunction) (Handler, ContentType)
}

type Handler interface {
	// Component 声明处理器为一个组件
	Component
	// ManyInputLimit 允许多种输入类型
	ManyInputLimit
	// SingleOutputLimit 仅允许一种输出类型
	SingleOutputLimit

	// Active 是否激活
	Active(Content, Subject) bool
	// Handle 处理函数
	Handle(Content, Subject) (Content, error)
}

type HandlerGroup interface {
	// Handler HandlerGroup 也是一个 Handler
	Handler

	// Add 添加一个 Handler 到该组中
	Add(Handler)
	// Remove 移除一个 Handler
	Remove(CID)
}

type Listener interface {
	// Component 声明监听器为一个组件
	Component

	// OnMount 挂载时执行
	OnMount()
	// OnUnmount 卸载时执行
	OnUnmount()
}

type LockLevel uint

type LockRef uint64

type ManagedScheduler interface {
	// Scheduler 声明托管式调度器为一个调度器
	Scheduler

	// Enable 启用指定的组件
	Enable(CID)
	// Disable 禁用指定的组件
	Disable(CID)
}

type ManyInputLimit interface {
	// InputLimit 输入限定类型
	InputLimit() []ContentType
}

type ManyOutputLimit interface {
	// OutputLimit 输出限定类型
	OutputLimit() []ContentType
}

type PioneerError interface {
	Error() string
}

type Poller interface {
	// Receiver 继承接收器接口
	Receiver

	// HasNext 是否存在下一项输入内容
	HasNext() bool
	// Next 获取下一项输入内容
	Next() (Content, Subject, error)
}

type PollerFactory interface {
	// CreatePoller 构建轮询器
	CreatePoller() (Poller, error)
}

type ProcessManager interface {
	// Process 处理消息
	Process(Content) (Content, error)
}

type PushScheduler interface {
	ManagedScheduler

	// Import 导出推送器
	// 优先于 Prepare 之前执行
	Import(...Pusher)
	// SelectSuitable 选择合适的推送器
	// Content: 请求的内容
	// Subject: 请求的主体
	// ContentType: 要求的响应内容类型（返回的 Pusher 的输入类型必须可以接受该类型）
	// TransformFunction: 内容转换函数
	SelectSuitable(Content, Subject, ContentType, TransformFunction) Pusher
}

type Pusher interface {
	// Sender 继承发送器接口
	Sender

	// Push 将指定的内容发送给用户
	Push(Content, Subject) error
}

type PusherFactory interface {
	// CreatePusher 构建推送器
	CreatePusher() (Pusher, error)
}

type Receiver interface {
	// Component 声明接收器为一个组件
	Component
	// ManyOutputLimit 允许接收器接收多种类型的输入
	// 接收器的输出等同于整个引擎的输入
	ManyOutputLimit
}

type RegisterPoint string

type Scheduler interface {
	// Component 声明调度器为一个组件
	Component
}

type Sender interface {
	// Component 声明发送器为一个组件
	Component
	// ManyInputLimit 允许发送器发送多种类型的输出
	// 发送器的输入等同于整个引擎的输出
	ManyInputLimit
}

type SeriousError interface {
	PioneerError
}

type Server interface {
	// Receiver 继承接收器接口
	Receiver
	// Sender 继承发送器接口
	Sender

	// OnStart 开始服务
	OnStart()
	// OnStop 暂停服务
	OnStop()
}

type ServiceError interface {
	PioneerError
}

type SessionListener interface {
	Listener

	// OnCreateSession 创建会话时执行
	OnCreateSession(sessionID string)
	// OnDestroySession 销毁会话时执行
	OnDestroySession(sessionID string)
}

type SingleInputLimit interface {
	// InputLimit 输入限定类型
	InputLimit() ContentType
}

type SingleOutputLimit interface {
	// OutputLimit 输出限定类型
	OutputLimit() ContentType
}

type Subject interface {
	// Get 获取主体值
	Get(SubjectMark) string
	// Set 设置主体值
	Set(SubjectMark, string) string
}

type SubjectMark int64

type TextContent interface {
	// Content 继承 Content 接口
	Content

	// GetText 获取文本内容
	GetText() string
	// GetCharset 获取该文本的字符编码
	GetCharset() string
}

type TransformFunction func(Content, ContentType) Content

type TransformScheduler interface {
	ManagedScheduler

	// Import 导出转换器
	// 优先于 Prepare 之前执行
	Import(...Transformer)
	// SelectSuitable 选择合适的转换器
	// src : 输入的内容类型
	// dst : 输出的内容类型
	SelectSuitable(src ContentType, dst ContentType) Transformer
}

type Transformer interface {
	// Component 声明变换器为一个组件
	Component
	// SingleInputLimit 仅允许一种输入类型
	SingleInputLimit
	// SingleOutputLimit 仅允许一种输出类型
	SingleOutputLimit

	// Transform 转换
	Transform(original Content) Content
}

type Version [3]uint8