binding

package
v0.30.4 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package binding states where each field of an API request comes from, and refuses a request type that leaves the answer open.

A field reads from exactly one place. A field the body fills names its key with `json:"key"` and carries no other source tag. Every other field declares `json:"-"`, which keeps encoding/json from filling it by its Go name, and names at most one of the sources in Sources: none means the handler fills it. An embedded struct with no json tag contributes its fields as if they were declared in place, as encoding/json promotes them. A struct the body fills holds only body fields, since echo also walks into it for the path, query and headers.

Index

Constants

This section is empty.

Variables

View Source
var IdentityClaims = []string{"id", "tenant", "device", "role", "admin", "admin_id"}

IdentityClaims are the values an identity tag may name: the caller's user ID, tenant, device UID, role, whether they are an instance administrator, and the administrator's ID.

View Source
var Sources = []string{"param", "query", "header", "identity", "form"}

Sources are the struct tags that name a non-body source of a request field.

Functions

func Check

func Check(t reflect.Type) error

Check returns the error SchemaOf returns for t.

func MustCheck

func MustCheck[T any]()

MustCheck panics with the error Check returns for T, so a request type that breaks the rule stops the server from mounting the route that binds it.

Types

type Schema

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

Schema is what a request type takes from the body.

func SchemaOf

func SchemaOf(t reflect.Type) (*Schema, error)

SchemaOf returns the schema of t, a struct or a pointer to one. It returns a nil schema and no error for any other type, which binds no fields, and the first field that breaks the rule as an error naming its path. The answer is computed once per type.

func (*Schema) Foreign

func (s *Schema) Foreign(object map[string]json.RawMessage) []string

Foreign returns the keys of a JSON object body that would name a request field read from somewhere else, matching them as encoding/json does: without regard to case, and only when no body field claims the key first.

type Source

type Source struct {
	// Tag is "json" for the body, one of [Sources], or empty for a field the handler fills.
	Tag string
	// Name is the body key, path parameter, query parameter, header, identity claim or form field
	// the field reads.
	Name string
}

Source is where one request field reads its value from.

func NamedSources

func NamedSources(tag reflect.StructTag) []Source

NamedSources returns every one of Sources the tag names with a non-empty value, in the order of Sources. A tag naming none of them returns nil.

func SourceOf

func SourceOf(tag reflect.StructTag) (Source, error)

SourceOf reads the source a field declares through its tag. It returns an error when the tag names no json key and lacks `json:"-"`, which leaves encoding/json free to fill the field from a body key matching its Go name; when it names the body and another source; when it names more than one of Sources; and when an identity tag names none of IdentityClaims.

func (Source) IsBody

func (s Source) IsBody() bool

IsBody reports whether the request body fills the field.

Directories

Path Synopsis
Package bindingtest applies the binding rule to the source of a package, so that a request type no route test reaches still fails a build.
Package bindingtest applies the binding rule to the source of a package, so that a request type no route test reaches still fails a build.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL