feat(server): say what was wrong with a rejected filter

[geovannewashington]

What

A rejected filter now names its own reason in the fields map the error envelope already carries. Nine distinct causes get nine distinct reasons where there used to be two strings. The envelope, the 400 status and the OpenAPI schema are unchanged, so a client that only reads the status code is unaffected.

Companion PR: shellhub-io/cloud#2543 , which moves cloud's three list routes onto the same seam so they answer identically. Merge this one first.

Closes #6467

Why

ValidateFilters returned one sentinel for six causes and applyQuery collapsed seven into two strings, so a script author could not tell a typo in a field name from a filter that was merely too big. The server knew the difference at the moment it decided to refuse, and threw it away one call before anything needed it.

Before	After
"filter": "is not valid"	"filter": "names an unknown field: nmae"
"filter": "is not valid"	"filter": "operator gt is not valid for name"
"filter": "is not valid"	"filter": "value exceeds the maximum size for name"
"filter": "cannot be decoded"	"filter": "is not valid base64"

Changes

pkg/api/query classifies its own refusals instead of discarding the classification. FieldConstraints.Names separates "no such field" from "that operator is not allowed here", which Allows used to answer as one. Three sentinels are added: ErrFilterNotBase64, ErrFilterTooManyItems, and ErrFilterShapeInvalid for JSON that parses but is not a filter. ErrFilterValueTooLarge splits an oversized value of an acceptable type from one of the wrong type. ErrFilterOperatorInvalid was declared but never returned by production code; it is now real. A FilterError carrier holds the offending field and operator alongside the sentinel and wraps it, so every existing errors.Is check keeps working.

server/api/pkg/gateway maps sentinel to reason in one place, at the seam every list route crosses, so no route can drift from the wording. The echoed identifier is capped at 64 runes and marks a cut, since the field name is client-supplied and only filter values are otherwise length-bounded.

Testing

Unit and HTTP-level tests pass: pkg/api/query, the gateway package, and the full server module. The gateway's rejection table went from 5 cases to 13, each asserting a distinct fields map. The one pre-existing failure, TestInstallScriptRendersAValidShellScript, is unrelated (the script is not mounted in the container).

./bin/docker-compose exec server go test ./api/pkg/gateway/ -run TestListHoldsTheQueryToTheContractItsRegistrationNamed -v
./bin/docker-compose exec server go test ./../pkg/api/query/...

Also exercised end to end against a running dev stack, since the reason strings are a client-facing contract and only a real request proves what a client receives.

TOKEN=$(curl -s -X POST http://localhost/api/login -H 'Content-Type: application/json' -d '{"username":"<you>","password":"<pw>"}' | jq -r .token)
AUTH="Authorization: Bearer $TOKEN"
b64() { echo -n "$1" | basenc --base64url -w0 | tr -d '='; }

curl -s "http://localhost/api/devices?filter=$(b64 '[{"type":"property","params":{"name":"nmae","operator":"eq","value":"x"}}]')" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=$(b64 '[{"type":"property","params":{"name":"name","operator":"gt","value":"x"}}]')" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=$(b64 '[{"type":"property","params":{"name":"name","operator":"eq","value":{"a":1}}}]')" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=$(b64 "[{\"type\":\"property\",\"params\":{\"name\":\"name\",\"operator\":\"contains\",\"value\":\"$(printf 'A%.0s' {1..2000})\"}}]")" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=$(b64 '{"nonsense":true}')" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=$(b64 'not json at all')" -H "$AUTH"
curl -s "http://localhost/api/devices?filter=notbase64!!!" -H "$AUTH"

Observed, all 400:

{"message":"invalid entity","fields":{"filter":"names an unknown field: nmae"}}
{"message":"invalid entity","fields":{"filter":"operator gt is not valid for name"}}
{"message":"invalid entity","fields":{"filter":"value has the wrong type for name"}}
{"message":"invalid entity","fields":{"filter":"value exceeds the maximum size for name"}}
{"message":"invalid entity","fields":{"filter":"is valid JSON but not a filter"}}
{"message":"invalid entity","fields":{"filter":"is not valid JSON"}}
{"message":"invalid entity","fields":{"filter":"is not valid base64"}}

Controls: a valid filter still returns 200, and ?sort_by=nope still returns 400 with {"sort_by": "nope"} unchanged.

[github-actions]

Code Review Complete

The automated review ran but did not post an updated summary — this usually means no new issues were found since the previous review. If you've pushed changes and want a fresh pass, comment /review.

View job