grpcgen

Documentation

Overview

Package grpcgen generates idiomatic Go server and client wrappers for gRPC services defined in proto files.

Index

• func GenerateClient(specPath string, overlayPath string, outputDir string, goModule string, ...) error
• func GenerateCompositeClient(entries []CompositeEntry, outputDir, goModule string) error
• func GenerateCompositeServer(entries []CompositeEntry, outputDir, goModule, jniModule string) error
• func MergeClientData(dst, src *ClientData)
• func MergeServerData(dst, src *ServerData)
• func WriteClient(data *ClientData, outputDir string) error
• func WriteServer(data *ServerData, outputDir string) error
• type ClientData
  • func BuildClientFromMergedProto(specPath, overlayPath, goModule string, mergedProto *protogen.ProtoData, ...) (*ClientData, error)
  • func BuildClientFromSpec(specPath, overlayPath, goModule, protoDir string) (*ClientData, error)
• type ClientDataClass
• type ClientDataClassField
• type ClientMethod
• type ClientParam
• type ClientService
• type CompositeEntry
  • func EntriesFromServerData(data *ServerData) []CompositeEntry
  • func GenerateServer(specPath string, overlayPath string, outputDir string, goModule string, ...) ([]CompositeEntry, error)
• type ServerData
  • func BuildServerFromMergedProto(specPath, overlayPath, goModule, jniModule string, ...) (*ServerData, error)
  • func BuildServerFromSpec(specPath, overlayPath, goModule, jniModule, protoDir string) (*ServerData, error)
• type ServerDataClass
• type ServerDataClassField
• type ServerMethod
• type ServerService

Functions

func GenerateClient

func GenerateClient(
	specPath string,
	overlayPath string,
	outputDir string,
	goModule string,
	protoDir string,
) error

GenerateClient loads a Java API spec and overlay, merges them, builds client data structures, and writes a gRPC client implementation file. protoDir is the base directory containing compiled proto Go stubs (for name resolution).

func GenerateCompositeClient

func GenerateCompositeClient(entries []CompositeEntry, outputDir, goModule string) error

GenerateCompositeClient generates grpc/client/client.go which provides a unified Client with all per-package clients.

func GenerateCompositeServer

func GenerateCompositeServer(entries []CompositeEntry, outputDir, goModule, jniModule string) error

GenerateCompositeServer generates grpc/server/server.go which registers all per-package gRPC service servers.

func MergeClientData

func MergeClientData(dst, src *ClientData)

MergeClientData combines two ClientData for the same package. Services and data classes from src are appended to dst, deduplicating by name.

func MergeServerData

func MergeServerData(dst, src *ServerData)

MergeServerData combines two ServerData for the same package.

func WriteClient

func WriteClient(data *ClientData, outputDir string) error

WriteClient writes a ClientData to its package directory.

func WriteServer

func WriteServer(data *ServerData, outputDir string) error

WriteServer writes a ServerData to its package directory.

Types

type ClientData

type ClientData struct {
	Package     string          // Go package name, e.g. "location"
	GoModule    string          // Go module path, e.g. "github.com/AndroidGoLab/jni"
	Services    []ClientService // One per gRPC service in the package
	DataClasses []ClientDataClass
}

ClientData holds all information needed to render a gRPC client file.

func BuildClientFromMergedProto

func BuildClientFromMergedProto(specPath, overlayPath, goModule string, mergedProto *protogen.ProtoData, goNames protoscan.GoNames) (*ClientData, error)

BuildClientFromMergedProto builds client data using pre-merged ProtoData. This ensures message collision renames are reflected in the RPC lookup.

func BuildClientFromSpec

func BuildClientFromSpec(specPath, overlayPath, goModule, protoDir string) (*ClientData, error)

BuildClientFromSpec loads a spec/overlay pair and returns client data. Returns nil if the spec produces no services.

type ClientDataClass

type ClientDataClass struct {
	GoType string
	Fields []ClientDataClassField
}

ClientDataClass describes a data class used for result conversion in the client.

type ClientDataClassField

type ClientDataClassField struct {
	GoName    string // Field name in the Go struct
	ProtoName string // Field name in the proto message
	GoType    string // Go type
	ProtoType string // Proto Go type (may differ, e.g. int32 vs int16)
}

ClientDataClassField describes a field in a data class for client-side conversion.

type ClientMethod

type ClientMethod struct {
	GoName       string // Exported Go method name on the client, e.g. "GetLastKnownLocation"
	RequestType  string // Proto request message type
	ResponseType string // Proto response message type
	// Params to accept in the Go API.
	Params []ClientParam
	// Return type information.
	ReturnKind   string // "void", "string", "bool", "primitive", "data_class", "object"
	GoReturnType string // Go type of the result, e.g. "bool", "string", "int32"
	DataClass    string // If returning a data class, its Go type
	HasError     bool   // Whether the underlying method returns error
	HasResult    bool   // Whether the method returns a non-void value
	// Pre-rendered expression for extracting the result from the response.
	ResultExpr string // e.g. "resp.Result", "resp.GetResult()"
}

ClientMethod describes a single client RPC wrapper method.

type ClientParam

type ClientParam struct {
	GoName    string // Go parameter name
	GoType    string // Go type
	ProtoName string // Corresponding proto field name (exported)
	IsObject  bool   // Whether this is an object handle (int64 in proto)
}

ClientParam describes a parameter in the client's Go API.

type ClientService

type ClientService struct {
	GoType      string // Short name, e.g. "Manager"
	ServiceName string // Proto service name, e.g. "ManagerService"
	Methods     []ClientMethod
}

ClientService describes a gRPC service client wrapper.

type CompositeEntry

type CompositeEntry struct {
	Package      string // Go package name, e.g. "location"
	GoType       string // Server type name, e.g. "Manager"
	ServiceName  string // Proto service name, e.g. "ManagerService"
	NeedsHandles bool   // Whether the service needs an object handle store
}

CompositeEntry describes a generated per-package server or client for use in the composite registration/client file.

func EntriesFromServerData

func EntriesFromServerData(data *ServerData) []CompositeEntry

EntriesFromServerData extracts CompositeEntry records from a ServerData.

func GenerateServer

func GenerateServer(
	specPath string,
	overlayPath string,
	outputDir string,
	goModule string,
	jniModule string,
	protoDir string,
) ([]CompositeEntry, error)

GenerateServer loads a Java API spec and overlay, merges them, builds server data structures, and writes a gRPC server implementation file. It returns composite entries for each service generated (for use in the composite server registration file).

type ServerData

type ServerData struct {
	Package      string // Go package name, e.g. "location"
	GoModule     string // Go module path for proxy code, e.g. "github.com/AndroidGoLab/jni-proxy"
	JniModule    string // Go module path for the JNI bindings, e.g. "github.com/AndroidGoLab/jni"
	GoImport     string // Go import of the javagen package, e.g. "github.com/AndroidGoLab/jni/location"
	NeedsJNI     bool   // Whether the generated code needs to import the jni package
	NeedsHandles bool   // Whether the generated code needs to import the grpcserver handles package
	Services     []ServerService
	DataClasses  []ServerDataClass
}

ServerData holds all information needed to render a gRPC server file.

func BuildServerFromMergedProto

func BuildServerFromMergedProto(specPath, overlayPath, goModule, jniModule string, mergedProto *protogen.ProtoData, goNames protoscan.GoNames) (*ServerData, error)

BuildServerFromMergedProto builds server data using pre-merged ProtoData.

func BuildServerFromSpec

func BuildServerFromSpec(specPath, overlayPath, goModule, jniModule, protoDir string) (*ServerData, error)

BuildServerFromSpec loads a spec/overlay pair and returns server data. Returns nil if the spec produces no services.

type ServerDataClass

type ServerDataClass struct {
	GoType string
	Fields []ServerDataClassField
}

ServerDataClass describes a data class used for result conversion.

type ServerDataClassField

type ServerDataClassField struct {
	GoName    string
	ProtoName string
	GoType    string
}

ServerDataClassField describes a field in a data class.

type ServerMethod

type ServerMethod struct {
	GoName        string // Go method name on the gRPC service interface, e.g. "GetLastKnownLocation"
	SpecGoName    string // Go method name in the javagen code, e.g. "GetLastKnownLocation" or "getProvidersRaw"
	RequestType   string // Proto request message type, e.g. "GetLastKnownLocationRequest"
	ResponseType  string // Proto response message type, e.g. "GetLastKnownLocationResponse"
	CallArgs      string // Pre-rendered Go arguments, e.g. "req.GetProvider()"
	ReturnKind    string // "void", "string", "bool", "object", "primitive", "data_class"
	DataClass     string // If returning a data class, its Go type, e.g. "Location"
	HasError      bool   // Whether the javagen method returns error
	HasResult     bool   // Whether the javagen method returns a non-void value
	GoReturnType  string // Go type of the return value, e.g. "bool", "string", "*jni.Object"
	NeedsHandles  bool   // Whether any param or return uses object handles
	IsConstructor bool   // Whether this is the constructor RPC for a constructor class
	// Pre-rendered conversion expression for result assignment in proto response.
	ResultExpr string // e.g. "result", "int32(result)"
	// Pre-rendered data class conversion for the response.
	DataClassConversion string // e.g. "&pb.Location{\n\tLatitude: result.Latitude,\n...}"
}

ServerMethod describes a single RPC method implementation.

type ServerService

type ServerService struct {
	GoType            string // javagen type name, e.g. "Manager", "Adapter"
	ServiceName       string // proto service name, e.g. "ManagerService"
	GoImport          string // Go import path for the javagen package, e.g. "github.com/AndroidGoLab/jni/location"
	ImportAlias       string // import alias for the javagen package, e.g. "jnipkg" or "jnipkg2"
	Obtain            string // how the manager is obtained: "system_service", etc.
	InstantiationKind string // "system_service" or "constructor"
	Close             bool   // whether manager has Close()
	Methods           []ServerMethod
	NeedsHandles      bool // whether any method uses object handles
}

ServerService describes a gRPC service backed by a javagen-generated class.