title: Overview sidebar_position: 1 id: index 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 gRPC combines normal gRPC transport semantics with request and response models generated by the Fory compiler. The payload marshaller uses Fory rather than protobuf message bytes.

When to Use It

Use Fory gRPC when every peer is generated from the same Fory IDL, protobuf IDL, or FlatBuffers IDL contract and supports the matching Fory implementation for its language. Use ordinary protobuf gRPC when generic protobuf clients, reflection tools, or protobuf message bytes are required.

Schema Frontends

Fory gRPC companions can be generated from:

The compiler's Generated Code reference describes the model and service artifacts. Use Build Integration to wire generation into a project build.

Workflow

  1. Define messages and services in a supported compiler frontend.
  2. Generate models and gRPC companions with foryc.
  3. Add the normal gRPC dependencies for the selected language.
  4. Implement the generated server base and call the generated client.
  5. Verify unary and streaming calls between generated peers.

Python generates asynchronous grpc.aio companions by default and supports sync generation with --grpc-python-mode=sync. JavaScript uses @grpc/grpc-js for Node.js; browser clients are generated separately with --grpc-web and use grpc-web.

Architecture

Generated service companions use normal gRPC servers, channels, method descriptors, deadlines, status codes, interceptors, and streaming APIs. Fory-generated marshallers encode and decode the generated request and response models.

Ownership Boundary

Fory can generate service companions for application-provided gRPC implementations. Those companions provide Fory serialization for request and response objects; the application and gRPC stack still own listeners, channels, credentials, authentication, authorization, deadlines, retries, and transport lifecycle.

Fory packages do not add a gRPC implementation as a hard dependency. The application selects and configures its gRPC libraries.

Generated Service Surface

The compiler emits language-idiomatic service bases, clients or stubs, method metadata, and Fory marshallers. Model generation is documented under Generated Code; the language pages document server and client integration.

Interoperability

Fory gRPC peers interoperate only when they use the same generated service contract, matching Fory type identities, and compatible generated model schemas.

Protocol Boundary

The transport is gRPC, but the message bytes are Fory payloads. Generic protobuf clients and server reflection tools cannot decode those payloads as protobuf messages. Generate every peer through a supported Fory compiler frontend.

Verification

Test at least one unary call and every streaming shape used by the service. A protobuf UNIMPLEMENTED or decode failure usually means the peer used an ordinary protobuf stub or a different generated service contract.

Language Guides

Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, and Kotlin have documented gRPC companions. Use the support matrix and the selected language page for current dependencies and streaming support.

LanguageGuide
JavaJava
PythonPython
C++C++
GoGo
RustRust
JavaScript/TypeScriptNode.js and gRPC-Web
C#C#
DartDart
ScalaScala
KotlinKotlin