gen

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package gen generates project files from platformgo.yaml.

It produces the module wiring, their settings and the environment example. This is what removes manual edits when modules are added or removed: only the domain part stays in project code.

Index

Constants

View Source
const (
	BufPath     = "buf.yaml"
	BufGenPath  = "buf.gen.yaml"
	OpenAPIPath = "api/openapi/openapi.gen.go"

	// OpenAPIBasePath holds the human part of the API description — title, intro, tags,
	// security scheme. The generator fills the rest from the proto files; this file is
	// created once and belongs to the project, because only the project knows what to
	// tell the reader of its API.
	OpenAPIBasePath = "api/openapi/base.yaml"

	// APIGenDir is where the Go code of the proto files is generated.
	APIGenDir = "internal/api/gen"
)

Files of the api module.

View Source
const (
	OpenAPIConnect  = "connect"  // protoc-gen-connect-openapi, one api/openapi/openapi.yaml
	OpenAPIPlatform = "platform" // protoc-gen-platform-openapi, the platform's own generator
	OpenAPINone     = "none"     // none: the project keeps api/openapi/openapi.yaml itself
)

The generators of the OpenAPI description, the openapi.generator option of api.

View Source
const (
	ConnectOpenAPITool  = "github.com/sudorandom/protoc-gen-connect-openapi"
	PlatformModule      = "github.com/aidarbn/platform-go"
	PlatformOpenAPITool = PlatformModule + "/cmd/protoc-gen-platform-openapi"
)

The OpenAPI plugins as go tool packages.

View Source
const (
	MessagesPath   = "i18n/messages.yaml"
	MessagesGoPath = "i18n/messages.gen.go"
	I18nProtoPath  = "proto/platform/i18n/v1/i18n.proto" // under proto_dir of the api module

)

Files of the i18n module.

View Source
const (
	MonitoringPath = "monitoring.yml" // thresholds, owned by the project
	// MonitoringRulesPath holds the project's own alert rules in Prometheus format, owned
	// by the project; its groups are appended to the generated alerts.
	MonitoringRulesPath = "monitoring.rules.yml"

	MonitoringStack = monitoringDir + "docker-compose.yml"
)

Files of the monitoring module.

View Source
const (
	ConfigPath  = "cmd/app/config.gen.go"
	ModulesPath = "cmd/app/modules.gen.go"
	EnvPath     = ".env.example"

	// ProjectEnvPath holds the variables of the project's own code. It belongs to the
	// project, and its content is appended to .env.example, so one file documents the
	// whole environment and make run reads it.
	ProjectEnvPath = ".env.project.example"
	ComposePath    = "docker-compose.yml"

	// PolicyPath is the access policy of the project; PolicyGoPath embeds it.
	PolicyPath   = "rbac/policy.csv"
	PolicyGoPath = "rbac/policy.gen.go"

	// MigrationsPath embeds the SQL migrations of the project next to them.
	MigrationsPath = "db/migrations/migrations.gen.go"
)

Paths of generated files, relative to the project root.

View Source
const DefaultDomainDir = "internal/domain"

DefaultDomainDir is where enums are declared unless the enums module says otherwise.

View Source
const EnumsPath = "internal/enums/enums.gen.go"

EnumsPath is the generated catalog of the enums of the project.

View Source
const I18nProto = `` /* 1541-byte string literal not displayed */

I18nProto is the field option of the platform, the same file kit/i18nx is generated from. A test keeps the two identical.

View Source
const MessagesExample = `` /* 706-byte string literal not displayed */

MessagesExample is the file a project starts from when it enables the i18n module.

View Source
const MigrationsDir = "db/migrations"

MigrationsDir is where the SQL migrations of a project live.

View Source
const MonitoringExample = `` /* 731-byte string literal not displayed */

MonitoringExample is the thresholds file a project starts from. Its sections and keys are taply's, so the numbers read the same in every project.

View Source
const MonitoringRulesExample = `` /* 430-byte string literal not displayed */

MonitoringRulesExample is the rules file a project starts from.

View Source
const OpenAPIBaseExample = `` /* 966-byte string literal not displayed */

OpenAPIBaseExample is the starting point of the description: the generator never touches it again, so the project can say what its API is for.

View Source
const OpenAPIOptionsPath = "platform/openapi/v1/options.proto"

OpenAPIOptionsPath is the options of the platform's OpenAPI generator under the proto folder of the project, written with openapi.generator: platform.

View Source
const PolicyExample = `` /* 380-byte string literal not displayed */

PolicyExample is the policy a project starts from when it enables the rbac module.

View Source
const SettingsExample = `` /* 354-byte string literal not displayed */

SettingsExample is the schema a project starts from when it enables the settings module: an empty schema would leave an accessor with nothing to return.

View Source
const SettingsModule = "settings"

SettingsModule is the module name whose schema drives the generation.

View Source
const SettingsPath = "internal/settings/settings.gen.go"

SettingsPath is the generated typed access to the business settings. It lives in the project so that domain code reads a setting as a method call rather than a string key.

View Source
const SqlcPath = "db/sqlc.yaml"

SqlcPath is the sqlc configuration of a project that keeps the defaults of the sqlc option of the postgres module.

Variables

This section is empty.

Functions

func Apply

func Apply(dir string, files map[string][]byte) ([]string, error)

Apply writes the generated files that differ from what the project has and returns their paths. Untouched files keep their modification time, so a build that runs generation first does not rebuild everything.

func Changed

func Changed(dir string, files map[string][]byte) ([]string, error)

Changed returns the paths whose content in the project differs from the generated one. An empty list means generation is up to date.

func DomainDir added in v0.3.0

func DomainDir(f *spec.File) string

DomainDir is the directory the enums module scans.

func EnumsCode added in v0.3.0

func EnumsCode(f *spec.File, project fs.FS) ([]byte, error)

EnumsCode scans the domain package of the project for go-enum markers and generates the catalog, ported from taply's enumsgen.

func Files

func Files(dir string, f *spec.File) (map[string][]byte, error)

Files returns everything platformgo generates for the project: the module wiring and, when the settings module is enabled, the typed access to the business settings.

The schema is read from the project directory, so the generated code always matches the file a developer just edited.

func FilesFrom added in v0.2.0

func FilesFrom(f *spec.File, project fs.FS) (map[string][]byte, error)

FilesFrom is Files with the project read through project. apply passes the disk with the files it is about to create laid over it.

func IsGenerated added in v0.2.0

func IsGenerated(content []byte) bool

IsGenerated reports whether content carries the mark platformgo puts on the files it generates. A generated file that lost the mark has been taken over by hand, and apply leaves it alone.

func MonitoringFiles added in v0.3.0

func MonitoringFiles(f *spec.File, project fs.FS) (map[string][]byte, error)

MonitoringFiles generates the monitoring stack of the project: an OpenTelemetry collector next to the service and Prometheus, Alertmanager, Loki, Tempo and Grafana, with the dashboard and the alerts of the enabled modules.

func NewMigration added in v0.2.0

func NewMigration(dir, name string, now time.Time) (string, error)

NewMigration creates an empty goose migration named after the time and the given name and returns its path relative to the project. The timestamp keeps files ordered and avoids number clashes between branches.

func SettingsCode

func SettingsCode(raw []byte) ([]byte, error)

SettingsCode generates the typed access from the schema file contents.

func SettingsEnabled

func SettingsEnabled(f *spec.File) bool

SettingsEnabled reports whether the project enables the settings module.

func SettingsSchemaPath

func SettingsSchemaPath(f *spec.File) string

SettingsSchemaPath is the schema file of the project: settings.yaml unless the module section names another one.

func Wiring

func Wiring(f *spec.File) (map[string][]byte, error)

Wiring returns the generated files: path relative to the project root to content.

Types

type APISettings added in v0.9.0

type APISettings struct {
	ProtoDir string `yaml:"proto_dir"`
	Buf      struct {
		Deps           []string `yaml:"deps"`
		BreakingExcept []string `yaml:"breaking_except"`
	} `yaml:"buf"`
	OpenAPI struct {
		Generator string                 `yaml:"generator"`
		Documents []openapi.DocumentSpec `yaml:"documents"`
	} `yaml:"openapi"`
}

APISettings is the section of the api module: where the proto files are, buf dependencies and breaking rules on top of the platform's, and who writes the OpenAPI description.

func API added in v0.9.0

func API(f *spec.File) (APISettings, error)

API reads the section of the api module, with the defaults for what the file leaves out.

func (APISettings) GeneratesOpenAPI added in v0.9.0

func (s APISettings) GeneratesOpenAPI() bool

GeneratesOpenAPI reports whether make generate writes api/openapi/openapi.yaml.

func (APISettings) ProtoPath added in v0.9.0

func (s APISettings) ProtoPath(rel string) string

ProtoPath is a file under the proto folder.

func (APISettings) Tools added in v0.10.0

func (s APISettings) Tools(tools []registry.Tool, platformVersion string) []registry.Tool

Tools are the buf plugins the api module pins in go.mod, by the OpenAPI generator: the connect plugin for connect, the platform's plugin for platform, neither for none.

type JetSettings added in v0.11.0

type JetSettings struct {
	Out string `yaml:"out"`
}

JetSettings is the jet option of the postgres module: where the dynamic query builder is generated, relative to the project root, with forward slashes.

func Jet added in v0.11.0

func Jet(f *spec.File) (JetSettings, error)

Jet reads the jet option of the postgres module, with the default for what the file leaves out.

type PostgresCompose added in v0.11.0

type PostgresCompose struct {
	Enabled  bool     `yaml:"enabled"`
	Image    string   `yaml:"image"`
	DB       string   `yaml:"db"`
	User     string   `yaml:"user"`
	Password string   `yaml:"password"`
	Port     int      `yaml:"port"`
	DataDir  string   `yaml:"data_dir"`
	Command  []string `yaml:"command"`
	Init     string   `yaml:"init"` // relative to the project root; empty for none
}

PostgresCompose is the compose option of the postgres module: the local database in docker-compose.yml and the DATABASE_URL example in .env.example. With the defaults both are what every project had before the option existed, byte for byte.

func PostgresComposeSettings added in v0.11.0

func PostgresComposeSettings(f *spec.File) (PostgresCompose, error)

PostgresComposeSettings reads the compose option of the postgres module, with the defaults for what the file leaves out.

func (PostgresCompose) DatabaseURL added in v0.11.0

func (c PostgresCompose) DatabaseURL() string

DatabaseURL is the address of the local database, the DATABASE_URL example.

type SqlcGoType added in v0.9.0

type SqlcGoType struct {
	Import  string `yaml:"import"`
	Package string `yaml:"package"`
	Type    string `yaml:"type"`
	Pointer bool   `yaml:"pointer"`
	Slice   bool   `yaml:"slice"`
	// contains filtered or unexported fields
}

SqlcGoType is the go_type of an override: a type name ("int64") or an object.

func (*SqlcGoType) UnmarshalYAML added in v0.9.0

func (g *SqlcGoType) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML accepts both shapes sqlc accepts: go_type: int64 and go_type: {type: int64, pointer: true}.

type SqlcOverride added in v0.9.0

type SqlcOverride struct {
	DBType   string     `yaml:"db_type"`
	Column   string     `yaml:"column"`
	Nullable bool       `yaml:"nullable"`
	GoType   SqlcGoType `yaml:"go_type"`
}

SqlcOverride maps a database type or a column to a Go type, as an override of sqlc.

type SqlcSettings added in v0.9.0

type SqlcSettings struct {
	Dir           string            `yaml:"dir"`
	Queries       string            `yaml:"queries"`
	Out           string            `yaml:"out"`
	Package       string            `yaml:"package"`
	EmitInterface bool              `yaml:"emit_interface"`
	Overrides     []SqlcOverride    `yaml:"overrides"`
	Renames       map[string]string `yaml:"renames"`
}

SqlcSettings is the sqlc option of the postgres module: where the configuration, the queries and the generated code live, and the type mapping on top of the platform's. Paths use forward slashes; dir and out are relative to the project root, queries to dir.

func Sqlc added in v0.9.0

func Sqlc(f *spec.File) (SqlcSettings, error)

Sqlc reads the sqlc option of the postgres module, with the defaults for what the file leaves out.

func (SqlcSettings) ConfigPath added in v0.9.0

func (s SqlcSettings) ConfigPath() string

ConfigPath is where the sqlc configuration is generated.

func (SqlcSettings) QueriesDir added in v0.9.0

func (s SqlcSettings) QueriesDir() string

QueriesDir is the folder of the static queries, relative to the project root.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL