Repository navigation
feat(rows): read rows as objects on api/2 with ?shape=object - #65
rjzondervan wants to merge 11 commits into
Conversation
The single-row and listing routes return, with shape=object, one flat object per row keyed by the technical names of the columns, with the metadata in an @self block whose id is the row uuid. Datetimes carry the offset of the instance's default_timezone, links are {title, url, providerId} and relations are the uuid of the target row. The cells shape stays the default. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES (Strict) — self-review posted as COMMENT (GitHub blocks a verdict on your own PR)
Status: all 11 findings are addressed in 245f4e92, b302685b and ff1ce2d3 (10 fixed, the type of the object's keys kept by decision, see its thread); all threads are resolved. phpunit 721/721, Behat
@rows13/13. A re-review decides the verdict.
No blockers, but 4 concerns, and under Strict a 🟡 blocks. The object shape is read-only here and the routes keep their existing permission checks; the concerns are about what the object promises: a key for every column,
@selftimes that #63's filters can take back, relation uuids, and@selfthat a column can never replace. The fixes follow as new commits on this branch.
🟡 Concerns
- Columns without a stored cell are missing from the object
- @self timestamps use the instance offset, but the filter reads them as UTC
- Relations fall back to an int, contradicting 'relations are uuids'
- A column can overwrite @self
🟢 Minor
- No wired integration test for shape=object
- testCellsShapeIsTheDefault passes 'cells' explicitly
- Non-existent local times shift on read
- RowObject value type includes RowSelf for every key
- Unknown datetime format logs a warning per cell per request
- Columns are queried twice per request
- @self says lastEdit*, the filter and sort say updated*
✅ Verified clean
-
Both routes keep
RequirePermission(READ)and the service checks; on a view only the view's columns reach the object. -
Relation uuids expose nothing new: the cells shape already returns the target row id, and a uuid gives no access by itself.
-
findUuidsByIdsreads in chunks ofDB_CHUNK_SIZE, skips rows without a uuid and is tested against the database. -
An unknown
shapeis a 400 on both routes; federated tables and views are refused before serializing. -
Date-only and time-only columns stay naive; empty cells become
null. -
Scope: the single commit
32e3676a(14 files, +894/−10) againstreview-base/3096(#63's head). -
Checks on this head: phpunit 714/714, psalm, cs and rector clean, openapi up to date. Gates: the runner is not available for this repo, so the repo's own checks stand in. CI was still queued.
-
Live on the dev instance: an object only has keys for the cells that were stored (thread).
-
Connected issues: nextcloud#3096 (open; part 1 of 2,
Refs); depends on nextcloud#3095 (#63) and nextcloud#3093, both open.
🤖 Generated with Claude Code
- Every column a row is read with gets a property, null when the row has no cell for it. Row2 now carries the columns of its alias payload, narrowed by fields and view like the payload itself, so the serializer no longer loads the columns a second time. - @self is kept when a column has the same key, its times are in UTC as stored, so they can be used as they are in the createdAt and updatedAt filters, and it names the editor updatedBy/updatedAt like those filters. An empty creator stays null instead of "". - A relation is the uuid of the target row, its row id while the target has no uuid yet, and null when the target no longer exists: findUuidsByIds now returns null for an existing row without a uuid. - Stored datetimes with an unknown format are logged once per call. - The shape parameter documents the object shape; the tests cover the daylight saving gap and call getRow without a shape. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
A Behat scenario lists a table with ?shape=object and checks the uuid in @self, a value per column and null for a column without a value. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
The columns a row carries were built again for every row, also on the full listings of the frontend and API v1 that never use the object shape. The rows of one call now share the same maps. A test checks that a view's rows, listed and single, carry only the view's columns. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES (Strict) — self-review posted as COMMENT (GitHub blocks a verdict on your own PR)
Status: all round-2 findings and the reopened Behat thread are addressed in c1210b35, fcb69854, efb21af7, 792be9d1, 412bd4b5, 7ccf9726, 8ea10023, after three pre-push checks (the last clean); all threads are resolved. The fixes also make the object shape JSON-only for now (a 400 for XML; an XML serialization follows on its own branch). phpunit 743/743, Behat
@rows14/14. A re-review decides the verdict.
Round 1's fixes hold: 8 of 11 findings are addressed and the decision on the key type holds. The Behat scenario covers only part of what was asked, so its thread is reopened, and round 2 adds 2 🟡, both claims the fixes made that are false on the main path. Under Strict a 🟡 blocks. The fixes follow as new commits on this branch.
| Round | Found | Status |
|---|---|---|
1 (32e3676a) |
🟡 4 · 🟢 7 | 9 resolved, f8 kept by decision; the Behat thread reopened (partly addressed) |
2 (ff1ce2d3), this review |
🟡 2 | open |
| Finding | Was | Now | Where |
|---|---|---|---|
| Behat scenario covers a table only, no view, datetime, link or relation | 🟢 → 🟡 | partly addressed, reopened | thread |
| 🟡 findPage copies the column map per row again, and adds a per-row filter to every api/2 listing | new | new | thread |
| 🟡 @self times cannot be used 'as they are' in the createdAt/updatedAt filters | new | new | thread |
Details of this round
- Scope: the fix commits
245f4e92,b302685b,ff1ce2d3(32e3676a..ff1ce2d3, 14 files, 404 lines). - Verified clean: The cells shape (
jsonSerialize,dataByAlias) is byte-for-byte unchanged; the frontend and API v1 listings now share one column map;@selfkeys, nullable types and openapi match;findUuidsByIdshas no other callers; the daylight-saving gap is pinned. - Partly addressed, not reopened: The time-only subtype of the datetime branch is still untested (harmless: only a warning would change).
- Checks on this head: phpunit 721/721, Behat APIv2
@rows13/13, psalm, cs and rector clean; CI php-cs, openapi and stylelint green, the rest queued. Gates: the runner is not available for this repo, so the repo's own checks stand in. - Connected issues: nextcloud#3096 (open); depends on nextcloud#3095 (#63) and nextcloud#3093, both open.
The counts steer the next round: fix rules ON — 9 of 10 round-2 findings across #65 and #66 were introduced by the fixes (1 copy missed), so every round-3 fix goes through the class sweep and a pre-push check that repeats until it comes back clean.
🤖 Generated with Claude Code
findPage attached the payload with every column of the table or view and then filtered each row, which gave every row its own copy of the column map and a per-row filter on every listing. The payload is now attached with only the returned columns, after the data of a request for metadata only is emptied, so the rows of one listing share one map. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
The object shape returns the @self times as ATOM in UTC, with +00:00, but the createdAt and updatedAt filters refused any offset, so a time taken from a response was a bad request. A time that ends in Z or an offset of at most 14 hours is now converted to UTC, in which the meta fields are stored, and compared without it. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
A Behat scenario lists a table with a datetime, a time, a link and a relation column in the object shape, and a view of it with two of these columns. It checks the offset of the datetime, the link object, the uuid of the relation target, null for empty cells, the uuid in @self and that each object holds exactly the columns of the table or view. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
OCS renders a key that starts with @ as an XML attribute, so the @self block of the object shape made every XML response a 500. Until the object shape has an XML form, a request for it is refused with a 400 when the response would be XML, which OCS gives unless the format parameter or else the Accept header asks for JSON. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
The offset pattern accepted up to 14:59; the largest offset in use is +14:00, so anything beyond it is refused. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
A + in a query string reads as a space, so the offset of a time taken from @self has to be written as %2B there. The 400 of a single row also covers an unknown shape and the object shape for a response that is not JSON. Refs nextcloud#3096 Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
rjzondervan
left a comment
There was a problem hiding this comment.
Verdict: APPROVE (Strict, round-3 convergence) — self-review posted as COMMENT (GitHub blocks a verdict on your own PR)
Round 3 finds nothing new: all three round-2 points hold on the code and the delta adds no finding. Nothing stands between this PR and a merge. Its stopgap makes the object shape JSON-only for now; an XML serialization follows on its own branch.
| Round | Found | Status |
|---|---|---|
1 (32e3676a) |
🟡 4 · 🟢 7 | 10 resolved, the key type kept by decision |
2 (ff1ce2d3) |
🟡 2, Behat thread reopened | all resolved |
3 (8ea10023), this review |
— | nothing new |
| Finding | Was | Now | Where |
|---|---|---|---|
| findPage copies the column map per row again | 🟡 | addressed: one map per listing, refcount test | thread |
@self times not usable in the createdAt/updatedAt filters |
🟡 | addressed: Z and offsets up to ±14:00 converted to UTC; values without an offset reach the database unchanged | thread |
| Behat covers only a table | 🟡 | addressed: a table with datetime, time, link and relation, and a view, in the object shape | thread |
Details of this round
- Scope:
ff1ce2d3..8ea10023, seven commits (12 files), after three pre-push checks. - Verified clean: the offset conversion cannot change what an existing filter returns (none of the previously accepted formats ends in
Zor±HH:MM); the XML stopgap refuses exactly what OCS would have answered in XML, so no JSON client is refused (Accept: application/jsonwithoutformatpasses); the refcount test is robust on PHP 8.2+ and fails on per-row copies; the cells shape is unchanged. - Non-blocking notes:
getRows' "400:" line does not name the JSON-only refusal the waygetRow's does; the Behat datetime expectation assumes the test server has nodefault_timezone. Both can go with the XML branch. - Checks on this head: phpunit 743/743, Behat APIv2
@rows14/14, psalm, cs and rector clean, openapi up to date. Gates: the runner is not available for this repo, so the repo's own checks stand in. - Connected issues: nextcloud#3096 (open; part 1 of 2, closed by #66); depends on nextcloud#3095 (#63) and nextcloud#3093, both open.
🤖 Generated with Claude Code
Internal review draft. This PR exists only to run the review skills on the fork before the upstream PR is opened. The base
review-base/3096isfeat/3095/row-listingat 6055296 (the head of #63, which includes main b195670), so the diff shows only this PR's own commits. The upstream PR description will be written separately.Part 1 of 2 of nextcloud#3096, split from #64: this PR reads rows as objects, #66 writes them. Depends on nextcloud#3095 (#63) and nextcloud#3093.
Changes
?shape=objectonGET /api/2/{tables|views}/{nodeId}/rowsand/rows/{rowId}returns one flat object per row, with a property for every column the row is read with (narrowed byfieldsand the view), keyed by the column's technical name (column_{id}without one) andnullwithout a value.cellsstays the default; an unknown shape is a 400. The object shape is JSON-only for now: requested as XML (format=xml, an XMLAcceptheader, or neither) it is a 400; an XML serialization follows on its own branch.@self:id(the row uuid),rowId,tableId,createdBy,createdAt,updatedBy,updatedAt, with the times in UTC as stored (…+00:00), so they can be used as they are, offset included, in thecreatedAt/updatedAtfilters of feat(rows): list rows on api/2 with filter, sort, search and paging #63 (in a query string+is written%2B). A column can never replace@self.default_timezone(newInstanceTimezone, falls back to UTC); a time in a daylight-saving gap reads as the moment after the jump. Links are{title, url, providerId}.nullwhen the target no longer exists. The targets are loaded in one chunked query (RowSleeveMapper::findUuidsByIds, which givesnullfor an existing row without a uuid).Row2carries the columns of its alias payload;findPageattaches only the returned columns, shared by the rows of one listing, so the serializer needs no column query of its own.RowQueryResolver: thecreatedAt/updatedAtfilters accept a time ending inZor an offset up to ±14:00 and convert it to UTC.RowShape,RowObjectSerializer, response typesTablesRowObject,TablesRowObjectPageand their parts; openapi.json and openapi.ts regenerated.Checks run locally
APIv2.feature @rows14/14 (incl. the two object-shape scenarios: a table and a view, with datetime, time, link and relation columns), psalm, cs and rector clean, openapi.json and openapi.ts regenerate without a diff.🤖 Generated with Claude Code