package inbox

// inbox.go 定义 Inbox 接口.
//
// 模块定位:
//
//	Inbox 是 Agent 的"邮箱"接口抽象--每个 Agent 有自己的 Inbox,
//	其他 Agent 通过 Router 向其 Send 消息.
//
// 核心设计决策:
//
//	Send 非阻塞(丢失优于卡死):Agent 不应因接收方处理缓慢而阻塞.
//	Recv 阻塞(推送优于轮询):消费者用阻塞 Recv 等待消息,减少 CPU 空转.
//	Poll 非阻塞(紧急检查):如果消费者需要"有消息则处理,无消息则干别的".
//
//	精妙之处(CLEVER): Send/Recv/Poll 三种接收模式覆盖所有使用场景:
//	- 主循环:for { msg, err := Recv(ctx) }(阻塞等待)
//	- 超时检查:select { case msg := <-...: / case <-timer: }(见 MemoryInbox)
//	- 非侵入轮询:if msg, _ := Poll(); msg != nil(不阻塞主逻辑)
//	替代方案:只有 channel(无法统一 Close 语义,测试需要直接操作 channel).

import "context"

// Inbox 是消息收件箱接口.
// 每个 Agent 有自己的 Inbox,其他 Agent 通过 Router 向其 Send 消息.
//
// 升华改进(ELEVATED): 接口而非具体实现--
// 内存实现(MemoryInbox)用于同进程 Agent 协作;
// 未来可扩展 RedisInbox(跨进程),GRPCInbox(跨节点)而无需修改上层代码.
// 替代方案:直接暴露 MemoryInbox(绑定实现,无法测试替换).
type Inbox interface {
	// Send 向此 Inbox 投递一条消息(非阻塞).
	// 如果 Inbox 已满或已关闭,返回错误.
	Send(msg *Message) error

	// Recv 阻塞等待下一条消息,ctx 取消时返回 ctx.Err().
	// Inbox 关闭后,Recv 返回 ErrInboxClosed.
	Recv(ctx context.Context) (*Message, error)

	// Poll 非阻塞尝试获取下一条消息,无消息返回 nil, nil.
	// Inbox 关闭后,Poll 返回 nil, ErrInboxClosed.
	Poll() (*Message, error)

	// Close 关闭 Inbox,所有等待中的 Recv 返回错误.
	// Close 是幂等的,多次调用不 panic.
	Close() error
}