README
¶
VEF Framework Go
An opinionated Go framework for enterprise applications, built with Fiber, Uber FX, and Bun.
Unified API resources, generic CRUD, authentication, RBAC, validation, caching, events, storage, MCP, and more.
English | 简体中文 | Quick Start | Documentation | API Reference
VEF Framework Go combines dependency injection, HTTP routing, and data access into a cohesive application framework, with built-in support for API resources, authentication, RBAC, validation, caching, events, storage, MCP, and more.
This README is intentionally brief. Detailed tutorials and reference material are available on the documentation site.
Development status: the project is still pre-1.0. Expect breaking changes while conventions and APIs continue to evolve.
Why VEF
- One resource model for both RPC and REST APIs
- Generic CRUD primitives that reduce repetitive backend code
- Modular composition with Uber FX for clean wiring and extension
- Built-in auth, RBAC, rate limiting, audit, caching, events, storage, MCP, and other infrastructure you would otherwise assemble yourself
Quick Start
Requirements:
- Go 1.26.0 or newer
- No C toolchain required — the framework builds with
CGO_ENABLED=0; the built-in expression engine uses the pure-Goexpr-langlibrary - A supported database such as PostgreSQL, MySQL, or SQLite
Install:
go get github.com/coldsmirk/vef-framework-go
Create main.go:
package main
import "github.com/coldsmirk/vef-framework-go"
func main() {
vef.Run()
}
Create configs/application.toml:
[vef.app]
name = "my-app"
port = 8080
[vef.data_sources.primary]
type = "sqlite"
path = "./my-app.db"
# Additional named sources are optional; each one is reachable through
# datasource.Registry.Get("<name>"). Example:
# [vef.data_sources.analytics]
# type = "postgres"
# host = "analytics.example.com"
# database = "warehouse"
This is the smallest runnable configuration. Sections such as vef.monitor, vef.mcp, and vef.approval are optional.
Run:
go run main.go
VEF loads application.toml from ./configs, ., ../configs, or the path pointed to by VEF_CONFIG_PATH.
Core Concepts
vef.Run(...)starts the framework and wires the default module chain: config, data sources (the registry and primary database connection), middleware, API, security, event, CQRS, cron, redis, mold, storage, sequence, schema, monitor, MCP, and app.- API endpoints are defined as resources with
api.NewRPCResource(...)orapi.NewRESTResource(...). - Business modules are composed with FX options, for example
vef.ProvideAPIResource(...),vef.ProvideMiddleware(...), andvef.ProvideMCPTools(...). - CRUD-heavy modules can build on the generic helpers in
crud/instead of writing repetitive handlers from scratch.
Typical application layout:
my-app/
├── cmd/
├── configs/
└── internal/
├── auth/
├── sys/
├── <domain>/
└── web/
Documentation
- Documentation site: https://coldsmirk.github.io/vef-framework-go-docs
- API reference: https://pkg.go.dev/github.com/coldsmirk/vef-framework-go
- Repository knowledge map: https://deepwiki.com/coldsmirk/vef-framework-go
- Testing conventions: TESTING.md
If you need step-by-step guides, architectural deep dives, or feature-specific reference, prefer the documentation site rather than expanding this README.
Development
Common verification commands:
go test ./...
go test -race ./...
golangci-lint run
go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...
License
Licensed under the Apache License 2.0.
Documentation
¶
Index ¶
- Variables
- func NamedLogger(name string) logx.Logger
- func ProvideAPIResource(constructor any, paramTags ...string) fx.Option
- func ProvideApprovalLifecycleHook(constructor any, paramTags ...string) fx.Option
- func ProvideCQRSBehavior(constructor any, paramTags ...string) fx.Option
- func ProvideChallengeProvider(constructor any, paramTags ...string) fx.Option
- func ProvideDataSourceProvider(constructor any, paramTags ...string) fx.Option
- func ProvideEventConsumeMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideEventErrorSink(constructor any, paramTags ...string) fx.Option
- func ProvideEventMetricsRecorder(constructor any, paramTags ...string) fx.Option
- func ProvideEventPublishMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideEventTransport(constructor any, paramTags ...string) fx.Option
- func ProvideMCPPrompts(constructor any, paramTags ...string) fx.Option
- func ProvideMCPResourceTemplates(constructor any, paramTags ...string) fx.Option
- func ProvideMCPResources(constructor any, paramTags ...string) fx.Option
- func ProvideMCPTools(constructor any, paramTags ...string) fx.Option
- func ProvideMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideSPAConfig(constructor any, paramTags ...string) fx.Option
- func Run(options ...fx.Option)
- func SupplyBusinessBindingHook(constructor any) fx.Option
- func SupplyFileACL(constructor any) fx.Option
- func SupplyMCPServerInfo(info *mcp.ServerInfo) fx.Option
- func SupplySPAConfigs(config *middleware.SPAConfig, configs ...*middleware.SPAConfig) fx.Option
- func SupplyURLKeyMapper(constructor any) fx.Option
- type Hook
- type HookFunc
- type In
- type Lifecycle
- type Out
Constants ¶
This section is empty.
Variables ¶
var ( Provide = fx.Provide Supply = fx.Supply Annotate = fx.Annotate As = fx.As ParamTags = fx.ParamTags ResultTags = fx.ResultTags Self = fx.Self Invoke = fx.Invoke Decorate = fx.Decorate Module = fx.Module Private = fx.Private OnStart = fx.OnStart OnStop = fx.OnStop )
var ApprovalModule = iapproval.Module
ApprovalModule enables the optional approval (workflow) feature: pass it to vef.Run(...) to register the approval API resources, CQRS handlers, engine, binding listener, and timeout scanner. It is intentionally absent from the default boot sequence (bootmodules.Core) so applications that do not need workflows pay nothing. Approval events publish with event.WithTx and the binding listener subscribes, so the host must route approval.* to a transactional transport with a subscribable sink (see the approval docs).
Functions ¶
func NamedLogger ¶
NamedLogger creates a named logger instance for the specified component. This is a convenience function that wraps the internal logger factory.
func ProvideAPIResource ¶
ProvideAPIResource provides an API resource to the dependency injection container. The resource will be registered in the "vef:api:resources" group. The constructor must return api.Resource (not a concrete type).
func ProvideApprovalLifecycleHook ¶ added in v0.24.0
ProvideApprovalLifecycleHook registers a synchronous approval.InstanceLifecycleHook into the FX container. Hooks run inside the engine transaction for OnInstanceCreated / OnInstanceCompleted, so returning an error rolls back the surrounding business operation.
The constructor must return approval.InstanceLifecycleHook (not a concrete type). Multiple hooks compose via the `vef:approval:lifecycle_hooks` group.
func ProvideCQRSBehavior ¶
ProvideCQRSBehavior provides a CQRS behavior middleware to the dependency injection container. The constructor must return cqrs.Behavior (not a concrete type).
func ProvideChallengeProvider ¶
ProvideChallengeProvider provides a login challenge provider to the dependency injection container. The provider will be registered in the "vef:security:challenge_providers" group. The constructor must return security.ChallengeProvider (not a concrete type).
func ProvideDataSourceProvider ¶ added in v0.27.0
ProvideDataSourceProvider registers a datasource.Provider that the framework consults during boot, after the primary and static (TOML) data sources have been registered. Every spec returned by the provider's Load method is passed to datasource.Registry.Register; a name collision with any existing source (TOML or another provider) fails boot.
Typical use case: a tenant table in the primary database whose rows describe additional data sources. The provider reads the table during Load and returns one datasource.Spec per row. For periodic re-sync of the same table, register a cron job that calls datasource.Registry.Reconcile instead.
constructor is an fx-style factory that returns datasource.Provider (or a type that implements it).
func ProvideEventConsumeMiddleware ¶ added in v0.24.0
ProvideEventConsumeMiddleware registers a consume-side event middleware. The constructor must return event/middleware.ConsumeMiddleware.
func ProvideEventErrorSink ¶ added in v0.24.0
ProvideEventErrorSink overrides the framework's default async error sink. The constructor must return event.ErrorSink. Useful when async-publish failures need to flow to a metrics or alerting system rather than just the logger.
func ProvideEventMetricsRecorder ¶ added in v0.24.0
ProvideEventMetricsRecorder overrides the framework's default (expvar-backed) event.MetricsRecorder. The constructor must return event.MetricsRecorder. Use this when forwarding publish/consume observations to Prometheus, OpenTelemetry, or a vendor SDK.
Example:
fx.New(
vef.Module,
vef.ProvideEventMetricsRecorder(newPrometheusRecorder),
)
func ProvideEventPublishMiddleware ¶ added in v0.24.0
ProvideEventPublishMiddleware registers a publish-side event middleware. The constructor must return event/middleware.PublishMiddleware.
func ProvideEventTransport ¶ added in v0.24.0
ProvideEventTransport registers a custom event Transport. The constructor must return event/transport.Transport (or a type that satisfies it).
func ProvideMCPPrompts ¶
ProvideMCPPrompts provides an MCP prompt provider. The constructor must return mcp.PromptProvider (not a concrete type).
func ProvideMCPResourceTemplates ¶
ProvideMCPResourceTemplates provides an MCP resource template provider. The constructor must return mcp.ResourceTemplateProvider (not a concrete type).
func ProvideMCPResources ¶
ProvideMCPResources provides an MCP resource provider. The constructor must return mcp.ResourceProvider (not a concrete type).
func ProvideMCPTools ¶
ProvideMCPTools provides an MCP tool provider. The constructor must return mcp.ToolProvider (not a concrete type).
func ProvideMiddleware ¶
ProvideMiddleware provides a middleware to the dependency injection container. The middleware will be registered in the "vef:app:middlewares" group. The constructor must return app.Middleware (not a concrete type).
func ProvideSPAConfig ¶
ProvideSPAConfig provides a Single Page Application configuration to the dependency injection container. The config will be registered in the "vef:spa" group.
func Run ¶
Run starts the VEF framework with the provided options. It initializes all core modules and runs the application.
func SupplyBusinessBindingHook ¶ added in v0.24.0
SupplyBusinessBindingHook replaces the framework-provided default approval.BusinessBindingHook (no-op create + status write-back) with a host-supplied implementation. Hosts override this when their business row needs to be allocated during start_instance or when the write-back must touch additional columns / cross-service calls.
constructor is an fx-style factory that returns approval.BusinessBindingHook (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example:
fx.New(
vef.Module,
vef.SupplyBusinessBindingHook(newMyHook),
)
func SupplyFileACL ¶ added in v0.23.0
SupplyFileACL replaces the framework-provided default storage.FileACL with a business-specific implementation. The default ACL is pub-only (reads of keys under storage.PublicPrefix are allowed; everything else is denied), so any application that stores private files MUST register its own implementation through this helper.
constructor is an fx-style factory that returns storage.FileACL (or a type implementing it). It may declare any dependencies already registered in the fx graph — typically orm.DB plus any business services that own the reverse index from object key to owning row.
Example:
type myACL struct{ db orm.DB }
func newMyACL(db orm.DB) storage.FileACL {
return &myACL{db: db}
}
fx.New(
vef.Module,
vef.SupplyFileACL(newMyACL),
)
func SupplyMCPServerInfo ¶
func SupplyMCPServerInfo(info *mcp.ServerInfo) fx.Option
SupplyMCPServerInfo supplies MCP server info.
func SupplySPAConfigs ¶
func SupplySPAConfigs(config *middleware.SPAConfig, configs ...*middleware.SPAConfig) fx.Option
SupplySPAConfigs supplies multiple Single Page Application configurations to the dependency injection container. All configs will be registered in the "vef:spa" group.
func SupplyURLKeyMapper ¶ added in v0.23.0
SupplyURLKeyMapper replaces the framework-provided default storage.URLKeyMapper (storage.ProxyURLKeyMapper) with a business-specific implementation. The default mapper strips and prepends the framework's proxy prefix ("/storage/files/"), so it resolves the proxy URLs served by the built-in proxy middleware back to storage keys during meta:"rich_text" / "markdown" reconciliation. Applications that embed a different URL convention — external CDN URLs, or bare storage keys — register their own mapper here so those URLs can be resolved back to storage keys before consuming claims or scheduling deletions.
constructor is an fx-style factory that returns storage.URLKeyMapper (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example: serving files from an external CDN whose URLs embed bare storage keys after a fixed host prefix.
type cdnURLMapper struct{}
func (cdnURLMapper) URLToKey(u string) (key string, ok bool) {
const prefix = "https://cdn.example.com/"
if !strings.HasPrefix(u, prefix) {
return "", false
}
return strings.TrimPrefix(u, prefix), true
}
func (cdnURLMapper) KeyToURL(k string) string {
return "https://cdn.example.com/" + k
}
fx.New(
vef.Module,
vef.SupplyURLKeyMapper(func() storage.URLKeyMapper { return cdnURLMapper{} }),
)
Source Files
Directories