avero

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2026 License: MIT Imports: 31 Imported by: 0

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/cli/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.

The two modules

github.com/alternayte/avero is the host: the router, the lifecycle, the configuration, the telemetry, the views and the module system. An application imports it.

github.com/alternayte/avero/cli is the CLI: the commands, the scaffolder, the asset pipeline, the development loop and the MCP server. An application does not import it, so it compiles no bundler and no file watcher.

Take one part or take all of it. The router imports no database and no authentication library. An application that holds a router of another library states it in the wiring and keeps the lifecycle of the host. One handler, one middleware or one whole Avero router reaches a mux of the standard library with HTTP() and MustHandler().

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 templ, and forms with CSRF, flash messages and validation.
  • An asset pipeline with esbuild and the Tailwind standalone binary, and no Node.js for the ssr shape.
  • A TypeScript front end for the spa shape, built by Vite and carried by the binary, with the migrations beside it.
  • 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.
  • An OpenAPI 3.1 description that avero routes --openapi reads from the code, and a typed front end client that the spa shape generates from it.
  • AGENTS.md and four skills in the Agent Skills format, which a coding agent reads with no setting.

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, or the OpenAPI description
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 ui add <lib>    add a component library, such as basecoat
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 in TypeScript with React, TanStack Query and Vite 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.

An example ignores its output directory, as every application does, so a clone holds no built asset. Write the starter assets one time:

go run ./cli/internal/cmd/averoexamples -assets
cd examples/blog && go run .

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

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

View Source 
const (
	SourceEnv     = config.SourceEnv
	SourceDefault = config.SourceDefault
	SourceAbsent  = config.SourceAbsent
)

The sources that a report names.

View Source 
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.

View Source 
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.

View Source 
const MaxMultipartMemory = router.MaxMultipartMemory

MaxMultipartMemory is the number of bytes of a multipart request that stand in memory. See router.MaxMultipartMemory.

View Source 
const MigrateCommand = "migrate"

MigrateCommand is the inspection command that applies the migrations of the modules of an application, or reports the migrations that are pending.

The migrations of a module stand in the binary of the application, so the application applies them and the CLI asks for it. `avero migrate up` runs `go run . avero:migrate up`.

View Source 
const NoModuleMigrations = 3

NoModuleMigrations is the exit code of `avero:migrate` for an application whose modules state no migration.

The CLI reads it and applies the files of the migrations directory that avero.json names, so an application that holds SQL of its own keeps the reader of Avero.

View Source 
const ProblemContentType = router.ProblemContentType

ProblemContentType is the media type of a problem document.

View Source 
const Redacted = config.Redacted

Redacted replaces the value of a secret field wherever Avero prints it.

Variables

View Source 
var (
	// ErrNotFound states that the path names no thing. 404.
	ErrNotFound = router.ErrNotFound
	// ErrUnauthorized states that the request carries no identity. 401.
	ErrUnauthorized = router.ErrUnauthorized
	// ErrForbidden states that the identity may not do this. 403.
	ErrForbidden = router.ErrForbidden
	// ErrConflict states that the state of the thing refuses the change. 409.
	ErrConflict = router.ErrConflict
	// ErrBadRequest states that the request does not read. 400.
	ErrBadRequest = router.ErrBadRequest
	// ErrInternal states a fault of the service. 500.
	ErrInternal = router.ErrInternal
)

The problems that a service answers most. Compare with errors.Is.

Functions

func AppName added in v0.3.0 

func AppName() string

AppName returns the name of the application, which the description of the API carries.

The binary reads its own module path, so a person needs to state the name in no second place.

func AppVersion added in v0.3.0 

func AppVersion() string

AppVersion returns the version of the application, which the description of the API carries. A build from the source names 0.0.0.

func AssetHandler 

func AssetHandler(fsys fs.FS, m *Manifest) http.Handler

AssetHandler serves the built assets of a manifest. See assets.Handler. 

r.Mount("/assets/", avero.AssetHandler(dist, m))

func Attr 

func Attr(key string, value any) attribute.KeyValue

Attr builds a span attribute. A Secret reads as ******** and never reaches an exporter. See telemetry.Attr.

func Delete added in v0.3.0 

func Delete[T any, P router.Input[T], V any](r *Router, pattern string,
	fn func(c *Ctx, in T) (V, error), opts ...OpOption,
)

Delete registers a typed DELETE route.

func Exit 

func Exit(w io.Writer, err error) int

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 

func FieldError(ctx context.Context, field string) string

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 FileAccepted added in v0.6.0 

func FileAccepted(file *multipart.FileHeader, types ...string) bool

FileAccepted reports a file whose declared media type stands in the list. See router.FileAccepted.

func FileType added in v0.6.0 

func FileType(file *multipart.FileHeader) string

FileType returns the media type that the client declared for one file. See router.FileType.

func Get added in v0.3.0 

func Get[T any, P router.Input[T], V any](r *Router, pattern string,
	fn func(c *Ctx, in T) (V, error), opts ...OpOption,
)

Get registers a typed GET route.

func HasError 

func HasError(ctx context.Context, field string) bool

HasError reports whether this field failed validation. See view.HasError.

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 

func Inspecting(args []string) bool

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())
}

func Load 

func Load[T any](ctx context.Context) (*T, error)

Load reads the process environment into a new T. See config.Load.

func MustTx added in v0.5.0 

func MustTx(ctx context.Context) *drel.Tx

MustTx returns the transaction and panics when none is present. See db.MustTx.

func Old 

func Old(ctx context.Context, field string) string

Old returns the value that the person submitted for this field. See view.Old.

func OldFrom 

func OldFrom(ctx context.Context) any

OldFrom returns the input that failed validation.

func Patch added in v0.3.0 

func Patch[T any, P router.Input[T], V any](r *Router, pattern string,
	fn func(c *Ctx, in T) (V, error), opts ...OpOption,
)

Patch registers a typed PATCH route.

func Post added in v0.3.0 

func Post[T any, P router.Input[T], V any](r *Router, pattern string,
	fn func(c *Ctx, in T) (V, error), opts ...OpOption,
)

Post registers a typed POST route. The success answer is 201.

func Put added in v0.3.0 

func Put[T any, P router.Input[T], V any](r *Router, pattern string,
	fn func(c *Ctx, in T) (V, error), opts ...OpOption,
)

Put registers a typed PUT route.

func Repo added in v0.4.0 

func Repo[T any](ctx context.Context, meta drel.ModelMeta[T]) (*drel.TxRepository[T], error)

Repo returns the repository of the transaction of the request. See db.Repo.

The transaction middleware opens the transaction, so a handler always holds one. A job that reads outside a request opens its own with engine.WithTx. 

repo, err := avero.Repo(ctx, model.PostMeta)

func Save added in v0.4.0 

func Save(ctx context.Context) error

Save writes the staged changes inside the transaction of the request. See db.Save.

The transaction still commits at the end of the request. The flush only makes a later read of the same request see the write.

func Serve added in v0.4.0 

func Serve[C Configurer](s Service[C]) int

Serve runs one Avero application and returns the exit code of the process.

It runs the sequence of section 5.3 of the SDD. It answers an inspection command, loads the configuration, and opens the database. It builds the router and registers the boot checks and the migrator. It then runs the application until a signal or the end of the context.

An application with an unusual start calls Load, New and Run itself. Serve adds no behaviour that those three do not hold. 

func main() {
    os.Exit(avero.Serve(avero.Service[Config]{
        Args: os.Args[1:],
        Wire: wire,
        DSN:  func(c Config) string { return c.DatabaseURL },
    }))
}

func Session added in v0.5.0 

func Session(ctx context.Context) *store.Session

Session returns the auth-all session of the request, or nil. See auth.Session.

func Tx added in v0.5.0 

func Tx(ctx context.Context) (*drel.Tx, bool)

Tx returns the transaction that Transaction opened, and reports whether one surrounds the request. See db.Tx.

func UnpackMigrations added in v0.2.0 

func UnpackMigrations(fsys fs.FS, root string) (string, func(), error)

UnpackMigrations writes the migrations of an embedded file system into a temporary directory and returns it with the function that removes it.

An application that embeds its migrations therefore applies them from its own binary, and one artifact holds the server, the front end and the schema. 

//go:embed all:migrations
var migrations embed.FS

dir, clean, err := avero.UnpackMigrations(migrations, "migrations")
defer clean()

func User added in v0.5.0 

func User(ctx context.Context) *store.User

User returns the signed-in user of the request, or nil. See auth.User.

func WithAPI added in v0.3.0 

func WithAPI(api API) router.Option

WithAPI states the facts of the whole description of the API.

func WithForm 

func WithForm(page func(c *Ctx, f *Fields) ViewComponent) router.Option

WithForm renders the form again with 422 when validation fails. Pass it to NewRouter. See view.WithForm.

func WithResponder added in v0.5.0 

func WithResponder(fn Responder) router.Option

WithResponder sets how a typed handler turns its value into a Response. The default writes JSON. See router.WithResponder. 

r := avero.NewRouter(avero.WithResponder(func(c *avero.Ctx, code int, v any) avero.Response {
    if component, ok := v.(avero.ViewComponent); ok {
        return avero.View(component)
    }
    return avero.JSON(code, v)
}))

Types

type API added in v0.3.0 

type API = router.API

API states the facts of the whole description of an API: the name, the prose, the addresses, the schemes of the identity and the groups. See router.API.

type App 

type App = host.App

App is one Avero application.

func New 

func New(cfg BaseConfig, opts ...Option) *App

New builds an application. See host.New.

type AssetEntry 

type AssetEntry = assets.Entry

AssetEntry is one built asset.

type BaseConfig 

type BaseConfig = config.BaseConfig

BaseConfig holds the variables that every Avero application reads.

type Binder 

type Binder = router.Binder

Binder fills itself from a request. `avero generate` writes it.

type Check 

type Check = host.Check

Check is one boot check.

func BrokerCheck 

func BrokerCheck(address string) Check

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 

func DatabaseCheck(dsn string) Check

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 

func DatabaseCheckOn(e *drel.Engine) Check

DatabaseCheckOn proves the database with an engine that the application already opened.

func MigrationCheck 

func MigrationCheck(dsn, dir string) Check

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 MigrationCheckFS added in v0.2.0 

func MigrationCheckFS(dsn string, sets ...fs.FS) Check

MigrationCheckFS proves the embedded migration sets against a database that the check opens itself. `avero doctor` holds no engine, so it uses this one.

func MigrationCheckOn 

func MigrationCheckOn(e *drel.Engine, dir string) Check

MigrationCheckOn proves the migrations with an engine that the application already opened.

func MigrationCheckOnFS added in v0.2.0 

func MigrationCheckOnFS(e *drel.Engine, sets ...fs.FS) Check

MigrationCheckOnFS proves the migrations of the embedded sets of the feature slices. Each slice embeds its own, and drel merges them in version order.

func SecretCheck 

func SecretCheck(secret Secret) Check

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 Component 

type Component = host.Component

Component is a part of the application that has a lifecycle.

type Configurer added in v0.4.0 

type Configurer interface {
	Base() BaseConfig
}

Configurer gives Serve the base configuration of an application.

BaseConfig carries the method, so a configuration that embeds it satisfies the constraint and writes no code.

type Contact added in v0.3.0 

type Contact = router.Contact

Contact names the people who own the API.

type Contribution 

type Contribution = module.Contribution

Contribution is one row of the contribution table.

type Ctx 

type Ctx = router.Ctx

Ctx carries one request.

func NewCtx 

func NewCtx(w http.ResponseWriter, r *http.Request) *Ctx

NewCtx builds a Ctx for one request. A test calls a handler with it and needs no router. See router.NewCtx.

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 EventDesc 

type EventDesc = module.EventDesc

EventDesc is one event of a module.

type ExternalDocs added in v0.3.0 

type ExternalDocs = router.ExternalDocs

ExternalDocs names a document that stands outside this one.

type Field 

type Field = config.Field

Field is one row of a report.

type FieldDesc 

type FieldDesc = module.FieldDesc

FieldDesc is one field of a model or of an event.

type Fields 

type Fields = router.Fields

Fields holds one message for each field that failed validation.

func FieldsFrom 

func FieldsFrom(ctx context.Context) *Fields

FieldsFrom returns the validation result of a failed request. S10 renders the form again from it.

type HTTPModule 

type HTTPModule = module.HTTPModule

HTTPModule contributes routes.

type Handler 

type Handler = router.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 InboxHandler 

type InboxHandler = module.InboxHandler

InboxHandler is one message handler.

type InboxModule 

type InboxModule = module.InboxModule

InboxModule contributes message handlers.

type Job 

type Job = module.Job

Job is one scheduled unit of work.

type License added in v0.3.0 

type License = router.License

License names the licence of the API.

type Loader 

type Loader = config.Loader

Loader reads the configuration values.

type Manifest 

type Manifest = assets.Manifest

Manifest maps the name of an asset to the built file.

func LoadManifest 

func LoadManifest(fsys fs.FS, name string) (*Manifest, error)

LoadManifest reads the asset manifest from an embedded file system. See assets.LoadManifest. 

//go:embed all:assets/dist
var dist embed.FS
m, err := avero.LoadManifest(dist, "assets/dist/manifest.json")

func MountAssets added in v0.4.0 

func MountAssets(r *Router, dist fs.FS, root string) (*Manifest, error)

MountAssets reads the manifest of the built assets and serves them at /assets/.

root is the directory of the built output inside dist, such as "assets/dist". The manifest stands beside the files, so the caller states one path and not two. Mount strips the prefix, so the handler reads the path of the asset. 

manifest, err := avero.MountAssets(r, dist, "assets/dist")

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 Adapt 

func Adapt(name string, mw func(http.Handler) http.Handler) Middleware

Adapt turns a net/http middleware into an Avero middleware.

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 MaxBytes added in v0.6.0 

func MaxBytes(n int64) Middleware

MaxBytes refuses a request body that is larger than n bytes. An application that reads an upload states it, so a body cannot fill the disk of the server before a rule of a field reads the size of the file. See router.MaxBytes. 

r.Use(avero.MaxBytes(10 << 20))

func Recover 

func Recover(l *slog.Logger) Middleware

Recover turns a panic into 500.

func RequestID 

func RequestID() Middleware

RequestID gives each request an identifier.

func Transaction 

func Transaction(e *drel.Engine) Middleware

Transaction opens a drel transaction and decides the commit from the response. See db.Transaction.

It stands in the Tx field of Stack. A nil engine returns the zero middleware, which Stack leaves out.

type MigrationModule 

type MigrationModule = module.MigrationModule

MigrationModule contributes migration files.

type Migrator 

type Migrator = host.Migrator

Migrator applies the pending migrations at boot.

type ModelDesc 

type ModelDesc = module.ModelDesc

ModelDesc is one persistent model of a module.

type ModelModule added in v0.4.0 

type ModelModule = module.ModelModule

ModelModule states the persistent models of a module. `avero generate` writes the method.

type Module 

type Module = module.Module

Module is one feature of an application.

type ModuleReport 

type ModuleReport = module.Report

ModuleReport lists the contribution of every module.

type ModuleSet 

type ModuleSet = module.Set

ModuleSet holds the modules and the result of the inspection.

func Modules 

func Modules(ms ...Module) *ModuleSet

Modules inspects each module one time and returns the set. Attach adds the routes to a router. See module.Modules. 

set := avero.Modules(billing.New(db), catalog.New(db))
if err := set.Attach(r); err != nil {
    os.Exit(avero.Exit(os.Stderr, err))
}

type MountOption added in v0.5.0 

type MountOption = router.MountOption

MountOption states one more fact of a mount.

func KeepPrefix added in v0.5.0 

func KeepPrefix() MountOption

KeepPrefix passes the whole path to a mounted handler. See router.KeepPrefix. 

r.Mount("/api/auth", auth.Handler(), avero.KeepPrefix())

type NoBody added in v0.3.0 

type NoBody = router.NoBody

NoBody is the answer of a handler that carries none. The router writes 204. See router.NoBody.

type OTelConfig 

type OTelConfig = config.OTelConfig

OTelConfig holds the standard OTEL_* variables.

type OpOption added in v0.3.0 

type OpOption = router.OpOption

OpOption states one more fact of an operation, such as a tag or another answer.

func AnswerHeader added in v0.3.0 

func AnswerHeader(code int, name, description string) OpOption

AnswerHeader states a header that one answer carries, such as Location on a 201.

func Answers added in v0.3.0 

func Answers[T any](code int, description string) OpOption

Answers states one more status that the operation writes. 

avero.Post(r, "/posts", m.Create, avero.Answers[avero.Problem](409, "the title is taken"))

func AnswersNothing added in v0.3.0 

func AnswersNothing(code int, description string) OpOption

AnswersNothing states one more status that the operation writes with no body.

func Deprecated added in v0.3.0 

func Deprecated() OpOption

Deprecated marks an operation that a caller must leave.

func Describe added in v0.3.0 

func Describe(text string) OpOption

Describe states the operation at length, where a summary is one line.

func Public added in v0.3.0 

func Public() OpOption

Public states a route that needs no identity.

func Secured added in v0.3.0 

func Secured(schemes ...string) OpOption

Secured names the schemes that the route needs.

func Summary added in v0.3.0 

func Summary(text string) OpOption

Summary names the operation for a person.

func Tags added in v0.3.0 

func Tags(names ...string) OpOption

Tags group the operations of a description.

type Option 

type Option = host.Option

Option configures an application.

func WithChecks 

func WithChecks(cs ...Check) Option

WithChecks registers boot checks. See host.WithChecks.

func WithComponents 

func WithComponents(cs ...Component) Option

WithComponents registers components. See host.WithComponents.

func WithHandler 

func WithHandler(h http.Handler) Option

WithHandler mounts the application handler. See host.WithHandler.

func WithListener 

func WithListener(l net.Listener) Option

WithListener supplies the listener. See host.WithListener.

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger supplies the logger. See host.WithLogger.

func WithMigrator 

func WithMigrator(m Migrator) Option

WithMigrator supplies the migrator. See host.WithMigrator.

func WithSignals 

func WithSignals(sig ...os.Signal) Option

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 Problem added in v0.3.0 

type Problem = router.Problem

Problem is one error of an API, in the shape that RFC 9457 states. See router.Problem.

func BadRequest added in v0.3.0 

func BadRequest(detail string) *Problem

BadRequest returns the problem of a request that does not read.

func Conflict added in v0.3.0 

func Conflict(detail string) *Problem

Conflict returns the problem of a state that refuses the change.

func Forbidden added in v0.3.0 

func Forbidden(detail string) *Problem

Forbidden returns the problem of an identity that may not do this.

func NewProblem added in v0.3.0 

func NewProblem(code int, detail string) *Problem

NewProblem returns a problem with the standard title of the status. See router.NewProblem.

func NotFound added in v0.3.0 

func NotFound(thing, id string) *Problem

NotFound returns the problem of a thing that the table does not hold. 

return nil, avero.NotFound("post", in.ID)

func ProblemOf added in v0.3.0 

func ProblemOf(err error) *Problem

ProblemOf returns the problem that an error carries. See router.ProblemOf.

func Unauthorized added in v0.3.0 

func Unauthorized(detail string) *Problem

Unauthorized returns the problem of a request with no identity.

type Projection 

type Projection = module.Projection

Projection is one read model projection.

type ProjectorModule 

type ProjectorModule = module.ProjectorModule

ProjectorModule contributes projections.

type Ready 

type Ready = host.Ready

Ready is the optional readiness contract.

type Report 

type Report = config.Report

Report lists every configuration field with its value and its source.

func LoadFrom 

func LoadFrom[T any](ctx context.Context, l Loader) (*T, *Report, error)

LoadFrom reads l into a new T and returns a report. See config.LoadFrom.

type Responder added in v0.5.0 

type Responder = router.Responder

Responder turns the value that a typed handler returned into a Response. See router.Responder.

type Response 

type Response = router.Response

Response is the result of a handler.

func Empty 

func Empty(code int) Response

Empty returns a status with no body.

func HTML 

func HTML(code int, body string) Response

HTML returns an HTML response.

func JSON 

func JSON(code int, body any) Response

JSON returns a response that encodes body as JSON.

func NoContent 

func NoContent() Response

NoContent returns 204 with no body.

func Redirect 

func Redirect(code int, to string) Response

Redirect returns a redirect.

func Status 

func Status(code int) Response

Status returns a response that carries the standard text of the code.

func Text 

func Text(code int, body string) Response

Text returns a plain text response.

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 Route 

type Route = router.Route

Route is one registered route.

type RouteDesc 

type RouteDesc = module.RouteDesc

RouteDesc is one route of a module.

type RouteReport 

type RouteReport = router.Report

RouteReport lists every route of a router.

type Router 

type Router = router.Router

Router registers routes and builds the http.Handler.

func NewRouter 

func NewRouter(opts ...router.Option) *Router

NewRouter builds a router. See router.New.

type ScheduleModule 

type ScheduleModule = module.ScheduleModule

ScheduleModule contributes scheduled jobs.

type Scheduler 

type Scheduler = module.Scheduler

Scheduler collects the jobs of the modules.

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 Secret 

type Secret = config.Secret

Secret holds a value that no log line and no error message prints.

type SecurityScheme added in v0.3.0 

type SecurityScheme = router.SecurityScheme

SecurityScheme states how a caller proves its identity.

func APIKeyAuth added in v0.3.0 

func APIKeyAuth(header, description string) SecurityScheme

APIKeyAuth returns the scheme of a key that a header carries.

func BasicAuth added in v0.3.0 

func BasicAuth(description string) SecurityScheme

BasicAuth returns the scheme of a name and a password.

func BearerAuth added in v0.3.0 

func BearerAuth(description string) SecurityScheme

BearerAuth returns the scheme of a bearer token.

type Server added in v0.3.0 

type Server = router.Server

Server is one address that answers.

type Service added in v0.4.0 

type Service[C Configurer] struct {
	// Args holds the command line without the name of the program. Pass
	// os.Args[1:].
	Args []string
	// Wire builds the wiring of the application. An inspection command
	// passes a nil engine, and every command but `avero doctor` passes a
	// zero configuration.
	Wire func(engine *drel.Engine, cfg C) (*Wiring, error)
	// DSN reads the database address from the configuration. A nil value
	// starts an application with no database.
	DSN func(cfg C) string
	// Options pass to New after the options that Serve builds, so an
	// application can add a component or a check of its own.
	Options []Option
	// Ctx is the context of the run. A nil value uses context.Background.
	Ctx context.Context
	// Out and Err receive the output. A nil value uses os.Stdout and
	// os.Stderr.
	Out, Err io.Writer
}

Service states the parts of one application that Serve needs.

The zero value of every optional field states a sensible default, so a simple application fills three fields. See the SDD, 5.3, for the sequence that Serve runs.

type Source 

type Source = config.Source

Source states where a value came from.

type Stack added in v0.4.0 

type Stack = router.Stack

Stack builds the whole middleware chain in the order that the SDD states. An application states the parts that it runs, and Stack orders them. 

r.Use(avero.Stack{Secret: cfg.Secret, Logger: log, Engine: engine}.Middleware()...)

type Tag added in v0.3.0 

type Tag = router.Tag

Tag describes one group of operations.

type Telemetry 

type Telemetry = telemetry.Provider

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 

type TelemetryOption = telemetry.Option

TelemetryOption configures the telemetry provider.

type Toast 

type Toast = router.Toast

Toast is one message that the next rendered page shows.

func Toasts 

func Toasts(ctx context.Context) []Toast

Toasts returns the messages of this response. See view.Toasts.

type Validator 

type Validator = router.Validator

Validator checks itself. `avero generate` writes it.

type ViewComponent 

type ViewComponent = view.Component

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.

type ViewFunc 

type ViewFunc = view.Func

ViewFunc adapts a function to the Component interface.

type Wiring added in v0.4.0 

type Wiring struct {
	// Router holds the routes of the application. State it or state the
	// Handler, and not both.
	Router *Router
	// Handler serves the requests of an application that holds a router of
	// another library. State it or state the Router, and not both.
	//
	// The inspection commands read the routes of an Avero router, so
	// `avero routes` and `avero openapi` report nothing for such an
	// application. `avero doctor` reads the configuration and the checks, so
	// it works for both.
	Handler http.Handler
	// Modules holds the module set. Serve reads the migrations of each
	// module from it. An application that states no module holds no module
	// set, and the field stays nil.
	Modules *ModuleSet
	// Components are the parts of the application that hold a lifecycle,
	// such as an emailer, a blob store or a cache. Serve starts them in this
	// order and stops them in reverse order.
	//
	// A constructor must not dial, connect or read a file, because wire also
	// runs for an inspection command with a nil engine and a zero
	// configuration. Build the value in the constructor. Connect in Start.
	Components []Component
	// Checks are the boot checks of the application. Serve runs them before
	// the process serves, and `avero doctor` reports them. See DX-8.
	//
	// A check runs before every component starts. A check that depends on a
	// component must open its own connection and close it, and must not
	// assume the connection that Start of that component opened.
	Checks []Check
}

Wiring is what wire builds. Serve reads it.

An application states its routes in one of two ways. It states the Router, which is the whole host: the typed routes, the module system and the inspection commands. Or it states the Handler, which is any http.Handler, such as a chi router or a mux of the standard library. An application that states the Handler keeps the lifecycle, the configuration, the boot checks and `avero doctor`, and it keeps its own router.

The Modules, the Components and the Checks are optional, so a simple application states one field.

Source Files

View all Source files

Directories

Path Synopsis
Package assets holds the asset pipeline, S11.
 Package assets holds the asset pipeline, S11.
Package auth holds the auth-all glue of Avero: the user and the session of a request.
 Package auth holds the auth-all glue of Avero: the user and the session of a request.
cli module
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 db holds the drel glue of Avero: the transaction middleware, the transaction of a request and the repository of that transaction.
 Package db holds the drel glue of Avero: the transaction middleware, the transaction of a request and the repository of that transaction.
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.
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 module holds the module contract and the module inspection, S6.
 Package module holds the module contract and the module inspection, S6.
Package openapi writes the OpenAPI description of an application, S13.
 Package openapi writes the OpenAPI description of an application, S13.
Package router builds an http.Handler from typed handlers.
 Package router builds an http.Handler from typed handlers.
Package telemetry wires OpenTelemetry traces and metrics, and log/slog.
 Package telemetry wires OpenTelemetry traces and metrics, and log/slog.
Package view holds the helpers that a server rendered page needs, S10.
 Package view holds the helpers that a server rendered page needs, S10.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.