svcdef

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

• type DebugInfo
  • func (di *DebugInfo) Position(pos token.Pos) string
• type Enum
  • func NewEnum(e *ast.TypeSpec) (*Enum, error)
• type Field
  • func NewField(f *ast.Field) (*Field, error)
• type FieldType
• type HTTPBinding
• type HTTPParameter
• type LocationError
  • func NewLocationError(err string, path string, pos string) LocationError
  • func (le LocationError) Error() string
  • func (le LocationError) Location() string
• type Map
  • func NewMap(m ast.Expr) (*Map, error)
• type Message
  • func NewMessage(m *ast.TypeSpec) (*Message, error)
• type Service
  • func NewService(s *ast.TypeSpec, info *DebugInfo) (*Service, error)
• type ServiceMethod
  • func NewServiceMethod(m *ast.Field, info *DebugInfo) (*ServiceMethod, error)
• type Svcdef
  • func New(goFiles map[string]io.Reader, protoFiles map[string]io.Reader) (*Svcdef, error)
  • func NewFromString(def string, gopath []string) (*Svcdef, error)

Types

type DebugInfo

type DebugInfo struct {
	Fset *token.FileSet
	Path string
}

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.

func (*DebugInfo) Position

func (di *DebugInfo) Position(pos token.Pos) string

type Enum

type Enum struct {
	Name string
}

func NewEnum

func NewEnum(e *ast.TypeSpec) (*Enum, error)

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.

func NewField

func NewField(f *ast.Field) (*Field, error)

NewField returns a Field struct with information distilled from an *ast.Field. If the provided *ast.Field does not match the conventions of code generated by protoc-gen-go, an error will be returned.

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

type LocationError struct {
	Path     string
	Position string
	Err      string
}

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

func NewMap(m ast.Expr) (*Map, error)

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:

1. The KeyType of the *ast.MapType will always be an ast.Ident
2. 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 Message

type Message struct {
	Name   string
	Fields []*Field
}

Message represents a protobuf Message, though greatly simplified.

func NewMessage

func NewMessage(m *ast.TypeSpec) (*Message, error)

NewMessage returns a new Message struct derived from an *ast.TypeSpec with a Type of *ast.StructType.

type Service

type Service struct {
	Name    string
	Methods []*ServiceMethod
}

func NewService

func NewService(s *ast.TypeSpec, info *DebugInfo) (*Service, error)

NewService returns a new Service struct derived from an *ast.TypeSpec with a Type of *ast.InterfaceType representing an "{SVCNAME}Server" interface.

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
	PBPkgName 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.

func New

func New(goFiles map[string]io.Reader, protoFiles map[string]io.Reader) (*Svcdef, error)

New creates a Svcdef by parsing the provided Go and Protobuf source files to derive type information, gRPC service data, and HTTP annotations.

func NewFromString

func NewFromString(def string, gopath []string) (*Svcdef, error)

NewFromString creates a Svcdef from a string of a valid protobuf file. Very useful in tests.