Repository navigation
feat(api): pages and widgets on api/2 - #3133
rubenvdlinde wants to merge 16 commits into
Conversation
0511a8e to
d522080
Compare
d522080 to
e97b9ea
Compare
e97b9ea to
daeab7e
Compare
daeab7e to
a812d77
Compare
a812d77 to
e241b46
Compare
e241b46 to
ba00142
Compare
ba00142 to
d87850f
Compare
d87850f to
25ed0cc
Compare
9d761d3 to
1d7e6ea
Compare
1d7e6ea to
a9d2b12
Compare
a9d2b12 to
6e06229
Compare
6e06229 to
e835e69
Compare
| #[NoAdminRequired] | ||
| #[RequirePermission(permission: Application::PERMISSION_READ, typeParam: 'context', idParam: 'contextId')] | ||
| #[ApiRoute(verb: 'GET', url: '/api/2/contexts/{contextId}/pages/{technicalName}', requirements: ['contextId' => '\d+', 'technicalName' => '[a-z][a-z0-9_]*'])] | ||
| public function showByTechnicalName(int $contextId, string $technicalName): DataResponse { |
There was a problem hiding this comment.
Done. Pages now have a slug everywhere: the column, the API, the route GET /pages/{slug} and the export. The slug is set when the page is added, page_<id> if none is given, and never changes afterwards: a PATCH with a different slug gets a 400, sending the current one is fine. Columns and views keep their technical name, that is a separate thing.
cc @blizzz
| #[UserRateLimit(limit: 20, period: 60)] | ||
| #[RequirePermission(permission: Application::PERMISSION_MANAGE, typeParam: 'context', idParam: 'contextId')] | ||
| #[ApiRoute(verb: 'POST', url: '/api/2/contexts/{contextId}/pages', requirements: ['contextId' => '\d+'])] | ||
| public function create(int $contextId, string $title, ?string $technicalName = null, ?string $icon = null, ?string $description = null): DataResponse { |
There was a problem hiding this comment.
another slug todo (there are more in this PR, I won't mention the others to avoid useless clutter)
There was a problem hiding this comment.
btw, does the naming fit? create() is broad, the doc speaks of a grid page only.
There was a problem hiding this comment.
All of them are renamed, here and in the PRs on top of this one, including the frontend, which now asks for a slug only when a page is added.
cc @blizzz
There was a problem hiding this comment.
Fair point, it only ever adds a grid page. It is now createGridPage() in the controller and the service. The route stays POST /pages.
cc @blizzz
blizzz
left a comment
There was a problem hiding this comment.
The adaption to slug is open as well as Andy's findings.
e835e69 to
e5184de
Compare
Read, add, change and delete grid pages with their widgets, and list the widget types with their settings schemas. Reading needs read access to the application, changes need manage access. Page creation is limited to 20 a minute per user. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
- every page has a version that each save raises as its first write; a save of the
widgets names the version it was edited from and gets a 409 when another save
raised it since, so two editors no longer undo each other without a word
- raising the version locks the page, so a save and a delete of the same page run
one after the other, and adding a page locks its application against a delete
- create, update and delete answer from what they wrote instead of loading the
application again; reads look up the page itself
- the controller's permission checks are the only ones, as for the other endpoints
- the start page accepts widgets from the start and can lose its title again; the
delete rule names the start page
- titles and descriptions follow TextHelper, so a title of invisible spaces is refused
- widget settings are stored as text, not as a JSON column, and come back as an array,
or as {} when empty, so XML keeps them and JSON shows an object
- the widget types answer {} for a type without settings
- the widgets parameter has a named shape in the OpenAPI spec
- deleting a page is rate limited like the other changes
- the database error stub moves here from the data model
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…ector asks Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…ge is added One lock for the application row, which also takes the write lock first on SQLite. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Page update() and delete() now take the application lock before they raise the page version, as create() already did. Every writer then locks application, page and relations in that order, so a save can no longer leave widgets behind after a concurrent delete of the application, and the two cannot deadlock. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…version Once the version check of a save passed, a widget id that is not on the page, or a source that is not part of the application, cannot come from another save, so it is a 400 that names it instead of a 409. The version in the answer is read on the locked page row inside the transaction, so a save without a version no longer answers with a stale one. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…s them Deleting a table or view, or removing one from an application, locks the rows of the applications that hold it before it touches widgets, page contents or node relations, in ascending id order. A page save and an application delete take the application first too, so they wait for each other instead of deadlocking. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…Page A page takes its slug when it is added and keeps it: a save that names another slug is refused with 400, the current slug is accepted. The create endpoint and service method are named createGridPage, as they add a grid page only; the route stays POST /pages. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
e5184de to
1ae1875
Compare
Part of #3099, on top of #3132 (widget lifecycle). This adds the five endpoints from #3100. They're routed with
#[ApiRoute]on the controller, like the newer public endpoints, soroutes.phpdoesn't change.Size: 4027 lines: 763 code, 530 tests, and 2734 generated OpenAPI (
openapi.jsonandopenapi.ts) in separate commits you can skip.GET /api/2/contexts/{contextId}/pages/{pageId}GET /api/2/contexts/{contextId}/pages/{slug}POST /api/2/contexts/{contextId}/pagescreateGridPage()PATCH /api/2/contexts/{contextId}/pages/{pageId}DELETE /api/2/contexts/{contextId}/pages/{pageId}GET /api/2/widget-typesGridWidgetTypes::readWidget(), the same reader the imports use, and its settings are checked against its type's schema. Unknown settings are dropped and missing ones get their default. Settings are stored as text. A widget id that belongs to another page gives a 400.sourceis{nodeRelId}of that application. Anything else is refused with a 400, with the same message whether the table doesn't exist or just isn't in the application.page_<id>. An invalid one, or one already used in the application, gives a 400, and so does a PATCH that changes it. The slug is a readable address for reads only; every change goes by page id.version, returned with it. A save of the widgets sends the version it was edited from; when another save raised it since, the answer is a 409, so two editors no longer undo each other. A save, a page delete and removing a table or view from the application first lock the application (in ascending id when there are several), so they run one after the other. This closes the races and deadlocks Andy and blizzz found.RequirePermission, as for the other endpoints. Someone outside the application gets a 404, so outsiders can't tell whether an application exists. Reading needs only read access, which every member has, so reading a page has no 403. The service checks that a page belongs to the application in the URL.OpenAPI and the TypeScript types are regenerated, in a separate commit.
Saving a page never changes what's in the application, so it can't give the application's sharees access to another table. To show a table that isn't in the application yet, add it to the application first.
How it was tested
After the reviews by Arthur and Andy, on Nextcloud 34 with PostgreSQL:
PageServiceTest: reads by id and by name, a page of another application not found, create with an automatic or given slug and a taken slug, blank and invisible titles refused, the start page losing its title again, a save with widgets answering with what it stored, a save without a version refused, a stale version a 409, a page deleted in the meantime a 404, invalid widgets refused before any write (data provider), and deletesContextPageControllerTest: every endpoint, and 400, 404 and 409; the widget types answer{}for a type without settingsWidgetServiceTest,GridWidgetTypesTestandTextHelperTestphp-cs-fixer, clean; OpenAPI regenerated and in step with the codeBy hand on a test instance (Nextcloud 34, PostgreSQL), through the API, 29 checks, all as expected:
{}for the data type, and the page in XML keeps its widget settingsIn the browser, with the frontend of #3215: while a page was open in edit mode, another save went through the API. Saving in the browser then showed "Someone else saved this page in the meantime. Reload it to see their changes, then make yours again.", the editor stayed open, and the other save was kept.
🖼️ Screenshots
Backend only, no UI changes. The frontend follows in separate pull requests; #3215 sends the page version.
🏁 Checklist
/backport to stableX.X🤖 AI (if applicable)