From c105d2be7b315faaf3e748920687d1124f96e652 Mon Sep 17 00:00:00 2001 From: Byron Wang Date: Sun, 8 Jun 2025 17:54:38 +0800 Subject: [PATCH 1/3] add sri docs --- docs/runtime/sri.md | 281 ++++++++++++++++++++++++++++++++++++++++ docs/runtime/sri_cn.md | 282 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 563 insertions(+) create mode 100644 docs/runtime/sri.md create mode 100644 docs/runtime/sri_cn.md diff --git a/docs/runtime/sri.md b/docs/runtime/sri.md new file mode 100644 index 000000000..7d7e30128 --- /dev/null +++ b/docs/runtime/sri.md @@ -0,0 +1,281 @@ +# Dify Plugin Daemon - Serverless Runtime Interface (SRI) + +The Serverless Runtime Interface (**SRI**) is a set of HTTP APIs for packaging plugins into serverless components, allowing the Dify Plugin Daemon to remotely launch and operate them on external platforms (e.g., AWS Lambda). + +This interface enables the daemon to communicate with remote runtime environments via standard protocols to handle plugin deployment, execution, and instance queries. + +> ⚠️ **Note**: This interface is currently in the **Alpha** stage. Stability and backward compatibility are not guaranteed. A production-grade SRI implementation is available in the enterprise edition. For support, please contact `business@dify.ai`. + +--- + +## 🔧 Basic Configuration + +The daemon is configured using the following environment variables: + +| Variable | Description | +|----------|-------------| +| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_URL` | Base URL of the remote runtime environment, e.g., `https://example.com` | +| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_API_KEY` | Authentication token for accessing SRI, passed in the `Authorization` request header | + +--- + +## 📡 API Endpoints + +### `GET /ping` + +Used by the daemon for connectivity checks during startup. + +**Request** + +```http +GET /ping +Authorization: +``` + +**Response** + +- `200 OK`, response body is plain text: `"pong"` + +--- + +### `GET /v1/runner/instances` + +Returns information about plugin instances that are ready to run. + +**Query Parameters** + +- `filename` (required): Name of the uploaded plugin package, in the format: + + ``` + vendor@plugin@version@hash.difypkg + ``` + +**Response** + +```json +{ + "items": [ + { + "ID": "string", + "Name": "string", + "Endpoint": "string", + "ResourceName": "string" + } + ] +} +``` + +--- + +### `POST /v1/launch` + +Launches a plugin using a streaming event protocol for real-time daemon parsing of startup status. + +> This API uses `multipart/form-data` for submission and returns status via **Server-Sent Events (SSE)**. + +**Request Fields** + +| Field | Type | Description | +|------------|----------|-----------------------------------------------------| +| `context` | file | Plugin package file in `.difypkg` format | +| `verified` | boolean | Whether the plugin has been verified by the daemon | + +**SSE Response Format** + +```json +{ + "Stage": "healthz|start|build|run|end", + "State": "running|success|failed", + "Obj": "string", + "Message": "string" +} +``` + +**Stage Descriptions** + +| Stage | Meaning | Description | +|---------|------------------|--------------------------------------------------| +| healthz | Health check | Initializes runtime resources and containers | +| start | Startup prep | Prepares the environment | +| build | Build phase | Builds plugin dependencies and packages image | +| run | Execution phase | Plugin is running; returns key info on success | +| end | Completion | Final state confirmation: success or failure | + +When a message with `Stage=run` and `State=success` is received, the daemon will extract details and register the plugin instance: + +``` +endpoint=http://...,name=...,id=... +``` + +**Error Handling** + +- If any stage returns `State = failed`, it is considered a launch failure +- The daemon should abort the process and output the `Message` field as the error + +--- + +## 🔁 Communication Sequence (ASCII) + +```text +daemon Serverless Runtime Interface + |-------------------------------------->| + | GET /ping | + |<--------------------------------------| + | 200 OK "pong" | + |-------------------------------------->| + | GET /v1/runner/instances | + | filename | + |<--------------------------------------| + | {items} | + |-------------------------------------->| + | POST /v1/launch | + | context, verified multipart payload | + |<--------------------------------------| + | Building plugin... (SSE) | + |<--------------------------------------| + | Launching plugin... (SSE) | + |<--------------------------------------| + | Function: [Name] (SSE) | + |<--------------------------------------| + | FunctionUrl: [Endpoint] (SSE) | + |<--------------------------------------| + | Done: Plugin launched (SSE) | +``` + +--- + +## 📦 Plugin File Naming Convention + +Plugin files must use the `.difypkg` extension and follow this naming convention: + +``` +@@@.difypkg +``` + +Example: + +``` +langgenius@tavily@0.0.5@7f277f7a63e36b1b3e9ed53e55daab0b281599d14902664bade86215f5374f06.difypkg +``` + +--- + +## 📬 Contact Us + +For access to the enterprise-supported version or more details about plugin packaging and deployment, please contact: + +📧 `business@dify.ai` + +--- + +## 📘 OpenAPI Specification (YAML) + +```yaml +openapi: 3.0.3 +info: + title: Dify Plugin Daemon - Serverless Runtime Interface (SRI) + version: alpha + description: HTTP API specification for the Dify Plugin Daemon's Serverless Runtime + Interface (SRI). +paths: + /ping: + get: + summary: Health check endpoint + description: Used by the daemon to verify connectivity with the SRI. + responses: + '200': + description: Returns 'pong' if the service is alive + content: + text/plain: + schema: + type: string + example: pong + security: + - apiKeyAuth: [] + /v1/runner/instances: + get: + summary: List available plugin instances + parameters: + - name: filename + in: query + required: true + schema: + type: string + description: Full plugin package filename (e.g., vendor@plugin@version@hash.difypkg) + responses: + '200': + description: List of available plugin instances + content: + application/json: + schema: + type: object + properties: + items: + type: array + items: + type: object + properties: + ID: + type: string + Name: + type: string + Endpoint: + type: string + ResourceName: + type: string + security: + - apiKeyAuth: [] + /v1/launch: + post: + summary: Launch a plugin via SSE + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + context: + type: string + format: binary + description: Plugin package file (.difypkg) + verified: + type: boolean + description: Whether the plugin is verified + required: + - context + responses: + '200': + description: Server-Sent Events stream with plugin launch stages + content: + text/event-stream: + schema: + type: object + properties: + Stage: + type: string + enum: + - healthz + - start + - build + - run + - end + State: + type: string + enum: + - running + - success + - failed + Obj: + type: string + Message: + type: string + security: + - apiKeyAuth: [] +components: + securitySchemes: + apiKeyAuth: + type: apiKey + in: header + name: Authorization +``` diff --git a/docs/runtime/sri_cn.md b/docs/runtime/sri_cn.md new file mode 100644 index 000000000..7e5b6b829 --- /dev/null +++ b/docs/runtime/sri_cn.md @@ -0,0 +1,282 @@ +# Dify Plugin Daemon - Serverless Runtime Interface (SRI) + +Serverless Runtime Interface (**SRI**) 是一组用于将插件封装为 Serverless 组件，并由 Dify Plugin Daemon 在外部平台（如 AWS Lambda）上远程启动和运行的 HTTP 接口规范。 + +该接口允许 daemon 通过标准协议与远程运行环境通信，实现插件部署、运行、实例查询等功能。 + +> ⚠️ **注意**：当前接口处于 **Alpha 阶段**，不保证稳定性与向后兼容性。 企业版中提供生产级 SRI 实现, 如需请联系 `business@dify.ai`。 + +--- + +## 🔧 基础配置 + +daemon 通过如下环境变量进行配置： + +| 变量名 | 含义 | +|--------|------| +| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_URL` | 指定远程运行环境的 Base URL，例如 `https://example.com` | +| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_API_KEY` | 用于访问 SRI 的鉴权 token，将被加入请求 Header 中的 `Authorization` 字段 | + +--- + +## 📡 接口说明 + +### `GET /ping` + +用于 daemon 启动时的连通性检查。 + +**请求** + +```http +GET /ping +Authorization: +``` + +**响应** + +- `200 OK`，响应体为纯文本字符串 `"pong"` + +--- + +### `GET /v1/runner/instances` + +返回支持运行的插件实例信息。 + +**请求参数** + +- `filename`（必填）：上传的插件包文件名，格式为： + + ``` + vendor@plugin@version@hash.difypkg + ``` + +**响应** + +```json +{ + "items": [ + { + "ID": "string", + "Name": "string", + "Endpoint": "string", + "ResourceName": "string" + } + ] +} +``` + +--- + +### `POST /v1/launch` + +以流式事件的方式启动插件，供 daemon 实时解析启动状态。 + +> 本接口使用 `multipart/form-data` 提交，同时以 **Server-Sent Events（SSE）** 返回插件运行状态流。 + +**请求字段** + +| 字段名 | 类型 | 描述 | +|------------|-----------|----------------------------------------------| +| `context` | file | `.difypkg` 格式的插件包 | +| `verified` | boolean | 插件是否已通过 daemon 验证（由 manifest 判断） | + +**SSE 响应格式** + +```json +{ + "Stage": "healthz|start|build|run|end", + "State": "running|success|failed", + "Obj": "string", + "Message": "string" +} +``` + +**阶段说明** + +| Stage | 含义 | 行为说明 | +|---------|--------------|------------------------------------------------| +| healthz | 健康检查 | 初始化运行时资源，准备插件容器 | +| start | 启动准备阶段 | 准备环境 | +| build | 构建阶段 | 构建插件依赖，打包镜像 | +| run | 运行阶段 | 插件运行中，如成功将返回关键信息 | +| end | 启动完成 | 插件运行结果确认，可能为 success 或 failed | + +当接收到以下格式的 `Stage=run` 且 `State=success` 消息时，daemon 将提取其中信息并建立插件实例： + +``` +endpoint=http://...,name=...,id=... +``` + +**错误处理** + +- 任意阶段返回 `State = failed` 即视为启动失败 +- daemon 应中断流程并抛出异常，输出 `Message` 内容作为错误信息 + +--- + +## 🔁 通信时序图（ASCII） + +```text +daemon Serverless Runtime Interface + |-------------------------------------->| + | GET /ping | + |<--------------------------------------| + | 200 OK "pong" | + |-------------------------------------->| + | GET /v1/runner/instances | + | filename | + |<--------------------------------------| + | {items} | + |-------------------------------------->| + | POST /v1/launch | + | context, verified multipart payload | + |<--------------------------------------| + | Building plugin... (SSE) | + |<--------------------------------------| + | Launching plugin... (SSE) | + |<--------------------------------------| + | Function: [Name] (SSE) | + |<--------------------------------------| + | FunctionUrl: [Endpoint] (SSE) | + |<--------------------------------------| + | Done: Plugin launched (SSE) | +``` + +--- + +## 📦 插件文件名规范 + +插件文件扩展名必须为 `.difypkg`，命名格式如下： + +``` +@@@.difypkg +``` + +示例： + +``` +langgenius@tavily@0.0.5@7f277f7a63e36b1b3e9ed53e55daab0b281599d14902664bade86215f5374f06.difypkg +``` + +--- + +## 📬 联系我们 + +如需接入商业支持版本，或希望深入了解插件打包与部署规范，请联系： + +📧 `business@dify.ai` + +--- + +## 📘 OpenAPI 规范（YAML） + +```yaml +openapi: 3.0.3 +info: + title: Dify Plugin Daemon - Serverless Runtime Interface (SRI) + version: alpha + description: HTTP API specification for the Dify Plugin Daemon's Serverless Runtime + Interface (SRI). +paths: + /ping: + get: + summary: Health check endpoint + description: Used by the daemon to verify connectivity with the SRI. + responses: + '200': + description: Returns 'pong' if the service is alive + content: + text/plain: + schema: + type: string + example: pong + security: + - apiKeyAuth: [] + /v1/runner/instances: + get: + summary: List available plugin instances + parameters: + - name: filename + in: query + required: true + schema: + type: string + description: Full plugin package filename (e.g., vendor@plugin@version@hash.difypkg) + responses: + '200': + description: List of available plugin instances + content: + application/json: + schema: + type: object + properties: + items: + type: array + items: + type: object + properties: + ID: + type: string + Name: + type: string + Endpoint: + type: string + ResourceName: + type: string + security: + - apiKeyAuth: [] + /v1/launch: + post: + summary: Launch a plugin via SSE + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + context: + type: string + format: binary + description: Plugin package file (.difypkg) + verified: + type: boolean + description: Whether the plugin is verified + required: + - context + responses: + '200': + description: Server-Sent Events stream with plugin launch stages + content: + text/event-stream: + schema: + type: object + properties: + Stage: + type: string + enum: + - healthz + - start + - build + - run + - end + State: + type: string + enum: + - running + - success + - failed + Obj: + type: string + Message: + type: string + security: + - apiKeyAuth: [] +components: + securitySchemes: + apiKeyAuth: + type: apiKey + in: header + name: Authorization + +``` From ab4782f7c682908b3c1272e22f051c4cdf5d60b6 Mon Sep 17 00:00:00 2001 From: Byron Wang Date: Tue, 10 Jun 2025 11:20:51 +0800 Subject: [PATCH 2/3] add refer to readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 33a284898..57651cca9 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ All requests from Dify api based on HTTP protocol, but depends on the runtime ty - For local runtime, daemon will start plugin as the subprocess and communicate with the plugin via STDIN/STDOUT. - For debug runtime, daemon wait for a plugin to connect and communicate in full-duplex way, it's TCP based. -- For serverless runtime, plugin will be packaged to a third-party service like AWS Lambda and then be invoked by the daemon via HTTP protocol. +- For serverless runtime, plugin will be packaged to a third-party service like AWS Lambda and then be invoked by the daemon via HTTP protocol.You may refer to [SRI Docs](./docs/runtime/sri.md) for more detailed information. For more detailed introduction about Dify plugin, please refer to our docs [https://docs.dify.ai/plugins/introduction](https://docs.dify.ai/plugins/introduction). From 355064a3c72015e51519d2dc6c548eba8d627cd8 Mon Sep 17 00:00:00 2001 From: Byron Wang Date: Tue, 10 Jun 2025 11:22:37 +0800 Subject: [PATCH 3/3] format readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 57651cca9..3a4594d24 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ All requests from Dify api based on HTTP protocol, but depends on the runtime ty - For local runtime, daemon will start plugin as the subprocess and communicate with the plugin via STDIN/STDOUT. - For debug runtime, daemon wait for a plugin to connect and communicate in full-duplex way, it's TCP based. -- For serverless runtime, plugin will be packaged to a third-party service like AWS Lambda and then be invoked by the daemon via HTTP protocol.You may refer to [SRI Docs](./docs/runtime/sri.md) for more detailed information. +- For serverless runtime, plugin will be packaged to a third-party service like AWS Lambda and then be invoked by the daemon via HTTP protocol. You may refer to [SRI Docs](./docs/runtime/sri.md) for more detailed information. For more detailed introduction about Dify plugin, please refer to our docs [https://docs.dify.ai/plugins/introduction](https://docs.dify.ai/plugins/introduction).