Add ListPackages() to persistence service

Refs #988

This continues the work toward #988 by adding a `ListPackages()` method
to the persistence service that includes a count of the total search
results returned (before paging), as well as allowing filtering,
sorting, and paging of the search.

Other changes:
- Add a telemetry wrapper for the `ListPackages()` method to provide
  extra performance and debugging data
- Add additional commentary for the `Filter.Page()` method
- Add many unit tests for the `ListPackages()` functionality

internal/persistence/ent/client/filter.go

@@ -129,7 +129,18 @@ func orderFunc(field string, desc bool) func(sel *sql.Selector) {
 	}
 }
 
-// Page sets the limit and offset criteria.
+// Page sets the query limit and offset criteria.
+//
+// The actual query limit will be set to a value between one and MaxPageSize
+// based on the input limit (x) as follows:
+// (x < 0)               -> MaxPageSize
+// (x == 0)              -> DefaultPageSize
+// (0 < x < MaxPageSize) -> x
+// (x >= MaxPageSize)    -> MaxPageSize
+//
+// The actual query offset will be set based on the input offset (y) as follows:
+// (y <= 0) -> 0
+// (y > 0)  -> y
 func (f *Filter[Q, O, P]) Page(limit, offset int) {
 	f.addLimit(limit)
 
@@ -139,11 +150,6 @@ func (f *Filter[Q, O, P]) Page(limit, offset int) {
 }
 
 // addLimit adds the page limit l to a filter.
-//
-// If l < 0 the page limit is set to the maximum page size.
-// If l == 0 the page limit is set to the default page size.
-// If l > 0 but less than the max page size, the page limit is set to l.
-// If l > max page size the page limit is set to the max page size.
 func (f *Filter[Q, O, P]) addLimit(l int) {
 	switch {
 	case l == 0:

internal/persistence/ent/client/package.go

@@ -8,6 +8,8 @@ import (
 
 	"github.com/artefactual-sdps/enduro/internal/datatypes"
 	"github.com/artefactual-sdps/enduro/internal/persistence"
+	"github.com/artefactual-sdps/enduro/internal/persistence/ent/db"
+	"github.com/artefactual-sdps/enduro/internal/persistence/ent/db/pkg"
 )
 
 // CreatePackage creates and persists a new package using the values from pkg
@@ -130,3 +132,56 @@ func (c *client) UpdatePackage(
 
 	return convertPkgToPackage(p), nil
 }
+
+// ListPackages returns a slice of packages filtered according to f.
+func (c *client) ListPackages(ctx context.Context, f persistence.PackageFilter) (
+	[]*datatypes.Package, *persistence.Page, error,
+) {
+	res := []*datatypes.Package{}
+
+	page, whole := filterPackages(c.ent.Pkg.Query(), &f)
+
+	r, err := page.All(ctx)
+	if err != nil {
+		return nil, nil, newDBError(err)
+	}
+
+	for _, i := range r {
+		res = append(res, convertPkgToPackage(i))
+	}
+
+	total, err := whole.Count(ctx)
+	if err != nil {
+		return nil, nil, newDBError(err)
+	}
+
+	pp := &persistence.Page{
+		Limit:  f.Limit,
+		Offset: f.Offset,
+		Total:  total,
+	}
+
+	return res, pp, err
+}
+
+// filterPackages filters a package query based on filtering inputs.
+func filterPackages(q *db.PkgQuery, f *persistence.PackageFilter) (page, whole *db.PkgQuery) {
+	h := NewFilter(q, SortableFields{
+		pkg.FieldID: {Name: "ID", Default: true},
+	})
+	h.Equals(pkg.FieldName, f.Name)
+	h.Equals(pkg.FieldAipID, f.AIPID)
+	h.Equals(pkg.FieldLocationID, f.LocationID)
+	h.Equals(pkg.FieldStatus, f.Status)
+	h.AddDateRange(pkg.FieldStartedAt, f.StartedAt)
+	h.OrderBy(f.Sort)
+	h.Page(f.Limit, f.Offset)
+
+	// Update the filter values with the actual values set on the query. E.g.
+	// calling `h.Page(0,0)` will set the query limit equal to the default page
+	// size.
+	f.Limit = h.limit
+	f.Offset = h.offset
+
+	return h.Apply()
+}