Skip to content

Commit 7c1e46f

Browse files
41tair41tair
authored
add serverless runtime interface docs (#338)
* add sri docs * add refer to readme * format readme
1 parent 6873c3f commit 7c1e46f

File tree

3 files changed

+564
-1
lines changed

3 files changed

+564
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ All requests from Dify api based on HTTP protocol, but depends on the runtime ty
1414

1515
- For local runtime, daemon will start plugin as the subprocess and communicate with the plugin via STDIN/STDOUT.
1616
- For debug runtime, daemon wait for a plugin to connect and communicate in full-duplex way, it's TCP based.
17-
- 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.
17+
- 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.
1818

1919
For more detailed introduction about Dify plugin, please refer to our docs [https://docs.dify.ai/plugins/introduction](https://docs.dify.ai/plugins/introduction).
2020

‎docs/runtime/sri.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# Dify Plugin Daemon - Serverless Runtime Interface (SRI)
2+
3+
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).
4+
5+
This interface enables the daemon to communicate with remote runtime environments via standard protocols to handle plugin deployment, execution, and instance queries.
6+
7+
> ⚠️ **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 `[email protected]`.
8+
9+
---
10+
11+
## 🔧 Basic Configuration
12+
13+
The daemon is configured using the following environment variables:
14+
15+
| Variable | Description |
16+
|----------|-------------|
17+
| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_URL` | Base URL of the remote runtime environment, e.g., `https://example.com` |
18+
| `DIFY_PLUGIN_SERVERLESS_CONNECTOR_API_KEY` | Authentication token for accessing SRI, passed in the `Authorization` request header |
19+
20+
---
21+
22+
## 📡 API Endpoints
23+
24+
### `GET /ping`
25+
26+
Used by the daemon for connectivity checks during startup.
27+
28+
**Request**
29+
30+
```http
31+
GET /ping
32+
Authorization: <API_KEY>
33+
```
34+
35+
**Response**
36+
37+
- `200 OK`, response body is plain text: `"pong"`
38+
39+
---
40+
41+
### `GET /v1/runner/instances`
42+
43+
Returns information about plugin instances that are ready to run.
44+
45+
**Query Parameters**
46+
47+
- `filename` (required): Name of the uploaded plugin package, in the format:
48+
49+
```
50+
vendor@plugin@[email protected]
51+
```
52+
53+
**Response**
54+
55+
```json
56+
{
57+
"items": [
58+
{
59+
"ID": "string",
60+
"Name": "string",
61+
"Endpoint": "string",
62+
"ResourceName": "string"
63+
}
64+
]
65+
}
66+
```
67+
68+
---
69+
70+
### `POST /v1/launch`
71+
72+
Launches a plugin using a streaming event protocol for real-time daemon parsing of startup status.
73+
74+
> This API uses `multipart/form-data` for submission and returns status via **Server-Sent Events (SSE)**.
75+
76+
**Request Fields**
77+
78+
| Field | Type | Description |
79+
|------------|----------|-----------------------------------------------------|
80+
| `context` | file | Plugin package file in `.difypkg` format |
81+
| `verified` | boolean | Whether the plugin has been verified by the daemon |
82+
83+
**SSE Response Format**
84+
85+
```json
86+
{
87+
"Stage": "healthz|start|build|run|end",
88+
"State": "running|success|failed",
89+
"Obj": "string",
90+
"Message": "string"
91+
}
92+
```
93+
94+
**Stage Descriptions**
95+
96+
| Stage | Meaning | Description |
97+
|---------|------------------|--------------------------------------------------|
98+
| healthz | Health check | Initializes runtime resources and containers |
99+
| start | Startup prep | Prepares the environment |
100+
| build | Build phase | Builds plugin dependencies and packages image |
101+
| run | Execution phase | Plugin is running; returns key info on success |
102+
| end | Completion | Final state confirmation: success or failure |
103+
104+
When a message with `Stage=run` and `State=success` is received, the daemon will extract details and register the plugin instance:
105+
106+
```
107+
endpoint=http://...,name=...,id=...
108+
```
109+
110+
**Error Handling**
111+
112+
- If any stage returns `State = failed`, it is considered a launch failure
113+
- The daemon should abort the process and output the `Message` field as the error
114+
115+
---
116+
117+
## 🔁 Communication Sequence (ASCII)
118+
119+
```text
120+
daemon Serverless Runtime Interface
121+
|-------------------------------------->|
122+
| GET /ping |
123+
|<--------------------------------------|
124+
| 200 OK "pong" |
125+
|-------------------------------------->|
126+
| GET /v1/runner/instances |
127+
| filename |
128+
|<--------------------------------------|
129+
| {items} |
130+
|-------------------------------------->|
131+
| POST /v1/launch |
132+
| context, verified multipart payload |
133+
|<--------------------------------------|
134+
| Building plugin... (SSE) |
135+
|<--------------------------------------|
136+
| Launching plugin... (SSE) |
137+
|<--------------------------------------|
138+
| Function: [Name] (SSE) |
139+
|<--------------------------------------|
140+
| FunctionUrl: [Endpoint] (SSE) |
141+
|<--------------------------------------|
142+
| Done: Plugin launched (SSE) |
143+
```
144+
145+
---
146+
147+
## 📦 Plugin File Naming Convention
148+
149+
Plugin files must use the `.difypkg` extension and follow this naming convention:
150+
151+
```
152+
<vendor>@<plugin_name>@<version>@<sha256_hash>.difypkg
153+
```
154+
155+
Example:
156+
157+
```
158+
langgenius@[email protected]@7f277f7a63e36b1b3e9ed53e55daab0b281599d14902664bade86215f5374f06.difypkg
159+
```
160+
161+
---
162+
163+
## 📬 Contact Us
164+
165+
For access to the enterprise-supported version or more details about plugin packaging and deployment, please contact:
166+
167+
📧 `[email protected]`
168+
169+
---
170+
171+
## 📘 OpenAPI Specification (YAML)
172+
173+
```yaml
174+
openapi: 3.0.3
175+
info:
176+
title: Dify Plugin Daemon - Serverless Runtime Interface (SRI)
177+
version: alpha
178+
description: HTTP API specification for the Dify Plugin Daemon's Serverless Runtime
179+
Interface (SRI).
180+
paths:
181+
/ping:
182+
get:
183+
summary: Health check endpoint
184+
description: Used by the daemon to verify connectivity with the SRI.
185+
responses:
186+
'200':
187+
description: Returns 'pong' if the service is alive
188+
content:
189+
text/plain:
190+
schema:
191+
type: string
192+
example: pong
193+
security:
194+
- apiKeyAuth: []
195+
/v1/runner/instances:
196+
get:
197+
summary: List available plugin instances
198+
parameters:
199+
- name: filename
200+
in: query
201+
required: true
202+
schema:
203+
type: string
204+
description: Full plugin package filename (e.g., vendor@plugin@[email protected])
205+
responses:
206+
'200':
207+
description: List of available plugin instances
208+
content:
209+
application/json:
210+
schema:
211+
type: object
212+
properties:
213+
items:
214+
type: array
215+
items:
216+
type: object
217+
properties:
218+
ID:
219+
type: string
220+
Name:
221+
type: string
222+
Endpoint:
223+
type: string
224+
ResourceName:
225+
type: string
226+
security:
227+
- apiKeyAuth: []
228+
/v1/launch:
229+
post:
230+
summary: Launch a plugin via SSE
231+
requestBody:
232+
required: true
233+
content:
234+
multipart/form-data:
235+
schema:
236+
type: object
237+
properties:
238+
context:
239+
type: string
240+
format: binary
241+
description: Plugin package file (.difypkg)
242+
verified:
243+
type: boolean
244+
description: Whether the plugin is verified
245+
required:
246+
- context
247+
responses:
248+
'200':
249+
description: Server-Sent Events stream with plugin launch stages
250+
content:
251+
text/event-stream:
252+
schema:
253+
type: object
254+
properties:
255+
Stage:
256+
type: string
257+
enum:
258+
- healthz
259+
- start
260+
- build
261+
- run
262+
- end
263+
State:
264+
type: string
265+
enum:
266+
- running
267+
- success
268+
- failed
269+
Obj:
270+
type: string
271+
Message:
272+
type: string
273+
security:
274+
- apiKeyAuth: []
275+
components:
276+
securitySchemes:
277+
apiKeyAuth:
278+
type: apiKey
279+
in: header
280+
name: Authorization
281+
```

0 commit comments

Comments
 (0)