README
¶
Avero
Avero is an application host for Go services. It owns the composition root, the lifecycle, the configuration, the telemetry and the routing. It does not own the semantics of your application.
Avero is not a web framework. It writes plain Go that you can read, change and delete.
Start
go install github.com/alternayte/avero/cmd/avero@latest
avero new blog
cd blog
cp .env.example .env
avero migrate up
avero dev
The application answers on http://localhost:8080. A change to a .css file
reaches the browser in about 40 milliseconds. A change to a .go file reaches
it in under two seconds.
You need Go, and a database when you leave SQLite. You need no Node.js.
What you get
- One command writes an application that builds, runs and passes its tests.
- Typed handlers with generated binding and validation. No reflection runs on a request path.
- A module contract, so one directory holds one feature.
- Server rendered pages with forms, CSRF, flash messages and validation.
- An asset pipeline with esbuild and the Tailwind standalone binary.
- Datastar and htmx, as optional imports.
- An HTTP client generator with timeouts, retries, a circuit breaker and OTel spans.
- A development loop that swaps a stylesheet with no reload and morphs the page after a rebuild.
- An MCP server, so an agent reads the routes, the modules and the models, and writes a new slice.
The commands
avero new <name> write a new application
avero slice <name> write a new feature slice
avero dev run the application and rebuild it on each change
avero generate write the generated files
avero build generate, build the assets and compile the binary
avero migrate write and apply the migrations
avero routes print the routes
avero modules print the contribution of each module
avero schema print the models
avero doctor prove the configuration and the database
avero verify run the gate
avero mcp serve the agent surface over stdio
avero js pin <pkg> fetch a bundled module into the vendor directory
avero assets init write the package.json of tier 1
The shapes
| Shape | Application | Exercises |
|---|---|---|
ssr |
a blog with posts | the router, the views, the forms and the assets |
spa |
a task board | the JSON routes and the embedded front end |
api |
an order service | the JSON service and the generated client |
examples/ holds one application of each shape. The gate writes them again and
compares them, so they never drift from avero new.
The state of the subsystems
| ID | Subsystem | State |
|---|---|---|
| S1 | Configuration | ready |
| S2 | Host and lifecycle | ready |
| S3 | Telemetry | ready |
| S4 | Router and request context | ready |
| S5 | Handler codegen | ready |
| S6 | Module system | ready |
| S7 | Outbox relay | planned |
| S8 | Inbox consumer | planned |
| S9 | Event sourcing | planned |
| S10 | View layer | ready |
| S11 | Asset pipeline | ready |
| S12 | Hypermedia adapters | ready |
| S13 | Client codegen | ready |
| S14 | CLI and scaffolder | ready |
| S15 | Dev loop | ready |
| S16 | Agent surface | ready |
An application that publishes a message with an exactly-once effect waits for S7, S8 and S9. Every other shape works today.
The documents
- Getting started
- Configuration
- Routing and handlers
- Views and forms
- Assets
- HTTP clients
- The agent surface
- GraphQL
- The changelog
The gate
just verify
The gate runs gofmt, go vet, golangci-lint, the tests with the race detector, the integration tests, the regeneration check, the three reference applications, and the development experience budgets.
Licence
MIT. See LICENSE.
Documentation
¶
Overview ¶
Package avero is the name that an application writes.
It holds aliases and thin wrappers for the subsystem packages. It holds no logic and no state, so it is not a facade: it hides nothing and it adds no behaviour. Read the subsystem package for the contract of a name.
config the configuration loader and the report, S1 host the lifecycle, the readiness gate and the boot checks, S2 router the routes, the request context and the middleware, S4 module the module contract and the module inspection, S6 view the helpers of a server rendered page, S10 assets the asset pipeline and the manifest, S11
The hypermedia adapters, ds and htmx, are optional imports. This package holds no alias for them, so an application that needs neither carries neither. See the SDD, S12.
telemetry the traces, the metrics and the logger, S3
An application can import a subsystem directly. The two forms are the same types.
Index ¶
- Constants
- func AssetHandler(fsys fs.FS, m *Manifest) http.Handler
- func Attr(key string, value any) attribute.KeyValue
- func Exit(w io.Writer, err error) int
- func FieldError(ctx context.Context, field string) string
- func HasError(ctx context.Context, field string) bool
- func Inspect[T any](args []string, out, errOut io.Writer, r *Router, set *ModuleSet, ...) int
- func Inspecting(args []string) bool
- func Load[T any](ctx context.Context) (*T, error)
- func Old(ctx context.Context, field string) string
- func OldFrom(ctx context.Context) any
- func WithForm(page func(c *Ctx, f *Fields) ViewComponent) router.Option
- type App
- type AssetEntry
- type BaseConfig
- type Binder
- type Check
- type Component
- type Contribution
- type Ctx
- type DescribeModule
- type Description
- type EventDesc
- type Field
- type FieldDesc
- type Fields
- type HTTPModule
- type Handler
- type InboxHandler
- type InboxModule
- type Job
- type Loader
- type Manifest
- type Middleware
- func AccessLog(l *slog.Logger) Middleware
- func Adapt(name string, mw func(http.Handler) http.Handler) Middleware
- func CSRF(secret Secret, opts ...router.CookieOption) Middleware
- func Flash(secret Secret, opts ...router.CookieOption) Middleware
- func Recover(l *slog.Logger) Middleware
- func RequestID() Middleware
- func Transaction(e *drel.Engine) Middleware
- type MigrationModule
- type Migrator
- type ModelDesc
- type Module
- type ModuleReport
- type ModuleSet
- type OTelConfig
- type Option
- func WithChecks(cs ...Check) Option
- func WithComponents(cs ...Component) Option
- func WithHandler(h http.Handler) Option
- func WithListener(l net.Listener) Option
- func WithLogger(l *slog.Logger) Option
- func WithMigrator(m Migrator) Option
- func WithSignals(sig ...os.Signal) Option
- func WithoutSignals() Option
- type Projection
- type ProjectorModule
- type Ready
- type Report
- type Response
- func Empty(code int) Response
- func HTML(code int, body string) Response
- func JSON(code int, body any) Response
- func NoContent() Response
- func Redirect(code int, to string) Response
- func Status(code int) Response
- func Text(code int, body string) Response
- func View(c ViewComponent) Response
- func ViewStatus(code int, c ViewComponent) Response
- type Route
- type RouteDesc
- type RouteReport
- type Router
- type ScheduleModule
- type Scheduler
- type SchemaReport
- type Secret
- type Source
- type Telemetry
- type TelemetryOption
- type Toast
- type Validator
- type ViewComponent
- type ViewFunc
Constants ¶
const ( SourceEnv = config.SourceEnv SourceDefault = config.SourceDefault SourceAbsent = config.SourceAbsent )
The sources that a report names.
const ( ToastInfo = router.ToastInfo ToastSuccess = router.ToastSuccess ToastWarning = router.ToastWarning ToastError = router.ToastError // StatusCSRF is the status of a CSRF fault. StatusCSRF = router.StatusCSRF )
The toast levels and the CSRF status.
const InspectPrefix = "avero:"
InspectPrefix marks a command that the avero binary sends to the application. The CLI runs `go run . avero:routes`, because the routes and the modules of an application live in its own code. See the SDD, S14.
const Redacted = config.Redacted
Redacted replaces the value of a secret field wherever Avero prints it.
Variables ¶
This section is empty.
Functions ¶
func AssetHandler ¶
AssetHandler serves the built assets of a manifest. See assets.Handler.
r.Mount("/assets/", avero.AssetHandler(dist, m))
func Attr ¶
Attr builds a span attribute. A Secret reads as ******** and never reaches an exporter. See telemetry.Attr.
func Exit ¶
Exit writes err to w and returns the process exit code. It returns 0 for a nil error and 1 for any fault. It prints a configuration fault with the config format and every other fault with the host format. The caller owns the call to os.Exit.
func FieldError ¶
FieldError returns the validation message of this field.
The SDD names this helper Error. The root package already holds the Error name in the toast API of Ctx, and a package level Error reads as a fault type in Go. The view package holds the name that the SDD states, and a component calls view.Error.
func Inspect ¶
func Inspect[T any](args []string, out, errOut io.Writer, r *Router, set *ModuleSet, checks ...Check) int
Inspect answers one inspection command and returns the exit code.
The type parameter is the configuration of the application, so avero:doctor reports every variable that the application reads. The checks are the boot checks, so the doctor answers the question that DX-8 asks before the process starts.
func Inspecting ¶
Inspecting reports an inspection command. The application calls it before it loads the configuration and before it opens the database, so an inspection needs neither.
func main() {
r, modules := wire(nil)
if avero.Inspecting(os.Args[1:]) {
os.Exit(avero.Inspect[Config](os.Args[1:], os.Stdout, os.Stderr, r, modules))
}
os.Exit(run())
}
Types ¶
type BaseConfig ¶
type BaseConfig = config.BaseConfig
BaseConfig holds the variables that every Avero application reads.
type Check ¶
Check is one boot check.
func BrokerCheck ¶
BrokerCheck proves that the broker accepts a connection. It opens a TCP connection to the host of the address, because the broker library belongs to the application.
func DatabaseCheck ¶
DatabaseCheck proves that the database answers. It opens its own connection, so `avero doctor` runs it with no application. An application that already holds an engine passes it to DatabaseCheckOn.
func DatabaseCheckOn ¶
DatabaseCheckOn proves the database with an engine that the application already opened.
func MigrationCheck ¶
MigrationCheck proves that the database holds every migration of the directory. It opens its own connection, so `avero doctor` runs it with no application. An application that already holds an engine passes it to MigrationCheckOn, which opens nothing.
Register it with WithChecks, so a pending migration stops the process before it serves. See DX-8.
func MigrationCheckOn ¶
MigrationCheckOn proves the migrations with an engine that the application already opened.
func SecretCheck ¶
SecretCheck returns a boot check that proves AVERO_SECRET is long enough to sign a cookie. Register it with WithChecks, so that a weak secret stops the process with a repair sentence instead of a panic inside the router wiring. See DX-8.
app := avero.New(cfg.BaseConfig,
avero.WithChecks(avero.SecretCheck(cfg.Secret)),
avero.WithHandler(handler))
type Contribution ¶
type Contribution = module.Contribution
Contribution is one row of the contribution table.
type DescribeModule ¶
type DescribeModule = module.DescribeModule
DescribeModule states the description that an agent reads.
type Description ¶
type Description = module.Description
Description states what one module contributes. See AN-3.
type Fields ¶
Fields holds one message for each field that failed validation.
func FieldsFrom ¶
FieldsFrom returns the validation result of a failed request. S10 renders the form again from it.
type Handler ¶
Handler is one typed handler.
func In ¶
func In[T any, P interface { *T Binder Validator }](fn func(c *Ctx, in T) (Response, error), ) Handler
In adapts a typed handler to the router. The constraint requires the Bind and Validate methods that `avero generate` writes, so a missing or stale generated file is a compile fault at the route. See router.In.
r.Post("/things", avero.In(m.Create))
type Middleware ¶
type Middleware = router.Middleware
Middleware wraps a handler and carries a name.
func AccessLog ¶
func AccessLog(l *slog.Logger) Middleware
AccessLog writes one line for each request.
func CSRF ¶
func CSRF(secret Secret, opts ...router.CookieOption) Middleware
CSRF protects an unsafe method with a signed double-submit token. Pass cfg.Secret, which BaseConfig reads from AVERO_SECRET.
func Flash ¶
func Flash(secret Secret, opts ...router.CookieOption) Middleware
Flash carries a Toast from one request to the next. Pass cfg.Secret, which BaseConfig reads from AVERO_SECRET.
func Transaction ¶
func Transaction(e *drel.Engine) Middleware
Transaction opens a drel transaction and decides the commit from the response.
type MigrationModule ¶
type MigrationModule = module.MigrationModule
MigrationModule contributes migration files.
type ModuleReport ¶
ModuleReport lists the contribution of every module.
type OTelConfig ¶
type OTelConfig = config.OTelConfig
OTelConfig holds the standard OTEL_* variables.
type Option ¶
Option configures an application.
func WithChecks ¶
WithChecks registers boot checks. See host.WithChecks.
func WithComponents ¶
WithComponents registers components. See host.WithComponents.
func WithHandler ¶
WithHandler mounts the application handler. See host.WithHandler.
func WithListener ¶
WithListener supplies the listener. See host.WithListener.
func WithLogger ¶
WithLogger supplies the logger. See host.WithLogger.
func WithMigrator ¶
WithMigrator supplies the migrator. See host.WithMigrator.
func WithSignals ¶
WithSignals sets the signals that close the application. See host.WithSignals.
func WithoutSignals ¶
func WithoutSignals() Option
WithoutSignals installs no signal handler. See host.WithoutSignals.
type ProjectorModule ¶
type ProjectorModule = module.ProjectorModule
ProjectorModule contributes projections.
type Response ¶
Response is the result of a handler.
func View ¶
func View(c ViewComponent) Response
View renders a component with 200 and the HTML content type.
return avero.View(pages.Index(posts)), nil
func ViewStatus ¶
func ViewStatus(code int, c ViewComponent) Response
ViewStatus renders a component with this status. See view.ViewStatus.
type ScheduleModule ¶
type ScheduleModule = module.ScheduleModule
ScheduleModule contributes scheduled jobs.
type SchemaReport ¶
type SchemaReport = module.SchemaReport
SchemaReport lists the models of every module. `avero schema` prints it.
func Schema ¶
func Schema(set *ModuleSet) *SchemaReport
Schema returns the models that the modules describe.
type Telemetry ¶
Telemetry holds the tracer, the meter and the logger of one application. It is a component, so Stop flushes the exporters.
func NewTelemetry ¶
func NewTelemetry(cfg BaseConfig, opts ...TelemetryOption) (*Telemetry, error)
NewTelemetry builds the telemetry provider from the OTEL_* variables. See telemetry.New.
type TelemetryOption ¶
TelemetryOption configures the telemetry provider.
type ViewComponent ¶
ViewComponent renders itself. A templ component satisfies it. The root package already holds Component for the lifecycle contract of the host, so the view name carries the View prefix here.
func CSRFField ¶
func CSRFField() ViewComponent
CSRFField returns the hidden field that an unsafe form must carry.
The SDD names it CSRF. The root package already holds CSRF for the middleware, so the field carries the longer name here. A component calls view.CSRF.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets holds the asset pipeline, S11.
|
Package assets holds the asset pipeline, S11. |
|
cli
module
|
|
|
cmd
|
|
|
avero
command
Command avero writes an application, generates its code, proves its configuration and builds it.
|
Command avero writes an application, generates its code, proves its configuration and builds it. |
|
avero/dev
Package dev holds the development loop, S15.
|
Package dev holds the development loop, S15. |
|
Package codegen writes the binding and the validation of each handler input as plain Go.
|
Package codegen writes the binding and the validation of each handler input as plain Go. |
|
client
Package client holds the HTTP client generator and the runtime that its output calls, S13.
|
Package client holds the HTTP client generator and the runtime that its output calls, S13. |
|
client/internal/example
Package example holds the client that the tests of the generator drive.
|
Package example holds the client that the tests of the generator drive. |
|
internal/example
Package example is the fixture of the generator.
|
Package example is the fixture of the generator. |
|
Package config loads a configuration struct from environment variables.
|
Package config loads a configuration struct from environment variables. |
|
Package ds holds the Datastar adapter, S12.
|
Package ds holds the Datastar adapter, S12. |
|
Package host owns the lifecycle of an Avero application.
|
Package host owns the lifecycle of an Avero application. |
|
Package htmx holds the htmx adapter, S12.
|
Package htmx holds the htmx adapter, S12. |
|
internal
|
|
|
budget
Package budget records a development experience measurement in the artifacts of the repository.
|
Package budget records a development experience measurement in the artifacts of the repository. |
|
cli
Package cli holds the commands of the avero binary, S14.
|
Package cli holds the commands of the avero binary, S14. |
|
cmd/averoexamples
command
Command averoexamples writes the three reference applications into examples/, and proves that they match the templates of the scaffolder.
|
Command averoexamples writes the three reference applications into examples/, and proves that they match the templates of the scaffolder. |
|
cmd/averogen
command
Command averogen writes the binding and the validation of each handler input, and the implementation of each client interface.
|
Command averogen writes the binding and the validation of each handler input, and the implementation of each client interface. |
|
inspect
Package inspect runs an inspection command of an application and returns the JSON document that it printed.
|
Package inspect runs an inspection command of an application and returns the JSON document that it printed. |
|
migrations
Package migrations reads the migration files of an application and the rows that drel already applied.
|
Package migrations reads the migration files of an application and the rows that drel already applied. |
|
sse
Package sse writes a server sent event stream.
|
Package sse writes a server sent event stream. |
|
Package mcp serves the agent surface of an application over stdio, S16.
|
Package mcp serves the agent surface of an application over stdio, S16. |
|
Package module holds the module contract and the module inspection, S6.
|
Package module holds the module contract and the module inspection, S6. |
|
Package router builds an http.Handler from typed handlers.
|
Package router builds an http.Handler from typed handlers. |
|
Package scaffold writes a new Avero application, S14.
|
Package scaffold writes a new Avero application, S14. |
|
Package telemetry wires OpenTelemetry traces and metrics, and log/slog.
|
Package telemetry wires OpenTelemetry traces and metrics, and log/slog. |
|
Package verify runs the gate of an application and reports one record for each step, S16.
|
Package verify runs the gate of an application and reports one record for each step, S16. |
|
Package view holds the helpers that a server rendered page needs, S10.
|
Package view holds the helpers that a server rendered page needs, S10. |