vahidaghazadeh opened a new pull request, #12128:
URL: https://github.com/apache/apisix/pull/12128
### Description
This Pull Request introduces the `proxy-chain` plugin to APISIX, designed to
enhance the gateway's ability to orchestrate complex workflows by chaining
multiple upstream service calls in a sequential manner. The plugin merges the
responses from these services into a single payload, which is then passed to
the final upstream, making it ideal for scenarios requiring data aggregation or
step-by-step processing across microservices.
### Purpose
The primary goal of the `proxy-chain` plugin is to simplify workflows where
a single client request needs to interact with multiple backend services before
producing a final response. For example, in an e-commerce checkout process, the
plugin can:
1. Fetch user data from a customer service.
2. Validate payment details from a payment service.
3. Combine the results and forward them to an order processing service.
This eliminates the need for clients to manage these interactions manually
and reduces latency by handling them server-side within APISIX.
### How It Works
The plugin operates in the `access` phase of APISIX's request lifecycle and
performs the following steps:
1. **Request Parsing**: Extracts the incoming request body (JSON) and URI
arguments, merging them into an initial data set.
2. **Token Handling**: Optionally extracts an authentication token from a
configurable header (e.g., `Token` or `Authorization`) and passes it to
downstream services.
3. **Service Chaining**: Iterates through a list of configured services,
making HTTP requests to each in sequence:
- Sends the current merged data as the request body.
- Merges the response (JSON) into the cumulative data set.
4. **Final Output**: Updates the request body with the merged data and
forwards it to the upstream, optionally including the authentication token.
The plugin includes error handling for failed service calls or invalid JSON
responses, returning appropriate HTTP status codes and error messages.
### Configuration Schema
| Name | Type | Required | Default | Description
|
|----------------|--------|----------|---------|--------------------------------------------------|
| `services` | array | Yes | - | List of upstream services
to chain. |
| `services.uri` | string | Yes | - | URI of the upstream
service. |
| `services.method` | string | Yes | "POST" | HTTP method (GET, POST,
PUT, DELETE). |
| `token_header` | string | No | - | Custom header name for
passing a token between services. |
### Example Usage
Below is an example of how to configure and use the `proxy-chain` plugin in
APISIX:
#### Route Configuration
```json
{
"uri": "/offl/v1/checkout",
"methods": ["POST"],
"plugins": {
"proxy-chain": {
"services": [
{
"uri": "http://customer_service/api/v1/user";,
"method": "POST"
},
{
"uri": "http://payment_service/api/v1/validate";,
"method": "POST"
}
],
"token_header": "Token"
},
"proxy-rewrite": {
"uri": "/api/v1/checkout"
}
},
"upstream_id": "550932803756229477"
}
```
## Expected Behavior:
The plugin sends {"order_id": "12345"} to customer_service/api/v1/user,
receiving something like {"user_id": "67890"}.
It then sends the merged data {"order_id": "12345", "user_id": "67890"} to
payment_service/api/v1/validate, receiving {"status": "valid"}.
The final merged data {"order_id": "12345", "user_id": "67890", "status":
"valid"} is rewritten to /api/v1/checkout and sent to the upstream.
## Changes Introduced
Added apisix/apisix/plugins/proxy-chain.lua with the plugin implementation.
Updated documentation in docs/en/latest/plugins/proxy-chain.md (to be added
in a follow-up commit if needed).
## Why Include This Plugin?
Flexibility: Enables complex service orchestration without additional
middleware.
Performance: Reduces client-side latency by handling chaining server-side.
Reusability: Useful across various use cases like authentication flows, data
aggregation, and microservices coordination.
## Testing
The plugin has been tested in a Dockerized APISIX environment (version
3.11.0-debian) with the example configuration above.
Error handling for failed service calls and invalid JSON responses is
verified.
Suggestions for unit tests in t/plugin/ are welcome!
## Next Steps
Requesting feedback on the implementation and configuration schema.
Willing to add unit tests if required for acceptance
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
