You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/08/24 03:57:27 UTC
(fory-site) 04/04: 🔄 synced local 'docs/grpc/' with remote 'docs/grpc/'
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 c18d76ed26eabed4e9df265b17279fa45955cb02
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Mon Aug 24 03:57:18 2026 +0000
🔄 synced local 'docs/grpc/' with remote 'docs/grpc/'
---
docs/grpc/index.md | 3 +-
docs/grpc/swift.md | 243 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 245 insertions(+), 1 deletion(-)
diff --git a/docs/grpc/index.md b/docs/grpc/index.md
index 0aae10ce695..5dcb86f9d8b 100644
--- a/docs/grpc/index.md
+++ b/docs/grpc/index.md
@@ -96,7 +96,7 @@ different generated service contract.
## Language Guides
-Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, and Kotlin have documented gRPC
+Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin have documented gRPC
companions. Use the [support matrix](../introduction/support-matrix.md) and the selected language page
for current dependencies and streaming support.
@@ -112,3 +112,4 @@ for current dependencies and streaming support.
| Dart | [Dart](dart.md) |
| Scala | [Scala](scala.md) |
| Kotlin | [Kotlin](kotlin.md) |
+| Swift | [Swift](swift.md) |
diff --git a/docs/grpc/swift.md b/docs/grpc/swift.md
new file mode 100644
index 00000000000..34702f9fdd5
--- /dev/null
+++ b/docs/grpc/swift.md
@@ -0,0 +1,243 @@
+---
+title: Swift gRPC
+sidebar_position: 14
+id: swift
+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 Swift gRPC service companions for schemas that define
+services. The companion provides the usual gRPC service providers, clients,
+method descriptors, and service metadata, while request and response objects are
+serialized with Fory instead of protobuf.
+
+Use this mode when both RPC peers are generated from the same Fory IDL, protobuf
+IDL, or FlatBuffers IDL and both sides expect Fory-encoded message bodies. Use
+normal protobuf gRPC generation for APIs that must be consumed by generic
+protobuf clients, reflection tools, or components that expect protobuf bytes.
+
+The companion targets [grpc-swift](https://github.com/grpc/grpc-swift) 1.x. That
+line keeps the same platform floor as the Fory Swift package (macOS 13, iOS 16);
+grpc-swift 2.x requires a newer floor.
+
+## Add Dependencies
+
+The `Fory` package does not depend on grpc-swift. Add grpc-swift in the package
+that compiles or runs the generated companions:
+
+```swift
+// Package.swift
+dependencies: [
+ .package(url: "https://github.com/apache/fory.git", exact: "$version"),
+ .package(url: "https://github.com/grpc/grpc-swift.git", from: "1.23.0"),
+],
+targets: [
+ .target(
+ name: "App",
+ dependencies: [
+ .product(name: "Fory", package: "fory"),
+ .product(name: "GRPC", package: "grpc-swift"),
+ ]
+ )
+]
+```
+
+## 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 Swift model and gRPC companion code with `--grpc`:
+
+```bash
+foryc service.fdl --swift_out=./Sources/App --grpc
+```
+
+For this schema the Swift generator emits:
+
+| File | Purpose |
+| -------------------------------- | -------------------------------------------- |
+| `demo/greeter/greeter.swift` | Fory model types and the `ForyModule` helper |
+| `demo/greeter/GreeterGrpc.swift` | gRPC providers, client, and service metadata |
+
+Generated gRPC symbols are prefixed with the package, so the schema above emits
+`Demo_Greeter_GreeterAsyncProvider`, `Demo_Greeter_GreeterAsyncClient`, and
+`Demo_Greeter_GreeterProvider`. A schema with no package drops the prefix
+(`GreeterAsyncProvider`).
+
+## Implement a Server
+
+Conform a type to the generated `async`/`await` provider and host it with a
+normal grpc-swift `Server`:
+
+```swift
+import Fory
+import GRPC
+import NIOPosix
+
+final class GreeterService: Demo_Greeter_GreeterAsyncProvider {
+ func sayHello(
+ request: Demo.Greeter.HelloRequest,
+ context: GRPCAsyncServerCallContext
+ ) async throws -> Demo.Greeter.HelloReply {
+ Demo.Greeter.HelloReply(reply: "Hello, " + request.name)
+ }
+}
+
+let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+let server = try await Server.insecure(group: group)
+ .withServiceProviders([GreeterService()])
+ .bind(host: "127.0.0.1", port: 1234)
+ .get()
+```
+
+Request and response types are registered by the generated schema module that
+the companion uses, so server code does not register serializers by hand. An
+`EventLoopFuture`-based `Demo_Greeter_GreeterProvider` is also emitted for
+servers that do not use `async`/`await`.
+
+## Create a Client
+
+Use the generated async client over a grpc-swift channel:
+
+```swift
+import Fory
+import GRPC
+import NIOPosix
+
+let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+let channel = try GRPCChannelPool.with(
+ target: .host("127.0.0.1", port: 1234),
+ transportSecurity: .plaintext,
+ eventLoopGroup: group)
+
+let client = Demo_Greeter_GreeterAsyncClient(channel: channel)
+let reply = try await client.sayHello(Demo.Greeter.HelloRequest(name: "Fory"))
+print(reply.reply)
+```
+
+## Streaming RPCs
+
+Fory service definitions can use the four gRPC streaming shapes:
+
+```protobuf
+service Greeter {
+ rpc SayHello (HelloRequest) returns (HelloReply);
+ rpc LotsOfReplies (HelloRequest) returns (stream HelloReply);
+ rpc LotsOfGreetings (stream HelloRequest) returns (HelloReply);
+ rpc BidiHello (stream HelloRequest) returns (stream HelloReply);
+}
+```
+
+Streaming methods present clean request and response types. The provider receives
+a response writer (`send(_:)`) for server output and an `AsyncSequence` for client
+input; the client returns an `AsyncSequence` of responses for server-streamed
+replies:
+
+```swift
+// Server side
+func lotsOfReplies(
+ request: Demo.Greeter.HelloRequest,
+ responseStream: Demo_Greeter_GreeterAsyncResponseStream<Demo.Greeter.HelloReply>,
+ context: GRPCAsyncServerCallContext
+) async throws {
+ try await responseStream.send(Demo.Greeter.HelloReply(reply: "Hi " + request.name))
+}
+
+// Client side
+for try await reply in client.lotsOfReplies(Demo.Greeter.HelloRequest(name: "Fory")) {
+ print(reply.reply)
+}
+```
+
+## gRPC Runtime Behavior
+
+Generated companions carry Fory-encoded bytes inside a private `GRPCPayload`
+wrapper. The Swift `Fory` instance is single-threaded, so the wrapper uses one
+`Fory` per thread, built from the schema module's configuration and registrations,
+which makes concurrent RPCs safe without sharing a single instance. Imported
+request and response types resolve to their own namespace and are registered
+transitively through the owning module, so a service that crosses an import
+boundary works without extra registration.
+
+## Swift Language Mode
+
+Compile generated companions in Swift 5 language mode (use
+`swift-tools-version:5.9`, or set `swiftLanguageMode(.v5)` on the target in a
+6.x manifest). grpc-swift moves each request and response between the calling
+task and the event loop, so the wire wrapper requires a `Sendable` payload, and
+generated Fory Swift models do not declare that conformance. This applies to
+every call shape, including unary calls, not only the streaming ones.
+
+## Known Limitations
+
+The generated client is async/await only. grpc-swift's `EventLoopFuture` client
+returns call objects parameterized by the on-the-wire message type, which would
+expose the internal Fory wrapper, so it is not emitted. Both providers (async and
+`EventLoopFuture`) are generated.
+
+Interceptors are not generated. grpc-swift interceptors are typed on the
+on-the-wire message, which is the internal Fory wrapper; emitting interceptor
+hooks would expose that wrapper. Use a custom channel or server configuration for
+cross-cutting concerns instead.
+
+RPC names must produce a usable Swift member. The compiler rejects an rpc whose
+name is only underscores, because it normalizes to `_`, which Swift reserves for
+discards. It also rejects `handle`, `serviceName`, `channel`, and
+`defaultCallOptions`, which collide with members of the generated provider and
+client. Rename the rpc in the schema.
+
+Swift models put each package under a nested `enum` namespace, so two schemas that
+share a top-level package component (for example `demo.shared` and `demo.greeter`)
+both emit `public enum Demo`. The compiler rejects that with a top-level symbol
+collision before it writes either file. This is a model-generation behavior, not
+specific to gRPC, but it also affects a service that imports across such packages.
+Give the schemas disjoint top-level packages (for example `shared.models` and
+`greeter.api`). Generating into separate Swift modules with one `foryc` invocation
+each only helps unrelated schemas, because the preflight collects imports
+recursively: compiling `demo.greeter` still includes `demo.shared` in the graph and
+rejects the duplicate `Demo` even if the shared schema was generated in another
+invocation. An import graph needs disjoint top-level packages.
+
+## Troubleshooting
+
+### Missing grpc-swift Types
+
+If the build cannot find `GRPCAsyncServerCallContext`, `Server`, or
+`GRPCChannelPool`, add the grpc-swift dependency and the `GRPC` product to the
+target that compiles the generated companion.
+
+### Protobuf Clients Cannot Decode the Service
+
+Generated companions exchange Fory-encoded bodies, not protobuf bytes. A generic
+protobuf client cannot decode them. Both peers must be generated from the same
+Fory IDL and use the generated Fory companions.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org