Merge pull request #419 from YusukeShimizu/rpc/paging-list-swaps-peers

Add paging to ListSwaps/ListPeers (bounded responses)

Author: YusukeShimizu

cmd/peerswaplnd/pscli/main.go

@@ -95,6 +95,19 @@ var (
 		Usage:    "node ID of the peer",
 		Required: true,
 	}
+	listPageSizeFlag = cli.UintFlag{
+		Name:  "page_size",
+		Usage: "max number of items to return (0 = all)",
+		Value: 100,
+	}
+	listPageTokenFlag = cli.StringFlag{
+		Name:  "page_token",
+		Usage: "paging token returned by the previous response",
+	}
+	listDescendingFlag = cli.BoolTFlag{
+		Name:  "descending",
+		Usage: "order by created_at descending (newest first)",
+	}
 
 	swapOutCommand = cli.Command{
 		Name:  "swapout",
@@ -131,15 +144,15 @@ var (
 
 	listSwapsCommand = cli.Command{
 		Name:   "listswaps",
-		Usage:  "lists all swaps",
-		Flags:  []cli.Flag{},
+		Usage:  "lists swaps (paged by default)",
+		Flags:  []cli.Flag{listPageSizeFlag, listPageTokenFlag, listDescendingFlag},
 		Action: listSwaps,
 	}
 
 	listPeersCommand = cli.Command{
 		Name:   "listpeers",
-		Usage:  "lists all peerswap-enabled peers",
-		Flags:  []cli.Flag{},
+		Usage:  "lists peerswap-enabled peers (paged by default)",
+		Flags:  []cli.Flag{listPageSizeFlag, listPageTokenFlag},
 		Action: listPeers,
 	}
 	reloadPolicyFileCommand = cli.Command{
@@ -178,6 +191,7 @@ var (
 	listActiveSwapsCommand = cli.Command{
 		Name:   "listactiveswaps",
 		Usage:  "list active swaps",
+		Flags:  []cli.Flag{listPageSizeFlag, listPageTokenFlag, listDescendingFlag},
 		Action: listActiveSwaps,
 	}
 	allowSwapRequestsCommand = cli.Command{
@@ -344,7 +358,11 @@ func listSwaps(ctx *cli.Context) error {
 	}
 	defer cleanup()
 
-	res, err := client.ListSwaps(context.Background(), &peerswaprpc.ListSwapsRequest{})
+	res, err := client.ListSwaps(context.Background(), &peerswaprpc.ListSwapsRequest{
+		PageSize:   uint32(ctx.Uint(listPageSizeFlag.Name)),
+		PageToken:  ctx.String(listPageTokenFlag.Name),
+		Descending: ctx.Bool(listDescendingFlag.Name),
+	})
 	if err != nil {
 		return err
 	}
@@ -359,7 +377,10 @@ func listPeers(ctx *cli.Context) error {
 	}
 	defer cleanup()
 
-	res, err := client.ListPeers(context.Background(), &peerswaprpc.ListPeersRequest{})
+	res, err := client.ListPeers(context.Background(), &peerswaprpc.ListPeersRequest{
+		PageSize:  uint32(ctx.Uint(listPageSizeFlag.Name)),
+		PageToken: ctx.String(listPageTokenFlag.Name),
+	})
 	if err != nil {
 		return err
 	}
@@ -452,7 +473,11 @@ func listActiveSwaps(ctx *cli.Context) error {
 	}
 	defer cleanup()
 
-	res, err := client.ListActiveSwaps(context.Background(), &peerswaprpc.ListSwapsRequest{})
+	res, err := client.ListActiveSwaps(context.Background(), &peerswaprpc.ListSwapsRequest{
+		PageSize:   uint32(ctx.Uint(listPageSizeFlag.Name)),
+		PageToken:  ctx.String(listPageTokenFlag.Name),
+		Descending: ctx.Bool(listDescendingFlag.Name),
+	})
 	if err != nil {
 		return err
 	}

docs/usage.md

@@ -173,6 +173,16 @@ pscli deletepeerpremiumrate --node_id [node_id] --asset [BTC|LBTC] --operation [
 
 `listpeers` - A command that returns peers that support the PeerSwap protocol. It also gives statistics about received and sent swaps to a peer.
 
+For LND:
+```bash
+# Page through results using next_page_token
+pscli listpeers --page_size 100
+pscli listpeers --page_size 100 --page_token "<next_page_token from previous response>"
+
+# Return all peers (may be large)
+pscli listpeers --page_size 0
+```
+
 Example output:
 ```bash
 [
@@ -207,8 +217,24 @@ Example output:
 
 `listswaps [detailed bool (optional)]` - A command that lists all swaps. If _detailed_ is set the output shows the swap data as it is saved in the database
 
+For LND:
+```bash
+# Page through results using next_page_token (newest first by default)
+pscli listswaps --page_size 100
+pscli listswaps --page_size 100 --page_token "<next_page_token from previous response>"
+
+# Return all swaps (may be large)
+pscli listswaps --page_size 0
+```
+
 `listactiveswaps` - List all ongoing swaps, useful to track swaps when upgrading PeerSwap
 
+For LND:
+```bash
+pscli listactiveswaps --page_size 100
+pscli listactiveswaps --page_size 100 --page_token "<next_page_token from previous response>"
+```
+
 `listswaprequests` - Lists rejected swaps requested by peer nodes.
 
 Example output:
@@ -278,4 +304,4 @@ Currently, it is not possible to set a label on the cln wallet
 For LND:
 To check the label attached to a transaction use `lncli listchaintxns`.
 
-For LBTC transactions, elementsd `SetLabel` will attach a label to the associated address.
+For LBTC transactions, elementsd `SetLabel` will attach a label to the associated address.

peerswaprpc/paging.go

@@ -0,0 +1,54 @@
+package peerswaprpc
+
+import (
+	"strconv"
+
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+const (
+	defaultPageSize = 100
+	maxPageSize     = 1000
+)
+
+func pagingBounds(total int, pageSize uint32, pageToken string, unpagedIfEmpty bool) (start, end int, nextPageToken string, err error) {
+	if total < 0 {
+		return 0, 0, "", status.Error(codes.Internal, "invalid total size")
+	}
+
+	if unpagedIfEmpty && pageSize == 0 && pageToken == "" {
+		return 0, total, "", nil
+	}
+
+	if pageToken != "" {
+		offset, err := strconv.Atoi(pageToken)
+		if err != nil || offset < 0 {
+			return 0, 0, "", status.Error(codes.InvalidArgument, "invalid page_token")
+		}
+		start = offset
+	}
+
+	size := int(pageSize)
+	if size <= 0 {
+		size = defaultPageSize
+	}
+	if size > maxPageSize {
+		size = maxPageSize
+	}
+
+	if start > total {
+		start = total
+	}
+
+	end = start + size
+	if end > total {
+		end = total
+	}
+
+	if end < total {
+		nextPageToken = strconv.Itoa(end)
+	}
+
+	return start, end, nextPageToken, nil
+}

peerswaprpc/paging_test.go

@@ -0,0 +1,63 @@
+package peerswaprpc
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+func TestPagingBounds_UnpagedIfEmpty(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(10, 0, "", true)
+	require.NoError(t, err)
+	require.Equal(t, 0, start)
+	require.Equal(t, 10, end)
+	require.Equal(t, "", nextToken)
+}
+
+func TestPagingBounds_DefaultPageSizeWhenTokenPresent(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(150, 0, "0", true)
+	require.NoError(t, err)
+	require.Equal(t, 0, start)
+	require.Equal(t, defaultPageSize, end)
+	require.Equal(t, "100", nextToken)
+}
+
+func TestPagingBounds_PageSizeAndToken(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(10, 3, "3", true)
+	require.NoError(t, err)
+	require.Equal(t, 3, start)
+	require.Equal(t, 6, end)
+	require.Equal(t, "6", nextToken)
+}
+
+func TestPagingBounds_LastPage(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(10, 3, "9", true)
+	require.NoError(t, err)
+	require.Equal(t, 9, start)
+	require.Equal(t, 10, end)
+	require.Equal(t, "", nextToken)
+}
+
+func TestPagingBounds_TokenBeyondEnd(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(10, 3, "20", true)
+	require.NoError(t, err)
+	require.Equal(t, 10, start)
+	require.Equal(t, 10, end)
+	require.Equal(t, "", nextToken)
+}
+
+func TestPagingBounds_InvalidToken(t *testing.T) {
+	_, _, _, err := pagingBounds(10, 3, "not-a-number", true)
+	require.Error(t, err)
+	require.Equal(t, codes.InvalidArgument, status.Code(err))
+}
+
+func TestPagingBounds_MaxPageSizeClamp(t *testing.T) {
+	start, end, nextToken, err := pagingBounds(5000, 50000, "0", true)
+	require.NoError(t, err)
+	require.Equal(t, 0, start)
+	require.Equal(t, maxPageSize, end)
+	require.Equal(t, "1000", nextToken)
+}