gggen

func ApplyServiceFile ¶

func ApplyServiceFile(file *ast.File, action *dsl.Action, servicePkgName string) (bool, error)

ApplyServiceFile brings an existing service file in line with action: the package clause with servicePkgName, the service struct and its receivers with the role name of an action naming its service, the type parameters of the service.Base embedding and the request and result types of the action method with the action's Payload and Result, and the gst model import with whether a model.Empty request or result needs it. For example, once the Create action declares Payload[*UserReq]() and Result[*UserRsp](),

service.Base[*model.User, *model.User, *model.User]
func (u *Creator) Create(ctx *gst.ServiceContext, req *model.User) (rsp *model.User, err error)

becomes

service.Base[*model.User, *model.UserReq, *model.UserRsp]
func (u *Creator) Create(ctx *gst.ServiceContext, req *model.UserReq) (rsp *model.UserRsp, err error)

Method bodies are left alone. The servicePkgName parameter specifies the expected package name for the service file. This should match the package name used in service registration to maintain consistency. It reports whether it changed anything, and the error of a receiver rename it refuses, see applyServiceRoleName.

func ApplyServiceFileWithModelSync ¶

func ApplyServiceFileWithModelSync(file *ast.File, action *dsl.Action, servicePkgName, modelDir string, modelInfo *modelinfo.Model) (bool, error)

ApplyServiceFileWithModelSync extends ApplyServiceFile to handle import path and package name updates. It will update import statements and package references when model packages are renamed.

Design Philosophy: This function uses AST manipulation instead of regenerating files to preserve user's code formatting and custom modifications. Different developers have different code formatting preferences, and we should not force our formatting on their existing code. We only update the necessary parts (imports and type references) while keeping everything else intact.

Example transformation when "model/oldpkg" is renamed to "model/newpkg": - Import statement: "myproject/model/oldpkg" -> "myproject/model/newpkg" - Type references: oldpkg.User -> newpkg.User, oldpkg.UserReq -> newpkg.UserReq, oldpkg.UserRsp -> newpkg.UserRsp

A model package named like a framework package the file imports is referred to through an alias (see serviceModelQualifier), so renaming "model/sample" to "model/service" turns

"myproject/model/sample"
service.Base[*sample.User, *sample.User, *sample.User]

into

model_service "myproject/model/service"
service.Base[*model_service.User, *model_service.User, *model_service.User]

A file that refers to the model package by the name of a framework package it imports cannot build, and nothing tells which package a reference through that name means, so it is rejected before anything is rewritten. Such a file imports a model package named like a framework package under that name:

import (
	"myproject/model/service"
	"github.com/hydroan/gst/service"
)

type Creator struct {
	service.Base[*service.User, *service.User, *service.User]
}

The error tells how to fix the file: import the model package as model_service "myproject/model/service" and refer to it through model_service, or delete the file for gg gen to generate it again. Only the framework packages count (see frameworkImportNamed): a file importing "github.com/cespare/xxhash/v2", a package named xxhash, next to a model package named v2 builds, and is synced like any other.

Parameters: - file: The AST file to process - action: The DSL action configuration - servicePkgName: The expected service package name - modelDir: The root model directory, such as model - modelInfo: The correct model generation context

It returns whether any changes were made to the file, and the error of a file it rejects.

func BuildAPIDocFile ¶

func BuildAPIDocFile(modulePath, pkgName string, entries modelinfo.APIDocEntries) (string, error)

BuildAPIDocFile generates the doc registration file, model/apidoc.gen.go, of the project at the module path modulePath, which registers struct, field and enum doc comments into the apidoc registry at build time, so the OpenAPI document keeps schema descriptions in binaries deployed without Go source files. For a User struct with a documented Name field and a UserRole enum it generates

// Code generated by gst; DO NOT EDIT.

package model

import "github.com/hydroan/gst/apidoc"

func init() {
	apidoc.Register("helloworld/model", "User", apidoc.StructDoc{
		Comment: "User is the user record.",
		Fields: map[string]string{
			"Name": "Name is the user name.",
		},
	})
	apidoc.RegisterEnum("helloworld/model", "UserRole", apidoc.EnumDoc{
		Comment: "UserRole grades what a user may do.",
		Values: []apidoc.EnumValue{
			{Value: "owner", Comment: "UserRoleOwner manages the project."},
			{Value: "member"},
		},
	})
}

func BuildMainFile ¶

func BuildMainFile(projectName string, extraDirs ...string) (string, error)

BuildMainFile generates the main.go file of the project at the module path projectName, importing the project's standard packages (ggconst.ProjectImportDirs) and extraDirs, the optional packages the project has — interceptor and pb, for one serving gRPC — in one sorted list: for helloworld with no extra package it generates

// Code generated by gst; DO NOT EDIT.

package main

import (
	_ "helloworld/component"
	_ "helloworld/configx"
	_ "helloworld/cronjob"
	_ "helloworld/leader"
	_ "helloworld/lock"
	_ "helloworld/middleware"
	_ "helloworld/model"
	_ "helloworld/module"
	"helloworld/router"
	_ "helloworld/service"

	"github.com/hydroan/gst/bootstrap"
)

func main() {
	bootstrap.RunOrDie(bootstrap.Bootstrap)
	bootstrap.RunOrDie(router.Init)
	bootstrap.RunOrDie(bootstrap.Run)
}

func BuildModelFile ¶

func BuildModelFile(modulePath, pkgName string, aliases map[string]string, stmts ...ast.Stmt) (string, error)

BuildModelFile generates the model registration file, model.gen.go, of the project at the module path modulePath, in package pkgName with stmts as the body of its init function; aliases maps each model package it imports to the alias ModelFileAliases picked for it. For the model User of the root model package and the model Box of the package at helloworld/model/sample it generates

// Code generated by gst; DO NOT EDIT.

package model

import (
	"helloworld/model/sample"

	"github.com/hydroan/gst/model"
)

func init() {
	model.Register[*User]()
	model.Register[*sample.Box]()
}

func BuildRouterFile ¶

func BuildRouterFile(modulePath, pkgName, gstModelPkg string, aliases map[string]string, stmts ...ast.Stmt) (string, error)

BuildRouterFile generates the router registration file, router.gen.go, of the project at the module path modulePath, in package pkgName with stmts ahead of the return statement of its Init function; gstModelPkg is the name the file imports the gst model package under, "" when no registration references it, and aliases maps each model package it imports to the alias RouterFileAliases picked for it. For the models Box and User of the root model package it generates

// Code generated by gst; DO NOT EDIT.

package router

import (
	"helloworld/model"

	"github.com/hydroan/gst"
	"github.com/hydroan/gst/router"
	"github.com/hydroan/gst/service"
)

func Init() error {
	router.Register[*model.Box, *model.Box, *model.Box](router.Auth(), "/api/boxes", &gst.ControllerConfig[*model.Box]{}, service.List)
	router.Register[*model.User, *model.User, *model.User](router.Pub(), "/api/users", &gst.ControllerConfig[*model.User]{}, service.Create)
	return nil
}

func BuildServiceFile ¶

func BuildServiceFile(modulePath, pkgName string, aliases map[string]string, stmts ...ast.Stmt) (string, error)

BuildServiceFile generates the service registration file, service.gen.go, of the project at the module path modulePath, in package pkgName with stmts as the body of its init function; aliases maps each service package it imports to the alias ServiceFileAliases picked for it, such as pkg1_user and pkg2_user for "helloworld/service/pkg1/user" and "helloworld/service/pkg2/user". For the Updater of the box service and the Creator of the user service it generates

// Code generated by gst; DO NOT EDIT.

package service

import (
	"helloworld/service/box"
	"helloworld/service/user"

	"github.com/hydroan/gst/service"
)

func init() {
	service.Register[*box.Updater](service.Update, "/api/boxes/:id")
	service.Register[*user.Creator](service.Create, "/api/users")
}

func EmptyLine ¶

func EmptyLine() ast.Stmt

EmptyLine builds a statement that prints as an empty line, which the generated service methods place before their return statement: a body built from StmtLogInfo(`"item create"`), EmptyLine() and Returns(ast.NewIdent("nil")) prints as

log.Info("item create")

return nil

It is an expression statement of an empty identifier: go/printer drops an *ast.EmptyStmt from a statement list without leaving a line for it.

func GenerateService ¶

func GenerateService(info *modelinfo.Model, action *dsl.Action, phase apiaction.Phase, servicePkgName string) *ast.File

GenerateService builds the scaffold of the action's service file in package servicePkgName: the service struct named after the action's role and the methods of phase. It returns nil when the action is disabled or declares no service. For a Create action on the model User of the root model package, a database model, the file prints as

package user

import (
	"helloworld/model"

	"github.com/hydroan/gst"
	"github.com/hydroan/gst/service"
)

type Creator struct {
	service.Base[*model.User, *model.User, *model.User]
}

func (u *Creator) Create(ctx *gst.ServiceContext, req *model.User) (rsp *model.User, err error) {
	log := u.WithContext(ctx, ctx.Phase())
	log.Info("user create")

	return rsp, nil
}

func (u *Creator) CreateBefore(ctx *gst.ServiceContext, user *model.User) error {
	log := u.WithContext(ctx, ctx.Phase())
	log.Info("user create before")

	return nil
}

func (u *Creator) CreateAfter(ctx *gst.ServiceContext, user *model.User) error {
	log := u.WithContext(ctx, ctx.Phase())
	log.Info("user create after")

	return nil
}

A List or Export action on a database model gets the Filter hook as well, between ListBefore and ListAfter, the order the controllers invoke them in. A model without a database table, one embedding model.Empty, gets no hooks at all. GenerateServiceShell returns the same file without the hooks.

func GenerateServiceShell ¶

func GenerateServiceShell(info *modelinfo.Model, action *dsl.Action, phase apiaction.Phase, servicePkgName string) *ast.File

GenerateServiceShell returns the file GenerateService returns for the same action without the hook placeholders: the struct and the action method, the shell gg module copy merges the module's service source onto. The shell owns the signatures the source's bodies are grafted onto and the source owns the hooks it defines; a placeholder the source does not define would stay in the copy as a hook that runs. For the Create action of the model User above the file prints as

package user

import (
	"helloworld/model"

	"github.com/hydroan/gst"
	"github.com/hydroan/gst/service"
)

type Creator struct {
	service.Base[*model.User, *model.User, *model.User]
}

func (u *Creator) Create(ctx *gst.ServiceContext, req *model.User) (rsp *model.User, err error) {
	log := u.WithContext(ctx, ctx.Phase())
	log.Info("user create")

	return rsp, nil
}

func GenerateServiceTest ¶

func GenerateServiceTest(info *modelinfo.Model, target modelinfo.ServiceTargetInfo, action *dsl.Action, route string) (string, error)

GenerateServiceTest builds the test scaffold gg gen writes next to the service file target locates when it creates the file: an external test package holding one test named after the action, which fails until the project deletes its first line, and then is the example request of the action, typed by the action's request and response types. route is the path the router registers the action at, API prefix included (see modelinfo.RouterTargetForAction). For the Create action of the model Record of the root model package of helloworld, registered at /api/records, it generates

package record_test

import (
	"testing"

	"helloworld/model"

	"github.com/hydroan/gst/client"
	"github.com/hydroan/gst/testutil"
	"github.com/stretchr/testify/require"
)

// TestCreate covers POST /api/records, served by Creator in create.go.
//
// The request goes through the framework client against the test server
// TestMain starts, so the route, the service and the database are exercised
// together. A route not declared Public() goes through the auth middleware the
// project registers, which reads the credentials the client carries: a token
// set with client.WithToken, headers set with client.WithHeader, and the
// cookies earlier responses set, kept in its cookie jar. A rejection is
// asserted with testutil.RequireError, and rows with the testutil.Require*
// helpers.
func TestCreate(t *testing.T) {
	t.Fatal("TestCreate is a scaffold: delete this line and finish the test below")

	cli, err := client.New(testutil.BaseURL())
	require.NoError(t, err)

	rsp, err := cli.Post[model.Record](t.Context(), "/api/records", &model.Record{})
	require.NoError(t, err)
	require.NotNil(t, rsp)
}

The example request of every action shape is pinned by the tests of this function: an item route reads the row's id from a placeholder variable, a batch route sends client.BatchItems or client.BatchIDs, a List without a declared result decodes client.ListResult, Import uploads a file, Export downloads the attachment and SSE consumes the stream. A Stream action, served over gRPC alone, is called through the client the protobuf plugin generated, on a connection to testutil.GRPCTarget: for the Stream action declaring Service("watch"), Payload and StreamingResult on the model Feed of the root model package, whose rpc is WatchFeed, the test reads

// TestWatch covers the WatchFeed rpc, served by Watch in watch.go.
//
// The call goes through a grpc-go client against the gRPC listener of the
// test server TestMain starts, so the rpc, the service and the database are
// exercised together. A method not declared Public() goes through the auth
// interceptors the project registers, which read the credentials the call
// carries in its outgoing metadata, set with metadata.AppendToOutgoingContext.
// A refusal is asserted on its status code, and rows with the testutil.Require*
// helpers.
func TestWatch(t *testing.T) {
	t.Fatal("TestWatch is a scaffold: delete this line and finish the test below")

	conn, err := grpc.NewClient(testutil.GRPCTarget(), grpc.WithTransportCredentials(insecure.NewCredentials()))
	require.NoError(t, err)
	t.Cleanup(func() {
		_ = conn.Close()
	})
	client := pb.NewFeedServiceClient(conn)

	stream, err := client.WatchFeed(t.Context(), &pb.WatchFeedRequest{})
	require.NoError(t, err)
	rsp, err := stream.Recv()
	require.NoError(t, err)
	require.NotNil(t, rsp)
}

and a client stream sends a request then reads the answer with CloseAndRecv, a bidirectional one sends, reads and closes its side.

func GenerateServiceTestMain ¶

func GenerateServiceTestMain(modulePath, servicePkgName string, extraDirs ...string) (string, error)

GenerateServiceTestMain builds the main_test.go gg gen writes into the service package servicePkgName of the module modulePath along with the package's first test scaffold, when no test file of the package declares TestMain yet. It links the packages main.go imports (ggconst.ProjectImportDirs), so the test server registers what the application registers, and declares the test server with the framework defaults spelled out, a no-op Seed among them, for the project to edit. For the package record of helloworld it generates

package record_test

import (
	"testing"

	// The registrations of main.go: the models, modules, services and cron
	// jobs register themselves through the init of these packages.
	_ "helloworld/component"
	_ "helloworld/configx"
	_ "helloworld/cronjob"
	_ "helloworld/leader"
	_ "helloworld/lock"
	_ "helloworld/middleware"
	_ "helloworld/model"
	_ "helloworld/module"
	"helloworld/router"
	_ "helloworld/service"

	"github.com/hydroan/gst/config"
	"github.com/hydroan/gst/testutil"
)

// TestMain starts the test server of this package the way main.go starts the
// application: the framework bootstraps against the backing services the
// Server declares, which come up in containers of their own, the routes are
// registered, and the server serves the tests until they are done. Database
// is the database the tests run against: config.DBSqlite needs no container,
// config.DBMySQL and config.DBPostgres run in one. Redis serves the modules
// that keep sessions or cache entries in it. Seed plants the baseline rows the
// tests start from through database.Database before the server serves.
func TestMain(m *testing.M) {
	testutil.Run(m, testutil.Server{
		Database: config.DBSqlite,
		Redis:    false,
		Routes:   router.Init,
		Seed:     func() error { return nil },
	})
}

func GstModelImportEntry ¶

func GstModelImportEntry(pkgName string) string

GstModelImportEntry returns the import entry ("path" or "alias path") that makes the given gst model package qualifier resolvable in a generated file: a service file takes it through imports(), the router file through BuildRouterFile. It returns "gstmodel github.com/hydroan/gst/model" for gstmodel and "github.com/hydroan/gst/model" for model.

func IsActionServiceSource ¶

func IsActionServiceSource(path string) bool

IsActionServiceSource reports whether the Go source file at path contains a type that embeds service.Base with three type parameters, matching gg-generated per-action service files (including those the DSL names with Service("name")). It returns false on read/parse errors.

func ModelFileAliases ¶

func ModelFileAliases(imports map[string]string) map[string]string

ModelFileAliases picks the aliases the project imports of the model registration file need (see ResolveImportConflicts); imports maps each imported model package path to its package name.

func ResolveImportConflicts ¶

func ResolveImportConflicts(declared map[string]string, reserved ...string) map[string]string

ResolveImportConflicts picks the alias each project import of a generated file needs. declared maps every import path to the name of the package it declares, and reserved lists the names the file's framework imports take. An import keeps its package name when no reserved name and no other import claims it, and spells the name out when the path does not tell it (see importSpecName), so the import shows the name the code refers to the package by; otherwise it is aliased with its last two path segments joined by an underscore ("svc/pkg1/user" becomes "pkg1_user"). Every import in a clash is aliased, not all but one: which import kept the name would depend on the others, and a new import sharing the name could take it away. An alias that still clashes with another name takes one more leading segment at a time, and one that runs out of segments gets a numeric suffix, so no two imports share a name and none takes a framework import's. Every alias is a Go identifier: characters an identifier cannot hold become underscores, and one that would start with a digit gets an underscore in front. The result maps each import path to the name it is written with, or to "" when it is written without one.

For example, the service registration file reserves service for its framework import, so the imports

"helloworld/service/account/recorditem" // package recorditem
"helloworld/service/api/v2"             // package v2
"helloworld/service/sample/entry_item"  // package entryitem
"helloworld/service/sample/item"        // package item
"helloworld/service/sample/record_item" // package recorditem
"helloworld/service/sample/service"     // package service

are written as

account_recorditem "helloworld/service/account/recorditem"
v2 "helloworld/service/api/v2"
entryitem "helloworld/service/sample/entry_item"
"helloworld/service/sample/item"
sample_record_item "helloworld/service/sample/record_item"
sample_service "helloworld/service/sample/service"

func Returns ¶

func Returns(exprs ...ast.Expr) *ast.ReturnStmt

Returns builds the return statement of exprs: for ast.NewIdent("rsp") and ast.NewIdent("nil") it builds

return rsp, nil

func RouterFileAliases ¶

func RouterFileAliases(imports map[string]string, gstModelPkg string) map[string]string

RouterFileAliases picks the aliases the project imports of the router registration file need (see ResolveImportConflicts); imports maps each imported model package path to its package name, and gstModelPkg is the name the file imports the gst model package under, "" when it does not.

func RouterGstModelUse ¶

func RouterGstModelUse(models []*modelinfo.Model) (pkgName string, needed bool)

RouterGstModelUse resolves how the generated router file references the gst model package. pkgName is the qualifier emitted for model.Empty: the plain package name by default, falling back to the gstmodel alias when a routed business model package is itself named "model" (two imports cannot take the same name in one file, so the plain qualifier would clash with that import). needed reports whether any routed action resolves either side to dsl.PayloadEmpty, i.e. whether the qualifier appears in the file at all. For example, a routed root model package with a List declaring only its result yields ("gstmodel", true), and routed models in package sample declaring both sides of every action yield ("model", false). Call it after the route/model ignore passes so disabled actions no longer count as routed.

func ServiceFileAliases ¶

func ServiceFileAliases(imports map[string]string) map[string]string

ServiceFileAliases picks the aliases the project imports of the service registration file need (see ResolveImportConflicts); imports maps each imported service package path to its package name.

func StmtLogInfo ¶

func StmtLogInfo(str string) *ast.ExprStmt

StmtLogInfo builds the statement that logs str, a quoted Go string literal: for str `"item create"` it builds

log.Info("item create")

func StmtLogWithContext ¶

func StmtLogWithContext(modelVarName string) *ast.AssignStmt

StmtLogWithContext builds the statement that opens a generated service method, taking the logger of the phase from the receiver named modelVarName: for u it builds

log := u.WithContext(ctx, ctx.Phase())

func StmtModelRegister ¶

func StmtModelRegister(modelName string) *ast.ExprStmt

StmtModelRegister builds the registration of a model in model.gen.go. modelName is the model type as the file refers to it, qualified when the model is declared outside the root model package: for User and sample.Record it builds

model.Register[*User]()
model.Register[*sample.Record]()

func StmtRouterRegister ¶

func StmtRouterRegister(modelPkgName, modelName, reqName, rspName, gstModelPkg string, routerGroup string, route string, paramName string, phase string) *ast.ExprStmt

StmtRouterRegister builds the registration of an action in router.gen.go: the model type, then the action's request and result types, reqName and rspName qualified by modelPkgName, the qualifier the file refers to the model package by. For example, it builds

router.Register[*model.Record, *model.Record, *model.Record](router.Auth(), "/api/records", &gst.ControllerConfig[*model.Record]{}, service.Create)
router.Register[*model.Record, *gstmodel.Empty, *model.BoxListRsp](router.Auth(), "/api/boxes", &gst.ControllerConfig[*model.Record]{}, service.List)
router.Register[*box.Record, *box.Record, *box.Record](router.Auth(), "/api/boxes/:id", &gst.ControllerConfig[*box.Record]{ParamName: "id"}, service.Get)

A dsl.PayloadEmpty side becomes *model.Empty under gstModelPkg, the qualifier the router file uses for model.Empty, resolved once per file by RouterGstModelUse. routerGroup names the router group accessor ("Auth" or "Pub"), route is the path the route is served at, shared verbatim with the matching StmtServiceRegister statement, paramName is the route parameter the controller reads the resource id from, "" for none, and phase names the phase of the action as the service package spells it, such as Create.

func StmtServiceRegister ¶

func StmtServiceRegister(serviceImport string, phase apiaction.Phase, route string) *ast.ExprStmt

StmtServiceRegister builds the registration of a service in service.gen.go. serviceImport is the service type as the file refers to it: for user.Creator, apiaction.Create and /api/users it builds

service.Register[*user.Creator](service.Create, "/api/users")

The route argument is the path the route is served at, the same string the matching StmtRouterRegister statement carries, because the service registry keys services by path and phase.

func SyncTestMainImports ¶

func SyncTestMainImports(fset *token.FileSet, file *ast.File, modulePath string, present []string) bool

SyncTestMainImports makes file, a TestMain file of the module modulePath parsed through fset with its comments, import the optional project packages the way main.go does, present being the directories the project holds (see gghelper.OptionalImportDrift): a missing import is added as a blank import in the group of the file's other imports of the module (see insertBlankImport), and a stale blank import is dropped with its comment; the rest of the file stays as it is. It reports whether file changed. The file is laid out by its positions, so go/format prints it with the groups it had, the added import sorted into its group. The scaffold GenerateServiceTestMain writes for a project holding neither package, synced for one holding interceptor and pb, is the scaffold it writes for that project, its project imports reading

_ "helloworld/component"
_ "helloworld/configx"
_ "helloworld/cronjob"
_ "helloworld/interceptor"
_ "helloworld/leader"
_ "helloworld/lock"
_ "helloworld/middleware"
_ "helloworld/model"
_ "helloworld/module"
_ "helloworld/pb"
"helloworld/router"
_ "helloworld/service"

func TestMainFile ¶

func TestMainFile(dir string) (string, error)

TestMainFile returns the path of the test file in dir declaring TestMain at package level, be it main_test.go or any other test file, since the test binary of a package takes its TestMain from any of them: for service/record/main_test.go declaring one, that path; "" when no test file of dir declares one, a missing directory included. A test file that does not parse is an error: gg cannot tell what it declares.