Struct InternalHookRegistry 

pub struct InternalHookRegistry { /* private fields */ }

内部钩子注册表

管理事件与处理器的映射关系。支持按事件键（type:action）或 事件类型（type）注册处理器。

线程安全

使用 RwLock 保护内部数据结构，支持多线程并发访问。

事件键格式

注册方式	事件键示例	触发条件
类型级别	agent	所有 Agent 事件
动作级别	agent:start	仅 Agent Start 事件

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
use std::sync::Arc;

let registry = InternalHookRegistry::new();

// 注册处理器
let handler: InternalHookHandlerFn = Arc::new(|event| {
    Box::pin(async move {
        println!("Event: {}", event.event_key());
        Ok(())
    })
});
registry.register("agent:start", handler);

// 查询已注册的事件键
let keys = registry.get_registered_keys();
assert!(keys.contains(&"agent:start".to_string()));

Implementations

impl InternalHookRegistry

pub fn new() -> Self

创建新的内部钩子注册表

返回值

返回一个空的注册表实例。

示例

use aster::hooks::internal::InternalHookRegistry;

let registry = InternalHookRegistry::new();
assert!(registry.get_registered_keys().is_empty());

pub fn register(&self, event_key: &str, handler: InternalHookHandlerFn)

注册处理器

将处理器注册到指定的事件键。支持两种注册方式：

• 类型级别：使用事件类型作为键（如 "agent"），匹配该类型的所有事件
• 动作级别：使用 type:action 格式（如 "agent:start"），匹配特定事件

同一事件键可以注册多个处理器，按注册顺序调用。

参数

• event_key: 事件键，可以是类型（如 "agent"）或 type:action 格式
• handler: 处理器函数

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
use std::sync::Arc;

let registry = InternalHookRegistry::new();

// 注册类型级别处理器（匹配所有 Agent 事件）
let type_handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
registry.register("agent", type_handler);

// 注册动作级别处理器（仅匹配 agent:start 事件）
let action_handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
registry.register("agent:start", action_handler);

pub fn unregister( &self, event_key: &str, handler: &InternalHookHandlerFn, ) -> bool

取消注册处理器

从指定事件键中移除处理器。使用 Arc::ptr_eq 比较处理器指针。

参数

• event_key: 事件键
• handler: 要移除的处理器

返回值

• true: 成功移除处理器
• false: 未找到匹配的处理器

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
use std::sync::Arc;

let registry = InternalHookRegistry::new();

let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
registry.register("agent:start", handler.clone());

// 取消注册
let removed = registry.unregister("agent:start", &handler);
assert!(removed);

// 再次取消注册返回 false
let removed_again = registry.unregister("agent:start", &handler);
assert!(!removed_again);

pub fn clear(&self)

清除所有处理器

移除注册表中的所有处理器和事件键。

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
use std::sync::Arc;

let registry = InternalHookRegistry::new();

let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
registry.register("agent:start", handler.clone());
registry.register("session:create", handler);

assert_eq!(registry.get_registered_keys().len(), 2);

registry.clear();
assert!(registry.get_registered_keys().is_empty());

pub fn get_registered_keys(&self) -> Vec<String>

获取已注册的事件键

返回所有已注册处理器的事件键列表。

返回值

事件键列表，顺序不保证。

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
use std::sync::Arc;

let registry = InternalHookRegistry::new();

let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
registry.register("agent:start", handler.clone());
registry.register("agent:stop", handler.clone());
registry.register("session:create", handler);

let keys = registry.get_registered_keys();
assert_eq!(keys.len(), 3);
assert!(keys.contains(&"agent:start".to_string()));
assert!(keys.contains(&"agent:stop".to_string()));
assert!(keys.contains(&"session:create".to_string()));

pub fn get_handlers(&self, event_key: &str) -> Vec<InternalHookHandlerFn>

获取指定事件键的处理器列表

返回注册到指定事件键的所有处理器的克隆列表。 此方法主要用于内部触发事件时获取处理器。

参数

• event_key: 事件键

返回值

处理器列表，如果没有注册任何处理器则返回空列表。

pub async fn trigger(&self, event: &mut InternalHookEvent) -> Result<()>

触发事件

先调用类型级别处理器（如 "agent"），再调用动作级别处理器（如 "agent:start"）。 处理器错误会被捕获并记录日志，不影响其他处理器执行。

执行顺序

1. 获取类型级别处理器（使用 event.event_type.to_string() 作为键）
2. 获取动作级别处理器（使用 event.event_key() 作为键）
3. 按注册顺序依次调用所有处理器

错误处理

• 处理器返回 Err: 记录错误日志，继续执行下一个处理器
• 处理器超时: 记录警告日志，继续执行下一个处理器

参数

• event: 可变的事件引用，处理器可以修改事件的 messages 字段

返回值

始终返回 Ok(())，处理器错误不会导致整体失败。

示例

use aster::hooks::internal::{InternalHookRegistry, InternalHookEvent, InternalHookEventType, InternalHookAction, InternalHookHandlerFn};
use std::sync::Arc;
use serde_json::json;

let registry = InternalHookRegistry::new();

// 注册类型级别处理器
let type_handler: InternalHookHandlerFn = Arc::new(|event| {
    Box::pin(async move {
        event.messages.push("Type handler called".to_string());
        Ok(())
    })
});
registry.register("agent", type_handler);

// 注册动作级别处理器
let action_handler: InternalHookHandlerFn = Arc::new(|event| {
    Box::pin(async move {
        event.messages.push("Action handler called".to_string());
        Ok(())
    })
});
registry.register("agent:start", action_handler);

// 触发事件
let mut event = InternalHookEvent::new(
    InternalHookEventType::Agent,
    InternalHookAction::Start,
    None,
    json!({}),
);

// 在异步上下文中调用
// registry.trigger(&mut event).await.unwrap();
// assert_eq!(event.messages, vec!["Type handler called", "Action handler called"]);

pub fn is_empty(&self) -> bool

检查是否有注册的处理器

返回值

• true: 注册表为空
• false: 有注册的处理器

pub fn handler_count(&self) -> usize

获取注册的处理器总数

返回值

所有事件键下注册的处理器总数。

Trait Implementations

impl Debug for InternalHookRegistry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for InternalHookRegistry

fn default() -> Self

Returns the “default value” for a type.