**feat(folder-resource): add offset and limit pagination for sub-folder search

[erickgonzalez]

Summary

Adds offset and limit query parameters to POST /api/v1/folder/byPath to fix silent truncation of folder lists. Closes #34505.

• Updated FolderHelper to support pagination via offset and limit parameters in findSubFoldersPathByParentPath method.
• Removed the hardcoded subfolder cap of 20 and introduced an effective-limit model.
• limit=-1 is treated as "unlimited" but bounded by SUB_FOLDER_UNLIMITED_SAFETY_CAP (10000) to avoid OOM on very large sites.
• Refactored findSubfoldersUnderHost and findSubfoldersUnderFolder to accept effectiveLimit.
• Final result slice uses subList(offset, offset+limit) wrapped in a fresh ArrayList to avoid backing-list aliasing.
• FolderResource.findSubFoldersByPath now validates inputs (offset >= 0, limit > 0 or limit == -1) and returns 400 on bad input.
• Overflow-safe effectiveLimit computation via a long intermediate clamped to Integer.MAX_VALUE.
• OpenAPI parameter descriptions document the -1 sentinel and the safety cap.
• Added 12 integration tests covering default cap, custom limit, offset paging, offset-beyond-total, limit=-1, negative offset/limit, limit=0, overflow input, and fewer-than-default-folders.

⚠️ Behavior change

The endpoint previously returned at most 20 subfolders silently (hardcoded). It now returns at most 40 by default. Existing clients that omit offset/limit will receive more results than before. This is intentional and addresses the bug described in #34505. Worth a regression sanity check on:

• Angular Site Browser / folder picker components consuming /api/v1/folder/byPath
• DotFolderService.getFolders() callers

Scope

This PR covers the BE side only. Follow-up tickets will wire the new pagination params into Content Drive and the Host/Folder Field in the new edit contentlet.

Test plan

• ./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=FolderResourceTest — all 22 tests pass
• Smoke test the Site Browser folder tree against a site with >40 subfolders
• Smoke test Content Drive (still uses default — will show up to 40 vs. 20)

ref: #34505

This PR fixes: #31934

[claude]

Claude finished @erickgonzalez's task in 3m 16s —— View job

---

PR Review

Solid, well-tested change overall. The validation, overflow guard, and integration test coverage are good. A few things worth a second look before merge:

---

1. The SUB_FOLDER_UNLIMITED_SAFETY_CAP is bypassable — clients can opt out of the safety net

FolderHelper.java:182-184

final int effectiveLimit = limit == -1
        ? SUB_FOLDER_UNLIMITED_SAFETY_CAP
        : (int) Math.min(Integer.MAX_VALUE, (long) offset + limit);

The 10 000 cap is only applied when a client passes limit=-1. A client that passes limit=1000000 (or limit=Integer.MAX_VALUE) sails right past it. Given the PR description sells this as "OOM protection on very large sites," the cap should clamp every code path, not just the sentinel. Consider:

final long requested = (limit == -1) ? SUB_FOLDER_UNLIMITED_SAFETY_CAP : (long) limit;
final long bounded = Math.min(requested, SUB_FOLDER_UNLIMITED_SAFETY_CAP);
final int effectiveLimit = (int) Math.min(Integer.MAX_VALUE, (long) offset + bounded);

This also makes the OpenAPI/Parameter description ("capped at 10000 as a safety limit") accurate for all callers, not just the -1 case.

---

2. "Pagination" here is in-memory slicing on top of a full-table fetch

The inner methods still call APILocator.getFolderAPI().findSubFolders(site|folder, ...), which loads every folder under the host/parent into memory along with a per-folder permission check (FolderFactoryImpl.findFoldersByHost → getSubFolders(...) + in-memory sort). The .limit(effectiveLimit) only truncates the stream that builds FolderSearchResultView objects — it doesn't reduce DB load.

Practical consequences:

• offset=10000, limit=10 still scans the full folder list of the site.
• The "safety cap" only protects against constructing too many response objects, not against the DB query / permission check on N rows. On the "very large sites" you're trying to protect, the bottleneck isn't there.
• Cost is O(total folders × users-with-permission-check) per request, regardless of paging.

Not a blocker — this is the same behavior the old code had — but the PR description ("avoid OOM on very large sites") oversells it. Worth a TODO or follow-up to push pagination into the DAO if real large-site support is the goal.

---

3. Cross-host pagination (when siteId is null) is non-deterministic

FolderHelper.java:189-195 / :201-207

When siteId is empty, the code iterates hostAPI.findAll(user, false) and concatenates each site's filtered folders. Two things to note:

• findAll(...) does not guarantee a stable ordering across calls. So offset=0, limit=40 followed by offset=40, limit=40 can return inconsistent or duplicated pages if the host list shuffles between requests (sites added/removed, cache reset, replica routing, etc.).
• The merged list isn't globally sorted — it's "site A's first N, then site B's first N, …" — so a user paging through results sees per-host runs, not a coherent alphabetical list.

If cross-host paging isn't actually used by callers, fine; but worth either documenting the limitation in the Swagger description or adding a defensive sort on the merged list. The integration tests don't cover the siteId=null path, so this is untested.

---

4. @DefaultValue("40") and "Default 40" strings duplicate SUB_FOLDER_DEFAULT_LIMIT

FolderResource.java:394-396

You introduced FolderHelper.SUB_FOLDER_DEFAULT_LIMIT = 40 but never reference it — @DefaultValue("40") and the description string "Default 40" are hardcoded. JAX-RS @DefaultValue needs a compile-time constant String, so you'd need @DefaultValue("" + FolderHelper.SUB_FOLDER_DEFAULT_LIMIT) — workable, but if anyone ever bumps the constant they'll silently miss two places. Either use the constant everywhere or drop it (since the only reference is the @DefaultValue literal).

---

5. Test javadoc is stale

FolderResourceTest.java:432-454

The javadoc says "Create 25 subfolders ... All 26 results returned (parent + all 25 subfolders)" but the loop creates 50 (for (int i = 0; i < 50; i++)) and the assertion is 51. The test itself is fine; just fix the comment so future maintainers don't get confused.

---

6. findSubfoldersUnderFolder adds the parent before the .limit(effectiveLimit) stream

FolderHelper.java:262-273

The parent entry is appended (line 263) and then up to effectiveLimit children are added. So per-host the method can return effectiveLimit + 1 items. Combined with the cross-host accumulation guard subFolders.size() < effectiveLimit, it means a single host can push the running total a hair over the cap. The final subList(...) saves you, but it's a subtle invariant. Same applies to the system-folder branch in findSubfoldersUnderHost (line 228).

No functional bug, but if you ever change the slicing, this is a footgun.

---

7. Minor: name effectiveLimit is misleading in the inner methods

In findSubFoldersPathByParentPath it really means "how many to fetch before we slice" — i.e., offset + limit. Passed verbatim into findSubfoldersUnderHost/Folder, where it's used as a per-host fetch ceiling. maxToFetch or fetchUpper would convey the intent better.

---

Summary

• Blocker? No — tests pass, validation is solid, overflow handled.
• Worth fixing before merge: update with latest SVN #1 (safety-cap bypass). That's the only one that contradicts the PR's stated guarantee.
• Worth following up: Test Branch and Commit #2 (real DB-level pagination), Add .gitignore #3 (multi-host stability + sort), wezell's issue #5 (test javadoc).
• Approved by @jcastro-dotcms already; flagging the above for visibility.

Fix issue #1 (safety cap bypass) →

• Read changed files
• Analyze pagination logic and edge cases
• Check input validation & overflow handling
• Review tests for coverage gaps
• Post review feedback
  • Branch: issue-31934-folderresource-bypath-limit-offset