add serverless runtime interface docs

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).
 

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 `[email protected]`.
+
+---
+
+## 🔧 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: <API_KEY>
+```
+
+**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@[email protected]
+  ```
+
+**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:
+
+```
+<vendor>@<plugin_name>@<version>@<sha256_hash>.difypkg
+```
+
+Example:
+
+```
+langgenius@[email protected]@7f277f7a63e36b1b3e9ed53e55daab0b281599d14902664bade86215f5374f06.difypkg
+```
+
+---
+
+## 📬 Contact Us
+
+For access to the enterprise-supported version or more details about plugin packaging and deployment, please contact:
+
+📧 `[email protected]`
+
+---
+
+## 📘 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@[email protected])
+      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
+```