feat: Add configurable page-size parameter to fga tuple read command

[Siddhant-K-code]

Description

This PR enhances the fga tuple read command by adding support for a configurable page-size parameter and implementing intelligent default page-size behavior based on the max-pages setting to improve performance when reading tuples.

Related Issue

Fixes #568

Changes made

• Added --page-size flag to the fga tuple read command
• Implemented smart default page-size logic:
  • When max-pages=0 (read all tuples): defaults to 100 for better efficiency
  • When max-pages!=0 (limited pages): defaults to 50 to maintain backward compatibility
  • When --page-size is explicitly specified: uses the provided value
• Updated internal tuple.Read function to accept page size as a parameter
• Updated cmd/store/export.go to use the appropriate page size
• Added comprehensive unit tests for the new page-size behavior

Command usage examples

1. Read all tuples (optimized with page-size=100)

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=0

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "reader",
        "object": "document:roadmap"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:design"
      },
      "timestamp": "2024-01-15T10:31:00Z"
    }
    // ... fetches up to 100 tuples per page instead of 50
  ],
  "continuation_token": ""
}

2. Read with limited pages (default page-size=50)

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=2 --user user:anne

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "reader",
        "object": "document:roadmap"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "key": {
        "user": "user:anne",
        "relation": "viewer",
        "object": "folder:projects"
      },
      "timestamp": "2024-01-15T10:32:00Z"
    }
    // ... up to 50 tuples per page (maintains backward compatibility)
  ],
  "continuation_token": ""
}

3. Read with custom page size

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=3 --page-size=75 --relation viewer

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "viewer",
        "object": "folder:projects"
      },
      "timestamp": "2024-01-15T10:32:00Z"
    },
    {
      "key": {
        "user": "user:bob",
        "relation": "viewer",
        "object": "folder:shared"
      },
      "timestamp": "2024-01-15T10:33:00Z"
    }
    // ... fetches up to 75 tuples per page as specified
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTUUoyN01MdTdqTjh0Ym42MjA4In0="
}

4. Help output showing new flag

Command:

fga tuple read --help

Output (relevant section):

Flags:
  -h, --help                 help for read
      --max-pages int        Max number of pages to get. Set to 0 to get all pages. (default 20)
      --object string        Object
      --output-format string Specifies the format for data presentation. Valid options: json, simple-json, csv, and yaml. (default "json")
      --page-size int32      Number of tuples to return per page. Defaults to 100 when max-pages=0, or 50 otherwise. Max is 100.
      --relation string      Relation
      --user string          User
      --consistency string   Consistency preference for the request. Valid options are HIGHER_CONSISTENCY and MINIMIZE_LATENCY.

Performance Impact

For stores with many tuples, this change significantly reduces API calls when reading all tuples:

Scenario	Before (page-size=50)	After (page-size=100)	Improvement
100 tuples	2 API calls	1 API call	50% reduction
500 tuples	10 API calls	5 API calls	50% reduction
1000 tuples	20 API calls	10 API calls	50% reduction
5000 tuples	100 API calls	50 API calls	50% reduction

No breaking changes

This PR does not include breaking changes.

The default behavior when max-pages!=0 remains unchanged (page-size=50), ensuring complete backward compatibility.

Summary by CodeRabbit

• New Features
  • Added a --page-size flag to the tuple read command, allowing users to control how many results are returned per page.
  • Introduced smart defaults when --page-size is not provided: 100 when no max page limit is set, and 50 when a max page limit is specified.
  • Improves pagination control and performance predictability when reading large sets of tuples.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds page-size support to tuple reads: introduces a --page-size flag, updates defaulting logic (100 when max-pages=0, else 50), threads pageSize through the CLI to internal tuple.Read, and updates the tuple.Read signature to accept pageSize. Also updates a store export call-site to pass an explicit default page size.

Changes

Cohort / File(s)	Summary
Tuple read command and internal API cmd/tuple/read.go, internal/tuple/read.go	Add pageSize parameter to tuple.Read; introduce --page-size flag; implement defaulting: pageSize=100 when max-pages=0, else 50; propagate pageSize to SDK read options.
Tuple read tests cmd/tuple/read_test.go	Update tests to pass/verify pageSize; add tests for defaulting behavior and custom page size.
Store export call-site update cmd/store/export.go	Update tuple.Read invocation to include explicit page size (tuple.DefaultReadPageSize) per new function signature.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor U as User
    participant CLI as fga tuple read (CLI)
    participant Resolver as PageSize Resolver
    participant T as internal/tuple.Read
    participant SDK as OpenFGA SDK

    U->>CLI: run "fga tuple read [--max-pages N] [--page-size P]"
    CLI->>Resolver: compute pageSize (N, P)
    alt P provided (>0)
        Note right of Resolver: Use P
    else P not provided (0)
        alt N == 0
            Note right of Resolver: pageSize = 100
        else N > 0
            Note right of Resolver: pageSize = 50
        end
    end
    Resolver-->>CLI: pageSize
    CLI->>T: Read(ctx, req, maxPages=N, pageSize, consistency)
    T->>SDK: Read(req, options{PageSize: pageSize}, paging)
    SDK-->>T: tuples (+continuation)
    T-->>CLI: aggregated response
    CLI-->>U: output tuples

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Default page-size = 100 when max-pages=0 (#568)	✅
Default page-size = 50 when max-pages!=0 (#568)	✅
Allow specifying page-size parameter; always honor it when provided (#568)	✅

Assessment against linked issues: Out-of-scope changes

Code Change	Explanation
Pass explicit default page size to tuple.Read in store export flow (cmd/store/export.go, exact lines not provided)	Not related to tuple read CLI behavior in #568; modifies store export path which isn’t mentioned in the issue. Line numbers unavailable in provided summary.

Suggested labels

codex

Suggested reviewers

• rhamzeh

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[rhamzeh]

Also would you mind updating the read section in the README?

[rhamzeh]

Thanks!