fix(sessions): apply the offset query parameter (#1765)

## Bug

`GET /api/v1/sessions` documents `offset` ("Number of sessions to skip
for pagination"). It parses the value and echoes it back in the
response's `offset` field, but never passes it on:
`storage.SessionFilter` has no offset, and `GetRecentSessionsFiltered`
always returns the first page. A client paging through sessions gets the
newest page repeatedly while the response claims `offset: N`.

## Trigger

With three or more stored sessions:

```
GET /api/v1/sessions?limit=1&offset=1
```

- Expected: the second-newest session, with `offset: 1`.
- Actual: the newest session, with `offset: 1`.

## Fix

- Add `Offset` to `storage.SessionFilter`.
- In `GetRecentSessionsFiltered`, skip that many sessions after the
existing sort and filter, so `total` stays the filtered count.
- Set `Offset` from the already-parsed query value in
`handleGetSessions`.
- An offset beyond the end returns an empty page.
- Callers that don't set `Offset` (the clients hub, runtime) behave
exactly as before.

## Test

- `TestGetRecentSessionsFiltered_Offset` (storage): unfiltered `limit=2,
offset=1` returns `[s-zed, s-api]`, and a filtered `client=cursor,
offset=1` returns `[s-old-cursor]` with total 2. An offset past the end
returns an empty page with the total intact.
- `TestSessions_OffsetReachesStorage` (httpapi): `?limit=1&offset=2`
reaches the controller as `SessionFilter.Offset == 2`.

## Commands run

- `CGO_ENABLED=0 go test -count=1 ./internal/storage`: ok
- `CGO_ENABLED=0 go test -count=1 ./internal/httpapi`: ok
- `CGO_ENABLED=0 go test -count=1 -run Session ./internal/runtime`: ok
- Storage behaviour reverted (the field kept so the test compiles): the
storage test fails, returning `[s-cursor2 s-zed]` instead of `[s-zed
s-api]`.
- Handler line reverted: the httpapi test fails with `expected: 2,
actual: 0`.
- `gofmt -l` on the edited files: no output

Author: rudycelekli

internal/httpapi/server.go

@@ -6900,6 +6900,7 @@ func (s *Server) handleGetSessions(w http.ResponseWriter, r *http.Request) {
 		s.writeError(w, r, http.StatusBadRequest, err.Error())
 		return
 	}
+	sessionFilter.Offset = offset
 
 	// Get recent sessions from controller
 	sessions, total, err := s.controller.GetRecentSessions(sessionFilter)

internal/httpapi/sessions_scope_test.go

@@ -111,3 +111,15 @@ func TestSessionsScope_RowsCarryAttributionAndFiltersReachStorage(t *testing.T)
 	assert.Contains(t, w.Body.String(), "client_name is not supported on this endpoint; filter by client")
 	assert.Zero(t, ctrl.callCount, "the check runs before any storage read")
 }
+
+func TestSessions_OffsetReachesStorage(t *testing.T) {
+	ctrl := &scopedSessionController{mockSessionController{apiKey: "test-key", sessions: scopeTestSessions()}}
+	srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/sessions?limit=1&offset=2", nil)
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, 2, ctrl.gotFilter.Offset, "offset query param must be passed to the session filter")
+}

internal/storage/manager.go

@@ -1532,6 +1532,7 @@ type SessionRecord struct {
 // TokenName are the credential at initialize.
 type SessionFilter struct {
 	Limit     int
+	Offset    int // matching sessions to skip, applied after sort and filter
 	Status    string
 	Profile   string
 	ClientID  string
@@ -1747,6 +1748,7 @@ func (m *Manager) GetRecentSessions(limit int, status string) ([]*SessionRecord,
 // never truncated out by a page of newer non-matching ones.
 func (m *Manager) GetRecentSessionsFiltered(f SessionFilter) ([]*SessionRecord, int, error) {
 	limit := f.Limit
+	offset := max(f.Offset, 0)
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
@@ -1792,17 +1794,18 @@ func (m *Manager) GetRecentSessionsFiltered(f SessionFilter) ([]*SessionRecord,
 				continue
 			}
 			total++
-			if len(sessions) < limit {
+			if total > offset && len(sessions) < limit {
 				sessions = append(sessions, session)
 			}
 		}
 		return sessions, total, nil
 	}
 
-	if limit < len(all) {
-		return all[:limit], len(all), nil
+	page := all[min(offset, len(all)):]
+	if limit < len(page) {
+		page = page[:limit]
 	}
-	return all, len(all), nil
+	return page, len(all), nil
 }
 
 // GetSessionByID retrieves a session by its ID

internal/storage/sessions_offset_test.go

@@ -0,0 +1,29 @@
+package storage
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetRecentSessionsFiltered_Offset(t *testing.T) {
+	m, cleanup := setupTestStorageForActivity(t)
+	defer cleanup()
+	seedScopeSessions(t, m) // newest first: s-cursor2, s-zed, s-api, s-old-cursor
+
+	got, total, err := m.GetRecentSessionsFiltered(SessionFilter{Limit: 2, Offset: 1})
+	require.NoError(t, err)
+	assert.Equal(t, 4, total)
+	assert.Equal(t, []string{"s-zed", "s-api"}, sessionIDs(got))
+
+	got, total, err = m.GetRecentSessionsFiltered(SessionFilter{Limit: 10, Offset: 1, ClientID: "cursor"})
+	require.NoError(t, err)
+	assert.Equal(t, 2, total, "total stays the filtered count")
+	assert.Equal(t, []string{"s-old-cursor"}, sessionIDs(got))
+
+	got, total, err = m.GetRecentSessionsFiltered(SessionFilter{Limit: 10, Offset: 9})
+	require.NoError(t, err)
+	assert.Equal(t, 4, total)
+	assert.Empty(t, got)
+}