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 ¶
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.
var Sources = []string{"param", "query", "header", "identity", "form"}
Sources are the struct tags that name a non-body source of a request field.
Functions ¶
Types ¶
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema is what a request type takes from the body.
func SchemaOf ¶
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 ¶
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 ¶
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.
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. |