tango

README

tanGO

tanGO is a small, explicit web framework for Go, inspired by Django's ergonomics but built from plain Go structs and interfaces — no code generation, no reflection-heavy magic beyond what's needed to read your model tags, and no hidden configuration.

Status: v0.1 candidate. The public API is still settling. Behavior described in this README and the linked docs reflects what's implemented today; anything explicitly marked "planned" or "future" is not yet built. See Limitations and compatibility before depending on tanGO for anything beyond experimentation.

What you get

• An explicit app/registry lifecycle (Config, App, Registry) — nothing boots implicitly.
• A URL dispatcher with named routes and reverse lookup, built on chi internally (chi itself is never part of your imports).
• Context helpers for JSON responses, request binding, redirects, and raw request/response escape hatches.
• A model metadata engine that reads plain Go structs and a handful of tags (tango:"pk", tango:"unique", tango:"index", tango:"fk=Other").
• A minimal db.Store for CRUD and raw SQL against SQLite or PostgreSQL, with minimal ORM foundations: foreign key fields, two-layer validation, and cascade delete — see relationships and admin foreign keys.
• Generated, typed Go migrations (tango makemigrations/migrate/migrate down) — no separate schema DSL.
• A server-rendered HTML admin (list/create/edit/delete, pagination, sorting, search) behind a session-cookie login, with CSRF protection and rate-limited login attempts — accounts are managed via tango admin create/resetpassword/deactivate.
• A CLI (tango run/check/makemigrations/migrate/newproject/newapp/tui/admin) that wraps ordinary go build/go run rather than replacing them.

Install

go get github.com/angvp/tango

Install the tango CLI (optional, but recommended — it wraps go run/go build with a few conventions the framework expects your main.go to implement):

go install github.com/angvp/tango/cmd/tango@latest

The smallest runnable application

The fastest way to see a real one is examples/jsonapi — a complete, separate Go module you can copy as a starting point. It was produced with:

tango newproject jsonapi
cd jsonapi
tango newapp greetings

tango newproject scaffolds a go.mod and a small main.go pre-wired for SQLite and the admin app; create your first admin account afterward with tango admin create <username>. tango newapp scaffolds an app stub; wiring it into main.go's InstalledApps is one line you write yourself — tanGO never edits your main.go for you. The example's app registers one named route:

func (App) Register(registry *tango.Registry) error {
	return registry.Routes().Include("/greetings/", tango.URLs{
		tango.Path("GET", "/{name}/", hello, tango.Name("hello")),
	})
}

func hello(ctx *tango.Context) error {
	name := ctx.Param("name")
	return ctx.JSON(200, map[string]string{"message": "Hello, " + name + "!"})
}

Run it:

cd examples/jsonapi
go run .
curl http://localhost:8000/greetings/World/
# {"message":"Hello, World!"}

Where to continue

• Tutorial — build one small application from scratch: bootstrap, routing, JSON views, persistence, migrations, and the HTML admin.
• Guides — standalone, task-oriented references: project structure, application architecture, configuration, models and tags, routing, Context, persistence, migrations, admin, app checks, dialect setup, reusable apps, and relationships/admin foreign keys.
• API reference — the supported v0.1 public surface, linked to runnable examples. Generated package docs are also available via go doc or pkg.go.dev once published.
• Examples — jsonapi (JSON-only); api-with-admin (JSON API and HTML admin sharing the same models, including an AuthorID-style foreign key with FK-backed admin editing); notes-starter (a keepable starter-style app using the reduced main.go shape); and reusable-greetings/reusable-greetings-host (a reusable tanGO app and a host project installing it, demonstrating contributed migrations and app-owned static assets).
• Limitations and compatibility — v0.1 non-goals, security boundaries, dialect differences, and APIs still expected to change.

Verifying the docs

Documentation in this repository is checked, not just written: every checked-in example under examples/ is built as its own module in CI, so a stale command or import path in a doc snippet gets caught rather than silently drifting from what actually runs. Run the same check locally before sending a documentation change:

go test ./...

TestExamplesAreIndependentModulesThatCompile (at the repository root) builds every examples/* module and runs its generated -check flag; the migration-generation tests in internal/cli similarly go build a real generated migrations package rather than only inspecting its source text.

License

MIT — see LICENSE.

Documentation

Index

• Variables
• func Check(config Config) error
• func DispatchFlags(config Config, sqlDB *sql.DB, dialect db.Dialect, ...) (bool, error)
• func DumpModels(config Config) ([]migration.Model, error)
• func LoadDBDSNFromEnv() string
• func LoadDBDialectFromEnv() (db.Dialect, error)
• func LoadEnvFile(path string) error
• func Serve(config Config, sqlDB *sql.DB, dialect db.Dialect) error
• type App
  • func NewApp(name string, registerFn func(*Registry) error) App
• type AppCheck
• type Checker
• type Config
  • func LoadConfigFromEnv() Config
• type Context
  • func (c *Context) Bind(dst any) error
  • func (c *Context) Context() context.Context
  • func (c *Context) HTML(status int, tmpl *template.Template, name string, data any) error
  • func (c *Context) JSON(status int, payload any) error
  • func (c *Context) Param(name string) string
  • func (c *Context) Query(name string) string
  • func (c *Context) Redirect(url string) error
  • func (c *Context) Request() *http.Request
  • func (c *Context) ResponseWriter() http.ResponseWriter
• type IncludeOption
  • func WithMiddleware(middleware ...Middleware) IncludeOption
• type Middleware
  • func Recoverer() Middleware
• type Params
• type ProjectStatus
  • func Status(ctx context.Context, config Config, sqlDB *sql.DB, dialect db.Dialect, ...) ProjectStatus
• type Registry
  • func BuildRegistry(config Config) (*Registry, error)
  • func NewRegistry() *Registry
  • func (r *Registry) Admin() *adminregistry.Registry
  • func (r *Registry) Checks() []AppCheck
  • func (r *Registry) Models() *model.Registry
  • func (r *Registry) Register(app App) error
  • func (r *Registry) Routes() *RouteRegistry
  • func (r *Registry) RunRegistration() error
  • func (r *Registry) SetStore(store *db.Store)
  • func (r *Registry) Store() (*db.Store, bool)
• type Reverser
• type Route
  • func Path(method, pattern string, view View, opts ...RouteOption) Route
  • func (r Route) Method() string
  • func (r Route) Middleware() []Middleware
  • func (r Route) Name() string
  • func (r Route) Pattern() string
  • func (r Route) View() View
• type RouteOption
  • func Name(name string) RouteOption
  • func Use(middleware ...Middleware) RouteOption
• type RouteRegistry
  • func (rr *RouteRegistry) Handler() (http.Handler, error)
  • func (rr *RouteRegistry) Include(prefix string, routes []Route, opts ...IncludeOption) error
  • func (rr *RouteRegistry) IncludedNames() []string
  • func (rr *RouteRegistry) IncludedPatterns() []string
  • func (rr *RouteRegistry) Reverser() (Reverser, error)
• type URLs
• type View

Variables

var ErrDuplicateApp = errors.New("tango: duplicate app name")

ErrDuplicateApp is returned by Registry.Register when an app with the same Name() has already been registered.

var ErrDuplicateRouteName = errors.New("tango: duplicate route name")

ErrDuplicateRouteName is returned when two routes resolve to the same fully-qualified name.

var ErrMalformedPattern = errors.New("tango: malformed route pattern")

ErrMalformedPattern is returned when a route pattern has unbalanced parameter placeholders (e.g. an unclosed "{").

var ErrMissingParam = errors.New("tango: missing route param")

ErrMissingParam is returned by Reverse when a pattern's placeholder has no corresponding entry in params.

var ErrRegistrationNotComplete = errors.New("tango: registration not complete")

ErrRegistrationNotComplete is returned by Handler and Reverser when Registry.RunRegistration has not yet completed.

var ErrUnknownRouteName = errors.New("tango: unknown route name")

ErrUnknownRouteName is returned by Reverse for a route name that was never registered.

Functions

func Check

func Check(config Config) error

Check validates that the configured app registry can boot, compile routes, and pass every AppCheck contributed by installed apps.

func DispatchFlags

func DispatchFlags(config Config, sqlDB *sql.DB, dialect db.Dialect, migrations []migration.Migration) (bool, error)

DispatchFlags handles tanGO's app-side CLI flags. It returns handled=true when a flag path ran and the caller should exit after checking err.

func DumpModels

func DumpModels(config Config) ([]migration.Model, error)

DumpModels boots config's registry and returns its registered models in the dialect-agnostic shape `tango makemigrations` diffs against. This is the documented convention behind the "-tango-dump-models" flag: an app's main.go handling that flag calls DumpModels, JSON-encodes the result to stdout, and exits — mirroring the "-check" flag convention from Milestone 6.

func LoadDBDSNFromEnv

func LoadDBDSNFromEnv() string

LoadDBDSNFromEnv returns TANGO_DB_DSN, or an empty string when unset.

func LoadDBDialectFromEnv

func LoadDBDialectFromEnv() (db.Dialect, error)

LoadDBDialectFromEnv returns the DB dialect selected by TANGO_DB_DIALECT. It defaults to SQLite when unset.

func LoadEnvFile

func LoadEnvFile(path string) error

LoadEnvFile loads simple KEY=VALUE lines from path into the process environment without overriding variables that are already set.

func Serve

func Serve(config Config, sqlDB *sql.DB, dialect db.Dialect) error

Serve builds and runs config's registry using sqlDB-backed persistence. dialect must match whatever dialect sqlDB was opened with — callers that also invoke DispatchFlags should pass the same dialect value to both.

Types

type App

type App interface {
	Name() string
	Register(*Registry) error
}

App is the narrow contract every tanGO application unit satisfies. This interface is stable: no breaking changes are planned, and apps are not expected to implement it by hand (use NewApp).

A distributable third-party app package should expose one exported App value or constructor at its package root, e.g.:

var App = tango.NewApp("widgets", registerWidgets)

or, if the app needs configuration:

func New(cfg Config) tango.App { ... }

Importers then reference it directly: InstalledApps: []tango.App{widgets.App} or InstalledApps: []tango.App{widgets.New(cfg)}. No other framework integration is required.

An App may optionally also implement Checker to contribute advisory checks; it is never required to.

An app that ships its own templates or static assets embeds and mounts them itself, via its own embed.FS and a route registered through Include/Routes() inside its Register callback — the same pattern the admin package uses. There is no separate framework-level mechanism for this.

func NewApp

func NewApp(name string, registerFn func(*Registry) error) App

NewApp constructs an App from a name and registration function.

type AppCheck

type AppCheck struct {
	Description string
	Err         error
}

AppCheck is one advisory finding contributed by an App. A nil Err means the check passed. Named AppCheck (not Check) to avoid colliding with the existing package-level Check(Config) error function from Milestone 6.

type Checker

type Checker interface {
	Checks() []AppCheck
}

Checker is an optional capability an App may implement to contribute advisory checks surfaced by Registry.Checks (and, in turn, `tango check`). Implementing Checker is never required.

type Config

type Config struct {
	InstalledApps []App
	Addr          string
	Middleware    []Middleware
}

Config is the minimal application configuration for v0.1.

func LoadConfigFromEnv

func LoadConfigFromEnv() Config

LoadConfigFromEnv returns a Config populated from environment variables.

type Context

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

Context wraps an HTTP request/response pair with high-value helpers. Escape hatches (Request, ResponseWriter) are available when the helpers below aren't enough.

func (*Context) Bind

func (c *Context) Bind(dst any) error

Bind decodes the request body as JSON into dst.

func (*Context) Context

func (c *Context) Context() context.Context

Context returns the wrapped request's standard context.Context. Context does not itself implement context.Context.

func (*Context) HTML

func (c *Context) HTML(status int, tmpl *template.Template, name string, data any) error

HTML renders the named template within tmpl (via tmpl.ExecuteTemplate) against data, writing it as an HTML response with the given status code. The render is buffered: nothing is written to the response until execution fully succeeds, so a template error is returned like any other view error (a clean framework-generated 500) instead of a response that already committed status and headers followed by a truncated or malformed body. tmpl must already be parsed; HTML has no opinion on template parsing, caching, or file layout.

func (*Context) JSON

func (c *Context) JSON(status int, payload any) error

JSON writes payload as a JSON response body with the given status code.

func (*Context) Param

func (c *Context) Param(name string) string

Param returns a named path parameter's value, or "" if absent.

func (*Context) Query

func (c *Context) Query(name string) string

Query returns a named URL query parameter's value, or "" if absent.

func (*Context) Redirect

func (c *Context) Redirect(url string) error

Redirect writes an HTTP redirect response to url.

func (*Context) Request

func (c *Context) Request() *http.Request

Request returns the wrapped *http.Request.

func (*Context) ResponseWriter

func (c *Context) ResponseWriter() http.ResponseWriter

ResponseWriter returns the wrapped http.ResponseWriter.

type IncludeOption

type IncludeOption func(*includeConfig)

IncludeOption customizes one Include call.

func WithMiddleware

func WithMiddleware(middleware ...Middleware) IncludeOption

WithMiddleware attaches Middleware to every Route mounted by one Include call. Middleware runs before *Context is constructed; the first middleware passed is outermost.

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware wraps a raw net/http handler before a *tango.Context exists. Use it for cross-cutting HTTP concerns such as recovery, logging, request IDs, CORS, or compression. Context-aware behavior such as auth redirects belongs in a View wrapper instead.

func Recoverer

func Recoverer() Middleware

Recoverer returns middleware that converts downstream panics into the same generic JSON 500 response tanGO uses for Views that return errors.

type Params

type Params map[string]string

Params holds substitution values for a reverse URL lookup.

type ProjectStatus

type ProjectStatus struct {
	RegistrationOK    bool   `json:"registrationOk"`
	RegistrationError string `json:"registrationError,omitempty"`
	DatabaseReachable bool   `json:"databaseReachable"`
	DatabaseError     string `json:"databaseError,omitempty"`
	MigrationsTotal   int    `json:"migrationsTotal"`
	MigrationsApplied int    `json:"migrationsApplied"`
	MigrationsPending int    `json:"migrationsPending"`
}

ProjectStatus is a snapshot of a project's registration, database, and migration state, produced by Status. It is the payload behind the documented "-tango-status" flag convention (see Milestone 8.3).

func Status

func Status(ctx context.Context, config Config, sqlDB *sql.DB, dialect db.Dialect, migrations []migration.Migration) ProjectStatus

Status reports config's registration status, sqlDB's reachability, and migrations' applied/pending counts, without writing to the database or filesystem. This is the documented convention behind the "-tango-status" flag: an app's main.go handling that flag calls Status, JSON-encodes the result to stdout, and exits — mirroring "-check" and "-tango-dump-models".

type Registry

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

Registry is the shared structure apps register into during boot.

func BuildRegistry

func BuildRegistry(config Config) (*Registry, error)

BuildRegistry registers Config.InstalledApps into a new Registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty, ready-to-use Registry.

func (*Registry) Admin

func (r *Registry) Admin() *adminregistry.Registry

Admin returns the admin sub-registry, creating it on first use.

func (*Registry) Checks

func (r *Registry) Checks() []AppCheck

Checks returns every advisory AppCheck contributed by installed apps that implement Checker, in InstalledApps order. Apps that do not implement Checker are skipped without error. Checks is only meaningful after RunRegistration has completed.

func (*Registry) Models

func (r *Registry) Models() *model.Registry

Models returns the model sub-registry, creating it on first use.

func (*Registry) Register

func (r *Registry) Register(app App) error

Register adds app to the registry. It returns an error wrapping ErrDuplicateApp if an app with the same Name() has already been registered, without invoking any app's Register callback.

func (*Registry) Routes

func (r *Registry) Routes() *RouteRegistry

Routes returns the route sub-registry, creating it on first use.

func (*Registry) RunRegistration

func (r *Registry) RunRegistration() error

RunRegistration invokes each registered app's Register callback exactly once, in the order the apps were added, passing this Registry to each. It stops and returns the first error encountered, and does not invoke any subsequent app's callback.

func (*Registry) SetStore

func (r *Registry) SetStore(store *db.Store)

SetStore stores the persistence store for apps that need database access. It also wires this Registry's model registry into store (store.UseModels), so Delete cascades across every registered model's foreign keys with no extra call needed by app code — see db.Store.UseModels.

func (*Registry) Store

func (r *Registry) Store() (*db.Store, bool)

Store returns the configured persistence store, if one has been set.

type Reverser

type Reverser interface {
	Reverse(name string, params Params) (string, error)
}

Reverser builds a URL for a fully-qualified route name.

type Route

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

Route declares how an HTTP method and path pattern map to a View.

func Path

func Path(method, pattern string, view View, opts ...RouteOption) Route

Path constructs a Route declaration without executing its View.

func (Route) Method

func (r Route) Method() string

Method returns the route's HTTP method.

func (Route) Middleware

func (r Route) Middleware() []Middleware

Middleware returns the route-scoped Middleware attached to this Route.

func (Route) Name

func (r Route) Name() string

Name returns the route's optional name.

func (Route) Pattern

func (r Route) Pattern() string

Pattern returns the route's path pattern.

func (Route) View

func (r Route) View() View

View returns the route's view.

type RouteOption

type RouteOption func(*Route)

RouteOption customizes a Route during construction.

func Name

func Name(name string) RouteOption

Name attaches a name to a Route declaration.

func Use

func Use(middleware ...Middleware) RouteOption

Use attaches Middleware to one Route. Middleware runs before *Context is constructed; the first middleware passed is outermost.

type RouteRegistry

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

RouteRegistry is the Milestone 2 sub-registry apps contribute routes to, mirroring the shape of Milestone 1's Registry sub-APIs.

func (*RouteRegistry) Handler

func (rr *RouteRegistry) Handler() (http.Handler, error)

Handler compiles the full route tree, contributed by every app's Include call, into a plain http.Handler. It returns ErrRegistrationNotComplete if Registry.RunRegistration has not yet completed, and a non-nil error if two different Include calls produced the same fully-qualified route name.

func (*RouteRegistry) Include

func (rr *RouteRegistry) Include(prefix string, routes []Route, opts ...IncludeOption) error

Include mounts routes under prefix, namespace-qualifying any named route and normalizing trailing slashes so Include("/users", ...) and Include("/users/", ...) behave identically. It fails fast on a malformed pattern or a duplicate fully-qualified name within this call's routes, registering none of them in that case. Cross-call duplicate detection is deferred to Handler/Reverser compile time.

func (*RouteRegistry) IncludedNames

func (rr *RouteRegistry) IncludedNames() []string

IncludedNames returns the fully-qualified names of every named route included so far, in inclusion order. It exists to make Include's namespacing/normalization behavior testable before Handler/Reverser land.

func (*RouteRegistry) IncludedPatterns

func (rr *RouteRegistry) IncludedPatterns() []string

IncludedPatterns returns the mounted path pattern of every route included so far, in inclusion order.

func (*RouteRegistry) Reverser

func (rr *RouteRegistry) Reverser() (Reverser, error)

Reverser compiles the full route tree (the same compilation Handler performs) and returns a Reverser for building URLs from route names. It returns ErrRegistrationNotComplete if Registry.RunRegistration has not yet completed.

type URLs

type URLs []Route

URLs is a plain list of Route values.

type View

type View func(*Context) error

View is the narrow handler contract every route dispatches to.