httpbind

tinybind-go

日本語

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

User guides: httpbind · jsonbind · configbind · htmlbind · sqlbind

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, kept in sync with binders and writers. 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)

stream, err := httpbind.NewStream[ChatEvent](w, r)
if err != nil {
    httpbind.WriteError(w, r, err)
    return
}
defer stream.Close()

_ = stream.Write(ChatEvent{Type: "delta", Delta: "hi"})
_ = stream.Write(ChatEvent{Type: "done"})

• Write can be called many times (incremental events).
• Format is chosen once in NewStream from ?stream=, Accept, User-Agent, then default NDJSON.
• 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

The CLI automatically discovers .tb.html and .tb.sql files in the target package and writes tinybind_templates_gen.go. SQL value expressions become driver arguments; PostgreSQL-style $1, $2, … placeholders are generated in encounter order:

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.

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   NewStream (SSE / NDJSON / JSON array auto)

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

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.
• JSON-only generated code imports jsonbind only; the test matrix builds it with tinygo build -target wasm.

Known limitations

License

Licensed under the Apache License, Version 2.0.