fix: identity list pagination in CLI command and SDK (#3482)

Adds correct pagination parameters to the SDK methods for listing identities and sessions.

BREAKING CHANGE: Pagination parameters for the `list identities` CLI command have changed from arguments to flags `--page-token` and `page-size`:

```
- kratos list identities 1 100
+ kratos list identities --page-size 100 --page-token ...
```

Furthermore, the JSON / JSON pretty output of `list identities` has changed:

```patch
-[
-  { "id": "..." },
-  { /* ... */ },
-  // ...
-]
+{
+  "identities": [
+    {"id": "..."},
+    { /* ... */ },
+    // ...
+  ],
+  "next_page_token": "..."
+}
```

Closes ory/sdk#284
Closes #3480

cmd/identities/definitions.go

@@ -14,7 +14,9 @@ import (
 type (
 	outputIdentity           kratos.Identity
 	outputIdentityCollection struct {
-		identities []kratos.Identity
+		Identities       []kratos.Identity `json:"identities"`
+		NextPageToken    string            `json:"next_page_token"`
+		includePageToken bool
 	}
 )
 
@@ -61,17 +63,23 @@ func (outputIdentityCollection) Header() []string {
 }
 
 func (c outputIdentityCollection) Table() [][]string {
-	rows := make([][]string, len(c.identities))
-	for i, ident := range c.identities {
+	rows := make([][]string, len(c.Identities))
+	for i, ident := range c.Identities {
 		rows[i] = outputIdentity(ident).Columns()
 	}
-	return rows
+	return append(rows,
+		[]string{""},
+		[]string{"NEXT PAGE TOKEN", c.NextPageToken},
+	)
 }
 
 func (c outputIdentityCollection) Interface() interface{} {
-	return c.identities
+	if c.includePageToken {
+		return c
+	}
+	return c.Identities
 }
 
 func (c *outputIdentityCollection) Len() int {
-	return len(c.identities)
+	return len(c.Identities)
 }

cmd/identities/get.go

@@ -82,7 +82,7 @@ func NewGetIdentityCmd() *cobra.Command {
 			if len(identities) == 1 {
 				cmdx.PrintRow(cmd, (*outputIdentity)(&identities[0]))
 			} else if len(identities) > 1 {
-				cmdx.PrintTable(cmd, &outputIdentityCollection{identities})
+				cmdx.PrintTable(cmd, &outputIdentityCollection{Identities: identities, includePageToken: false})
 			}
 			cmdx.PrintErrors(cmd, failed)
 

cmd/identities/import.go

@@ -84,7 +84,7 @@ Files can contain only a single or an array of identities. The validity of files
 			if len(imported) == 1 {
 				cmdx.PrintRow(cmd, (*outputIdentity)(&imported[0]))
 			} else {
-				cmdx.PrintTable(cmd, &outputIdentityCollection{identities: imported})
+				cmdx.PrintTable(cmd, &outputIdentityCollection{Identities: imported})
 			}
 			cmdx.PrintErrors(cmd, failed)
 

cmd/identities/list.go

@@ -6,6 +6,8 @@ package identities
 import (
 	"github.com/spf13/cobra"
 
+	"github.com/ory/x/pagination/keysetpagination"
+
 	"github.com/ory/kratos/cmd/cliclient"
 	"github.com/ory/x/cmdx"
 )
@@ -23,37 +25,41 @@ func NewListCmd() *cobra.Command {
 }
 
 func NewListIdentitiesCmd() *cobra.Command {
-	return &cobra.Command{
-		Use:     "identities [<page> <per-page>]",
+	c := &cobra.Command{
+		Use:     "identities",
 		Short:   "List identities",
-		Long:    "List identities (paginated)",
-		Example: "{{ .CommandPath }} 100 1",
+		Long:    "Return a list of identities.",
+		Example: "{{ .CommandPath }} --page-size 100",
 		Args:    cmdx.ZeroOrTwoArgs,
-		Aliases: []string{"ls"},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := cliclient.NewClient(cmd)
 			if err != nil {
 				return err
 			}
 
 			req := c.IdentityApi.ListIdentities(cmd.Context())
-			if len(args) == 2 {
-				page, perPage, err := cmdx.ParsePaginationArgs(cmd, args[0], args[1])
-				if err != nil {
-					return err
-				}
-
-				req = req.Page(page)
-				req = req.PerPage(perPage)
+			page, perPage, err := cmdx.ParseTokenPaginationArgs(cmd)
+			if err != nil {
+				return err
 			}
 
-			identities, _, err := req.Execute()
+			req = req.PageToken(page)
+			req = req.PageSize(int64(perPage))
+
+			identities, res, err := req.Execute()
 			if err != nil {
 				return cmdx.PrintOpenAPIError(cmd, err)
 			}
 
-			cmdx.PrintTable(cmd, &outputIdentityCollection{identities: identities})
+			pages := keysetpagination.ParseHeader(res)
+			cmdx.PrintTable(cmd, &outputIdentityCollection{
+				Identities:       identities,
+				NextPageToken:    pages.NextToken,
+				includePageToken: true,
+			})
 			return nil
 		},
 	}
+	cmdx.RegisterTokenPaginationFlags(c)
+	return c
 }

cmd/identities/list_test.go

@@ -5,9 +5,10 @@ package identities_test
 
 import (
 	"context"
-	"strings"
 	"testing"
 
+	"github.com/tidwall/gjson"
+
 	"github.com/ory/kratos/cmd/identities"
 
 	"github.com/ory/x/cmdx"
@@ -21,7 +22,6 @@ import (
 func TestListCmd(t *testing.T) {
 	c := identities.NewListIdentitiesCmd()
 	reg := setup(t, c)
-	require.NoError(t, c.Flags().Set(cmdx.FlagQuiet, "true"))
 
 	var deleteIdentities = func(t *testing.T, is []*identity.Identity) {
 		for _, i := range is {
@@ -31,25 +31,44 @@ func TestListCmd(t *testing.T) {
 
 	t.Run("case=lists all identities with default pagination", func(t *testing.T) {
 		is, ids := makeIdentities(t, reg, 5)
-		defer deleteIdentities(t, is)
+		require.NoError(t, c.Flags().Set(cmdx.FlagQuiet, "true"))
+		t.Cleanup(func() {
+			require.NoError(t, c.Flags().Set(cmdx.FlagQuiet, "false"))
+			deleteIdentities(t, is)
+		})
 
-		stdOut := execNoErr(t, c)
+		stdOut := cmdx.ExecNoErr(t, c)
 
 		for _, i := range ids {
 			assert.Contains(t, stdOut, i)
 		}
 	})
 
 	t.Run("case=lists all identities with pagination", func(t *testing.T) {
-		is, ids := makeIdentities(t, reg, 6)
-		defer deleteIdentities(t, is)
+		is, ids := makeIdentities(t, reg, 10)
+		t.Cleanup(func() {
+			deleteIdentities(t, is)
+		})
 
-		stdoutP1 := execNoErr(t, c, "0", "3")
-		stdoutP2 := execNoErr(t, c, "1", "3")
+		first := cmdx.ExecNoErr(t, c, "--format", "json-pretty", "--page-size", "2")
+		nextPageToken := gjson.Get(first, "next_page_token").String()
+		results := gjson.Get(first, "identities").Array()
+		for nextPageToken != "" {
+			next := cmdx.ExecNoErr(t, c, "--format", "json-pretty", "--page-size", "2", "--page-token", nextPageToken)
+			results = append(results, gjson.Get(next, "identities").Array()...)
+			nextPageToken = gjson.Get(next, "next_page_token").String()
+		}
 
-		for _, id := range ids {
-			// exactly one of page 1 and 2 should contain the id
-			assert.True(t, strings.Contains(stdoutP1, id) != strings.Contains(stdoutP2, id), "%s \n %s", stdoutP1, stdoutP2)
+		assert.Len(t, results, len(ids))
+		for _, expected := range ids {
+			var found bool
+			for _, actual := range results {
+				if actual.Get("id").String() == expected {
+					found = true
+					break
+				}
+			}
+			require.True(t, found, "could not find id: %s", expected)
 		}
 	})
 }

go.mod

@@ -76,7 +76,7 @@ require (
 	github.com/ory/jsonschema/v3 v3.0.8
 	github.com/ory/mail/v3 v3.0.0
 	github.com/ory/nosurf v1.2.7
-	github.com/ory/x v0.0.583
+	github.com/ory/x v0.0.588
 	github.com/phayes/freeport v0.0.0-20180830031419-95f893ade6f2
 	github.com/pkg/errors v0.9.1
 	github.com/pquerna/otp v1.4.0
@@ -97,6 +97,7 @@ require (
 	go.opentelemetry.io/otel v1.11.1
 	go.opentelemetry.io/otel/trace v1.11.1
 	golang.org/x/crypto v0.12.0
+	golang.org/x/exp v0.0.0-20220303212507-bbda1eaf7a17
 	golang.org/x/net v0.14.0
 	golang.org/x/oauth2 v0.11.0
 	golang.org/x/sync v0.1.0
@@ -250,6 +251,7 @@ require (
 	github.com/openzipkin/zipkin-go v0.4.1 // indirect
 	github.com/pelletier/go-toml v1.9.5 // indirect
 	github.com/pelletier/go-toml/v2 v2.0.7 // indirect
+	github.com/peterhellberg/link v1.2.0 // indirect
 	github.com/philhofer/fwd v1.1.2 // indirect
 	github.com/pkg/profile v1.7.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
@@ -298,7 +300,6 @@ require (
 	go.opentelemetry.io/otel/metric v0.33.0 // indirect
 	go.opentelemetry.io/otel/sdk v1.11.1 // indirect
 	go.opentelemetry.io/proto/otlp v0.19.0 // indirect
-	golang.org/x/exp v0.0.0-20220303212507-bbda1eaf7a17 // indirect
 	golang.org/x/mod v0.10.0 // indirect
 	golang.org/x/sys v0.11.0 // indirect
 	golang.org/x/term v0.11.0 // indirect

go.sum

@@ -816,8 +816,8 @@ github.com/ory/nosurf v1.2.7 h1:YrHrbSensQyU6r6HT/V5+HPdVEgrOTMJiLoJABSBOp4=
 github.com/ory/nosurf v1.2.7/go.mod h1:d4L3ZBa7Amv55bqxCBtCs63wSlyaiCkWVl4vKf3OUxA=
 github.com/ory/sessions v1.2.2-0.20220110165800-b09c17334dc2 h1:zm6sDvHy/U9XrGpixwHiuAwpp0Ock6khSVHkrv6lQQU=
 github.com/ory/sessions v1.2.2-0.20220110165800-b09c17334dc2/go.mod h1:dk2InVEVJ0sfLlnXv9EAgkf6ecYs/i80K/zI+bUmuGM=
-github.com/ory/x v0.0.583 h1:z6xkrTip16ytAcEvL+nRdK0J+jPWyBeo8qpFOAErZ1g=
-github.com/ory/x v0.0.583/go.mod h1:tgk6em/hJrDRmWAlM2g1hSNnE6rmCOk4eQ/q53/2kZc=
+github.com/ory/x v0.0.588 h1:3qoC1d7qTKnMLwS3Os7KVbDLeSOUHXON8hUFuGUoScQ=
+github.com/ory/x v0.0.588/go.mod h1:ksLBEd6iW6czGpE6eNA0gCIxO1FFeqIxCZgsgwNrzMM=
 github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
 github.com/pascaldekloe/goe v0.1.0 h1:cBOtyMzM9HTpWjXfbbunk26uA6nG3a8n06Wieeh0MwY=
 github.com/pascaldekloe/goe v0.1.0/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
@@ -826,6 +826,8 @@ github.com/pelletier/go-toml v1.9.5 h1:4yBQzkHv+7BHq2PQUZF3Mx0IYxG7LsP222s7Agd3v
 github.com/pelletier/go-toml v1.9.5/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c=
 github.com/pelletier/go-toml/v2 v2.0.7 h1:muncTPStnKRos5dpVKULv2FVd4bMOhNePj9CjgDb8Us=
 github.com/pelletier/go-toml/v2 v2.0.7/go.mod h1:eumQOmlWiOPt5WriQQqoM5y18pDHwha2N+QD+EUNTek=
+github.com/peterhellberg/link v1.2.0 h1:UA5pg3Gp/E0F2WdX7GERiNrPQrM1K6CVJUUWfHa4t6c=
+github.com/peterhellberg/link v1.2.0/go.mod h1:gYfAh+oJgQu2SrZHg5hROVRQe1ICoK0/HHJTcE0edxc=
 github.com/phayes/freeport v0.0.0-20180830031419-95f893ade6f2 h1:JhzVVoYvbOACxoUmOs6V/G4D5nPVUW73rKvXxP4XUJc=
 github.com/phayes/freeport v0.0.0-20180830031419-95f893ade6f2/go.mod h1:iIss55rKnNBTvrwdmkUpLnDpZoAHvWaiq5+iMmen4AE=
 github.com/philhofer/fwd v1.1.2 h1:bnDivRJ1EWPjUIRXV5KfORO897HTbpFAQddBdE8t7Gw=

internal/client-go/.openapi-generator/FILES

@@ -62,7 +62,6 @@ docs/NeedsPrivilegedSessionError.md
 docs/OAuth2Client.md
 docs/OAuth2ConsentRequestOpenIDConnectContext.md
 docs/OAuth2LoginRequest.md
-docs/Pagination.md
 docs/PatchIdentitiesBody.md
 docs/PerformNativeLogoutBody.md
 docs/RecoveryCodeForIdentity.md
@@ -176,7 +175,6 @@ model_needs_privileged_session_error.go
 model_o_auth2_client.go
 model_o_auth2_consent_request_open_id_connect_context.go
 model_o_auth2_login_request.go
-model_pagination.go
 model_patch_identities_body.go
 model_perform_native_logout_body.go
 model_recovery_code_for_identity.go

internal/client-go/README.md

@@ -186,7 +186,6 @@ Class | Method | HTTP request | Description
  - [OAuth2Client](docs/OAuth2Client.md)
  - [OAuth2ConsentRequestOpenIDConnectContext](docs/OAuth2ConsentRequestOpenIDConnectContext.md)
  - [OAuth2LoginRequest](docs/OAuth2LoginRequest.md)
- - [Pagination](docs/Pagination.md)
  - [PatchIdentitiesBody](docs/PatchIdentitiesBody.md)
  - [PerformNativeLogoutBody](docs/PerformNativeLogoutBody.md)
  - [RecoveryCodeForIdentity](docs/RecoveryCodeForIdentity.md)