grpc-swift/docs/api.md

gRPC Swift Public API

gRPC Swift follows Semantic Versioning 2.0.0 (SemVer) which requires that projects declare a public API.

For the purpose of this document we consider the gRPC Swift public API to be limited to:

1. the GRPC module (i.e., code in in Sources/GRPC), and
2. modules generated by the protoc-gen-grpc-swift plugin.

Below we cover what consitutes the public API of each, how to use them in an acceptable manner, and compatability between GRPC and modules generated by protoc-gen-grpc-swift.

GRPC and Generated Modules

All exported types and methods from the GRPC module and those generated by protoc-gen-grpc-swift are considered public API except for the following:

• types which are prefixed with an an underscore (_)
• all methods on types whose name is prefixed with an underscore (_)
• methods which are prefixed with an underscore (_)

Examples

• Server.insecure(group:) is part of the public API.
• _GRPCClientChannelHandler.channelRead(context:data:) is not part of the public API, the type _GRPCClientChannelHandler starts with an underscore.
• EmbeddedChannel._configureForEmbeddedServerTest() is not part of the public API, the method starts with an underscore.

Acceptable Use of the API

Conforming Types to Protocols

In gRPC Swift, and more generally Swift, it is only acceptable to conform a type to a protocol if you control either the type, the protocol, or both.

• You must not conform any types from GRPC or generated code to protocols which you do not own.
• You must not add conformance to protocols defined by GRPC or generated code for types you do not own.

Examples

• extension MyMessageSerializer: MessageSerializer { ... } is acceptable assuming MyMessageSerializer exists in your own codebase.
• extension GRPCPayloadSerializer: DebugStringConvertible { ... } is not acceptable, GRPCPayloadSerializer is defined in GRPC and DebugStringConvertible is a standard library protocol.

Extending GRPC or Generated Types

Extending GRPC or generated types with private or internal methods and properties is always allowed.

In order to avoid the potential for clashing names, extending GRPC or generated types with public methods and properties is acceptable if:

• The extension uses a type you own, either as a return type or as a non-default argument.
• The extension is prefixed with a name which will avoid avoid ambiguity (such as the name of your module).

Examples

The following is not acceptable since it is public and does not use a type owned by the implementer of the extension.

extension Server.Builder {
  public func withSignalHandler(_ handler: @escaping (Int) -> Void) -> Self {
    ...
  }
}

The following is acceptable, MySignal is defined in the same module as the extension and is used as a non-default argument.

public struct MySignal {
  public var signal: Int
}

extension Server.Builder {
  public func withSignalHandler(_ handler: @escaping (MySignal) -> Void) -> Self {
    ...
  }
}

The following is acceptable because the method is internal.

extension Server.Builder {
  internal func withSignalHandler(_ handler: @escaping (Int) -> Void) -> Self {
    ...
  }
}

Promises the GRPC team make

Before releasing a new major version, i.e. gRPC Swift 2.0.0, we promise that:

• None of the public API will be knowingly removed. We will restore any accidental removals as we become aware of them.
• All additions to the global namespace will be prefixed with GRPC or gRPC.

We may deprecate APIs before the next major release, however, they will remain supported.

Examples

• We might add a new type called GRPCChannelPool
• We might add a new module called GRPCTestKit
• We might add a new gloabl function called gRPCRun
• We will not add a new type called ChannelPool
• We will not add a new module called TestKit
• We will not add a new gloabl function called run

Generated Code

gRPC Swift generates code via its protoc plugin protoc-gen-grpc-swift. In order to develop the library over time without breaking existing generated code it is important to lay out any API and compatability guarantees.

Before releasing a new major version, i.e. gRPC Swift 2.0.0, we promise that:

• The GRPC module will be backward compatible with all code generated by the protoc-gen-grpc-swift plugin.
• Generated code will not have its API broken by being updated.

Examples

• Code generated with protoc-gen-grpc-swift 1.3.0 will always be compatible with GRPC 1.3.0 and higher.
• Code generated with protoc-gen-grpc-swift 1.5.0 offers no compatability guarantees compatible with GRPC versions lower than 1.5.0.