feat: Streamed List Objects support ( consumer callback )

[SoulPancake]

Description

API model is generated using https://github.com/openfga/sdk-generator/pull/656

What problem is being solved?

The Java SDK currently lacks support for the streamedListObjects API endpoint, which prevents developers from efficiently processing large lists of objects in an asynchronous, streaming manner. This limitation can cause memory issues and performance bottlenecks when dealing with large result sets.

How is it being solved?

This PR implements support for the streamedListObjects API endpoint using a consumer callback pattern. The implementation allows clients to process objects as they are streamed from the server, rather than waiting for the entire response to be loaded into memory.

What changes are made to solve it?

• Added new streamedListObjects API method with consumer callback support for asynchronous streaming
• Implemented streaming response handling for efficient processing of large object lists
• Added comprehensive test coverage to validate streaming functionality
• Updated API models and documentation to include the new streaming endpoint
• Provided example code demonstrating how to use the streaming functionality

References

Review Checklist

• [x] I have clicked on "allow edits by maintainers".
• [ ] I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• [x] The correct base branch is being used, if not main
• [x] I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

Release Notes

• New Features

  • Added streamedListObjects API endpoint for asynchronous streaming of object lists

• Documentation

  • Documented new streaming endpoint and response model definitions
  • Provided example code demonstrating streaming functionality

• Tests

  • Added comprehensive test coverage for streaming features

[coderabbitai[bot]]

[!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.

[!NOTE]

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

This pull request adds streaming support to the OpenFGA Java SDK for the list objects API endpoint. New model classes, API methods, and client-level wrappers enable non-blocking, line-by-line streaming of results via CompletableFuture. Includes comprehensive unit and integration tests, and a working example project demonstrating the feature.

Changes

Cohort / File(s)	Summary
Streamed response models src/main/java/dev/openfga/sdk/api/model/StreamResultOfStreamedListObjectsResponse.java, src/main/java/dev/openfga/sdk/api/model/StreamedListObjectsResponse.java	New model classes for streaming responses with JSON serialization, equality, and URL query string support. StreamResultOfStreamedListObjectsResponse wraps either a result or an error; StreamedListObjectsResponse holds the object name.
Documentation for models docs/StreamResultOfStreamedListObjectsResponse.md, docs/StreamedListObjectsResponse.md	Documentation pages describing the new model structures and their properties.
Core API streaming src/main/java/dev/openfga/sdk/api/OpenFgaApi.java	Adds two new public methods (streamedListObjects, streamedListObjectsWithHttpInfo) returning CompletableFuture<ApiResponse<StreamResultOfStreamedListObjectsResponse>>, with telemetry setup.
Streaming API implementation src/main/java/dev/openfga/sdk/api/StreamedListObjectsApi.java	New public class providing asynchronous streaming via CompletableFuture and Java HttpClient with line-by-line NDJSON parsing; supports optional error callbacks and configuration overrides.
Client-level streaming src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java	Adds three public overloads of streamedListObjects with varying configurability; delegates to StreamedListObjectsApi.
Client streaming options src/main/java/dev/openfga/sdk/api/client/model/ClientStreamedListObjectsOptions.java	New configuration class for streaming calls; holds authorizationModelId, consistency preference, and optional headers with fluent setters.
Unit tests src/test/java/dev/openfga/sdk/api/client/StreamedListObjectsTest.java	Comprehensive test suite covering success, error handling, empty streams, parameter validation, consumer invocation, chaining, header propagation, and HTTP error scenarios.
Integration tests src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java	New integration test method validating streaming scenarios (basic, error handling, chaining) with real futures.
Example project examples/streamed-list-objects/Makefile, examples/streamed-list-objects/README.md, examples/streamed-list-objects/build.gradle, examples/streamed-list-objects/gradle.properties, examples/streamed-list-objects/gradle/wrapper/gradle-wrapper.properties, examples/streamed-list-objects/gradlew, examples/streamed-list-objects/gradlew.bat, examples/streamed-list-objects/settings.gradle, examples/streamed-list-objects/src/main/java/dev/openfga/sdk/example/StreamedListObjectsExample.java	Complete standalone example project with build configuration, Gradle wrapper, and StreamedListObjectsExample demonstrating store creation, model setup, tuple writing, streaming consumption, and cleanup.
README and API docs README.md, docs/OpenFgaApi.md	Updated to document the new streamedListObjects API endpoint and exported models.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Client as OpenFgaClient
    participant API as StreamedListObjectsApi
    participant HTTP as HttpClient
    participant Parser as NDJSON Parser

    User->>Client: streamedListObjects(request, consumer)
    Client->>Client: validate & build ListObjectsRequest
    Client->>API: new StreamedListObjectsApi()
    Client->>API: streamedListObjects(storeId, body, consumer, errorConsumer)
    API->>HTTP: sendAsync(POST /stores/{id}/streamed-list-objects)
    
    rect rgb(200, 220, 240)
        Note over HTTP,Parser: Streaming Response
        HTTP-->>API: HttpResponse (NDJSON body stream)
        loop for each line
            API->>Parser: processLine(line)
            alt contains result
                Parser->>Consumer: accept(object)
            else contains error
                Parser->>ErrorConsumer: accept(exception)
            end
        end
    end
    
    API-->>Client: CompletableFuture<Void> (completes when stream ends)
    Client-->>User: CompletableFuture<Void>

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Specific areas requiring attention:
  • StreamedListObjectsApi.java — complex streaming logic with NDJSON line parsing, error handling via callbacks, and HTTP response body streaming; validate line parsing and error propagation paths
  • StreamedListObjectsTest.java — comprehensive mock setup and varied test scenarios; verify mock HttpResponse construction and consumer/error-consumer invocation semantics
  • Parameter validation consistency across three OpenFgaClient.streamedListObjects overloads
  • Example project build configuration (gradlew, gradle-wrapper.properties) — verify paths and Gradle version compatibility

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Streamed List Objects support ( consumer callback )' accurately reflects the main changes: adding streaming support for listing objects with consumer-based callbacks.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

[!TIP]

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example:

"Create a concise high-level summary as a bullet-point list. Then include a Markdown table showing lines added and removed by each contributing author."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

:x: Patch coverage is 40.36697% with 130 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 36.89%. Comparing base (d93032f) to head (035c939).

Files with missing lines	Patch %	Lines
...del/StreamResultOfStreamedListObjectsResponse.java	15.90%	37 Missing :warning:
...fga/sdk/api/model/StreamedListObjectsResponse.java	10.81%	33 Missing :warning:
...va/dev/openfga/sdk/api/StreamedListObjectsApi.java	65.33%	16 Missing and 10 partials :warning:
src/main/java/dev/openfga/sdk/api/OpenFgaApi.java	0.00%	17 Missing :warning:
...java/dev/openfga/sdk/api/client/OpenFgaClient.java	51.42%	11 Missing and 6 partials :warning:

:x: Your project status has failed because the head coverage (36.89%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #252      +/-   ##
============================================
+ Coverage     36.47%   36.89%   +0.42%     
- Complexity     1144     1187      +43     
============================================
  Files           188      192       +4     
  Lines          7192     7410     +218     
  Branches        824      854      +30     
============================================
+ Hits           2623     2734     +111     
- Misses         4462     4553      +91     
- Partials        107      123      +16     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.