Apache Dubbo-Go-Pixiu

Dubbo-Go-Pixiu is a high-performance AI and API Gateway built on Dubbo-go. It serves two primary purposes:

1. AI Gateway: Provides unified access to LLMs (OpenAI, Anthropic, or custom/on-prem models) and MCP (Model Context Protocol) services. It allows you to expose HTTP APIs as MCP Servers and manage AI workloads with plugins for authentication, rate-limiting, and model orchestration.
2. API Gateway: Bridges external protocols (HTTP, gRPC) with internal Dubbo clusters (Dubbo2, Triple). It acts as a sidecar solution for connecting non-Java applications (Go, Python, Node.js) to Dubbo services.

Additionally, Pixiu functions as a Kubernetes Ingress Controller, allowing for declarative traffic governance and routing via Kubernetes APIs.

The dgp.filter.grpc.proxy filter provides gRPC proxy capabilities for the Pixiu gateway. It supports gRPC Server Reflection, allowing the gateway to dynamically parse and inspect message content at runtime without requiring pre-compiled .proto files.

Core Capabilities

• Dynamic Message Decoding: Parse and inspect gRPC messages on the fly.
• Protocol Detection: Supports both standard gRPC and the Dubbo Triple protocol.
• Descriptor Caching: Uses a TTL-based cache for method descriptors to improve performance.
• Graceful Degradation: The hybrid mode allows automatic fallback to passthrough if reflection fails.

grpc_filters:
  - name: dgp.filter.grpc.proxy
    config: {} # Defaults to passthrough mode

The Pixiu User Guide provides comprehensive documentation for getting started, understanding the API model, managing responses, installing the gateway, and configuring specific filters like OpenAPI Request Validation and SAML Auth.

Key topics include:

• Quick Start: Initial setup and first steps.
• Api Model: Understanding how APIs are defined and structured in Pixiu.
• Response: Managing and customizing API responses.
• Installation: Procedures for deploying Pixiu.
• Filters: Detailed guides for implementing security and validation logic, such as OpenAPI Request Validation Filter and SAML Auth Filter.

As of version 1.1.0, Dubbo-Go-Pixiu provides advanced capabilities for managing Large Language Model (LLM) traffic through its AI Gateway features:

• LLM Proxy: Supports retry mechanisms with configurable strategy abstractions and failure fallback capabilities.
• Token Management: Includes a Token billing/statistics Filter and a Tokenizer Filter that supports Content-Encoding.
• Streaming Support: Full support for HTTP/SSE streaming inference, suitable for long-connection data pipelines.
• LLM Configuration: A new LLMMeta field is available to simplify LLM Endpoint configurations.
• LLM Service Discovery: Supports using Nacos as an LLM registry center.
• Observability: Enhanced upstream tracing and metric collection for model services.

The llm_meta block allows you to customize how the gateway handles specific LLM upstream endpoints. It supports the following fields:

• fallback (boolean): If true, the gateway attempts the next endpoint in the cluster if all retries on the current endpoint fail. If false, the gateway stops and returns the last error to the client.
• api_key (string): The API key injected into the request headers when forwarding to the LLM service.
• retry_policy (object): Defines the retry strategy for the endpoint. It requires a name (case-insensitive) and a config object containing policy-specific parameters.

The OpenAPI validation process follows these steps at runtime:

1. Startup: Pixiu loads the OpenAPI file and builds an SDK validator using libopenapi.
2. Entry: A request enters the openapi.Decode() stage.
3. Matching: Pixiu checks if the OpenAPI document contains the specific path and method of the request.
4. Decision:
   • If not declared: Validation is skipped; the request continues to the next filter.
   • If declared: The request is validated via libopenapi-validator.
5. Outcome:
   • Success: The request continues to subsequent filters.
   • Failure: Pixiu immediately returns a 400 Bad Request to the client.

Pixiu allows you to map incoming request data from different sources—such as URI path parameters, query strings, or the request body—to the downstream integration request.

• Query Strings: Defined in inboundRequest.queryStrings. You can mark them as required: true.
• URI Path Parameters: Defined using the restful resource type. Parameters in the path (e.g., /:name) are accessible via the uri prefix (e.g., uri.name).
• Mapping: Use mappingParams in the integrationRequest section to transfer values from the inbound request to the downstream request. You can map from uri.*, queryStrings.*, or requestBody.* to target fields in the downstream request.

The MCP router can consume JWT claims (such as tenant or agent_role) to implement isolation and specific workflows.

Important Requirements:

• The router does not re-validate tokens. It consumes claims that have already been validated by the MCP auth filter earlier in the filter chain.
• For claim-based rules to work, the auth filter must be present in the chain and must successfully populate the JWT claims.
• Unconditional rules (rules that do not require specific claims) will work even without an auth filter.