Context 与 Service

构成 Hydro 可扩展性基础的核心插件系统类。基类来自 cordis。

import { Context, Service, Fiber, FiberState } from 'hydrooj';

Context

每个插件可访问的核心对象。提供事件订阅、服务注入、路由注册和生命周期管理功能。

Context 继承自 cordis.Context，通过 ApiMixin 服务添加了 Hydro 特有的方法。WebService 还混入了 Route、Connection 和 withHandlerClass。

路由方法

由 WebService 混入，用于注册 HTTP 和 WebSocket 处理器。

方法	说明
Route(name, path, Handler, ...permPrivChecker)	注册 HTTP 路由；绑定 name、path 和 Handler 类，可附加权限/特权守卫。
Connection(name, path, Handler, ...permPrivChecker)	注册 WebSocket 连接端点；签名与 Route 相同，但用于持久连接。

事件方法

继承自 cordis.Context。Hydro 定义了自己的 EventMap（参见 Events），包含领域相关事件。

方法	说明
on(event, callback)	订阅事件；返回一个 Disposable，调用即可移除监听器。
emit(event, ...args)	同步触发事件，通知所有已注册的监听器。
parallel(event, ...args)	触发事件并并发运行所有监听器；返回 Promise，在所有监听器完成后 resolve。
broadcast(event, ...args)	跨所有集群进程广播事件（PM2 或 MongoDB 总线）；在每个节点上调用 parallel。

生命周期与插件方法

继承自 cordis.Context，用于管理插件和副作用。

方法	说明
plugin(Plugin, config?)	在当前上下文注册并初始化插件（类或函数）；返回 Fiber。
effect(() => Disposable)	注册副作用；返回的清理函数在上下文销毁时调用。
mixin(serviceId, methods)	将服务实例上的命名方法混入上下文原型，使其可通过 ctx.method() 调用。
inject	在插件/服务类上声明服务依赖（静态 inject 数组）。

Hydro 特有方法

由 ApiMixin 添加 —— 可作为每个上下文实例的直接方法调用。

方法	说明
addScript(name, description, schema, run)	注册一个具名管理脚本，包含输入验证和异步执行函数。
provideModule(type, id, module)	注册一个可插拔模块（如 'hash'、'problemSearch'）到全局模块注册表。
injectUI(node, name, args?, ...permPrivChecker)	将 UI 组件注入到前端插槽（Nav、ProblemAdd、ControlPanel 等），可附加权限守卫。
setImmediate(callback)	在下一个事件循环 tick 调度回调；上下文销毁时自动清理。

Context 属性

属性	类型	说明
loader	Loader	管理插件生命周期和热重载的插件加载器服务。
check	CheckService	用于健康监测的检查/ping 服务。
domain	DomainDoc?	当前域文档（在域作用域的上下文中可用）。
geoip	GeoIP?	GeoIP 解析服务（可选，可能未加载）。

---

Service

所有 Hydro 服务的抽象基类。继承 cordis.Service<T, Context>。

import { Service } from 'hydrooj';

export default class MyService extends Service {
    static inject = ['database'];  // 声明依赖

    constructor(ctx: Context) {
        super(ctx, 'myService');
    }
}

服务通过 ctx.plugin(MyService) 注册，以其服务 ID 在上下文中可用。其他插件通过静态 inject 数组声明依赖。

---

类型

Fiber 和 FiberState 从 hydrooj 重新导出（源自 cordis，适配 Hydro 的 Context）。Disposable 和 Plugin 为 cordis 内部类型，供参考。

类型	说明
Fiber	cordis.Fiber<Context> —— 表示插件在上下文树中的生命周期节点；追踪状态（pending、loading、active、disposed）。
FiberState	Fiber 生命周期状态枚举：PENDING、LOADING、ACTIVE、DISPOSED 等。
Disposable	() => void —— 由 on()、effect() 等注册方法返回的清理函数（cordis 类型，需从 cordis 直接导入）。
Plugin	插件定义的类型别名 —— 可以是继承 Service 的类或 (ctx, config) => void 函数（cordis 类型，需从 cordis 直接导入）。