config

package
v1.33.26 Latest Latest
Warning

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

Go to latest
Published: May 18, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package config provides configuration management for Buffalo.

Index

Constants

View Source
const CurrentSchemaVersion = 2

CurrentSchemaVersion is the schema version produced by this build of Buffalo. Configs without `schema_version` are treated as v1 for backward compatibility. Bump this constant whenever the YAML shape changes in a non-backward-compatible way.

View Source
const EnvPrefix = "BUFFALO"

EnvPrefix is the prefix all Buffalo environment variables share.

Variables

This section is empty.

Functions

func ApplyEnv added in v1.33.17

func ApplyEnv(v *viper.Viper)

ApplyEnv configures the supplied viper instance to honor BUFFALO_* env overrides for every nested key declared in envBindKeys. Safe to call on both the global viper (`viper.GetViper()`) and on instances created via `viper.New()` from LoadFromFile.

func DefaultExternalPrefixes added in v1.2.0

func DefaultExternalPrefixes() []string

DefaultExternalPrefixes returns the default list of external import prefixes that should not be modified during import fixing

func EnvBindKeys added in v1.33.17

func EnvBindKeys() []string

EnvBindKeys returns a copy of the registered env-bound keys for tests and docs.

func GenerateJSONSchema added in v1.33.15

func GenerateJSONSchema() ([]byte, error)

GenerateJSONSchema produces a JSON Schema document describing buffalo.yaml. Source of truth: the Config struct and its `mapstructure` / `desc` tags.

func MarshalDefaultYAML added in v1.33.15

func MarshalDefaultYAML(profile Profile) ([]byte, error)

MarshalDefaultYAML renders the default config as a buffalo.yaml-ready document with a header comment that references the JSON Schema for IDE validation.

func MigrateFile added in v1.33.15

func MigrateFile(path string, dryRun bool) (out []byte, from, to int, err error)

MigrateFile reads `path`, applies migrations, and writes the result back. When dryRun is true the file is not modified; the new contents are returned.

func MigrateYAMLBytes added in v1.33.15

func MigrateYAMLBytes(data []byte) (out []byte, from, to int, err error)

MigrateYAMLBytes applies all schema migrations needed to bring `data` from its current version up to CurrentSchemaVersion. Returns the migrated bytes, the source version, and the target version. Source version is inferred: missing `schema_version` -> 1.

Types

type BaseFieldConfig added in v1.21.0

type BaseFieldConfig struct {
	Name         string `mapstructure:"name"`
	Type         string `mapstructure:"type"`
	PrimaryKey   bool   `mapstructure:"primary_key"`
	AutoGenerate bool   `mapstructure:"auto_generate"`
	AutoNow      bool   `mapstructure:"auto_now"`
	AutoNowAdd   bool   `mapstructure:"auto_now_add"`
	Nullable     bool   `mapstructure:"nullable"`
	Comment      string `mapstructure:"comment"`
}

BaseFieldConfig describes a field injected into the generated BaseModel.

type BazelConfig added in v1.30.0

type BazelConfig struct {
	// Enabled activates Bazel integration (auto-detect workspace, generate BUILD files).
	Enabled bool `mapstructure:"enabled"`

	// AutoDetect enables automatic detection of Bazel workspace.
	// When true, Buffalo looks for MODULE.bazel/WORKSPACE in parent directories.
	AutoDetect bool `mapstructure:"auto_detect"`

	// BazelPath is the path to the bazel binary. Defaults to "bazel".
	BazelPath string `mapstructure:"bazel_path"`

	// UseQuery uses `bazel query` to discover proto targets instead of file parsing.
	// Requires bazel to be installed. Falls back to file parsing if unavailable.
	UseQuery bool `mapstructure:"use_query"`

	// Patterns lists Bazel target patterns to scan (e.g., "//proto/...", "//api/...").
	// Defaults to ["//..."].
	Patterns []string `mapstructure:"patterns"`

	// GenerateBuildFiles controls whether Buffalo generates BUILD.bazel for output.
	GenerateBuildFiles bool `mapstructure:"generate_build_files"`

	// StripImportPrefix is applied to proto_library targets.
	StripImportPrefix string `mapstructure:"strip_import_prefix"`

	// GoModulePath overrides the Go module path used in go_proto_library importpath.
	GoModulePath string `mapstructure:"go_module_path"`
}

BazelConfig contains Bazel integration settings.

type BuildConfig

type BuildConfig struct {
	Workers     int         `mapstructure:"workers"`
	Incremental bool        `mapstructure:"incremental"`
	Cache       CacheConfig `mapstructure:"cache"`
}

BuildConfig contains build settings

type CacheConfig

type CacheConfig struct {
	Enabled   bool   `mapstructure:"enabled"`
	Directory string `mapstructure:"directory"`
}

CacheConfig contains cache settings

type Config

type Config struct {
	// SchemaVersion identifies the buffalo.yaml schema. Use `buffalo config migrate`
	// to upgrade older files. Missing field is interpreted as v1.
	SchemaVersion int `mapstructure:"schema_version" json:"schema_version,omitempty" desc:"Configuration schema version. Current: 2."`

	Project      ProjectConfig           `mapstructure:"project"`
	Proto        ProtoConfig             `mapstructure:"proto"`
	Output       OutputConfig            `mapstructure:"output"`
	Languages    LanguagesConfig         `mapstructure:"languages"`
	Build        BuildConfig             `mapstructure:"build"`
	Bazel        BazelConfig             `mapstructure:"bazel"`
	Versioning   VersioningConfig        `mapstructure:"versioning"`
	Logging      LoggingConfig           `mapstructure:"logging"`
	Dependencies []dependency.Dependency `mapstructure:"dependencies"`
	Plugins      []PluginConfig          `mapstructure:"plugins"`
	Templates    []TemplateConfig        `mapstructure:"templates"`
	Models       ModelsConfig            `mapstructure:"models"`
	Tools        ToolsConfig             `mapstructure:"tools"`

	// ConfigDir is the directory containing the loaded config file.
	// All relative paths in the config are resolved relative to this directory.
	// Set automatically by LoadFromFile. Empty when loaded from CWD.
	ConfigDir string `mapstructure:"-"`
}

Config represents the Buffalo configuration

func DefaultConfig added in v1.33.15

func DefaultConfig(profile Profile) *Config

DefaultConfig returns a programmatically built default Config for the given profile. This is the single source of truth for shipped defaults; configs/default.yaml is regenerated from this via `buffalo config schema --emit=yaml`.

func Load

func Load() (*Config, error)

Load loads configuration from viper

func LoadFromFile

func LoadFromFile(path string) (*Config, error)

LoadFromFile loads configuration from a specific file

func (*Config) GetEnabledLanguages

func (c *Config) GetEnabledLanguages() []string

GetEnabledLanguages returns a list of enabled languages

func (*Config) GetModelsOutputDir added in v1.21.0

func (c *Config) GetModelsOutputDir(language string) string

GetModelsOutputDir returns the models output directory for a specific language. Priority: language.models_output > output.directories["models_<lang>"] > output.base_dir/<lang>/models

func (*Config) GetORMPlugin added in v1.21.0

func (c *Config) GetORMPlugin(language string) string

GetORMPlugin returns the ORM plugin string for a language.

func (*Config) GetOutputDir

func (c *Config) GetOutputDir(language string) string

GetOutputDir returns the output directory for a specific language

func (*Config) GetPb2ImportPrefix added in v1.21.7

func (c *Config) GetPb2ImportPrefix(language string) string

GetPb2ImportPrefix returns the pb2 import prefix for Python. Only relevant for Python language.

func (*Config) IsGenerateModelsFromProto added in v1.21.2

func (c *Config) IsGenerateModelsFromProto() bool

IsGenerateModelsFromProto returns true when plain proto messages (without buffalo.models annotations) should also produce model code.

func (*Config) IsLanguageEnabled

func (c *Config) IsLanguageEnabled(language string) bool

IsLanguageEnabled returns whether a language is enabled

func (*Config) IsORMEnabled added in v1.21.0

func (c *Config) IsORMEnabled(language string) bool

IsORMEnabled returns whether ORM model generation is enabled for a language.

func (*Config) Normalize added in v1.22.1

func (c *Config) Normalize()

Normalize applies backward-compatible mapping between legacy and current fields.

func (*Config) ResolveRelativePaths added in v1.33.4

func (c *Config) ResolveRelativePaths()

ResolveRelativePaths resolves all relative paths in the config relative to ConfigDir. If ConfigDir is empty (config loaded from CWD), paths are left unchanged.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the configuration

type CppConfig

type CppConfig struct {
	Enabled      bool   `mapstructure:"enabled"`
	Namespace    string `mapstructure:"namespace"`
	ORM          bool   `mapstructure:"orm"`
	ORMPlugin    string `mapstructure:"orm_plugin"`
	ModelsOutput string `mapstructure:"models_output"`
}

CppConfig contains C++-specific settings

type CppLock added in v1.2.0

type CppLock struct {
	Enabled   bool   `yaml:"enabled" json:"enabled"`
	Namespace string `yaml:"namespace,omitempty" json:"namespace,omitempty"`
	OutputDir string `yaml:"output_dir" json:"output_dir"`
}

CppLock contains locked C++ configuration

type DependencyLock added in v1.2.0

type DependencyLock struct {
	Name    string `yaml:"name" json:"name"`
	Type    string `yaml:"type" json:"type"` // git, http, local
	URL     string `yaml:"url,omitempty" json:"url,omitempty"`
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	Path    string `yaml:"path,omitempty" json:"path,omitempty"`
	Hash    string `yaml:"hash" json:"hash"`

	// ExternalPrefixes are the detected external import prefixes from this dependency
	ExternalPrefixes []string `yaml:"external_prefixes,omitempty" json:"external_prefixes,omitempty"`
}

DependencyLock contains locked dependency information

type GoConfig

type GoConfig struct {
	Enabled      bool   `mapstructure:"enabled"`
	Module       string `mapstructure:"module"`
	Generator    string `mapstructure:"generator"`
	ORM          bool   `mapstructure:"orm"`
	ORMPlugin    string `mapstructure:"orm_plugin"`
	ModelsOutput string `mapstructure:"models_output"`
}

GoConfig contains Go-specific settings

type GoLock added in v1.2.0

type GoLock struct {
	Enabled   bool   `yaml:"enabled" json:"enabled"`
	Module    string `yaml:"module,omitempty" json:"module,omitempty"`
	OutputDir string `yaml:"output_dir" json:"output_dir"`
}

GoLock contains locked Go configuration

type LanguagesConfig

type LanguagesConfig struct {
	Python     PythonConfig     `mapstructure:"python"`
	Go         GoConfig         `mapstructure:"go"`
	Rust       RustConfig       `mapstructure:"rust"`
	Cpp        CppConfig        `mapstructure:"cpp"`
	Typescript TypescriptConfig `mapstructure:"typescript"`
}

LanguagesConfig contains language-specific settings

type LanguagesLock added in v1.2.0

type LanguagesLock struct {
	Python *PythonLock `yaml:"python,omitempty" json:"python,omitempty"`
	Go     *GoLock     `yaml:"go,omitempty" json:"go,omitempty"`
	Rust   *RustLock   `yaml:"rust,omitempty" json:"rust,omitempty"`
	Cpp    *CppLock    `yaml:"cpp,omitempty" json:"cpp,omitempty"`
}

LanguagesLock contains locked language configurations

type LockFile added in v1.2.0

type LockFile struct {
	// Version of the lock file format
	Version string `yaml:"version" json:"version"`

	// GeneratedAt is when the lock file was generated
	GeneratedAt time.Time `yaml:"generated_at" json:"generated_at"`

	// ConfigHash is the SHA256 hash of the buffalo.yaml file
	ConfigHash string `yaml:"config_hash" json:"config_hash"`

	// Project information
	Project ProjectLock `yaml:"project" json:"project"`

	// Proto files information
	Proto ProtoLock `yaml:"proto" json:"proto"`

	// Languages configuration with resolved values
	Languages LanguagesLock `yaml:"languages" json:"languages"`

	// Dependencies with resolved versions and hashes
	Dependencies []DependencyLock `yaml:"dependencies" json:"dependencies"`

	// Tools information
	Tools ToolsLock `yaml:"tools" json:"tools"`
}

LockFile represents the buffalo.lock file structure

func (*LockFile) GetExcludeImports added in v1.2.0

func (l *LockFile) GetExcludeImports() []string

GetExcludeImports returns the resolved exclude imports for Python

func (*LockFile) HasProtoFileChanged added in v1.2.0

func (l *LockFile) HasProtoFileChanged(path string, currentHash string) bool

HasProtoFileChanged checks if a specific proto file has changed

func (*LockFile) ToJSON added in v1.2.0

func (l *LockFile) ToJSON() (string, error)

ToJSON returns the lock file as JSON (for debugging)

type LockFileManager added in v1.2.0

type LockFileManager struct {
	// contains filtered or unexported fields
}

LockFileManager manages buffalo.lock file operations

func NewLockFileManager added in v1.2.0

func NewLockFileManager(configPath string) *LockFileManager

NewLockFileManager creates a new lock file manager

func (*LockFileManager) Generate added in v1.2.0

func (m *LockFileManager) Generate(cfg *Config, protoFiles []string) (*LockFile, error)

Generate generates a new lock file from the config

func (*LockFileManager) GetLockPath added in v1.2.0

func (m *LockFileManager) GetLockPath() string

GetLockPath returns the path to the lock file

func (*LockFileManager) Load added in v1.2.0

func (m *LockFileManager) Load() (*LockFile, error)

Load loads the lock file from disk

func (*LockFileManager) NeedsRegeneration added in v1.2.0

func (m *LockFileManager) NeedsRegeneration() (bool, string, error)

NeedsRegeneration checks if the lock file needs to be regenerated

func (*LockFileManager) Save added in v1.2.0

func (m *LockFileManager) Save(lock *LockFile) error

Save saves the lock file to disk

func (*LockFileManager) Verify added in v1.33.17

func (m *LockFileManager) Verify(cfg *Config, protoFiles []string) (*LockFile, []string, error)

Verify compares the on-disk lock file against the current config and proto files. It returns a list of human-readable mismatch reasons; an empty slice means the lock file is fully consistent. The lock file itself is returned when present so callers can still apply resolved values without rewriting.

Verify is the strict-mode counterpart of NeedsRegeneration: it never rewrites or regenerates the lock file, making it safe to use under --frozen-lockfile in CI.

type LoggingConfig

type LoggingConfig struct {
	Level  string `mapstructure:"level"`
	Format string `mapstructure:"format"`
	Output string `mapstructure:"output"`
	File   string `mapstructure:"file"`
}

LoggingConfig contains logging settings

type ModelsConfig added in v1.21.0

type ModelsConfig struct {
	Enabled                 bool              `mapstructure:"enabled"`
	GenerateModelsFromProto bool              `mapstructure:"generate_models_from_proto"`
	BaseModelFields         []BaseFieldConfig `mapstructure:"base_model_fields"`
}

ModelsConfig contains buffalo.models generation settings.

type OutputConfig

type OutputConfig struct {
	BaseDir                string            `mapstructure:"base_dir"`
	Directories            map[string]string `mapstructure:"directories"`
	PreserveProtoStructure bool              `mapstructure:"preserve_proto_structure"`
}

OutputConfig contains output settings

type PluginConfig added in v1.0.0

type PluginConfig struct {
	Name       string                 `mapstructure:"name"`
	Enabled    bool                   `mapstructure:"enabled"`
	HookPoints []string               `mapstructure:"hooks"`
	Priority   int                    `mapstructure:"priority"`
	Options    map[string]interface{} `mapstructure:"config"`
}

PluginConfig contains plugin configuration

type Profile added in v1.33.15

type Profile string

Profile selects which preset DefaultConfig produces.

const (
	// ProfileMinimal: smallest viable config (one language enabled).
	ProfileMinimal Profile = "minimal"
	// ProfileFull: every documented field present (good for discovery).
	ProfileFull Profile = "full"
	// ProfileBazel: full + Bazel integration enabled.
	ProfileBazel Profile = "bazel"
)

type ProjectConfig

type ProjectConfig struct {
	Name    string `mapstructure:"name"`
	Version string `mapstructure:"version"`
}

ProjectConfig contains project-level settings

type ProjectLock added in v1.2.0

type ProjectLock struct {
	Name    string `yaml:"name" json:"name"`
	Version string `yaml:"version" json:"version"`
}

ProjectLock contains locked project information

type ProtoConfig

type ProtoConfig struct {
	Paths       []string `mapstructure:"paths"`
	Exclude     []string `mapstructure:"exclude"`
	ImportPaths []string `mapstructure:"import_paths"`
}

ProtoConfig contains proto file settings

type ProtoFileLock added in v1.2.0

type ProtoFileLock struct {
	Hash         string    `yaml:"hash" json:"hash"`
	Size         int64     `yaml:"size" json:"size"`
	ModifiedAt   time.Time `yaml:"modified_at" json:"modified_at"`
	Package      string    `yaml:"package,omitempty" json:"package,omitempty"`
	Dependencies []string  `yaml:"dependencies,omitempty" json:"dependencies,omitempty"`
}

ProtoFileLock contains locked information for a single proto file

type ProtoLock added in v1.2.0

type ProtoLock struct {
	// Files is a map of proto file path to its hash
	Files map[string]ProtoFileLock `yaml:"files" json:"files"`

	// ImportPaths are the resolved import paths
	ImportPaths []string `yaml:"import_paths" json:"import_paths"`

	// TotalFiles count
	TotalFiles int `yaml:"total_files" json:"total_files"`
}

ProtoLock contains locked proto files information

type PythonConfig

type PythonConfig struct {
	Enabled         bool     `mapstructure:"enabled"`
	Package         string   `mapstructure:"package"`
	Generator       string   `mapstructure:"generator"`
	WorkDir         string   `mapstructure:"workdir"`
	ExcludeImports  []string `mapstructure:"exclude_imports"`
	ORM             bool     `mapstructure:"orm"`
	ORMPlugin       string   `mapstructure:"orm_plugin"`
	ModelsOutput    string   `mapstructure:"models_output"`
	Pb2ImportPrefix string   `mapstructure:"pb2_import_prefix"`
}

PythonConfig contains Python-specific settings

type PythonLock added in v1.2.0

type PythonLock struct {
	Enabled bool `yaml:"enabled" json:"enabled"`

	// WorkDir is the working directory prefix for imports
	WorkDir string `yaml:"workdir,omitempty" json:"workdir,omitempty"`

	// ExcludeImports are prefixes to exclude from import fixing (auto-detected + user-defined)
	ExcludeImports []string `yaml:"exclude_imports" json:"exclude_imports"`

	// OutputDir is the resolved output directory
	OutputDir string `yaml:"output_dir" json:"output_dir"`
}

PythonLock contains locked Python configuration

type RustConfig

type RustConfig struct {
	Enabled      bool   `mapstructure:"enabled"`
	Generator    string `mapstructure:"generator"`
	ORM          bool   `mapstructure:"orm"`
	ORMPlugin    string `mapstructure:"orm_plugin"`
	ModelsOutput string `mapstructure:"models_output"`
}

RustConfig contains Rust-specific settings

type RustLock added in v1.2.0

type RustLock struct {
	Enabled   bool   `yaml:"enabled" json:"enabled"`
	Generator string `yaml:"generator,omitempty" json:"generator,omitempty"`
	OutputDir string `yaml:"output_dir" json:"output_dir"`
}

RustLock contains locked Rust configuration

type SchemaMigration added in v1.33.15

type SchemaMigration struct {
	From        int
	To          int
	Description string
	Apply       func(root *yaml.Node) error
}

SchemaMigration mutates a buffalo.yaml YAML node in-place to upgrade it from one schema version to the next. Migrations are pure: they only touch `node`, never the filesystem.

type TemplateConfig added in v1.0.0

type TemplateConfig struct {
	Name     string            `mapstructure:"name"`
	Language string            `mapstructure:"language"`
	Path     string            `mapstructure:"path"`
	Patterns []string          `mapstructure:"patterns"`
	Vars     map[string]string `mapstructure:"vars"`
}

TemplateConfig contains template configuration

type ToolPin added in v1.33.17

type ToolPin struct {
	// Version is the expected `--version` output substring (e.g. "3.21.12").
	Version string `mapstructure:"version"`

	// Sha256 optionally pins the binary content. When set, `buffalo tools
	// verify` recomputes the digest of the resolved binary and refuses to
	// run on mismatch.
	Sha256 string `mapstructure:"sha256,omitempty"`

	// Path overrides PATH-based discovery and forces a specific binary.
	Path string `mapstructure:"path,omitempty"`
}

ToolPin describes the expected version (and optional checksum) of a tool.

type ToolsConfig added in v1.33.17

type ToolsConfig struct {
	// Protoc pins the protoc compiler binary itself.
	Protoc *ToolPin `mapstructure:"protoc,omitempty"`

	// Plugins pins protoc-gen-* helpers keyed by their bare plugin name
	// (e.g. "go", "go-grpc", "python", "ts"). Buffalo prepends "protoc-gen-"
	// when resolving the actual binary on PATH.
	Plugins map[string]ToolPin `mapstructure:"plugins,omitempty"`
}

ToolsConfig pins external code-generation binaries (protoc and the protoc-gen-* family). Pinning makes builds reproducible across machines and is required by `buffalo build --frozen-lockfile`.

type ToolsLock added in v1.2.0

type ToolsLock struct {
	Protoc        string `yaml:"protoc,omitempty" json:"protoc,omitempty"`
	ProtocVersion string `yaml:"protoc_version,omitempty" json:"protoc_version,omitempty"`
}

ToolsLock contains locked tools information

type TypescriptConfig added in v1.22.0

type TypescriptConfig struct {
	Enabled      bool                    `mapstructure:"enabled"`
	Generator    string                  `mapstructure:"generator"`
	Output       string                  `mapstructure:"output"`
	Plugins      []string                `mapstructure:"plugins"`
	Options      TypescriptOptionsConfig `mapstructure:"options"`
	ORM          bool                    `mapstructure:"orm"`
	ORMPlugin    string                  `mapstructure:"orm_plugin"`
	ModelsOutput string                  `mapstructure:"models_output"`
}

TypescriptConfig contains TypeScript-specific settings

type TypescriptOptionsConfig added in v1.22.1

type TypescriptOptionsConfig struct {
	Generator        string `mapstructure:"generator"`
	ProtocGenTsPath  string `mapstructure:"protoc_gen_ts_path"`
	TsProtoPath      string `mapstructure:"ts_proto_path"`
	ESModules        *bool  `mapstructure:"es_modules"`
	GenerateGrpc     *bool  `mapstructure:"generate_grpc"`
	GenerateGrpcWeb  *bool  `mapstructure:"generate_grpc_web"`
	GenerateNiceGrpc *bool  `mapstructure:"generate_nice_grpc"`
	OutputIndex      *bool  `mapstructure:"output_index"`
}

TypescriptOptionsConfig contains nested TypeScript options for backward-compatible YAML schema.

type VersioningConfig

type VersioningConfig struct {
	Enabled      bool   `mapstructure:"enabled"`
	Strategy     string `mapstructure:"strategy"`      // hash, timestamp, semantic, git
	OutputFormat string `mapstructure:"output_format"` // directory, suffix
	KeepVersions int    `mapstructure:"keep_versions"` // 0 = keep all, >0 = keep N latest
}

VersioningConfig contains versioning settings

Jump to

Keyboard shortcuts

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