Documentation
¶
Overview ¶
Package pb generates the protobuf definitions of a gst project's gRPC services and the Go files serving them, from the schema pbschema derives of the models declaring GRPC(): the definitions printed as .proto files that mirror the model directory under pb/; beside each, a .gen.go with the type serving the service, the calls of its actions, the handlers of its rpcs and the conversions between the messages and the Go types (see handlerFile); and, in every package under pb/, a pb.gen.go registering its services on the listener (see registrationFiles). A diagnostic of the derivation stops the generation before any file is produced.
Two libraries stand in for protoc, so nothing needs it installed: the files are written by protoprint, the one package of jhump/protoreflect used, which prints the assembled descriptors as .proto source with their comments and layout; they are read back by bufbuild/protocompile, a protobuf compiler front end in pure Go that parses and links .proto source into descriptors, here to compile the definitions for the plugins that write the Go files beside them (see Compile) and, in tests, to compile the generated files the way protoc would. The Go files are type-checked before any is written (see TypeCheck).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnchecked = errors.New("the generated Go files could not be type-checked")
ErrUnchecked is what TypeCheck wraps when the generated files could not be checked at all, the packages they import failing to list: a project whose module graph the go command cannot resolve yet, before go mod tidy. The files are written unchecked then, go build being where they are checked next.
Functions ¶
func TypeCheck ¶
TypeCheck type-checks the Go files among files, the packages gg gen writes under pb/ in the project at dir, module modulePath: each package is checked from its files the way the go command compiles it once written, the project packages and the dependencies it imports read from their compiled export data, and a generated package imported by another generated one checked first. Every error is reported as a diagnostic at the file and line of the generated file, in a *DiagnosticsError; nil when the packages type-check; an error wrapping ErrUnchecked when the imports could not be listed.
Types ¶
type File ¶
type File struct {
// Path is slash-separated and relative to the project root, such as
// pb/archive/document.proto for the model file model/archive/document.go,
// pb/archive/document.gen.go for its handlers and
// pb/archive/document.pb.go for the messages compiled from it.
Path string
// Content is the source of the file.
Content string
// Service reports whether a definition declares a service, which is
// what decides whether Compile writes a _grpc.pb.go beside it; false
// for a Go file.
Service bool
}
File is one generated file under pb/: a .proto definition, the Go file Generate writes beside it with the handlers of its services and the conversions of its messages, the registration file, or a Go file Compile made of a definition.
func Compile ¶
Compile compiles the .proto files Generate produced into the Go files the protobuf plugins write for them, each beside its definition: for pb/sample.proto, pb/sample.pb.go with its messages and, when the file declares a service, pb/sample_grpc.pb.go with the service; for pb/record/item.proto, pb/record/item.pb.go in the package its go_package names. The definitions are compiled in memory, with protocompile standing in for protoc and carrying the well-known types they import, so nothing has to be on disk first and nothing is written when a definition or a plugin refuses; the plugins get the descriptors the way protoc hands them over, comments included. The files come back sorted by path.
func Generate ¶
Generate derives the protobuf definitions of the models declaring GRPC() (see pbschema.Derive) and renders them: one .proto file per Go file the types are declared in, with the Go file serving each definition beside it and the registration file, sorted by path (see File.Definition for telling the two kinds apart). Models declaring no GRPC() produce no file at all, and a *pbschema.DiagnosticsError of the derivation is returned as is.
For example, the model file model/note.go of module tmpapp declaring
// Note is a note kept by the note service.
type Note struct {
// Title is the display title.
Title string `json:"title" pb:"11"`
Tags []string `json:"tags,omitempty" pb:"12" gorm:"-"`
model.Base
}
func (Note) TableName() string { return "notes" }
func (Note) Design() {
dsl.GRPC()
dsl.Migrate()
dsl.Endpoint("notes")
dsl.Create(func() {})
dsl.Get(func() {})
}
gets the file pb/note.proto:
// Code generated by gst; DO NOT EDIT.
syntax = "proto3";
package tmpapp;
import "google/protobuf/timestamp.proto";
option go_package = "tmpapp/pb;pb";
// Note is a note kept by the note service.
message Note {
// The identifier of the record, assigned when it is created.
string id = 1;
// The id of the user who created the record.
string created_by = 2;
// The id of the user who last updated the record.
string updated_by = 3;
// When the record was created.
google.protobuf.Timestamp created_at = 4;
// When the record was last updated.
google.protobuf.Timestamp updated_at = 5;
// Title is the display title.
string title = 11;
repeated string tags = 12;
}
// CreateNoteRequest is the request of NoteService.CreateNote.
message CreateNoteRequest {
// note is the Note to create.
Note note = 1;
}
// CreateNoteResponse is the response of NoteService.CreateNote.
message CreateNoteResponse {
// note is the Note created.
Note note = 1;
}
// GetNoteRequest is the request of NoteService.GetNote.
message GetNoteRequest {
// id is the id of the Note.
string id = 1;
// expand is the associations to expand, as the _expand query parameter names them.
repeated string expand = 2;
// depth is the depth of the expansion, as the _depth query parameter.
uint32 depth = 3;
}
// GetNoteResponse is the response of NoteService.GetNote.
message GetNoteResponse {
// note is the Note found.
Note note = 1;
}
// NoteService serves the actions of Note over gRPC.
service NoteService {
// CreateNote is the Create action of Note on /api/notes.
rpc CreateNote ( CreateNoteRequest ) returns ( CreateNoteResponse );
// GetNote is the Get action of Note on /api/notes/:id.
rpc GetNote ( GetNoteRequest ) returns ( GetNoteResponse );
}
func (File) Definition ¶
Definition reports whether the file is a .proto definition, the kind Compile compiles, rather than a Go file.
Source Files