Skip to content

Commit 98191e0

Browse files
luoluoyuyuluoluoyuyu
committed
update docs
1 parent 077bc8b commit 98191e0

2 files changed

Lines changed: 67 additions & 67 deletions

File tree

‎docs/go-sdk-guide-zh.md‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@ Function Stream 为 Go 开发者提供基于 WebAssembly（WASI P2）的算子
2727

2828
## 一、SDK 核心组件
2929

30-
| 组件 | 定位 | 说明 |
31-
|------|------|------|
32-
| **fssdk** | 主包 | 对外入口，提供 `Driver`、`Context`、`Store` 等类型及 `Run(driver)`。 |
33-
| **api** | 接口定义 | 定义 `Driver`、`Context`、`Store`、`Iterator`、`ComplexKey` 及错误码。 |
34-
| **impl** | 运行时实现 | 将 Driver 与 WASM 宿主（processor WIT）桥接，内部使用。 |
30+
| 组件 | 定位 | 说明 |
31+
|--------------|--------|--------------------------------------------------------------|
32+
| **fssdk** | 主包 | 对外入口，提供 `Driver`、`Context`、`Store` 等类型及 `Run(driver)`。 |
33+
| **api** | 接口定义 | 定义 `Driver`、`Context`、`Store`、`Iterator`、`ComplexKey` 及错误码。 |
34+
| **impl** | 运行时实现 | 将 Driver 与 WASM 宿主（processor WIT）桥接，内部使用。 |
3535
| **bindings** | WIT 绑定 | 由 wit-bindgen-go 根据 `wit/processor.wit` 生成的 Go 绑定，供 impl 调用。 |
3636

3737
Go 算子**仅依赖 fssdk**：实现 `Driver`（或嵌入 `BaseDriver`），在 `init()` 中调用 `fssdk.Run(&YourProcessor{})` 即可。
@@ -44,16 +44,16 @@ Go 算子**仅依赖 fssdk**：实现 `Driver`（或嵌入 `BaseDriver`），在
4444

4545
所有 Go 算子必须实现 `fssdk.Driver` 接口。运行时在对应时机调用以下方法：
4646

47-
| 方法 | 触发时机 | 说明 |
48-
|------|----------|------|
49-
| `Init(ctx, config)` | 函数启动时执行一次 | 初始化状态、获取 Store、解析 config。 |
50-
| `Process(ctx, sourceID, data)` | 每收到一条消息时 | 核心处理逻辑：计算、状态读写、`ctx.Emit()`。 |
51-
| `ProcessWatermark(ctx, sourceID, watermark)` | 收到水位线事件时 | 处理基于时间的窗口或乱序重排，可转发 `EmitWatermark`。 |
52-
| `TakeCheckpoint(ctx, checkpointID)` | 系统做状态备份时 | 可持久化额外内存状态，保证强一致性。 |
53-
| `CheckHeartbeat(ctx)` | 定期健康检查 | 返回 `false` 会触发算子重启。 |
54-
| `Close(ctx)` | 函数关闭时 | 释放资源、清空引用。 |
55-
| `Exec(ctx, className, modules)` | 扩展能力（可选） | 动态加载模块等，默认可不实现。 |
56-
| `Custom(ctx, payload)` | 自定义 RPC（可选） | 请求/响应自定义字节，默认返回 payload 副本。 |
47+
| 方法 | 触发时机 | 说明 |
48+
|----------------------------------------------|-------------|-------------------------------------|
49+
| `Init(ctx, config)` | 函数启动时执行一次 | 初始化状态、获取 Store、解析 config。 |
50+
| `Process(ctx, sourceID, data)` | 每收到一条消息时 | 核心处理逻辑：计算、状态读写、`ctx.Emit()`。 |
51+
| `ProcessWatermark(ctx, sourceID, watermark)` | 收到水位线事件时 | 处理基于时间的窗口或乱序重排，可转发 `EmitWatermark`。 |
52+
| `TakeCheckpoint(ctx, checkpointID)` | 系统做状态备份时 | 可持久化额外内存状态，保证强一致性。 |
53+
| `CheckHeartbeat(ctx)` | 定期健康检查 | 返回 `false` 会触发算子重启。 |
54+
| `Close(ctx)` | 函数关闭时 | 释放资源、清空引用。 |
55+
| `Exec(ctx, className, modules)` | 扩展能力（可选） | 动态加载模块等，默认可不实现。 |
56+
| `Custom(ctx, payload)` | 自定义 RPC（可选） | 请求/响应自定义字节，默认返回 payload 副本。 |
5757

5858
### 2.2 BaseDriver
5959

@@ -98,13 +98,13 @@ func init() {
9898

9999
`fssdk.Context` 在 Init / Process / ProcessWatermark 等回调中传入，提供：
100100

101-
| 方法 | 说明 |
102-
|------|------|
103-
| `Emit(targetID uint32, data []byte) error` | 将数据发往指定输出通道。 |
104-
| `EmitWatermark(targetID uint32, watermark uint64) error` | 发射水位线。 |
105-
| `GetOrCreateStore(name string) (Store, error)` | 按名称获取或创建 KV Store（基于 RocksDB）。 |
106-
| `Config() map[string]string` | 获取启动时下发的配置（对应 config.yaml 中的 init 等）。 |
107-
| `Close() error` | 关闭 Context，一般由运行时管理。 |
101+
| 方法 | 说明 |
102+
|----------------------------------------------------------|---------------------------------------|
103+
| `Emit(targetID uint32, data []byte) error` | 将数据发往指定输出通道。 |
104+
| `EmitWatermark(targetID uint32, watermark uint64) error` | 发射水位线。 |
105+
| `GetOrCreateStore(name string) (Store, error)` | 按名称获取或创建 KV Store（基于 RocksDB）。 |
106+
| `Config() map[string]string` | 获取启动时下发的配置（对应 config.yaml 中的 init 等）。 |
107+
| `Close() error` | 关闭 Context，一般由运行时管理。 |
108108

109109
### 3.2 Store（KV 状态）
110110

@@ -271,16 +271,16 @@ config.yaml 中需配置 `name`、`type: processor`、`input-groups`、`outputs`
271271

272272
SDK 通过 `fssdk.SDKError` 返回错误，可用 `errors.As` 获取 `Code`：
273273

274-
| 错误码 | 含义 |
275-
|--------|------|
276-
| `ErrRuntimeInvalidDriver` | 传入的 Driver 无效。 |
277-
| `ErrRuntimeNotInitialized` | 运行时未初始化即调用。 |
278-
| `ErrRuntimeClosed` | 运行时已关闭。 |
279-
| `ErrStoreInvalidName` | Store 名称不合法。 |
280-
| `ErrStoreInternal` | Store 内部错误。 |
281-
| `ErrStoreNotFound` | 未找到指定 Store。 |
282-
| `ErrStoreIO` | Store 读写异常。 |
283-
| `ErrResultUnexpected` | 宿主返回了意外结果。 |
274+
| 错误码 | 含义 |
275+
|----------------------------|----------------|
276+
| `ErrRuntimeInvalidDriver` | 传入的 Driver 无效。 |
277+
| `ErrRuntimeNotInitialized` | 运行时未初始化即调用。 |
278+
| `ErrRuntimeClosed` | 运行时已关闭。 |
279+
| `ErrStoreInvalidName` | Store 名称不合法。 |
280+
| `ErrStoreInternal` | Store 内部错误。 |
281+
| `ErrStoreNotFound` | 未找到指定 Store。 |
282+
| `ErrStoreIO` | Store 读写异常。 |
283+
| `ErrResultUnexpected` | 宿主返回了意外结果。 |
284284

285285
处理示例：
286286

@@ -303,7 +303,7 @@ if err != nil {
303303

304304
## 七、目录结构参考
305305

306-
```
306+
```text
307307
go-sdk/
308308
├── Makefile # env / wit / bindings / build
309309
├── fssdk.go # 对外入口与类型重导出

‎docs/go-sdk-guide.md‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,12 @@ Function Stream provides a WebAssembly (WASI P2) based operator SDK for Go devel
2727

2828
## 1. SDK Core Components
2929

30-
| Component | Role | Description |
31-
|-----------|------|-------------|
32-
| **fssdk** | Main package | Public entry point; exposes `Driver`, `Context`, `Store`, and `Run(driver)`. |
33-
| **api** | Interface definitions | Defines `Driver`, `Context`, `Store`, `Iterator`, `ComplexKey`, and error codes. |
34-
| **impl** | Runtime implementation | Bridges the Driver to the WASM host (processor WIT); internal use. |
35-
| **bindings** | WIT bindings | Go code generated by wit-bindgen-go from `wit/processor.wit`; used by impl. |
30+
| Component | Role | Description |
31+
|--------------|------------------------|----------------------------------------------------------------------------------|
32+
| **fssdk** | Main package | Public entry point; exposes `Driver`, `Context`, `Store`, and `Run(driver)`. |
33+
| **api** | Interface definitions | Defines `Driver`, `Context`, `Store`, `Iterator`, `ComplexKey`, and error codes. |
34+
| **impl** | Runtime implementation | Bridges the Driver to the WASM host (processor WIT); internal use. |
35+
| **bindings** | WIT bindings | Go code generated by wit-bindgen-go from `wit/processor.wit`; used by impl. |
3636

3737
Operators **only depend on fssdk**: implement `Driver` (or embed `BaseDriver`) and call `fssdk.Run(&YourProcessor{})` from `init()`.
3838

@@ -44,16 +44,16 @@ Operators **only depend on fssdk**: implement `Driver` (or embed `BaseDriver`) a
4444

4545
All Go operators must implement the `fssdk.Driver` interface. The runtime invokes the following methods at the appropriate times:
4646

47-
| Method | When invoked | Description |
48-
|--------|--------------|-------------|
49-
| `Init(ctx, config)` | Once when the function starts | Initialize state, obtain Store, parse config. |
50-
| `Process(ctx, sourceID, data)` | For each incoming message | Core logic: compute, state read/write, `ctx.Emit()`. |
51-
| `ProcessWatermark(ctx, sourceID, watermark)` | On watermark events | Handle time-based windows or out-of-order logic; may forward via `EmitWatermark`. |
52-
| `TakeCheckpoint(ctx, checkpointID)` | When the system backs up state | Persist extra in-memory state for strong consistency. |
53-
| `CheckHeartbeat(ctx)` | Periodic health check | Return `false` to trigger operator restart. |
54-
| `Close(ctx)` | When the function shuts down | Release resources and clear references. |
55-
| `Exec(ctx, className, modules)` | Optional extension | Dynamic module loading, etc.; default no-op. |
56-
| `Custom(ctx, payload)` | Optional custom RPC | Request/response custom bytes; default returns a copy of payload. |
47+
| Method | When invoked | Description |
48+
|----------------------------------------------|--------------------------------|-----------------------------------------------------------------------------------|
49+
| `Init(ctx, config)` | Once when the function starts | Initialize state, obtain Store, parse config. |
50+
| `Process(ctx, sourceID, data)` | For each incoming message | Core logic: compute, state read/write, `ctx.Emit()`. |
51+
| `ProcessWatermark(ctx, sourceID, watermark)` | On watermark events | Handle time-based windows or out-of-order logic; may forward via `EmitWatermark`. |
52+
| `TakeCheckpoint(ctx, checkpointID)` | When the system backs up state | Persist extra in-memory state for strong consistency. |
53+
| `CheckHeartbeat(ctx)` | Periodic health check | Return `false` to trigger operator restart. |
54+
| `Close(ctx)` | When the function shuts down | Release resources and clear references. |
55+
| `Exec(ctx, className, modules)` | Optional extension | Dynamic module loading, etc.; default no-op. |
56+
| `Custom(ctx, payload)` | Optional custom RPC | Request/response custom bytes; default returns a copy of payload. |
5757

5858
### 2.2 BaseDriver
5959

@@ -98,13 +98,13 @@ func init() {
9898

9999
`fssdk.Context` is passed into Init, Process, ProcessWatermark, etc. It provides:
100100

101-
| Method | Description |
102-
|--------|-------------|
103-
| `Emit(targetID uint32, data []byte) error` | Send data to the given output channel. |
104-
| `EmitWatermark(targetID uint32, watermark uint64) error` | Emit a watermark. |
105-
| `GetOrCreateStore(name string) (Store, error)` | Get or create a KV Store by name (RocksDB-backed). |
106-
| `Config() map[string]string` | Startup configuration (e.g. from config.yaml init section). |
107-
| `Close() error` | Close the context; usually managed by the runtime. |
101+
| Method | Description |
102+
|----------------------------------------------------------|-------------------------------------------------------------|
103+
| `Emit(targetID uint32, data []byte) error` | Send data to the given output channel. |
104+
| `EmitWatermark(targetID uint32, watermark uint64) error` | Emit a watermark. |
105+
| `GetOrCreateStore(name string) (Store, error)` | Get or create a KV Store by name (RocksDB-backed). |
106+
| `Config() map[string]string` | Startup configuration (e.g. from config.yaml init section). |
107+
| `Close() error` | Close the context; usually managed by the runtime. |
108108

109109
### 3.2 Store (KV State)
110110

@@ -271,16 +271,16 @@ Configure `name`, `type: processor`, `input-groups`, and `outputs` (e.g. Kafka)
271271

272272
The SDK returns errors as `fssdk.SDKError`; use `errors.As` to get the `Code`:
273273

274-
| Code | Meaning |
275-
|------|---------|
276-
| `ErrRuntimeInvalidDriver` | Invalid Driver passed to Run. |
277-
| `ErrRuntimeNotInitialized` | Runtime not initialized. |
278-
| `ErrRuntimeClosed` | Runtime already closed. |
279-
| `ErrStoreInvalidName` | Invalid Store name. |
280-
| `ErrStoreInternal` | Store internal error. |
281-
| `ErrStoreNotFound` | Store not found. |
282-
| `ErrStoreIO` | Store I/O error. |
283-
| `ErrResultUnexpected` | Unexpected result from host. |
274+
| Code | Meaning |
275+
|----------------------------|-------------------------------|
276+
| `ErrRuntimeInvalidDriver` | Invalid Driver passed to Run. |
277+
| `ErrRuntimeNotInitialized` | Runtime not initialized. |
278+
| `ErrRuntimeClosed` | Runtime already closed. |
279+
| `ErrStoreInvalidName` | Invalid Store name. |
280+
| `ErrStoreInternal` | Store internal error. |
281+
| `ErrStoreNotFound` | Store not found. |
282+
| `ErrStoreIO` | Store I/O error. |
283+
| `ErrResultUnexpected` | Unexpected result from host. |
284284

285285
Example handling:
286286

@@ -303,7 +303,7 @@ if err != nil {
303303

304304
## 7. Directory Layout
305305

306-
```
306+
```text
307307
go-sdk/
308308
├── Makefile # env / wit / bindings / build
309309
├── fssdk.go # Entry point and type re-exports

0 commit comments

Comments
 (0)