aiway_plugin/
lib.rs

1//! # aiway-plugin
2//!
3//! 网关插件 SDK，定义插件接口和数据交换类型。
4//!
5//! ## 架构
6//! - **插件侧**：插件开发者依赖此 crate，实现 `Plugin` trait，使用 `export_wasm!` 宏导出 WASM
7//! - **宿主侧**：`plugin-manager` crate 提供 wasmtime 运行时，加载并执行 WASM 插件
8//!
9//! ## 数据交换
10//! Host 与 WASM 之间通过 bincode 序列化传递数据，定义在 [`wasm_types`] 模块中。
11
12pub mod wasm_types;
13
14mod macros;
15mod plugin_ctx;
16mod wasm_ctx;
17
18pub use crate::plugin_ctx::{
19    FormPart, HttpRequest, HttpRequestBuilder, HttpResponse, LOG_DEBUG, LOG_ERROR, LOG_INFO,
20    LOG_TRACE, LOG_WARN, PluginContext,
21};
22use aiway_protocol::context::http::{request, response};
23pub use async_trait::async_trait;
24pub use bytes::Bytes;
25pub use http;
26pub use semver::Version;
27pub use serde_json;
28use serde_json::Value;
29pub use wasm_ctx::WasmHttpContext;
30/// 插件错误类型
31#[derive(Debug)]
32pub enum PluginError {
33    /// 执行插件业务逻辑时的错误
34    ExecuteError(String),
35    /// 插件不存在
36    NotFound(String),
37    /// 从磁盘或网络加载插件时错误
38    LoadError(String),
39    /// 序列化/反序列化错误
40    SerializeError(String),
41    /// HTTP 错误（发起HTTP调用错误）
42    HttpError(String),
43    /// 插件主动拒绝请求，携带 HTTP 状态码和消息
44    ///
45    /// 用于限流(429)、鉴权失败(403)、参数校验(400) 等场景，
46    /// 网关会透传 status 作为 HTTP 响应码返回给客户端。
47    Reject(u16, String),
48}
49
50impl std::fmt::Display for PluginError {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        match self {
53            PluginError::ExecuteError(msg) => write!(f, "{}", msg),
54            PluginError::NotFound(msg) => write!(f, "{}", msg),
55            PluginError::LoadError(msg) => write!(f, "{}", msg),
56            PluginError::SerializeError(msg) => write!(f, "{}", msg),
57            PluginError::HttpError(msg) => write!(f, "{}", msg),
58            PluginError::Reject(status, message) => write!(f, "[{}] {}", status, message),
59        }
60    }
61}
62
63/// 插件接口 trait
64///
65/// 插件开发者实现此 trait，宿主侧通过 `plugin-manager` 调用。
66/// 上下文参数使用 `&mut dyn PluginContext`，宿主侧和 WASM 侧分别有不同实现。
67#[async_trait]
68pub trait Plugin: Send + Sync {
69    /// 插件名称
70    fn name(&self) -> &str;
71    /// 插件信息
72    fn info(&self) -> PluginInfo;
73
74    /// 请求阶段，可改写头部
75    async fn on_request(
76        &self,
77        _config: &Value,
78        _head: &mut request::Parts,
79        _ctx: &mut dyn PluginContext,
80    ) -> Result<(), PluginError> {
81        Ok(())
82    }
83
84    /// 请求体阶段，可改写请求体
85    async fn on_request_body(
86        &self,
87        _config: &Value,
88        _body: &mut Option<Bytes>,
89        _ctx: &mut dyn PluginContext,
90    ) -> Result<(), PluginError> {
91        Ok(())
92    }
93
94    /// 响应阶段，可改写头部
95    async fn on_response(
96        &self,
97        _config: &Value,
98        _head: &mut response::Parts,
99        _ctx: &mut dyn PluginContext,
100    ) -> Result<(), PluginError> {
101        Ok(())
102    }
103
104    /// 响应体阶段，可改写响应体
105    async fn on_response_body(
106        &self,
107        _config: &Value,
108        _body: &mut Option<Bytes>,
109        _ctx: &mut dyn PluginContext,
110    ) -> Result<(), PluginError> {
111        Ok(())
112    }
113
114    /// 日志阶段
115    async fn on_logging(&self, _: &Value, _: &mut dyn PluginContext) {}
116}
117
118/// 插件信息
119#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
120pub struct PluginInfo {
121    /// 插件版本
122    pub version: Version,
123    /// 默认配置
124    pub default_config: Value,
125    /// 描述
126    pub description: String,
127    /// 插件使用手册
128    pub readme: Option<String>,
129}
130
131/// 简易 block_on，用于在同步上下文（WASM 内部）中执行 async 函数。
132///
133/// WASM 环境无真正异步 I/O，插件 future 必须立即返回 `Ready`。
134/// 若返回 `Pending` 说明插件误用了异步 I/O（如网络请求），直接 panic 露问题。
135pub fn block_on<F: Future>(f: F) -> F::Output {
136    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
137
138    fn noop_clone(_: *const ()) -> RawWaker {
139        RawWaker::new(std::ptr::null(), &VTABLE)
140    }
141    fn noop(_: *const ()) {}
142    static VTABLE: RawWakerVTable = RawWakerVTable::new(noop_clone, noop, noop, noop);
143
144    let raw_waker = RawWaker::new(std::ptr::null(), &VTABLE);
145    let waker = unsafe { Waker::from_raw(raw_waker) };
146    let mut cx = Context::from_waker(&waker);
147
148    let mut f = std::pin::pin!(f);
149    match f.as_mut().poll(&mut cx) {
150        Poll::Ready(val) => val,
151        Poll::Pending => panic!(
152            "plugin future returned Pending in WASM context; \
153             WASM plugins must not perform real async I/O"
154        ),
155    }
156}
aiway_plugin/lib.rs

aiway_plugin/
lib.rs
