Documentation
¶
Overview ¶
Package search is the search contract of Nanostack DB: the page, sort and cursor types that every layer shares, the limits of a search, its errors, and All, which reads every page of a search.
The package imports the standard library only, so an API, domain or test package can import it with no SQL dialect and no database driver. The code that runs a search on a database is in other packages of this module.
A search answers a page (Result) of the rows that match its filters. A page starts after a cursor (Pagination.Cursor, the NextCursor of the previous page) or at an offset, never both. CheckPage is the rule for a page that every search applies, for HTTP and Go callers alike.
The errors fall into two groups. A client error (IsClientError) is a request the caller can fix: the HTTP edge answers it with a 400, and core/log logs it at Debug. ErrUnscoped is a programming error: the HTTP edge answers it with a 500, and core/log logs it at Error.
Index ¶
- Constants
- Variables
- func All[Q Pager[Q], R any](ctx context.Context, q Q, page func(context.Context, Q) (Result[R], error)) ([]R, error)
- func CheckPage(p Pagination) error
- func EncodeCursor(order string, values []any) (string, error)
- func IsClientError(err error) bool
- type Cursor
- type Pager
- type Pagination
- type Result
- type Sort
- type SortDirection
Examples ¶
Constants ¶
const ( // MaxLimit is the largest page a search serves. MaxLimit = 1000 // MaxCursorLength bounds the opaque cursor a client may send back. A // cursor carries one value per ordering column, so a few hundred bytes is // typical. The bound leaves room for several text sort values of 1,000 // characters each, which is why a sortable text column must be bounded // (VARCHAR(255) or a validated length): a longer value would issue a // cursor that DecodeCursor refuses. MaxCursorLength = 8192 // MaxInValues is the largest number of values of one set filter (In, // InFold or ContainsAny). More values are ErrTooManyValues. PostgreSQL // binds at most 65535 parameters per statement. MaxInValues = 1000 // MaxTermLength is the largest number of characters of one text term // (Contains). A longer term is ErrTermTooLong. MaxTermLength = 1000 )
Limits of a search. A product's API contract may set lower limits; the runtime never serves more than these.
Variables ¶
var ( // ErrInvalidCursor reports a cursor that cannot continue this search: it // is malformed, too long, or was issued for a different ordering. ErrInvalidCursor error = &clientError{"search: invalid cursor"} // ErrCursorWithOffset reports a page that sets both a cursor and a // non-zero offset. A cursor already says where the page starts. ErrCursorWithOffset error = &clientError{"search: cursor cannot be combined with offset"} // ErrUnknownSort reports a sort field the search cannot order by. A // silent fallback to the default order would answer another question // than the client asked. ErrUnknownSort error = &clientError{"search: unknown sort field"} // ErrInvalidLimit reports a page size outside 1 to MaxLimit. ErrInvalidLimit error = &clientError{"search: limit out of range"} // ErrInvalidOffset reports a negative offset. ErrInvalidOffset error = &clientError{"search: offset out of range"} // ErrTooManyValues reports a set filter with more than MaxInValues values. ErrTooManyValues error = &clientError{"search: too many values"} // ErrTermTooLong reports a text term longer than MaxTermLength characters. ErrTermTooLong error = &clientError{"search: term too long"} )
The client errors of a search. Each answers HTTP 400, and each has a Level method that returns slog.LevelDebug, so core/log's LevelFor logs it at Debug through any wrapping: the API refusing a bad request is not the service failing.
var ErrUnscoped = errors.New("search: no tenant scope; build the search from its generated spec")
ErrUnscoped reports a search that has no tenant scope: it was not built from its generated spec, a scope value is zero (an empty id, a nil UUID), or a context scope returned no condition. It is a programming error, not a client error: it has no Level method, so core/log logs it at Error, and the HTTP edge answers it with a 500.
Functions ¶
func All ¶
func All[Q Pager[Q], R any](ctx context.Context, q Q, page func(context.Context, Q) (Result[R], error)) ([]R, error)
All reads every page of q through page and returns every item, in order. It serves internal batch reads; an API pages instead. It never changes the caller's q. It stops at the first error of page, and before each page when ctx is done. A search with no match gives an empty slice, not nil.
All also stops with an error when a page gives back the cursor it started after. Such a page does not move forward, and without the check All reads it again until ctx ends; an internal batch read often has no deadline.
Example ¶
items, err := search.All(context.Background(), numbers{n: 3}, pageOfNumbers)
fmt.Println(items, err)
Output: [1 2 3] <nil>
func CheckPage ¶
func CheckPage(p Pagination) error
CheckPage reports whether a search can serve the page. It refuses a limit outside 1 to MaxLimit (ErrInvalidLimit) and a negative offset (ErrInvalidOffset), then applies Validate. An HTTP request passes the API contract first; CheckPage applies the same rule to a Go caller.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/nanostack-dev/nanostack-framework/db/search"
)
func main() {
fmt.Println(search.CheckPage(search.Pagination{Limit: 20}))
err := search.CheckPage(search.Pagination{Limit: 5000})
fmt.Println(errors.Is(err, search.ErrInvalidLimit), search.IsClientError(err))
}
Output: <nil> true true
func EncodeCursor ¶
EncodeCursor builds the opaque token for the row whose ordering values are given. Values must be JSON-encodable; nil encodes a SQL NULL. A token longer than MaxCursorLength is an error of the search, not of the client: sort only on bounded columns.
func IsClientError ¶
IsClientError reports whether err is a search error the caller caused, at any depth of wrapping. Each answers HTTP 400. ErrUnscoped is not one, and it wins: an error that also holds ErrUnscoped (for example through errors.Join) is not a client error, because a missing tenant scope is a programming error even when the request was also bad.
core/log's LevelFor reads the first Level method it finds, and core cannot import db. So a join of a client error and ErrUnscoped can still log at Debug there. Wrap ErrUnscoped alone, never in a join with a client error.
Types ¶
type Cursor ¶
type Cursor struct {
// Order identifies the ordering, for example "created_at:DESC,id:DESC".
// A cursor only continues the ordering it was issued for.
Order string
// Values holds one JSON value per ordering column, in order. A JSON null
// is a SQL NULL.
Values []json.RawMessage
}
Cursor is the decoded form of an opaque pagination token: the ordering it was issued for and the last row's value for each ordering column.
A cursor is position, not authority. It is neither signed nor encrypted: tenant scope and filters always come from the request, so an edited cursor can at most move the start of a page inside rows the caller may already read. Never put anything into a cursor that the caller may not see.
func DecodeCursor ¶
DecodeCursor parses a token that EncodeCursor produced. Every failure wraps ErrInvalidCursor, so a caller translates them with one errors.Is.
type Pager ¶
Pager is a search that can continue after a cursor. After returns a copy that starts after cursor; it never changes the search it is called on.
type Pagination ¶
type Pagination struct {
Limit int32 `json:"limit" validate:"required,min=1,max=1000"`
Offset int32 `json:"offset" validate:"min=0"`
// Cursor is an opaque token from Result.NextCursor. Empty starts at the
// first row.
Cursor string `json:"cursor,omitempty" validate:"max=8192"`
}
Pagination selects one page. Cursor is the standard: pass the previous result's NextCursor to continue. Offset remains for clients that jump to a page number, and cannot be combined with a cursor.
func (Pagination) Validate ¶
func (p Pagination) Validate() error
Validate reports whether the cursor of the page can run: a cursor must fit MaxCursorLength and cannot be combined with a non-zero offset. It does not check the limit and the offset; CheckPage does.
type Result ¶
type Result[T any] struct { Items []T // Total counts every match of the filters, not only this page or the // rows after the cursor. Total int64 // Count is len(Items). Count int // NextCursor continues the search after the last item. It is empty when // no rows follow, so an empty NextCursor is the end of the iteration. NextCursor string }
Result is one page of a search.
type Sort ¶
type Sort[F ~string] struct { Field F `validate:"required"` Direction SortDirection `validate:"required,oneof=ASC DESC"` }
Sort is one requested sort key. The validate tags stay for hand-written searches that validate their request structs.
type SortDirection ¶
type SortDirection string
SortDirection is the direction of one sort key.
const ( SortAscending SortDirection = "ASC" SortDescending SortDirection = "DESC" )
The sort directions. They are the wire values of the API.