httpbind

tinybind-go

日本語

Reflection-free, code-generation-first binding for TinyGo and standard Go. Runtime dependencies are isolated into HTTP, JSON, SQL, and DynamoDB packages.

User guides: httpbind · jsonbind · cborbind · configbind · htmlbind · sqlbind · dynamobind · firestorebind · cachekeybind · reloadable components · fasthttp backend

Building a framework on top of this? Start with framework facilities, the index of what is available to you and what is not, then htmlbind for framework owners and, if your users will build against fasthttp, the fasthttp backend for framework owners. Owning a browser runtime as well? Client behaviour covers server actions, client handlers, and component parameters in one place.

Define request/response structs once. The generator emits type-specific binders and writers, so the same model covers JSON, form, multipart, and query (plus path / header / cookie via tags). Responses adapt to the client Accept (and streaming negotiation where used). From the same analysis it also generates OpenAPI 3.1 (JSON), kept in sync with binders and writers, with godoc comments carried into summary / description. Route registration is discovered by static analysis of real net/http styles (HandleFunc, Handle, method values, wrappers, and so on)—not by a separate DSL.

type CreateUserRequest struct {
	// input = query + payload (JSON / form / multipart). Tag may be omitted.
	Name  string `input:"name"`  // same as untagged: Name string
	Email string `input:"email"` // same as untagged: Email string
	OrgID string `path:"org_id"`
	Token string `header:"Authorization"`
}

type CreateUserResponse struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
	OrgID string `json:"org_id"`
}

func createUserHandler(w http.ResponseWriter, r *http.Request) {
	input, err := httpbind.Bind[CreateUserRequest](r)
	if err != nil {
		httpbind.WriteError(w, r, err)
		return
	}
	// Name/Email: query and/or JSON/form/multipart body (input).
	// OrgID from path, Token from Authorization header.
	out := CreateUserResponse{
		ID:    "u_1",
		Name:  input.Name,
		Email: input.Email,
		OrgID: input.OrgID,
	}
	_ = httpbind.Write[CreateUserResponse](w, r, out)
}

Run the generator on the package (binders + OpenAPI embed):

go run ./cmd/tinybind-gen generate -dir . -openapi

The same generation pass also supports CLI-only application subcommands through configbind.SubCommand[T], including required, optional, and rest positional arguments. See the configbind subcommand guide.

Struct tag reference

Wire name defaults to the lower-camel field name when a tag value is omitted (e.g. untagged Name → "name").

input vs payload vs query

• Prefer input (or no tag) for normal fields that may arrive as query or body.
• Use query / payload only when you must restrict the origin (e.g. search filters in the query string, body-only JSON fields).
• payload is not the same as input: it does not accept query parameters.

Example that mixes restrictions:

type SearchRequest struct {
	Keyword string `query:"keyword"`   // query only
	Page    int    `query:"page"`
	Filter  string `payload:"filter"`  // body only (JSON/form/multipart)
}

Response structs commonly use standard json:"..." names for encoding; request binding still uses the source tags above.

Streaming (ideal API)

httpbind.WriteStream(w, r, func(s *httpbind.Stream[ChatEvent]) error {
    if err := s.Write(ChatEvent{Type: "delta", Delta: "hi"}); err != nil {
        return err
    }
    return s.Write(ChatEvent{Type: "done"})
})

• Write can be called many times (incremental events).
• Format is chosen once when the stream opens, from ?stream=, Accept, User-Agent, then default NDJSON.
• The entry closes the stream, so the trailing ] of the JSON array framing is written even when the callback fails halfway.
• Formats:
  • SSE — text/event-stream
  • NDJSON / JSONL — application/x-ndjson (one object per line; not a JSON array)
  • JSON array — application/json as [obj1,obj2,...] (Close writes the trailing ])
• Do not use removed helpers WriteNDJSON / WriteSSE.

Packages

go run ./cmd/tinybind-gen generate -dir ./path/to/package

Every generated file records a // tinybind:generated comment holding the SHA-256 of the inputs that produced it, so a run whose package sources, templates, go.mod, options, and generator binary all hash to the recorded value exits without regenerating. -force regenerates regardless. See docs/httpbind.md.

The CLI automatically discovers .tb.html and .tb.sql files in the target package and writes tinybind_templates_gen.go. A package containing SQL templates must name its database with -sql-dialect postgresql, mysql, or sqlite; there is no default. SQL value expressions become driver arguments, and placeholders are generated in encounter order in the style that dialect requires — $1, $2, … for PostgreSQL and ? for MySQL and SQLite:

package store

type User { id: int, name: string }

export statement FindUser(id: int): sql.optional<User> {
SELECT id, name FROM users WHERE id = {id}
}

This generates both BuildFindUser(id) (Statement, error) and the FindUser(ctx, db, id) (*User, error) convenience API. The SQL compiler also supports sql.exec, sql.one<T>, sql.many<T>, private sql.predicate composition, private sql.relation<T> subqueries, conditional clauses, and array value-list expansion. Hand-authored placeholders and unguarded UPDATE/DELETE statements are rejected.

sql.many<T> streams rows as iter.Seq2[T, error] without first allocating a result slice. Query, scan, and iteration errors are yielded as the error value, and stopping the range early closes the underlying sql.Rows:

for user, err := range FindUsers(ctx, db, filter) {
    if err != nil {
        return err
    }
    // consume user
}

Web frameworks can opt in to executor-from-Context wrappers while the explicit db APIs remain available:

go run ./cmd/tinybind-gen generate -dir ./path/to/package -sql-context-api

The generated FindUsersContext(ctx, filter) resolves the *sql.DB, *sql.Conn, or *sql.Tx installed with sqlbind.WithSQLExecutor. This allows transaction middleware to keep the executor inside its callback Context:

web.Transaction(func(ctx context.Context) error {
    for user, err := range FindUsersContext(ctx, filter) {
        if err != nil {
            return err
        }
        // consume user within the transaction
    }
    return nil
})

Custom generator commands may use a framework-owned Context key by setting a resolver with the signature func(context.Context) (SQLExecutor, error); setting it also enables the Context wrappers:

options.SQLExecutorResolver = &generator.SymbolPattern{
    PackagePath: "example.com/web/dbctx",
    Name:        "Executor",
}

Frameworks may wrap the runtime functions and still make those calls visible to the generator. Register the wrapper's package identity, semantic operation, and the zero-based positions of only the type/value roles that the generator needs:

package main

import "github.com/shibukawa/tinybind-go/generator"

func main() {
    calls := generator.NewCallRegistry()
    if err := calls.Register(
        // func RegisterConfig[T any](ctx context.Context, name string) *T
        generator.ConfigBindCall(
            generator.Function("example.com/framework", "RegisterConfig"),
            generator.GenericType("config", 0),
            generator.Argument("prefix", 1),
        ),
        // func Created(ctx context.Context, w http.ResponseWriter, value any) error
        generator.ResponseWriteStatusCall(
            generator.Function("example.com/framework", "Created"),
            generator.ArgumentType("response", 2),
            generator.Constant("status", 201),
        ),
    ); err != nil {
        panic(err)
    }
    options, err := calls.Options(generator.DefaultOptions())
    if err != nil {
        panic(err)
    }
    generator.Main(generator.MustCommandSet(generator.GenerateCommand(options)))
}

Extra wrapper arguments do not need to be described. Use GenericType when the model comes from a generic type argument, ArgumentType when it comes from a value argument's static type, Argument for a runtime value such as a config prefix or route pattern, and Constant when the wrapper hides a fixed value such as status 201. The available operations have matching constructors: RequestBindCall, ResponseWriteCall, ResponseWriteStatusCall, StreamCreateCall, JSONDecodeCall, JSONEncodeCall, RowsScanCall, ConfigBindCall, ConfigSubCommandCall, RouteRegisterCall, and ErrorResponseCall. Function targets package functions; Method targets named-receiver methods.

The required role names, in the same order, are request; response; response + status; stream; decode; encode; row; config + prefix; config + name + help; pattern + handler; and status.

RuntimePackages remains a shorthand for functions with the standard tinybind names and signatures. Use explicit call patterns for renamed wrappers, reordered arguments, extra arguments, or hidden constants. generator.Options{} deliberately has no discovery identities. Add a feature to DisableFeatures to prevent discovery even under -generate-all.

A framework can combine the built-in generate command with its own lifecycle commands:

commands := generator.MustCommandSet(
    generator.GenerateCommand(options),
    generator.Command{Name: "init", Summary: "initialize a project", Run: runInit},
    generator.Command{Name: "build", Summary: "generate and build", Run: runBuild},
    generator.Command{Name: "watch", Summary: "watch, generate, and build", Run: runWatch},
)
generator.Main(commands)

Each command receives a context.Context, arguments, and injected CommandIO containing stdin/stdout/stderr, working directory, and environment. A build or watch implementation can generate in-process without invoking a CLI:

result, err := generator.New(options).GeneratePackage(ctx, generator.GenerateRequest{
    Dir: dir, OpenAPI: true,
})

GeneratePackage runs template, mapping, configbind, and optional OpenAPI generation and returns the written paths. generator.Main is only the outer process boundary; tests and composed commands should call CommandSet.Run or GeneratePackage directly.

Generation is usage-aware: a package that only calls DecodeJSON[T] gets only its JSON decoder, imports jsonbind, and does not import the root HTTP runtime or net/http. Set Options.GenerateAll for the legacy all-enabled-mappings mode. Compatible multipart file aliases can be listed in Options.FileTypes.Set.

Standalone JSON uses the dependency-isolated package:

value, err := jsonbind.DecodeJSON[Document](reader)
err = jsonbind.EncodeJSON(writer, value)

JSON reads are capped at 1 MiB by default. Use jsonbind.SetMaxJSONBodyBytes globally or jsonbind.DecodeJSONLimit per call. jsonbind returns transport-neutral errors; httpbind.Bind maps an oversized HTTP request to status 413.

Joined SQL rows can be grouped into an object tree with generated, reflection-free ScanRows[T] code:

type Organization struct {
    ID    int    `db:"organization_id" groupkey:""`
    Name  string `db:"organization_name"`
    Users []User
}
type User struct {
    ID   int    `db:"user_id" groupkey:""`
    Name string `db:"user_name"`
}

organizations, err := sqlbind.ScanRows[Organization](rows)

Every grouped struct level has one groupkey field. Repeated keys merge into the same object; a NULL child key represents an absent outer-join child.

Formatting templates

.tb.html, .tb.sql, and .tb.dynamo are file formats this module invented, so no editor knows how to format them. The generator ships the formatter:

go run ./cmd/tinybind-gen fmt -w -dir ./store

-l lists the files that would change and exits non-zero, which is the CI form. -as sql (or html, dynamo) filters one source from stdin to stdout, which is what an editor "format on save" hook needs.

What it does per format:

• SQL — one clause per line, CTE bodies and subqueries indented under their own SELECT, JOIN and its ON split, AND/OR aligned when a condition list is long. Keyword case, literals, and comments are left exactly as written.
• HTML — one tag per line inside head, table, and the other positions where the HTML parser discards whitespace anyway. Elsewhere a line break only replaces whitespace that was already there, so <b>a</b><i>b</i> stays glued and rendering never changes. pre, textarea, script, style, and any preserve-whitespace subtree are copied byte for byte.
• DynamoDB — table then key, one clause per line.

A source that does not parse is reported and left untouched. Everything the command does is available as a library:

import "github.com/shibukawa/tinybind-go/templates/templatefmt"

formatted, err := templatefmt.Source("users.tb.sql", source, templatefmt.Options{})
results, err := templatefmt.Dir("./store", templatefmt.Options{Width: 120})

templatefmt.Dir reads but never writes; each Result reports whether the file would change and carries Write() for when you want it applied.

Template positions in generated Go

Generated Go is output, not source, so an error inside it names a file you never wrote. -template-line-directives maps the generated code back to the template line that produced it, using Go //line directives:

go run ./cmd/tinybind-gen generate -dir ./store -template-line-directives

A type error in a template expression then reports store/users.tb.sql:5 instead of a line of tinybind_templates_gen.go, and every reader that honours the directive follows: the compiler, go vet, delve, gopls, and your editor. Generated lines that came from no template keep reporting against the generated file.

The path written into the directive is absolute. The toolchain shortens it against wherever you ran the command, so the same string reads as store/users.tb.sql from the module root and ./users.tb.sql from inside the package — and go build and go vet agree on it, which no relative form manages. -trimpath normalises it in the binary exactly as it does any other source path, so a release build carries yourmodule/store/users.tb.sql.

How far it reaches depends on the dialect:

• SQL — a statement is emitted as a real Go function, so a panic inside one names the .tb.sql file in its stack frame as well.
• HTML — compile time only. Rendering walks an instruction list inside the shared htmlbind coordinator, so a failing render's frames are in that package and no directive on generated code can move them.
• DynamoDB — one mapping per declaration. The parser records a line and no column, so there is nothing finer to map.

It is off by default, and two things are worth knowing before turning it on. Enabling it rewrites every generated file that carries a template — with absolute paths in it, so its bytes now depend on where the checkout lives. That costs nothing if you keep generated Go out of version control, and misleads every other machine if you commit it. It also grows the mapped parts of it by roughly a third: a directive is repeated per line, because one that is not only maps the line directly below it. Comments reach no binary, so this is source size and nothing else. Second, a covered test run under directives writes a profile that keeps the generated file's path while using the mapped line numbers, so go tool cover renders against lines that do not exist in the file it names — leave the flag off for coverage.

Taking Artifact values instead of written files? The directive that ends a mapped span has to name the file you write it as, and only you know that name:

content := generator.ResolveTemplatePositions(artifact.Content, artifact.OutputBase+"_pw_gen.go")

Skipping that call misreports generated scaffolding and leaves every template position intact.

Demo

go generate ./examples/demo
go run ./examples/demo
# http://localhost:8080/       index + browser stream demo
# http://localhost:8080/docs/  Swagger UI
# http://localhost:8080/chat   WriteStream (SSE / NDJSON / JSON array auto)

See examples/demo/README.md for full curl recipes.

Benchmarks

Generated code has no reflection to drive and no intermediate map[string]any to build, which is where the difference comes from. Measured on an Apple M3, Go 1.26.5, darwin/arm64, best of 10 runs.

Each pair produces the same output: the JSON codecs are checked against encoding/json by differential fuzzing, and the handler and template pairs are asserted equivalent by the tests sitting beside the benchmarks. Reproduce with:

go test ./internal/benchfixture -run xxx -bench . -benchmem

Throughput

The document is a 312-byte order with a nested object, a three-element array of objects, and a string array. The page is a five-row user list.

The JSON comparisons are against encoding/json; the handler row against a hand-written net/http handler doing the same decode, path, and header reads; the HTML row against an html/template template rendering the same document.

Encoding allocates nothing: generated encoders append into a pooled buffer, so a response costs no garbage at all. Decoding's 15 allocations are the 13 strings and slices that end up in the result, plus the body buffer and its reader — there is nothing left to remove without changing what the caller gets back. The HTML render's four allocations are per render rather than per row — the bound fragment, the options, the renderer, and its conversion buffer — so a longer page costs the same four.

Binary size

The same small JSON program built two ways, once over encoding/json and once over generated jsonbind codecs. jsonbind does not import encoding/json at all, so the reflection-based codec never enters the binary. Built with Go 1.26.5 and TinyGo 0.41.1; the native rows are darwin/arm64.

Stripping makes the gap matter more, not less: once debug information is gone, the reflection machinery is a larger share of what is left. On a stripped TinyGo wasm build it is about half the binary.

The wasm and native rows strip differently because the debug information lives in different places. A wasm binary embeds its DWARF, which is what -no-debug removes; a Mach-O binary never carries it (macOS keeps DWARF in a separate dSYM), so -no-debug changes nothing there and strip, which drops the symbol table, is the flag's native equivalent.

encoding/json/v2

encoding/json/v2 and jsontext are stable as of Go 1.27, but this module declares go 1.26.0 and stays there — bumping it would raise the minimum Go version for every package this module exports, for every downstream consumer, just to build a benchmark measuring whether v2 is worth switching to. The comparison lives behind an opt-in build tag instead, and needs a locally bumped go.mod to compile at all, since Go resolves stdlib API availability from the module's own declared language version rather than from a flag:

go test ./internal/benchfixture -tags tinybind_jsonv2bench -run xxx -bench JSON -benchmem

(with this module's own go.mod temporarily raised to go 1.27.0, or run from a throwaway module that imports this repo for its fixtures).

Turning the flag on and changing nothing else is a real improvement for decoding, because the v1 API is reimplemented over v2 — but watch the encode row, which gets 2.3× slower and allocates 12× more. The flag is not free either way.

Generating onto jsontext, the v2 tokenizer, was the interesting option: the same key-switch shape driven by ReadToken lands on 13 allocations with a reused decoder — exactly what jsonbind.Parser allocates — but takes 1320 ns to do it, and 1804 ns · 1600 B · 38 allocs when the decoder is constructed per call, as a codec entry point would have to.

Size settles it. On the same small program, the experiment costs:

A stripped wasm build with the experiment on is 3.5× the size of the same program on jsonbind. For a library whose first-class target is TinyGo, that rules v2 out as a dependency, and nothing in the speed columns argues for carrying a second implementation behind a build tag to get it.

TinyGo

TinyGo is a first-class target for generated binding code. The JSON runtime is kept independent of net/http so it can be used on js/wasm toolchains where TinyGo's standard-library HTTP path is unavailable.

Verified with TinyGo 0.41.1 + Go 1.26.x.

./scripts/tinygo-check.sh

Runtime notes relevant to TinyGo

• AsHTTPError avoids errors.As (unimplemented AssignableTo on some TinyGo builds).
• WriteError hand-builds problem JSON (avoids fragile nested encoding/json + RawMessage interactions).
• Registry uses reflect.Type only as a type identity key, not for field walking.
• Generated bind/write code does not import reflect.
• jsonbind parses and writes JSON itself and does not import encoding/json, so a JSON-only binary carries no reflection-based codec — around 40% of a tinygo build -target wasi binary, and about half of a -no-debug one. See Benchmarks.
• Do not import encoding/json/v2 or jsontext into code a TinyGo build reaches. jsonbind never calls either, and the one place this repo does — internal/benchfixture, behind the tinybind_jsonv2bench build tag — measured a stripped wasi binary at 3.5× the size of the same program on jsonbind; see encoding/json/v2.

Known limitations

License

Licensed under the Apache License, Version 2.0.