This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit e076552b648ef8f7d3e0cac2da2a9e174eaa3448
Author: chaokunyang <[email protected]>
AuthorDate: Sun Aug 2 17:15:50 2026 +0000

    🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
 docs/guide/cpp/grpc-support.md | 277 +++++++++++++++++++++++++++++++++++++++++
 docs/guide/cpp/index.md        |   1 +
 2 files changed, 278 insertions(+)

diff --git a/docs/guide/cpp/grpc-support.md b/docs/guide/cpp/grpc-support.md
new file mode 100644
index 0000000000..4fe547d32c
--- /dev/null
+++ b/docs/guide/cpp/grpc-support.md
@@ -0,0 +1,277 @@
+---
+title: gRPC Support
+sidebar_position: 12
+id: grpc_support
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Fory can generate C++ gRPC service companions for schemas that define services.
+The generated code uses gRPC C++ for transport and Fory for request and
+response payload serialization. It requires gRPC C++ 1.39.0 or later.
+
+Use this mode when every RPC peer is generated from the same Fory IDL, protobuf
+IDL, or FlatBuffers IDL and you want gRPC transport semantics with Fory payload
+encoding. Use standard protobuf gRPC code generation when clients or tools must
+consume protobuf message bytes directly.
+
+## Add Dependencies
+
+With Bazel, use the Fory label that is visible from your workspace.
+The example below is for a project that consumes Fory as an external module 
named `fory`:
+
+```bazel
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+    name = "greeter_generated",
+    srcs = ["generated/demo_greeter.service.grpc.cc"],
+    hdrs = glob(["generated/*.h"]),
+    includes = ["generated"],
+    deps = [
+        "@fory//cpp/fory/serialization:fory_serialization",
+        "@grpc//:grpc++",
+    ],
+)
+```
+
+Inside the Fory repository, use `//cpp/fory/serialization:fory_serialization`
+instead of `@fory//cpp/fory/serialization:fory_serialization`.
+
+With CMake, make the Fory C++ target visible first. For an installed Fory
+package, use `find_package(Fory CONFIG REQUIRED)`, then add the generated 
source
+and link both libraries explicitly:
+
+```cmake
+find_package(Fory CONFIG REQUIRED)
+find_package(gRPC 1.39.0 CONFIG REQUIRED)
+
+add_library(greeter_generated
+    generated/demo_greeter.service.grpc.cc
+)
+target_compile_features(greeter_generated PUBLIC cxx_std_17)
+target_include_directories(greeter_generated PUBLIC generated)
+target_link_libraries(greeter_generated PUBLIC
+    fory::serialization
+    gRPC::grpc++
+)
+```
+
+If your project brings Fory in with `FetchContent` or `add_subdirectory`, call
+that before linking `fory::serialization`.
+
+Use dependency versions that are compatible with the rest of your service
+stack.
+
+## Define a Service
+
+Service definitions can come from Fory IDL, protobuf IDL, or FlatBuffers
+`rpc_service` definitions. A Fory IDL service looks like this:
+
+```protobuf
+package demo.greeter;
+
+message HelloRequest {
+  string name = 1;
+}
+
+message HelloReply {
+  string reply = 1;
+}
+
+service Greeter {
+  rpc SayHello (HelloRequest) returns (HelloReply);
+}
+```
+
+Generate C++ model and gRPC companion code with `--grpc`:
+
+```bash
+foryc service.fdl --cpp_out=./generated/cpp --grpc
+```
+
+For this schema, the C++ generator emits:
+
+| File                           | Purpose                                     
       |
+| ------------------------------ | 
-------------------------------------------------- |
+| `demo_greeter.h`               | Fory model types and registration helpers   
       |
+| `demo_greeter.service.h`       | Synchronous service interface and path 
constants   |
+| `demo_greeter.service.grpc.h`  | Synchronous client, server adapter, and 
Fory codec |
+| `demo_greeter.service.grpc.cc` | Stub calls and server route implementations 
       |
+
+Include the generated gRPC header from application code and compile
+`demo_greeter.service.grpc.cc` once in your build target. The codec is 
generated
+directly in the gRPC header; there is no separate Fory gRPC runtime source 
file.
+
+## Implement a Server
+
+Implement the generated synchronous interface and register the generated server
+adapter with a normal gRPC C++ server.
+
+```cpp
+#include "demo_greeter.service.grpc.h"
+
+#include <memory>
+#include <grpcpp/server_builder.h>
+#include <grpcpp/security/server_credentials.h>
+
+class MyGreeter final : public demo::greeter::service::Greeter {
+ public:
+  ::grpc::Status SayHello(::grpc::ServerContext* context,
+                          const ::demo::greeter::HelloRequest* request,
+                          ::demo::greeter::HelloReply* response) override {
+    (void)context;
+    response->set_reply("Hello, " + request->name());
+    return ::grpc::Status::OK;
+  }
+};
+
+MyGreeter implementation;
+demo::greeter::service::grpc::GreeterServiceGrpc service(&implementation);
+::grpc::ServerBuilder builder;
+builder.AddListeningPort("0.0.0.0:50051", ::grpc::InsecureServerCredentials());
+builder.RegisterService(&service);
+std::unique_ptr<::grpc::Server> server = builder.BuildAndStart();
+server->Wait();
+```
+
+Generated request and response types are serialized by the generated service
+code, so service implementations do not perform manual Fory registration.
+
+## Create a Client
+
+Use the generated synchronous client stub:
+
+```cpp
+#include "demo_greeter.service.grpc.h"
+
+#include <iostream>
+#include <grpcpp/create_channel.h>
+#include <grpcpp/security/credentials.h>
+
+auto channel =
+    ::grpc::CreateChannel("localhost:50051", 
::grpc::InsecureChannelCredentials());
+auto stub = demo::greeter::service::grpc::GreeterStub::NewStub(channel);
+
+demo::greeter::HelloRequest request;
+request.set_name("Fory");
+demo::greeter::HelloReply response;
+::grpc::ClientContext context;
+::grpc::Status status = stub->SayHello(&context, request, &response);
+if (status.ok()) {
+  std::cout << response.reply() << std::endl;
+}
+```
+
+gRPC C++ still owns channel configuration, credentials, deadlines, metadata,
+cancellation, retry policy, and transport lifecycle.
+
+## Streaming RPCs
+
+Fory service definitions can use unary, server-streaming, client-streaming, and
+bidirectional streaming RPC shapes:
+
+```protobuf
+service Greeter {
+  rpc SayHello (HelloRequest) returns (HelloReply);
+  rpc LotsOfReplies (HelloRequest) returns (stream HelloReply);
+  rpc LotsOfGreetings (stream HelloRequest) returns (HelloReply);
+  rpc Chat (stream HelloRequest) returns (stream HelloReply);
+}
+```
+
+Generated C++ code follows synchronous gRPC C++ conventions:
+
+- Unary methods return `grpc::Status` and use request and response pointers.
+- Server-streaming methods return `std::unique_ptr<grpc::ClientReader<U>>` on
+  clients and receive `grpc::ServerWriter<U>*` on servers.
+- Client-streaming methods return `std::unique_ptr<grpc::ClientWriter<T>>` on
+  clients and receive `grpc::ServerReader<T>*` on servers.
+- Bidirectional methods return
+  `std::unique_ptr<grpc::ClientReaderWriter<T, U>>` on clients and receive
+  `grpc::ServerReaderWriter<U, T>*` on servers.
+- The generated codec is used for every message frame, including streaming
+  frames.
+
+Use the generated method signatures as the source of truth for concrete request
+and response types in your service implementation:
+
+```cpp
+::grpc::Status LotsOfReplies(
+    ::grpc::ServerContext* context,
+    const ::demo::greeter::HelloRequest* request,
+    ::grpc::ServerWriter<::demo::greeter::HelloReply>* writer) override {
+  (void)context;
+  ::demo::greeter::HelloReply reply;
+  reply.set_reply("Hello, " + request->name());
+  writer->Write(reply);
+  reply.set_reply("Welcome, " + request->name());
+  writer->Write(reply);
+  return ::grpc::Status::OK;
+}
+```
+
+Generated clients return standard gRPC C++ streaming helpers:
+
+```cpp
+demo::greeter::HelloRequest request;
+request.set_name("Fory");
+
+::grpc::ClientContext context;
+auto reader = stub->LotsOfReplies(&context, request);
+demo::greeter::HelloReply reply;
+while (reader->Read(&reply)) {
+  std::cout << reply.reply() << std::endl;
+}
+::grpc::Status status = reader->Finish();
+```
+
+Complete client streams with `WritesDone()` and always call `Finish()` to 
obtain
+the final status.
+
+The generated descriptors preserve the exact IDL service and method names for
+the gRPC path.
+
+## gRPC Runtime Behavior
+
+The generated service companion only supplies Fory serialization and gRPC C++
+bindings. Operational behavior remains standard gRPC C++ behavior:
+
+- Deadlines and cancellations
+- TLS and authentication
+- Status codes and metadata
+- Channel and server lifecycle
+- Synchronous streaming backpressure
+
+## Troubleshooting
+
+### Missing gRPC C++ Headers or Symbols
+
+Add the gRPC C++ dependency shown above to the target that compiles the
+generated service files, and compile the generated `.service.grpc.cc` file
+exactly once.
+
+### `UNIMPLEMENTED`
+
+Confirm that the generated server adapter was registered with
+`ServerBuilder::RegisterService(...)`, and that the client and server were
+generated from the same package, service, and method names.
+
+### Protobuf Clients Cannot Decode the Service
+
+Fory gRPC companions do not use protobuf wire encoding for messages. Use a
+Fory-generated client for Fory-generated services, or provide a separate
+protobuf service endpoint for generic protobuf clients.
diff --git a/docs/guide/cpp/index.md b/docs/guide/cpp/index.md
index d3a0f5c0e5..b20df8a572 100644
--- a/docs/guide/cpp/index.md
+++ b/docs/guide/cpp/index.md
@@ -282,3 +282,4 @@ std::thread t2([&]() {
 - [Supported Types](supported-types.md) - All supported types
 - [Custom Serializers](custom-serializers.md) - Extend serialization behavior
 - [Row Format](row-format.md) - Zero-copy row-based format
+- [gRPC Support](grpc-support.md) - Fory payloads over gRPC C++


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to