Documentation
¶
Overview ¶
Package svcdef provides a straightforward view of the Go code for a gRPC service defined using protocol buffers. Information is distilled from the .proto files comprising the definition, as well as the Go source files generated from those same .proto files.
Since svcdef is only meant to be used to generate Go code, svcdef has a limited view of the definition of the gRPC service.
Additionally, since svcdef only parses Go code generated by protoc-gen-go, all methods accept only ast types with structures created by protoc-gen-go. See NewTYPE functions such as NewMap for details on the relevant conventions.
Note that svcdef does not support embedding sub-fields of nested messages into the path of an HTTP annotation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DebugInfo ¶
DebugInfo contains context necessary for many functions to provide useful debugging output when encountering errors. All DebugInfo methods are implemented such that calling them with `nil` recievers means they'll return empty values. And since DebugInfo is used PURELY for creating nice error messages and no actual business logic depends on them, this means you can safely pass 'nil' DebugInfo structs to functions and you'll just get unhelpful error messages out, it won't break things. This is done to make the code more testable.
type Field ¶
type Field struct {
Name string
// PBFieldName is the string value of the field name in the definition .proto file.
// For Example: 'snake_case' from below -- where Name would be 'SnakeCase'
// `protobuf:"varint,1,opt,name=snake_case,json=snakeCase" json:"snake_case,omitempty"`
PBFieldName string
Type *FieldType
}
Field represents a field on a protobuf message.
type FieldType ¶
type FieldType struct {
// Name will contain the name of the type, for example "string" or "bool"
Name string
// Enum contains a pointer to the Enum type this fieldtype represents, if
// this FieldType represents an Enum. If not, Enum is nil.
Enum *Enum
// OneofTypes contains the array of types within a oneof block. If not, is nil
// Example proto:
// message {
// oneof daterange {
// int64 a = 1;
// int64 b = 2;
// }
// }
Oneof []*Field
// Message contains a pointer to the Message type this FieldType
// represents, if this FieldType represents a Message. If not, Message is
// nil.
Message *Message
// Map contains a pointer to the Map type this FieldType represents, if
// this FieldType represents a Map. If not, Map is nil.
Map *Map
// StarExpr is True if this FieldType represents a pointer to a type.
StarExpr bool
// ArrayType is True if this FieldType represents a slice of a type.
ArrayType bool
}
FieldType contains information about the type of one Field on a message, such as if that Field is a slice or if it's a pointer, as well as a reference to the definition of the type of this Field.
type HTTPBinding ¶
type HTTPBinding struct {
Verb string
Path string
// There is one HTTPParamter for each of the fields on parent service
// methods RequestType.
Params []*HTTPParameter
}
HTTPBinding represents one of potentially several bindings from a gRPC service method to a particuar HTTP path/verb.
type HTTPParameter ¶
type HTTPParameter struct {
// Field points to a Field on the Parent service methods "RequestType".
Field *Field
// Location will be either "body", "path", or "query"
Location string
}
HTTPParameter represents the location of one field for a given HTTPBinding. Each HTTPParameter corresponds to one Field of the parent ServiceMethod.RequestType.Fields
type LocationError ¶
LocationError is a special kind of error, carrying special information about where the error was encountered within a file.
func NewLocationError ¶
func NewLocationError(err string, path string, pos string) LocationError
func (LocationError) Error ¶
func (le LocationError) Error() string
func (LocationError) Location ¶
func (le LocationError) Location() string
type Map ¶
type Map struct {
// KeyType will always be a basetype, e.g. string, int64, etc.
KeyType *FieldType
ValueType *FieldType
}
func NewMap ¶
NewMap returns a new Map struct derived from an ast.Expr interface implemented by an *ast.MapType struct. This code cannot accept an arbitrary MapType, only one which follows the conventions of Go code generated by protoc-gen-go. Those conventions are:
- The KeyType of the *ast.MapType will always be an ast.Ident
- The ValueType may be an ast.Ident OR an ast.StarExpr -> ast.Ident
These rules are a result of the rules for map fields of Protobuf messages, namely that a key may only be represented by a non-float basetype (e.g. int64, string, etc.), and that a value may be either a basetype or a Message type or an Enum type. In the resulting Go code, a basetype will be represented as an ast.Ident, while a key that is a Message or Enum type will be represented as an *ast.StarExpr which references an ast.Ident.
type Service ¶
type Service struct {
Name string
Methods []*ServiceMethod
}
type ServiceMethod ¶
type ServiceMethod struct {
Name string
RequestType *FieldType
ResponseType *FieldType
// Bindings contains information for mapping http paths and paramters onto
// the fields of this ServiceMethods RequestType.
Bindings []*HTTPBinding
}
func NewServiceMethod ¶
func NewServiceMethod(m *ast.Field, info *DebugInfo) (*ServiceMethod, error)
NewServiceMethod returns a new ServiceMethod derived from a method of a Service interface. This is accepted in the form of an *ast.Field which contains the name of the method.
type Svcdef ¶
type Svcdef struct {
// PkgName will be the pacakge name of the go file(s) analyzed. So if a
// Go file contained "package authz", then PkgName will be "authz". If
// multiple Go files are analyzed, it will be the package name of the last
// go file analyzed.
PkgName string
Messages []*Message
Enums []*Enum
// Service contains the sole service for this Svcdef
Service *Service
}
Svcdef is the top-level struct for the definition of a service.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Svcparse, which stands for "service parser" will parse the 'service' declarations within a provided protobuf and associate comments within that file with the various components of the service.
|
Svcparse, which stands for "service parser" will parse the 'service' declarations within a provided protobuf and associate comments within that file with the various components of the service. |