Compare commits

...

3 Commits
2.0.0 ... main

Author SHA1 Message Date
Rick Newton-Rogers 5a53247bc4
Correct Generating-stubs.md example JSON (#76)
I believe the example JSON is missing a comma so I inserted it; then
fixed up other JSON issues.
2025-07-08 16:20:35 +01:00
George Barnett 8125093686
Document how to create a public service with private implementation (#73)
Motivation:

Sometimes libraries want to vend a public gRPC service but without
exposing the generated types as part of the public API. This is easy to
achieve but non-obvious.

Modifications:

- Add an article explaining how to achieve this

Result:

Easier for users to learn how to do this
2025-06-04 10:20:45 +01:00
George Barnett 6bd6c50372
Fix some incorrect docs on protoc options (#71)
Motivation:

In #70 the protoc plugin got renamed, some of the docs weren't updated
appropriately.

Modifications:

- Update the docs

Result:

More accurate docs
2025-06-02 14:32:37 +00:00
3 changed files with 64 additions and 18 deletions

View File

@ -56,18 +56,18 @@ You must name the file `grpc-swift-proto-generator-config.json` and structure it
"generate": {
"clients": true,
"servers": true,
"messages": true,
"messages": true
},
"generatedSource": {
"accessLevelOnImports": false,
"accessLevel": "internal",
}
"protoc": {
"executablePath": "/opt/homebrew/bin/protoc"
"importPaths": [
"../directory_1",
],
"accessLevel": "internal"
},
"protoc": {
"executablePath": "/opt/homebrew/bin/protoc",
"importPaths": [
"../directory_1"
]
}
}
```
@ -98,37 +98,37 @@ lower in the file hierarchy supersedes one above it.
The [`grpc-swift-protobuf`](https://github.com/grpc/grpc-swift-protobuf) package provides
`protoc-gen-grpc-swift-2`, a program which is a plugin for the Protocol Buffers compiler, `protoc`.
To generate gRPC stubs for your `.proto` files directly you must run the `protoc` command with
the `--grpc-swift_out=<DIRECTORY>` option:
the `--grpc-swift-2_out=<DIRECTORY>` option:
```console
protoc --grpc-swift_out=. my-service.proto
protoc --grpc-swift-2_out=. my-service.proto
```
> `protoc-gen-grpc-swift-2` only generates gRPC stubs, it doesn't generate messages. You must use
> `protoc-gen-swift` to generate messages in addition to gRPC Stubs.
The presence of `--grpc-swift_out` tells `protoc` to use the `protoc-gen-grpc-swift-2` plugin. By
The presence of `--grpc-swift-2_out` tells `protoc` to use the `protoc-gen-grpc-swift-2` plugin. By
default it'll look for the plugin in your `PATH`. You can also specify the path to the plugin
explicitly:
```console
protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift_out=. my-service.proto
protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto
```
You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using
the `--grpc-swift_opt` argument:
the `--grpc-swift-2_opt` argument:
```console
protoc --grpc-swift_opt=<OPTION_NAME>=<OPTION_VALUE> --grpc-swift_out=.
protoc --grpc-swift-2_opt=<OPTION_NAME>=<OPTION_VALUE> --grpc-swift-2_out=.
```
You can specify multiple options by passing the `--grpc-swift_opt` argument multiple times:
You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times:
```console
protoc \
--grpc-swift_opt=<OPTION_NAME1>=<OPTION_VALUE1> \
--grpc-swift_opt=<OPTION_NAME2>=<OPTION_VALUE2> \
--grpc-swift_out=.
--grpc-swift-2_opt=<OPTION_NAME1>=<OPTION_VALUE1> \
--grpc-swift-2_opt=<OPTION_NAME2>=<OPTION_VALUE2> \
--grpc-swift-2_out=.
```
#### Generator options

View File

@ -0,0 +1,45 @@
# Public services with private implementations
Learn how to create a `public` gRPC service with private implementation details.
## Overview
It's not uncommon for a library to provide a gRPC service as part of its API.
For example, the gRPC Swift Extras package provides implementations of the gRPC
health and reflection services. Making the implementation of a service `public`
would require its generated gRPC and message types to also be `public`. This is
undesirable as it leaks implementation details into the public API of the
package. This article explains how to keep the generated types private while
making the service available as part of the public API.
## Hiding the implementation
You can hide the implementation details of your service by providing a wrapper
type conforming to `RegistrableRPCService`. This is the protocol used by
`GRPCServer` to register service methods with the server's router. Implementing
`RegistrableRPCService` is straightforward and can delegate to the underlying
service. This is demonstrated in the following code:
```swift
public struct GreeterService: RegistrableRPCService {
private var base: Greeter
public init() {
self.base = Greeter()
}
public func registerMethods<Transport>(
with router: inout RPCRouter<Transport>
) where Transport: ServerTransport {
self.base.registerMethods(with: &router)
}
}
```
In this example `Greeter` implements the underlying service and would conform to
the generated service protocol but would have a non-public access level.
`GreeterService` is a public wrapper type conforming to `RegistrableRPCService`
which implements its only requirement, `registerMethods(with:)`, by calling
through to the underlying implementation. The result is a service which can be
registered with a server where none of the generated types are part of the
public API.

View File

@ -23,6 +23,7 @@ This package provides three products:
- <doc:Generating-stubs>
- <doc:API-stability-of-generated-code>
- <doc:Understanding-the-generated-code>
- <doc:Public-services-with-private-implementations>
### Serialization