kayx23 commented on code in PR #13296: URL: https://github.com/apache/apisix/pull/13296#discussion_r3143786919
########## docs/zh/latest/plugins/grpc-web.md: ########## @@ -52,54 +89,149 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 前提条件 + +在进行示例操作之前，请完成以下步骤来设置上游服务器和 gRPC-Web 客户端。 + +#### 启动上游服务器 + +启动一个 [grpcbin 服务器](https://github.com/moul/grpcbin)作为示例上游： + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri":"/grpc/web/*", - "plugins":{ - "grpc-web":{} - }, - "upstream":{ - "scheme":"grpc", - "type":"roundrobin", - "nodes":{ - "127.0.0.1:1980":1 - } - } -}' +docker run -d \ + --name grpcbin \ + -p 9000:9000 \ + moul/grpcbin ``` -## 测试插件 +#### 生成 gRPC-Web 客户端代码 + +下载 Protocol Buffer 定义文件 `hello.proto`： + +```shell +curl -O https://raw.githubusercontent.com/moul/pb/refs/heads/master/hello/hello.proto +``` -请参考 [gRPC-Web Client Runtime Library](https://www.npmjs.com/package/grpc-web) 或 [Apache APISIX gRPC Web Test Framework](https://github.com/apache/apisix/tree/master/t/plugin/grpc-web) 了解如何配置你的 Web 客户端。 +安装 [`protobuf`](https://github.com/protocolbuffers/protobuf/releases) 和 [`protoc-gen-grpc-web`](https://github.com/grpc/grpc-web/releases)。 -运行 gRPC Web 客户端后，你可以从浏览器或通过 Node.js 向 APISIX 发出请求。 +从 `hello.proto` 生成 gRPC-Web 客户端代码： -:::note +```shell +protoc \ + --js_out=import_style=commonjs:. \ + --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. \ + hello.proto +``` -请求方式仅支持 `POST` 和 `OPTIONS`，详细信息请参考：[CORS support](https://github.com/grpc/grpc-web/blob/master/doc/browser-features.md#cors-support) 。 +您应在当前目录看到两个生成的文件：`hello_pb.js`（Protocol Buffers 消息类）和 `hello_grpc_web_pb.js`（gRPC-Web 客户端存根）。 -内容类型支持 `application/grpc-web`、`application/grpc-web-text`、`application/grpc-web+proto`、`application/grpc-web-text+proto`，详细信息请参考：[Protocol differences vs gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2) 。 +#### 创建客户端 -::: +创建 Node.js 项目并安装所需依赖： + +```shell +npm init -y +npm install xhr2 grpc-web google-protobuf +``` + +创建客户端文件： + +```js title="client.js" +const XMLHttpRequest = require('xhr2'); +const { HelloServiceClient } = require('./hello_grpc_web_pb'); +const { HelloRequest } = require('./hello_pb'); + +global.XMLHttpRequest = XMLHttpRequest; + +function sayHello(){ + const client = new HelloServiceClient('http://127.0.0.1:9080/grpc/web', null, { + format: 'text', + }); + const req = new HelloRequest(); + req.setGreeting('jack'); + + const call = client.sayHello(req, {}, (err, resp) => { + if (err) { + console.error('grpc error:', err.code, err.message); + } else { + console.log('reply:', resp.getReply()); + } + }); + + call.on('metadata', (metadata) => { + console.log('Response headers:', metadata); + }); +} + +function lotsOfReplies() { + const client = new HelloServiceClient('http://127.0.0.1:9080/grpc/web', null, { + format: 'text', + }); + const req = new HelloRequest(); + req.setGreeting('rep'); + const stream = client.lotsOfReplies(req, {}); + + stream.on('metadata', (metadata) => { Review Comment: `lotsOfReplies()` 函数仅注册了 `metadata` 监听器，没有处理实际的流式回复数据。读者按此示例运行时，只能看到响应头日志，无法看到任何流式回复内容。请补充 `data` 和 `end` 处理器，使示例完整可验证，例如： ```js stream.on('data', (response) => { console.log('Reply:', response.getReply()); }); stream.on('end', () => { console.log('Stream ended'); }); stream.on('error', (err) => { console.error('Error:', err); }); ``` ########## docs/en/latest/plugins/grpc-web.md: ########## @@ -51,52 +89,149 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Prerequisites + +Before proceeding with the examples, complete the following steps to set up an upstream server and gRPC-Web client. + +#### Start an Upstream Server + +Start a [grpcbin server](https://github.com/moul/grpcbin) to serve as the example upstream: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri":"/grpc/web/*", - "plugins":{ - "grpc-web":{} - }, - "upstream":{ - "scheme":"grpc", - "type":"roundrobin", - "nodes":{ - "127.0.0.1:1980":1 - } - } -}' +docker run -d \ + --name grpcbin \ + -p 9000:9000 \ + moul/grpcbin ``` -## Example usage +#### Generate gRPC-Web Client Code -Refer to [gRPC-Web Client Runtime Library](https://www.npmjs.com/package/grpc-web) or [Apache APISIX gRPC Web Test Framework](https://github.com/apache/apisix/tree/master/t/plugin/grpc-web) to learn how to setup your web client. +Download the Protocol Buffer definition `hello.proto`: -Once you have your gRPC Web client running, you can make a request to APISIX from the browser or through Node.js. +```shell +curl -O https://raw.githubusercontent.com/moul/pb/refs/heads/master/hello/hello.proto +``` -:::note +Install [`protobuf`](https://github.com/protocolbuffers/protobuf/releases) and [`protoc-gen-grpc-web`](https://github.com/grpc/grpc-web/releases). -The supported request methods are `POST` and `OPTIONS`. See [CORS support](https://github.com/grpc/grpc-web/blob/master/doc/browser-features.md#cors-support). +Generate the gRPC-Web client code from `hello.proto`: -The supported `Content-Type` includes `application/grpc-web`, `application/grpc-web-text`, `application/grpc-web+proto`, and `application/grpc-web-text+proto`. See [Protocol differences vs gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2). +```shell +protoc \ + --js_out=import_style=commonjs:. \ + --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. \ + hello.proto +``` -::: +You should see two files generated in the current directory: `hello_pb.js` for Protocol Buffers message classes and `hello_grpc_web_pb.js` for gRPC-Web client stubs. -## Delete Plugin +#### Create a Client -To remove the `grpc-web` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Create a Node.js project and install the required dependencies: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +npm init -y +npm install xhr2 grpc-web google-protobuf +``` + +Create a client file: + +```js title="client.js" +const XMLHttpRequest = require('xhr2'); +const { HelloServiceClient } = require('./hello_grpc_web_pb'); +const { HelloRequest } = require('./hello_pb'); + +global.XMLHttpRequest = XMLHttpRequest; + +function sayHello(){ + const client = new HelloServiceClient('http://127.0.0.1:9080/grpc/web', null, { + format: 'text', + }); + const req = new HelloRequest(); + req.setGreeting('jack'); + + const call = client.sayHello(req, {}, (err, resp) => { + if (err) { + console.error('grpc error:', err.code, err.message); + } else { + console.log('reply:', resp.getReply()); + } + }); + + call.on('metadata', (metadata) => { + console.log('Response headers:', metadata); + }); +} + +function lotsOfReplies() { + const client = new HelloServiceClient('http://127.0.0.1:9080/grpc/web', null, { + format: 'text', + }); + const req = new HelloRequest(); + req.setGreeting('rep'); + const stream = client.lotsOfReplies(req, {}); + + stream.on('metadata', (metadata) => { Review Comment: The `lotsOfReplies()` function only attaches a `metadata` listener on the stream — it never handles the actual reply data. Readers running this example will see the headers log but none of the streamed replies. Please add a `data` handler (and ideally an `end` handler) so the example is complete and observable, e.g.: ```js stream.on('data', (response) => { console.log('Reply:', response.getReply()); }); stream.on('end', () => { console.log('Stream ended'); }); stream.on('error', (err) => { console.error('Error:', err); }); ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
