protogen

Documentation

Overview

Package protogen generates an annotated SnAPI `api` package (handler stubs + DTOs) from a .proto spec. It is the reverse of internal/parser + internal/generator: instead of turning annotated Go into a server, it turns a .proto file into annotated Go that the existing snapi build/serve/watch pipeline then consumes unchanged.

Index

• func Generate(specPath, outputDir string) error
• type CompileError
  • func (e *CompileError) Error() string
  • func (e *CompileError) Unwrap() error
• type Enum
• type EnumValue
• type Field
• type Message
• type Method
• type MethodView
• type ModuleNotFoundError
  • func (e *ModuleNotFoundError) Error() string
• type ProtoFile
• type RenderError
  • func (e *RenderError) Error() string
  • func (e *RenderError) Unwrap() error
• type Route
• type RouteParam
• type Service
• type ServiceView

Functions

func Generate

func Generate(specPath, outputDir string) error

Generate compiles specPath and writes annotated handler(s) plus DTOs. Where they land is decided by the spec itself:

• If the main .proto file declares `option go_package = "path;name";` (the standard protobuf mechanism for this -- see resolveGoPackage), handler files go to <path> (resolved against the enclosing module) as package <name>.
• Otherwise, handler files go directly into outputDir -- exactly the directory given, no implicit subdirectory -- as package "api".

Either way, DTOs always go into a "model" subdirectory next to the handlers and are always regenerated (pure derived data). Handler files are written only if they don't already exist yet, so hand-filled business logic survives re-running this against an updated spec.

outputDir doesn't need to contain go.mod itself -- it's located by searching outputDir and its ancestors, exactly like the `go` tool, so `snapi proto spec.proto .` works with go.mod at the module root regardless of where go_package ultimately places the handlers.

Types

type CompileError

type CompileError struct {
	SpecPath string
	Err      error
}

CompileError wraps failures from compiling a .proto spec.

func (*CompileError) Error

func (e *CompileError) Error() string

func (*CompileError) Unwrap

func (e *CompileError) Unwrap() error

type Enum

type Enum struct {
	Name   string
	Values []EnumValue
}

Enum is a generated int32-backed enum type plus its named values.

type EnumValue

type EnumValue struct {
	Name   string
	Number int32
}

EnumValue is a single `<EnumName>_<VALUE>` constant.

type Field

type Field struct {
	GoName     string
	JSONName   string
	GoType     string
	OneofGroup string // non-empty names a real (non-synthetic) oneof this field belongs to
}

Field is a single DTO struct field.

type Message

type Message struct {
	Name   string
	Fields []Field
}

Message is a single generated DTO struct.

type Method

type Method struct {
	Name         string // RPC name, e.g. "GetTodo"
	RequestType  string // bare model type name, "" if the request is google.protobuf.Empty
	ResponseType string // bare model type name, "" if the response is google.protobuf.Empty
	Route        Route
}

Method is a single routable RPC.

type MethodView

type MethodView struct {
	FuncName          string // free-function name (func layout) or method name (struct layout)
	RPCName           string
	HTTPMethod        string
	Path              string
	OperationID       string
	PathParams        []RouteParam
	QueryParams       []RouteParam
	RequestType       string
	ResponseType      string
	SuccessStatus     string
	SuccessDesc       string
	ExtraBindingsNote string
}

MethodView is the template data for one generated handler.

type ModuleNotFoundError

type ModuleNotFoundError struct {
	OutputDir string
}

ModuleNotFoundError indicates outputDir has no go.mod to read a module path from. `snapi proto` writes into an existing Go module; it does not scaffold one.

func (*ModuleNotFoundError) Error

func (e *ModuleNotFoundError) Error() string

type ProtoFile

type ProtoFile struct {
	Name      string // base file name without extension, e.g. "todo"
	NeedsTime bool
	Messages  []Message
	Enums     []Enum
}

ProtoFile is the DTO-relevant content of a single .proto file: every message (nested messages flattened to top-level Go structs) and enum it declares. One ProtoFile renders to one dedicated file in api/model.

type RenderError

type RenderError struct {
	File string
	Err  error
}

RenderError wraps failures rendering a generated Go file.

func (*RenderError) Error

func (e *RenderError) Error() string

func (*RenderError) Unwrap

func (e *RenderError) Unwrap() error

type Route

type Route struct {
	Method        string
	Path          string
	PathParams    []RouteParam
	QueryParams   []RouteParam
	BodyField     string // "" = no body, "*" = whole input message, else a specific field name
	ExtraBindings int    // count of dropped additional_bindings entries
}

Route is the resolved HTTP shape of a single RPC.

type RouteParam

type RouteParam struct {
	Name string
	Type string
}

RouteParam is a single @SnAPI.Path/@SnAPI.Query annotation's (name, type).

type Service

type Service struct {
	Name             string // short Go name, e.g. "TodoService"
	FQName           string // fully-qualified, e.g. "todo.v1.TodoService"
	Methods          []Method
	SkippedStreaming []string
}

Service is a single proto `service` with its routable (non-streaming) RPCs.

type ServiceView

type ServiceView struct {
	PackageName        string // the file's own `package` clause, e.g. "api"
	ModelImportPath    string // full import path of the sibling model package
	PackageServiceName string
	IsStruct           bool
	NeedsModel         bool
	SkippedStreaming   []string
	Methods            []MethodView
}

ServiceView is the template data for one generated <service>.go file.