Skip to content

feat(rows): read rows as objects on api/2 with ?shape=object - #65

Draft
rjzondervan wants to merge 11 commits into
review-base/3096from
feat/3096/1-object-read
Draft

rjzondervan wants to merge 11 commits into
review-base/3096from
feat/3096/1-object-read

Conversation

@rjzondervan

@rjzondervan rjzondervan commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

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/3096 is feat/3095/row-listing at 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=object on GET /api/2/{tables|views}/{nodeId}/rows and /rows/{rowId} returns one flat object per row, with a property for every column the row is read with (narrowed by fields and the view), keyed by the column's technical name (column_{id} without one) and null without a value. cells stays the default; an unknown shape is a 400. The object shape is JSON-only for now: requested as XML (format=xml, an XML Accept header, or neither) it is a 400; an XML serialization follows on its own branch.
  • The metadata is in @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 the createdAt/updatedAt filters 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.
  • Datetime cells carry the offset of the instance's default_timezone (new InstanceTimezone, falls back to UTC); a time in a daylight-saving gap reads as the moment after the jump. Links are {title, url, providerId}.
  • Relations are the uuid of the target row; its row id while the target has no uuid yet (the backfill job of UUIDs for rows nextcloud/tables#3093 has not reached it); null when the target no longer exists. The targets are loaded in one chunked query (RowSleeveMapper::findUuidsByIds, which gives null for an existing row without a uuid).
  • Row2 carries the columns of its alias payload; findPage attaches only the returned columns, shared by the rows of one listing, so the serializer needs no column query of its own.
  • This PR also changes feat(rows): list rows on api/2 with filter, sort, search and paging #63's RowQueryResolver: the createdAt/updatedAt filters accept a time ending in Z or an offset up to ±14:00 and convert it to UTC.
  • New RowShape, RowObjectSerializer, response types TablesRowObject, TablesRowObjectPage and their parts; openapi.json and openapi.ts regenerated.

Checks run locally

  • On this head: phpunit 743/743, Behat APIv2.feature @rows 14/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

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>
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/ResponseDefinitions.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved
Comment thread lib/ResponseDefinitions.php Resolved

@rjzondervan rjzondervan left a comment •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 @rows 13/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, @self times that #63's filters can take back, relation uuids, and @self that a column can never replace. The fixes follow as new commits on this branch.

🟡 Concerns

🟢 Minor

✅ 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.

  • findUuidsByIds reads in chunks of DB_CHUNK_SIZE, skips rows without a uuid and is tested against the database.

  • An unknown shape is 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) against review-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

rjzondervan and others added 3 commits November 18, 2026 14:47
- 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>
Comment thread lib/Service/RowService.php Resolved
Comment thread lib/Service/RowObjectSerializer.php Resolved

@rjzondervan rjzondervan left a comment •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 @rows 14/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; @self keys, nullable types and openapi match; findUuidsByIds has 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 @rows 13/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

rjzondervan and others added 7 commits November 19, 2026 10:11
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 rjzondervan left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Z or ±HH:MM); the XML stopgap refuses exactly what OCS would have answered in XML, so no JSON client is refused (Accept: application/json without format passes); 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 way getRow's does; the Behat datetime expectation assumes the test server has no default_timezone. Both can go with the XML branch.
  • Checks on this head: phpunit 743/743, Behat APIv2 @rows 14/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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant