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

    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
          	// 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
                          	SnakeName    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
                            
                            	ImportPaths []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.

                                  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.