[Feature] Add unified dashboards + folders (projects)

[yotamloe]

Description

-Add support for unified dashboards + folders (projects)

What type of PR is this?

(check all applicable)

• 🍕 Feature
• 🐛 Bug Fix
• 🧑‍💻 Code Refactor
• 🔥 Performance Improvements
• ✅ Test
• 🤖 Build / CI
• ⏩ Revert

Added tests?

• 👍 yes
• 🙅 no, because they aren't needed
• 🙋 no, because I need help from somebody

[8naama]

Great work! Left small comments

[8naama]

missing some endpoint that might be handy when working on the provider:

• GET /projects/<projectId>/dashboards - per-project list
• POST /dashboards/search - search for datasource

worth to verify with app team if there are others that may be useful

[pincher95]

Both exist — added, with unit + live integration tests.

• GET /projects/{projectId}/dashboards → ListFolderDashboards(folderId). One gotcha worth knowing: an id matching no folder answers 200 [], identical to an existing empty folder, so it cannot be used to detect a missing folder.
• POST /dashboards/search → SearchDashboards(req), returning flat dashboards as {results, total, pagination}.

The search one is a straight correction on my side: I removed a SearchDashboards earlier in this PR because the published docs do not list the route. The docs are wrong — it is live on /perses-public, and I had also been probing it on the old /perses gateway at the time. Probed 2026-08-20:

• filter.searchTerm genuinely filters (exact term → 1 result, nonsense term → 0). That is a real difference from POST /projects/search, which returns every folder regardless of the term.
• pagination.pageNumber/pageSize are honoured and echoed; total is the unpaginated match count. Default page size is 20.
• GET /dashboards/search → 404, so POST only.
• filter.createdBy is accepted but ignored — a bogus account id still returns everything. Mapped for symmetry with the projects filter, documented as non-functional.

The app-team check for further endpoints is still open — I only probed the two you listed plus the routes this package already uses.

[pincher95]

Following up on the "search for datasource" part specifically — that endpoint cannot do it.

I created a dashboard whose display name, panel name, datasource reference and PromQL query each carried a distinctive token, then searched for each in turn:

searchTerm = datasource name  zzdatasource132334      -> total=0   matched: False
searchTerm = panel name       panel one               -> total=0   matched: False
searchTerm = display name     Totally Unrelated       -> total=0   matched: False
searchTerm = promql query     up                      -> total=0   matched: False
searchTerm = metadata name    ds-20260820132334-d     -> total=1   matched: True

filter.searchTerm matches the Perses document's metadata.name and nothing else — it is an identity lookup, not a full-text search over the document. Nothing on this gateway finds dashboards by the datasource they reference; you would have to list and walk Doc client-side.

Documented in the godoc and the README, and the search IT now gives the dashboard a display name distinct from its metadata.name and asserts the display name matches nothing, so this cannot quietly change meaning later.

Pushed as 5e0f4b7. If finding dashboards by datasource is the actual need, that is worth raising with the app team as a gap rather than something the client can work around cheaply.

[8naama]

previous PR lowercased such errors, worth to keep coherent

[pincher95]

Fixed — base URL not defined in both packages, and the tests that pin the string.

Left API token not defined capitalised, which is what master does post-#163 (initialism, so ST1005 allows it). Also picked up the rest of that PR's modernization while here: interface{} → any across both packages, since master has none left.

[8naama]

I think the comment is a bit confusing, the dashboard object has both a id and uid fields; so does the returned id actually the uid or the new id following the change?

[pincher95]

The doubt was well placed — that line was wrong, and so was the code under it.

Re-probed live with a dashboard at version 2: MoveDashboardResponse's id is the version-row id, not the uid. The reason it read as a uid is that the server creates a dashboard with id == uid == name; the three only diverge after the first update, and everything in this PR had only ever been checked against freshly created dashboards.

The README now carries an Identifiers section instead of that one-liner: which field is which, what each is for, that MoveDashboardResponse.Id is a version-row id, that unified_projects.ProjectDashboard exposes both, and the version-1 coincidence that hides the difference in the first place.

[8naama]

not sure the comment is correct here, if it's the dashboard uid or it's new id

[pincher95]

Correct to doubt it — the comment was wrong. MoveDashboardResponse.Id is the moved dashboard's current version-row id, not its uid.

Probe against api.logz.io, 2026-08-20:

v2: rowId=c26f75a3-…  uid=fc82f90d-…
PUT /dashboards/move -> 200 {"id": "c26f75a3-…"}
  move.id == uid   ? False
  move.id == rowId ? True

Against a version-1 dashboard the same call returns a value equal to the uid — but only because a new dashboard has id == uid == name. That is exactly why the old integration test passed: it created a dashboard and moved it immediately, so assert.Equal(created.Uid, moved.Id) held for either field and proved nothing.

Fixed both sides: the field is documented for what it actually is (an acknowledgement, not a handle — keep using the uid you passed as DashboardId), and the move IT now updates the dashboard first so the row id forks off the uid, then asserts moved.Id == updated.Id and moved.Id != created.Uid.

[8naama]

does the API return uid here too? if so, worth mapping it since it's the stable id

[pincher95]

Yes, it does — and mapping it turned out to matter more than cosmetics, because the Id that was there is a trap.

Probe against api.logz.io, 2026-08-20. Embedded payload keys:

["createdAt","createdBy","deletedAt","deletedBy","doc","id","isDeleted",
 "isPrivate","name","projectId","uid","updatedAt","updatedBy","version"]

On a version-2 dashboard the two identifiers diverge, and only one of them resolves:

embedded id  = a10ef4b5-…   GET /projects/{p}/dashboards/{id}  -> 404
embedded uid = 6701d8fd-…   GET /projects/{p}/dashboards/{uid} -> 200

So ProjectDashboard.Id is the version-row id, replaced on every update, and not addressable. A provider persisting it would have stored a value that breaks the first time a user edits the dashboard — silently, because it works fine until then.

What made this invisible: a brand-new dashboard is created with id == uid == name. The round-3 assertion item.Dashboards[0].Id == created.Uid ran against a freshly created dashboard, so it passed for either field. It was a coincidence, not a verification, and I read it as settling the question.

Changes:

• ProjectDashboard now maps Uid alongside Id, with Uid documented as the handle and Id as the non-addressable version row.
• Embedded-dashboard fixtures carry different uid and id values, so a dropped field cannot pass by matching.
• Unit tests pin both fields; the create-dashboard IT updates the dashboard first, then asserts Uid resolves and Id returns "failed with missing unified dashboard".