@pipod/cli 0.1.16 → 0.1.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.js +23 -6
- package/dist/cli.js.map +1 -1
- package/docs/pod-list-pagination.md +52 -0
- package/man/pipod-config.5 +1 -1
- package/man/pipod.1 +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Pod-list pagination
|
|
2
|
+
|
|
3
|
+
`pipod ls` (also `pipod list`) reads every page before applying display filters or
|
|
4
|
+
rendering the oldest-activity-first tree. Quiet output contains each full pod ID
|
|
5
|
+
once. Project, template, account and machine-group scopes use the same page walk;
|
|
6
|
+
so do short-ref/name resolution and bulk archive/restore/GC selection.
|
|
7
|
+
|
|
8
|
+
## API contract
|
|
9
|
+
|
|
10
|
+
`GET /v1/pods` returns `{ pods, nextCursor }`. A page contains at most `limit`
|
|
11
|
+
pods (default 100, maximum 200). `nextCursor: null` means the last page, including
|
|
12
|
+
an empty result. Otherwise pass that opaque string as `cursor` on the next request,
|
|
13
|
+
keeping the same filters. Do not derive it from `lastActivityAt` or `createdAt`:
|
|
14
|
+
the cursor retains PostgreSQL microseconds and the pod UUID tie-breaker. The
|
|
15
|
+
order is descending `(COALESCE(last_activity_at, created_at), id)`.
|
|
16
|
+
|
|
17
|
+
The cursor contains a boundary, not a row lookup, so deleting the boundary pod
|
|
18
|
+
does not invalidate it. It is not an authorization grant: every page still
|
|
19
|
+
applies the authenticated organization, owner and pod-token subtree restrictions.
|
|
20
|
+
Malformed cursors and requests combining `cursor` with `before` return 400.
|
|
21
|
+
|
|
22
|
+
`before` remains the legacy timestamp-only boundary. A new CLI falls back to it
|
|
23
|
+
only when the response omits `nextCursor`; old clients continue working with new
|
|
24
|
+
servers but cannot recover ties or microseconds using their old page walk. Both
|
|
25
|
+
sides must be upgraded for lossless pagination of an unchanged roster.
|
|
26
|
+
|
|
27
|
+
This is a live listing, not a database snapshot. Concurrent activity can move a
|
|
28
|
+
pod ahead of an already-read boundary. The CLI deduplicates IDs if it sees a pod
|
|
29
|
+
again and fails explicitly on a repeated cursor rather than reporting a silently
|
|
30
|
+
truncated roster. Rerun a listing after concurrent activity for a fresh view.
|
|
31
|
+
|
|
32
|
+
## Manual acceptance (no unit tests)
|
|
33
|
+
|
|
34
|
+
Use an explicit disposable migrated database, never a production fixture insert.
|
|
35
|
+
Run the actual pod routes over loopback HTTP and the built CLI by absolute path:
|
|
36
|
+
|
|
37
|
+
- More than 400 pods with identical activity timestamps, including ties spanning
|
|
38
|
+
multiple pages; every matching ID appears exactly once.
|
|
39
|
+
- Several distinct PostgreSQL timestamps within one millisecond; no IDs disappear
|
|
40
|
+
at the page boundary. Include null activity with creation-time fallback.
|
|
41
|
+
- Empty, short, exact-multiple and final pages; authoritative `nextCursor` works
|
|
42
|
+
even with pages smaller than the CLI's requested maximum.
|
|
43
|
+
- Account, project, template, state, owner, gone-row and pod-token subtree filters
|
|
44
|
+
remain in force on subsequent pages. Archived pods filling an early page do not
|
|
45
|
+
hide active pods on later pages. Check quiet and rendered output.
|
|
46
|
+
- Delete the last pod of one page, then follow its cursor successfully.
|
|
47
|
+
- Malformed cursor and simultaneous `cursor`/`before` return 400.
|
|
48
|
+
- A legacy server omitting `nextCursor` is still traversed with `before`.
|
|
49
|
+
A server repeating a cursor fails without printing an incomplete quiet roster.
|
|
50
|
+
|
|
51
|
+
Live rollout acceptance uses read-only listings. It must not manufacture hundreds
|
|
52
|
+
of billable pods or change existing pods' timestamps to force a page boundary.
|
package/man/pipod-config.5
CHANGED
package/man/pipod.1
CHANGED