Skip to content

Commit b9023d5

Browse files
huv1khuv1k
committed
feat(api): add sort order to GET /v2/sandboxes
Add an order=asc|desc query param to GET /v2/sandboxes so clients can request ascending or descending order by sandbox start time (defaults to desc, the previous hardcoded behavior). - Ascending is implemented as the exact reverse of the existing keyset order (started_at ASC, sandbox_id DESC), so it maps onto a backward scan of the existing idx_snapshots_team_time_id index - no new index/migration. - Add a direction-aware first-page cursor, ascending variants of the in-memory sort and cursor filter, and a GetSnapshotsWithCursorAsc keyset query. - Thread the direction through the v2 handler; the legacy v1 list is untouched. - Tests: ascending default cursor, sort + cursor-filter tie-breaks, and a DB-backed test asserting oldest-first ordering and gap-free pagination.
1 parent 711aa33 commit b9023d5

10 files changed

Lines changed: 685 additions & 207 deletions

File tree

‎packages/api/internal/api/api.gen.go‎

Lines changed: 231 additions & 186 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/api/internal/handlers/sandboxes_list.go‎

Lines changed: 39 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ func (a *APIStore) getPausedSandboxes(
3838
queryLimit int32,
3939
cursorTime time.Time,
4040
cursorID string,
41+
order utils.SortDirection,
4142
) ([]utils.PaginatedSandbox, error) {
4243
queryMetadata := dbtypes.JSONBStringMap{}
4344
if metadataFilter != nil {
@@ -49,7 +50,7 @@ func (a *APIStore) getPausedSandboxes(
4950
// O(rows × array_size) and caused 40s+ query times with large arrays.
5051
dbLimit := queryLimit + int32(len(runningSandboxesIDs))
5152

52-
snapshots, err := a.throttledGetSnapshots(ctx, queries.GetSnapshotsWithCursorParams{
53+
snapshots, err := a.throttledGetSnapshots(ctx, order, queries.GetSnapshotsWithCursorParams{
5354
Limit: dbLimit,
5455
TeamID: teamID,
5556
Metadata: queryMetadata,
@@ -149,6 +150,12 @@ func (a *APIStore) GetV2Sandboxes(c *gin.Context, params api.GetV2SandboxesParam
149150
states = append(states, *params.State...)
150151
}
151152

153+
// Sort direction by start time. Defaults to descending (newest first).
154+
order := utils.SortDesc
155+
if params.Order != nil && *params.Order == api.Asc {
156+
order = utils.SortAsc
157+
}
158+
152159
// Initialize pagination
153160
pagination, err := utils.NewPagination[utils.PaginatedSandbox](
154161
utils.PaginationParams{
@@ -159,6 +166,7 @@ func (a *APIStore) GetV2Sandboxes(c *gin.Context, params api.GetV2SandboxesParam
159166
DefaultLimit: sandboxesDefaultLimit,
160167
MaxLimit: sandboxesMaxLimit,
161168
DefaultID: utils.MaxSandboxID,
169+
Order: order,
162170
},
163171
)
164172
if err != nil {
@@ -204,7 +212,7 @@ func (a *APIStore) GetV2Sandboxes(c *gin.Context, params api.GetV2SandboxesParam
204212
c.Header("X-Total-Running", strconv.Itoa(len(runningSandboxList)))
205213

206214
// Filter based on cursor
207-
runningSandboxList = utils.FilterBasedOnCursor(runningSandboxList, pagination.CursorTime(), pagination.CursorID())
215+
runningSandboxList = utils.FilterBasedOnCursor(runningSandboxList, pagination.CursorTime(), pagination.CursorID(), order)
208216

209217
sandboxes = append(sandboxes, runningSandboxList...)
210218
}
@@ -219,7 +227,7 @@ func (a *APIStore) GetV2Sandboxes(c *gin.Context, params api.GetV2SandboxesParam
219227
runningSandboxesIDs = append(runningSandboxesIDs, info.SandboxID)
220228
}
221229

222-
pausedSandboxList, err := a.getPausedSandboxes(ctx, team.ID, runningSandboxesIDs, metadataFilter, pagination.QueryLimit(), pagination.CursorTime(), pagination.CursorID())
230+
pausedSandboxList, err := a.getPausedSandboxes(ctx, team.ID, runningSandboxesIDs, metadataFilter, pagination.QueryLimit(), pagination.CursorTime(), pagination.CursorID(), order)
223231
if err != nil {
224232
logger.L().Error(ctx, "Error getting paused sandboxes", zap.Error(err))
225233
a.sendAPIStoreError(c, http.StatusInternalServerError, "Error getting paused sandboxes")
@@ -229,14 +237,14 @@ func (a *APIStore) GetV2Sandboxes(c *gin.Context, params api.GetV2SandboxesParam
229237

230238
pausingSandboxList := instanceInfoToPaginatedSandboxes(pausingSandboxes)
231239
pausingSandboxList = utils.FilterSandboxesOnMetadata(pausingSandboxList, metadataFilter)
232-
pausingSandboxList = utils.FilterBasedOnCursor(pausingSandboxList, pagination.CursorTime(), pagination.CursorID())
240+
pausingSandboxList = utils.FilterBasedOnCursor(pausingSandboxList, pagination.CursorTime(), pagination.CursorID(), order)
233241

234242
sandboxes = append(sandboxes, pausedSandboxList...)
235243
sandboxes = append(sandboxes, pausingSandboxList...)
236244
}
237245

238246
// We need to sort again after merging running and paused sandboxes
239-
utils.SortPaginatedSandboxesDesc(sandboxes)
247+
utils.SortPaginatedSandboxes(sandboxes, order)
240248

241249
sandboxes = pagination.ProcessResultsWithHeader(c, sandboxes, func(s utils.PaginatedSandbox) (time.Time, string) {
242250
return s.PaginationTimestamp, s.SandboxID
@@ -358,12 +366,35 @@ func convertFromDBMountsToAPIMounts(mounts []*dbtypes.SandboxVolumeMountConfig)
358366
return &results
359367
}
360368

361-
// throttledGetSnapshots runs GetSnapshotsWithCursor gated by the sandbox list semaphore.
362-
func (a *APIStore) throttledGetSnapshots(ctx context.Context, params queries.GetSnapshotsWithCursorParams) ([]queries.GetSnapshotsWithCursorRow, error) {
369+
// throttledGetSnapshots runs the cursor snapshot query gated by the sandbox list
370+
// semaphore, picking the ascending or descending keyset query based on the requested
371+
// order. The ascending query returns an identically-shaped row, converted back to the
372+
// descending row type so callers share a single conversion path.
373+
func (a *APIStore) throttledGetSnapshots(ctx context.Context, order utils.SortDirection, params queries.GetSnapshotsWithCursorParams) ([]queries.GetSnapshotsWithCursorRow, error) {
363374
if err := a.sandboxListSem.Acquire(ctx, 1); err != nil {
364375
return nil, err
365376
}
366377
defer a.sandboxListSem.Release(1)
367378

368-
return a.sqlcDB.GetSnapshotsWithCursor(ctx, params)
379+
if order != utils.SortAsc {
380+
return a.sqlcDB.GetSnapshotsWithCursor(ctx, params)
381+
}
382+
383+
ascRows, err := a.sqlcDB.GetSnapshotsWithCursorAsc(ctx, queries.GetSnapshotsWithCursorAscParams{
384+
Limit: params.Limit,
385+
TeamID: params.TeamID,
386+
Metadata: params.Metadata,
387+
CursorTime: params.CursorTime,
388+
CursorID: params.CursorID,
389+
})
390+
if err != nil {
391+
return nil, err
392+
}
393+
394+
rows := make([]queries.GetSnapshotsWithCursorRow, len(ascRows))
395+
for i, r := range ascRows {
396+
rows[i] = queries.GetSnapshotsWithCursorRow(r)
397+
}
398+
399+
return rows, nil
369400
}

‎packages/api/internal/utils/pagination.go‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,15 @@ func generateCursor(timestamp time.Time, id string) string {
1616
return base64.URLEncoding.EncodeToString([]byte(cursor))
1717
}
1818

19+
// SortDirection is the order in which keyset-paginated results are returned.
20+
// The zero value is SortDesc, preserving the default newest-first behavior.
21+
type SortDirection int
22+
23+
const (
24+
SortDesc SortDirection = iota
25+
SortAsc
26+
)
27+
1928
// PaginationParams holds pagination parameters from the API request
2029
type PaginationParams struct {
2130
Limit *int32
@@ -27,6 +36,10 @@ type PaginationConfig struct {
2736
DefaultLimit int32
2837
MaxLimit int32
2938
DefaultID string // Default cursor ID when no token is provided (e.g., max UUID or max sandbox ID)
39+
// Order controls the first-page cursor when no token is provided. For
40+
// SortDesc the first page starts at "now" (newest first); for SortAsc it
41+
// starts at the zero time (oldest first).
42+
Order SortDirection
3043
}
3144

3245
// Cursor represents a parsed pagination cursor
@@ -60,7 +73,7 @@ func NewPagination[T any](params PaginationParams, config PaginationConfig) (*Pa
6073

6174
// Parse cursor token
6275
var err error
63-
p.cursor, err = parseCursorToken(params.NextToken, config.DefaultID)
76+
p.cursor, err = parseCursorToken(params.NextToken, config)
6477
if err != nil {
6578
return nil, fmt.Errorf("invalid next token: %w", err)
6679
}
@@ -132,7 +145,7 @@ func (p *Pagination[T]) setHeader(c *gin.Context) {
132145
}
133146

134147
// parseCursorToken parses a cursor token, returning default values if token is nil/empty
135-
func parseCursorToken(token *string, defaultID string) (Cursor, error) {
148+
func parseCursorToken(token *string, config PaginationConfig) (Cursor, error) {
136149
if token != nil && *token != "" {
137150
cursorTime, cursorID, err := ParseCursor(*token)
138151
if err != nil {
@@ -142,6 +155,13 @@ func parseCursorToken(token *string, defaultID string) (Cursor, error) {
142155
return Cursor{Time: cursorTime, ID: cursorID}, nil
143156
}
144157

145-
// Default to current time and provided default ID to get the first page
146-
return Cursor{Time: time.Now(), ID: defaultID}, nil
158+
// Default cursor for the first page. For descending order we start at "now"
159+
// (so everything older is included); for ascending order we start at the
160+
// zero time (so everything newer is included).
161+
defaultTime := time.Now()
162+
if config.Order == SortAsc {
163+
defaultTime = time.Time{}
164+
}
165+
166+
return Cursor{Time: defaultTime, ID: config.DefaultID}, nil
147167
}

‎packages/api/internal/utils/pagination_test.go‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,42 @@ func TestPagination_CursorTime(t *testing.T) {
191191
assert.Equal(t, timestamp, p.CursorTime())
192192
}
193193

194+
func TestPagination_DefaultCursorByDirection(t *testing.T) {
195+
t.Parallel()
196+
197+
t.Run("descending defaults to now", func(t *testing.T) {
198+
t.Parallel()
199+
200+
before := time.Now()
201+
p, err := NewPagination[testItem](PaginationParams{}, PaginationConfig{
202+
DefaultLimit: 10,
203+
MaxLimit: 100,
204+
DefaultID: "default-id",
205+
})
206+
require.NoError(t, err)
207+
after := time.Now()
208+
209+
assert.False(t, p.CursorTime().Before(before), "default cursor time should be ~now")
210+
assert.False(t, p.CursorTime().After(after), "default cursor time should be ~now")
211+
assert.Equal(t, "default-id", p.CursorID())
212+
})
213+
214+
t.Run("ascending defaults to zero time", func(t *testing.T) {
215+
t.Parallel()
216+
217+
p, err := NewPagination[testItem](PaginationParams{}, PaginationConfig{
218+
DefaultLimit: 10,
219+
MaxLimit: 100,
220+
DefaultID: "default-id",
221+
Order: SortAsc,
222+
})
223+
require.NoError(t, err)
224+
225+
assert.True(t, p.CursorTime().IsZero(), "ascending default cursor time should be the zero time")
226+
assert.Equal(t, "default-id", p.CursorID())
227+
})
228+
}
229+
194230
func TestPagination_CursorID(t *testing.T) {
195231
t.Parallel()
196232
config := PaginationConfig{

‎packages/api/internal/utils/sandboxes_list.go‎

Lines changed: 34 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -77,33 +77,58 @@ func ParseCursor(cursor string) (time.Time, string, error) {
7777
return cursorTime, parts[1], nil
7878
}
7979

80-
func FilterBasedOnCursor(sandboxes []PaginatedSandbox, cursorTime time.Time, cursorID string) []PaginatedSandbox {
81-
// Apply cursor-based filtering if cursor is provided
80+
// FilterBasedOnCursor keeps only the sandboxes that fall after the cursor in the
81+
// requested order. Descending order pages through (started_at DESC, sandbox_id ASC);
82+
// ascending order is the exact reverse (started_at ASC, sandbox_id DESC), matching
83+
// SortPaginatedSandboxes and the keyset SQL queries.
84+
func FilterBasedOnCursor(sandboxes []PaginatedSandbox, cursorTime time.Time, cursorID string, order SortDirection) []PaginatedSandbox {
8285
var filteredSandboxes []PaginatedSandbox
8386
for _, sandbox := range sandboxes {
84-
// Take sandboxes with start time before cursor time OR
85-
// same start time but sandboxID greater than cursor ID (for stability)
86-
if sandbox.StartedAt.Before(cursorTime) ||
87-
(sandbox.StartedAt.Equal(cursorTime) && sandbox.SandboxID > cursorID) {
87+
var include bool
88+
if order == SortAsc {
89+
include = sandbox.StartedAt.After(cursorTime) ||
90+
(sandbox.StartedAt.Equal(cursorTime) && sandbox.SandboxID < cursorID)
91+
} else {
92+
include = sandbox.StartedAt.Before(cursorTime) ||
93+
(sandbox.StartedAt.Equal(cursorTime) && sandbox.SandboxID > cursorID)
94+
}
95+
96+
if include {
8897
filteredSandboxes = append(filteredSandboxes, sandbox)
8998
}
9099
}
91100

92101
return filteredSandboxes
93102
}
94103

95-
// SortPaginatedSandboxesDesc sorts the sandboxes by StartedAt (descending),
96-
// then by SandboxID (ascending) for stability
97-
func SortPaginatedSandboxesDesc(sandboxes []PaginatedSandbox) {
104+
// SortPaginatedSandboxes sorts the sandboxes by StartedAt then SandboxID for stable
105+
// pagination. Descending order is StartedAt DESC, SandboxID ASC; ascending order is
106+
// the exact reverse (StartedAt ASC, SandboxID DESC) so it maps onto a backward scan
107+
// of the (team_id, sandbox_started_at DESC, sandbox_id) index.
108+
func SortPaginatedSandboxes(sandboxes []PaginatedSandbox, order SortDirection) {
98109
slices.SortFunc(sandboxes, func(a, b PaginatedSandbox) int {
99110
if !a.StartedAt.Equal(b.StartedAt) {
111+
if order == SortAsc {
112+
return a.StartedAt.Compare(b.StartedAt)
113+
}
114+
100115
return b.StartedAt.Compare(a.StartedAt)
101116
}
102117

118+
if order == SortAsc {
119+
return strings.Compare(b.SandboxID, a.SandboxID)
120+
}
121+
103122
return strings.Compare(a.SandboxID, b.SandboxID)
104123
})
105124
}
106125

126+
// SortPaginatedSandboxesDesc preserves the descending-only entry point used by the
127+
// legacy (v1) list endpoint.
128+
func SortPaginatedSandboxesDesc(sandboxes []PaginatedSandbox) {
129+
SortPaginatedSandboxes(sandboxes, SortDesc)
130+
}
131+
107132
func FilterSandboxesOnMetadata(sandboxes []PaginatedSandbox, metadata *map[string]string) []PaginatedSandbox {
108133
if metadata == nil {
109134
return sandboxes

‎packages/api/internal/utils/sandboxes_list_test.go‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,107 @@ package utils
22

33
import (
44
"testing"
5+
"time"
56

67
"github.com/stretchr/testify/assert"
78
"github.com/stretchr/testify/require"
9+
10+
"github.com/e2b-dev/infra/packages/api/internal/api"
811
)
912

13+
func newPaginatedSandbox(id string, startedAt time.Time) PaginatedSandbox {
14+
return PaginatedSandbox{
15+
ListedSandbox: api.ListedSandbox{
16+
SandboxID: id,
17+
StartedAt: startedAt,
18+
},
19+
PaginationTimestamp: startedAt,
20+
}
21+
}
22+
23+
func sandboxIDs(sandboxes []PaginatedSandbox) []string {
24+
ids := make([]string, len(sandboxes))
25+
for i, s := range sandboxes {
26+
ids[i] = s.SandboxID
27+
}
28+
29+
return ids
30+
}
31+
32+
func TestSortPaginatedSandboxes(t *testing.T) {
33+
t.Parallel()
34+
35+
t0 := time.Date(2024, 1, 1, 10, 0, 0, 0, time.UTC)
36+
t1 := time.Date(2024, 1, 1, 11, 0, 0, 0, time.UTC)
37+
38+
// Two sandboxes share t1 to exercise the SandboxID tie-break.
39+
build := func() []PaginatedSandbox {
40+
return []PaginatedSandbox{
41+
newPaginatedSandbox("b", t1),
42+
newPaginatedSandbox("a", t1),
43+
newPaginatedSandbox("c", t0),
44+
}
45+
}
46+
47+
t.Run("descending: started_at desc, sandbox_id asc", func(t *testing.T) {
48+
t.Parallel()
49+
50+
sandboxes := build()
51+
SortPaginatedSandboxes(sandboxes, SortDesc)
52+
assert.Equal(t, []string{"a", "b", "c"}, sandboxIDs(sandboxes))
53+
})
54+
55+
t.Run("ascending: started_at asc, sandbox_id desc", func(t *testing.T) {
56+
t.Parallel()
57+
58+
sandboxes := build()
59+
SortPaginatedSandboxes(sandboxes, SortAsc)
60+
assert.Equal(t, []string{"c", "b", "a"}, sandboxIDs(sandboxes))
61+
})
62+
63+
t.Run("Desc wrapper matches descending", func(t *testing.T) {
64+
t.Parallel()
65+
66+
sandboxes := build()
67+
SortPaginatedSandboxesDesc(sandboxes)
68+
assert.Equal(t, []string{"a", "b", "c"}, sandboxIDs(sandboxes))
69+
})
70+
}
71+
72+
func TestFilterBasedOnCursor(t *testing.T) {
73+
t.Parallel()
74+
75+
t0 := time.Date(2024, 1, 1, 10, 0, 0, 0, time.UTC)
76+
t1 := time.Date(2024, 1, 1, 11, 0, 0, 0, time.UTC)
77+
t2 := time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC)
78+
79+
sandboxes := []PaginatedSandbox{
80+
newPaginatedSandbox("older", t0),
81+
newPaginatedSandbox("cursor-a", t1),
82+
newPaginatedSandbox("cursor-m", t1),
83+
newPaginatedSandbox("cursor-z", t1),
84+
newPaginatedSandbox("newer", t2),
85+
}
86+
87+
t.Run("descending keeps older and equal-time greater id", func(t *testing.T) {
88+
t.Parallel()
89+
90+
// Cursor at (t1, "cursor-m"): next page is everything strictly "after" it
91+
// in started_at DESC, sandbox_id ASC order.
92+
got := FilterBasedOnCursor(sandboxes, t1, "cursor-m", SortDesc)
93+
assert.ElementsMatch(t, []string{"cursor-z", "older"}, sandboxIDs(got))
94+
})
95+
96+
t.Run("ascending keeps newer and equal-time smaller id", func(t *testing.T) {
97+
t.Parallel()
98+
99+
// Cursor at (t1, "cursor-m"): next page is everything strictly "after" it
100+
// in started_at ASC, sandbox_id DESC order.
101+
got := FilterBasedOnCursor(sandboxes, t1, "cursor-m", SortAsc)
102+
assert.ElementsMatch(t, []string{"cursor-a", "newer"}, sandboxIDs(got))
103+
})
104+
}
105+
10106
func TestParseFilters(t *testing.T) {
11107
t.Parallel()
12108
t.Run("happy path", func(t *testing.T) {

0 commit comments

Comments
 (0)