strict-query

command
v14.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause Imports: 4 Imported by: 0

Documentation

Overview

Query parameters that refuse to be wrong, and partial updates that refuse to be silent.

ctx.Query().GetInt("limit") answers zero for "limit=lots", and every hand-written date filter answers the zero date for "from=yesterday". The endpoint then returns 200 with the wrong rows and nobody finds out. The strict readers render the 400 themselves and report whether the handler may continue, exactly like ctx.BindJSON:

ctx.QueryDate(key, opts...)  a types.SimpleDate, "2006-01-02" or "2006-1-2"
ctx.QueryInt(key, opts...)   an int
ctx.QueryBool(key, opts...)  strconv.ParseBool plus yes/no/on/off

The three options they share:

iris.QueryRequired()          an absent or blank value is a 400 naming the key
iris.QueryDefault("20")       the raw value to parse when the key is absent,
                              written in the same wire form the client uses
iris.QueryZeroValues("0")     the placeholders older clients send for "unset";
                              such a value reads exactly like an absent one

QueryDefault wins over QueryRequired: a reader with something to fall back on is never missing a value. A default that does not parse is a mistake in the program, so it panics on the first request rather than answering 400.

ctx.BindUpdate[T] is the same idea for a PATCH: it decodes the body as ctx.BindJSON does and reads the "columns" query key, the members the client wants written. A column that is not a member of T answers 400 naming it and the members it could have been, because without that check a typo updates nothing and the client is told it succeeded. No columns at all means a full update and a nil slice.

Learn: reject a bad query value with a 400 instead of a silent zero, and refuse a PATCH column that does not exist instead of reporting success. Before: ../raw-body

Run:

go run main.go

Try:

curl -i 'localhost:8080/events'                                        # 400 INVALID_ARGUMENT, from is required
curl -i 'localhost:8080/events?from=yesterday'                         # 400 INVALID_ARGUMENT, not a date
curl -i 'localhost:8080/events?from=2026-01-01&limit=lots'             # 400 INVALID_ARGUMENT, not an integer
curl -i 'localhost:8080/events?from=2026-01-01'                        # 200, limit defaults to 20
curl -i 'localhost:8080/events?from=2026-01-01&to=null&archived=yes'   # 200, "null" reads as absent
curl -i 'localhost:8080/events?from=0'                                 # 400, "0" reads as absent and from is required

curl -i -X PATCH 'localhost:8080/events/1?columns=note' -d '{"note":"checked"}'   # 204 No Content
curl -i -X PATCH 'localhost:8080/events/1?columns=note' -d '{"note":"checked"}'   # 304 Not Modified, same value
curl -i -X PATCH 'localhost:8080/events/1?columns=nte'  -d '{"note":"typo"}'      # 400 INVALID_ARGUMENT

Both 400s carry the same rest/errors envelope, the one every other rejection in the framework renders ("id" is the tracking id written to the log too):

{"id":"56d67e5c-7bf1-428d-af86-e3b16d72abf1",
 "http_error_code":{"canonical_name":"INVALID_ARGUMENT","status":400},
 "message":"missing from query parameter: expected a date of the 2006-01-02 form"}

{"id":"213dddc3-5877-4ff5-90f4-e171bd4953c8",
 "http_error_code":{"canonical_name":"INVALID_ARGUMENT","status":400},
 "message":"unknown column: nte: allowed columns: id, note, severity"}

Next: ../pagination

Jump to

Keyboard shortcuts

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