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, vef.approval, and vef.integration 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 ProvideApprovalAggregator(constructor any, paramTags ...string) fx.Option
- func ProvideApprovalFormSchemaParser(constructor any, paramTags ...string) fx.Option
- func ProvideApprovalLifecycleHook(constructor any, paramTags ...string) fx.Option
- func ProvideAuthStrategy(constructor any, paramTags ...string) fx.Option
- func ProvideCQRSBehavior(constructor any, paramTags ...string) fx.Option
- func ProvideChallengeProvider(constructor any, paramTags ...string) fx.Option
- func ProvideCronJobHandler(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 ProvideIntegrationInboundAuthScheme(constructor any, paramTags ...string) fx.Option
- func ProvideIntegrationInboundHandler(constructor any, paramTags ...string) fx.Option
- func ProvideIntegrationOutboundAuthScheme(constructor any, paramTags ...string) fx.Option
- func ProvideJSLib(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 ProvideSessionRevocationListener(constructor any, paramTags ...string) fx.Option
- func Run(options ...fx.Option)
- func SupplyBusinessRefProvider(constructor any) fx.Option
- func SupplyBusinessRefResolver(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 (internal/bootmodules) 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).
var IntegrationModule = iintegration.Module
IntegrationModule enables the optional integration engine: config- and script-driven adapters that translate between external systems (HIS, LIS, third-party APIs) and the application's standard contracts. It registers the contract/system/adapter/route management resources, the invocation log, the dry-run test console, and provides integration.Invoker for business code. Absent from the default boot sequence so applications that do not integrate pay nothing.
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 ProvideApprovalAggregator ¶ added in v0.36.0
ProvideApprovalAggregator registers a custom detail-table aggregator for approval field conditions alongside the built-in sum / count / avg. The constructor must return an approval.Aggregator; the condition evaluator picks it up by its AggregateKind with no changes to existing code.
vef.ProvideApprovalAggregator(func() approval.Aggregator { return myMedian{} })
func ProvideApprovalFormSchemaParser ¶ added in v0.38.0
ProvideApprovalFormSchemaParser overrides the framework's default approval.FormSchemaParser — the built-in vef-framework-react form-editor parser — with a host implementation. The replacement is wholesale, not additive: every deployed form schema goes through it, so it must understand every designer document the host submits. The constructor must return approval.FormSchemaParser. Parsing runs once at flow deploy; versions deployed earlier keep the form_fields they were persisted with.
Example:
fx.New(
vef.Module,
vef.ProvideApprovalFormSchemaParser(newMyDesignerParser),
)
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 / OnInstanceTransition, 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 ProvideAuthStrategy ¶ added in v0.34.0
ProvideAuthStrategy provides a custom API authentication strategy to the dependency injection container. The strategy will be registered in the "vef:api:auth_strategies" group and is selected per resource through api.AuthConfig.Strategy by the name it reports from Name(). The constructor must return api.AuthStrategy (not a concrete type).
Example:
type apiKeyStrategy struct{ /* ... */ }
func (*apiKeyStrategy) Name() string { return "api-key" }
func (s *apiKeyStrategy) Authenticate(ctx fiber.Ctx, options map[string]any) (*security.Principal, error) {
/* validate the credential and return the principal */
}
func newAPIKeyStrategy(db orm.DB) api.AuthStrategy { return &apiKeyStrategy{ /* ... */ } }
fx.New(
vef.Module,
vef.ProvideAuthStrategy(newAPIKeyStrategy),
)
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 ProvideCronJobHandler ¶ added in v0.40.0
ProvideCronJobHandler registers a durable cron job handler with the schedule store (vef.cron.store). Exactly one handler per job name; duplicates fail at start-up. Persisted schedules reference the handler by name, and a handler may ship a default schedule that is seeded when absent.
vef.ProvideCronJobHandler(func(svc *ReportService) cron.JobHandler {
return cron.NewJobHandler("report.daily", svc.GenerateDaily,
cron.WithDefaultSchedule(cron.ScheduleSpec{Trigger: cron.Expr("0 2 * * *", "Asia/Shanghai")}))
})
constructor is an fx-style factory that returns cron.JobHandler.
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 ProvideIntegrationInboundAuthScheme ¶ added in v0.39.0
ProvideIntegrationInboundAuthScheme registers a custom inbound auth scheme for the integration engine (requires IntegrationModule). Systems reference schemes by name in their inbound auth config; a scheme whose Name matches a built-in (none / ip / http_basic / bearer / header / query / signature / script) replaces it.
vef.ProvideIntegrationInboundAuthScheme(func() integration.InboundAuthScheme { return &partnerTokenScheme{} })
constructor is an fx-style factory that returns integration.InboundAuthScheme.
func ProvideIntegrationInboundHandler ¶ added in v0.39.0
ProvideIntegrationInboundHandler registers the business handler serving one inbound integration contract (requires IntegrationModule). Exactly one handler may serve a contract; duplicates fail at start-up.
vef.ProvideIntegrationInboundHandler(func(db orm.DB) integration.InboundHandler {
return integration.NewInboundHandler("lab.report_result", func(ctx context.Context, report LabReport) (Ack, error) { ... })
})
constructor is an fx-style factory that returns integration.InboundHandler.
func ProvideIntegrationOutboundAuthScheme ¶ added in v0.39.0
ProvideIntegrationOutboundAuthScheme registers a custom auth scheme for the integration engine (requires IntegrationModule). Systems reference schemes by name in their auth config; a scheme whose Name matches a built-in (none / http_basic / bearer / header / query / signature / script) replaces it.
vef.ProvideIntegrationOutboundAuthScheme(func() integration.OutboundAuthScheme { return &hmacScheme{} })
constructor is an fx-style factory that returns integration.OutboundAuthScheme.
func ProvideJSLib ¶ added in v0.39.0
ProvideJSLib contributes a JavaScript library to the shared js.Engine. The framework already seeds six libraries at safe defaults: the always-on utilities console / crypto / cache, and the opt-in capabilities events / http / sql. This is for either of two things:
Overriding a default: return a library whose Name matches a built-in (jssql.Name, jshttp.Name, ...) and it replaces the default, keeping the default's tier — an always-on utility stays always-on, an opt-in capability stays opt-in. Use it to supply your own policy: enable sql.execute, restrict HTTP hosts, back the cache with Redis, restrict publishable event types.
Adding a new library: return a library with a fresh name. New libraries join the opt-in catalog, seen only when a runtime is created with js.EnableLibs(...).
vef.ProvideJSLib(func(db orm.DB) js.Lib { return jssql.New(db, config.Postgres, jssql.WithExecute()) }) vef.ProvideJSLib(func() js.Lib { return jshttp.New(jshttp.WithPublicNetworkOnly()) })
constructor is an fx-style factory that returns a js.Lib.
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 ProvideSessionRevocationListener ¶ added in v0.40.0
ProvideSessionRevocationListener registers a security.SessionRevocationListener that observes login-session revocations (logout, concurrent-login eviction, administrative kicks). The framework fires listeners synchronously from its own revocation paths — implementations must be fast and non-blocking.
vef.ProvideSessionRevocationListener(func(audit *AuditService) security.SessionRevocationListener {
return audit
})
constructor is an fx-style factory that returns security.SessionRevocationListener.
func Run ¶
Run starts the VEF framework with the provided options. It initializes all core modules and runs the application.
func SupplyBusinessRefProvider ¶ added in v0.35.0
SupplyBusinessRefProvider replaces the default no-op approval.BusinessRefProvider with a host implementation that resolves or allocates the business row during start_instance, inside the same transaction. Register one when the business record must come into existence together with the instance; callers that already know the reference can simply pass businessRef in the start parameters instead.
The engine-owned write-back of approval outcomes is not affected by this hook and cannot be replaced — hosts extend around it with ProvideApprovalLifecycleHook or event subscriptions.
constructor is an fx-style factory that returns approval.BusinessRefProvider (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example:
fx.New(
vef.Module,
vef.SupplyBusinessRefProvider(newOrderRefProvider),
)
func SupplyBusinessRefResolver ¶ added in v0.35.0
SupplyBusinessRefResolver replaces the default approval.BusinessRefResolver. The default handles a bare single-column key and a composite key encoded as a JSON object. Register a replacement when Instance.BusinessRef uses another shape or resolving the configured key requires a host lookup.
constructor is an fx-style factory that returns approval.BusinessRefResolver (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example:
fx.New(
vef.Module,
vef.SupplyBusinessRefResolver(newCompositeRefResolver),
)
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{} }),
)
Types ¶
type Hook ¶
func StartStopHook ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
vef-cli
command
|
|
|
internal
|
|
|
approval/storage
Package storage implements the form-data storage strategies for the approval module.
|
Package storage implements the form-data storage strategies for the approval module. |