Skip to content

feat(contexts): give applications a menu with its own API - #3135

Open
rubenvdlinde wants to merge 23 commits into
feat/noid/grid-pages-apifrom
feat/noid/app-menu-model
Open

rubenvdlinde wants to merge 23 commits into
feat/noid/grid-pages-apifrom
feat/noid/app-menu-model

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Part of the stack on #3133. Implements the menu proposal on #3100: the model and the API. Export and import follow in #3138. This replaces the earlier version of this pull request, together with #3136 and #3137.

Size: 3374 lines: 915 code, 434 tests, 2017 generated OpenAPI and 8 version.

Agreed on #3100

  • No technical name on menu items. An export refers to an item's group by its position in the exported menu.
  • Three target columns (page_id, node_rel_id, url), of which at most one is set. The service enforces it; the rule is in the entity docblock.
  • Remnants: deleting a target removes its menu items in the same transaction; creating or changing an item checks its target in its own transaction; reading still leaves out an item whose target is missing, as a safety net. No background job.
  • Empty groups stay in the data. Editors see them, readers without manage access don't.
  • The routes sit under the application, like the other application routes: /api/2/contexts/{contextId}/menu.

What changes

  • A menu item opens at most one thing: a page of the application ({pageId}), a table or view of the application by its node relation ({nodeRelId}), or an http or https link ({url}). An item that opens nothing is a group. Groups are top-level and only groups hold items, so a menu is one level deep.
  • An item without a title shows the title of what it opens: the page, the table or view, or the link. The start page without a title shows the name of the application. The API returns both title (as stored) and displayTitle.
  • Every application gets one item, without a title, for its start page: a migration adds it to existing applications, and creating or importing an application adds it too. It's an ordinary item.
  • Cleanup: an item goes with its target, in the same transaction: when its page is deleted, when its table or view leaves the application (through the application's nodes, a scheme import, or because the table or view is deleted, also with its owner), and with the application. The items of a deleted group move to the top level.
  • At most 200 items per application.
  • The application response stays as it is on main. Permission checks and the application response don't load the menu.
  • Endpoints on api/2, with #[ApiRoute]:
    • GET /api/2/contexts/{contextId}/menu returns the menu as a flat list in display order, with parentId
    • POST /api/2/contexts/{contextId}/menu adds an item to the end: title, icon, description, target
    • PATCH /api/2/contexts/{contextId}/menu/{itemId} changes an item; a target replaces the previous one, a group that holds items can't get one
    • DELETE /api/2/contexts/{contextId}/menu/{itemId} deletes an item
    • PUT /api/2/contexts/{contextId}/menu/order takes items: [{id, parentId}] in display order. It lists every item exactly once, a parent is a top-level group listed before its items, and it saves all of it or nothing ("changed in between, reload"). It returns the whole menu, and saves the order in one query.
  • Versions: GET /menu returns an ETag, and the order save needs it in If-Match. A stale version gives a 409, a missing If-Match a 400. Response bodies don't change.
  • Permissions: reading needs read access, changes need manage access, checked once through the item's application. Outsiders and items of another application get a 404, also when the item is reached through an application the user does manage, readers who try a change a 403, a target outside the application a 400. #[RequirePermission] covers every endpoint.
  • Titles, descriptions, icons and links go through the same shared helpers as pages and widgets (TextHelper for text): blanks at either end, including no-break and zero width spaces, are trimmed.
  • Rate limits with #[UserRateLimit]: 20 a minute on every menu write.
  • The app version goes to 2.5.0-dev.3.

How it was tested

After the reviews, on Nextcloud 34 with PostgreSQL:

  • MenuServiceTest against the database: the start page item of a new application, title fallback for every kind of target, invalid items (data provider), at most one target, empty groups hidden from readers, the 200-item cap, PATCH semantics, a group with items can't get a target, order and grouping, deleting a group, invalid orders that save nothing (data provider), cleanup with the page, the node and the application, a dangling item left out, only managers change the menu (data provider), and an item not found through another application
  • MenuControllerTest: arguments passed on and every error mapped to its status (data providers)
  • the full unit suite on this branch: 628 tests
  • psalm and php-cs-fixer, clean; OpenAPI regenerated and in step with the code

By hand on a test instance (Nextcloud 34, PostgreSQL), through the API, 18 checks, all as expected:

  • a new application has one item, for its start page; GET /api/2/menu is gone (404)
  • add a group, a link, the table (titled after it) and a page item whose title is only no-break and zero width spaces, which counts as no title; a target outside the application gives a 400
  • change an item, and put the link in the group with an order
  • an item changed or deleted through another application the user manages: 404
  • a reader reads the menu and gets a 403 on add and change; someone outside the application gets a 404
  • deleting the group moves its item to the top; deleting a page removes its item

🖼️ Screenshots

Backend only, no UI changes.

🏁 Checklist

  • ⛑️ Tests (unit and/or integration) are included or not needed
  • 🔙 Backport requests are created or not needed: /backport to stableX.X
  • 📅 Milestone is set
  • 🌸 PR title is meaningful (if it should be in the changelog: is it meaningful to users?)

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

@rubenvdlinde
rubenvdlinde added this pull request to stack #3139 October 22, 2026 11:42
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch from 9847aa9 to 5825db2 Compare October 22, 2026 13:25
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch from 5825db2 to 9e81a78 Compare October 23, 2026 08:05
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch 2 times, most recently from 7e236cc to c7a6e95 Compare October 26, 2026 09:24
@rubenvdlinde
rubenvdlinde marked this pull request as ready for review October 26, 2026 09:25
return null;
}

$table = $schema->createTable(self::TABLE);

@enjeck enjeck Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could we add the menu's data model to #3100 first, so we agree on it like we did for pages and widgets? #3099 only describes a menu of pages like a start page item that people can rename, move or remove. Items for tables, views and links are new to me

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done. The proposal is on #3100 and blizzz has answered it. This PR is rebuilt on that proposal: one table, tables_contexts_menu_item, created by a single migration.

$table->addColumn('icon', Types::STRING, ['notnull' => false, 'length' => 64]);
$table->addColumn('description', Types::TEXT, ['notnull' => false]);
$table->addColumn('target_type', Types::STRING, ['notnull' => true, 'length' => 16]);
$table->addColumn('target_id', Types::INTEGER, ['notnull' => false]);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could menu items use node_rel_id, like widgets? Then removing a table can also remove its menu item

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes. A table or view item now points at its node_rel_id. When the table or view leaves the application, its items are removed in the same transaction as its widget sources.

Comment thread lib/Db/ContextMapper.php Outdated
}

return $this->formatResultRows($r, $userId);
return $this->formatResultRows($r, $userId, $this->menuItemMapper->findByContextIds([$contextId]));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Permission checks use findById(), so each check now runs this menu query for no reason. Maybe should be conditional

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks, that query is gone. The menu is no longer loaded with the application. It has its own endpoint, GET /api/2/menu?contextId=, so findById() and the permission checks don't touch it at all.

Comment thread lib/Service/ContextService.php Outdated
Comment on lines +368 to +373
// Deleting the application first takes the write lock before anything is read, so on
// SQLite a concurrent write fails this transaction at once and the retry runs it again.
$this->atomicRetry(function () use ($context): void {
$this->contextMapper->delete($context);
$this->shareService->deleteAllForContext($context);
$this->menuItemMapper->deleteAllByContextId($context->getId());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

should this be in a different PR?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes. That change came out of this PR. All that's left in ContextService is what the menu needs: a new application gets one item for its start page, and deleting an application or one of its tables or views removes the items that open it.

@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch from f8caaaa to e311b8c Compare November 19, 2026 13:36
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch from e311b8c to 7d1eec4 Compare November 20, 2026 10:53
@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

On the points from the review summary: #3211 and #3212 already use dev.1 and dev.2 and land before the menu, so the menu is now 2.5.0-dev.3 and its migration runs on instances that are on either of them. They're one helper now that takes the noun, used by pages, widgets and menu items, so the rule and the message live in one place. The chunk size is a DB_CHUNK_SIZE constant on MenuItemMapper, every menu write is rate limited at 20 a minute, and on the tests: both are covered now: the 200th item is accepted before the 201st is refused, and an order entry whose group isn't in the list is refused.

cc @blizzz

rubenvdlinde and others added 23 commits November 21, 2026 11:53
An application gets a menu of items. An item opens at most one thing: a
page of the application, a table or view of the application by its node
relation, or an http or https link. An item that opens nothing is a
group; groups are top-level and only groups hold items, so a menu is one
level deep. An item without a title shows the title of what it opens.
An item has no technical name of its own. A menu holds at most 200
items.

The menu has its own endpoints on api/2: GET /menu?contextId= returns the
menu as a flat list in display order, POST /menu adds an item to the
end, PATCH and DELETE /menu/{itemId} change or delete one item, and
PUT /menu/order saves the order and grouping of the whole menu in one
transaction. Reading needs read access to the application and changes
need manage access, checked once through the item's application.
Outsiders get a 404, readers who try a change a 403 and a target outside
the application a 400. Create is limited to 20 a minute per user, a
change or an order to 60.

Of the three target columns (page, node relation, link) at most one is
set, which the service enforces. Creating or changing an item checks its
target in the transaction that saves it. Empty groups stay in the menu;
readers without manage access don't see them.

A new application gets one item, without a title, for its start page.
An item goes when its target goes, in the same transaction: with its
page, when its table or view leaves the application or is deleted, and
with the application. The items of a deleted group move to the top
level. An item whose target is gone anyway is left out when the menu is
read. Applications that exist today have no items and open their start
page.

Co-authored-by: remko48 <remko@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>
- menu item titles and descriptions follow TextHelper, like pages and widgets, so
  one rule and one pair of limits covers all three
- the migration step sorts after the steps of #2476 and of the grid pages stack
- tests follow the page service, which no longer checks permissions itself

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
A menu item could be added to an application while it was deleted and stay
behind, and the menu's rules were checked on reads another write could change.
Creating, changing, deleting and ordering items now lock the application as
their first statement, which on SQLite also takes the write lock first.

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>
Existing applications get the start page item from the migration, an
imported application gets it with its pages, and an item added to a
menu without any item comes after it.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…one order

An application loses its menu last, just before its own row, and both
node removals delete widget sources, page contents, menu items and then
the relation.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…helper

Pages, widgets and menu items name what a text belongs to and share the
rule and the message.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
A menu link is parsed with parse_url(), needs a host and a scheme link
cells allow, so internationalized domains, non-ASCII paths and hosts
with an underscore work. Both compare the scheme without case.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…controller

The controller turns them into MenuTarget and MenuOrderEntry and answers
400 for a wrong shape, including an object where a list is expected, so
the service only checks what depends on the application.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
GET, the order save and the item lookup use one rule, so an item whose
table or view cannot be found is left out of all of them and a menu saved
as GET returned it goes through.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…ttributes

The service no longer checks manage permissions a second time, loads the
application once per request, and the order save answers from the items
it saved. A controller test checks the permission attribute of every
route.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
GET /menu sends the version of the order and grouping as ETag, and the
order save takes it back as If-Match. The save compares it under the
application lock, so a stale list gets 409 whatever changed in between,
and the answer carries the new ETag. The response body keeps its shape.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…checked

create() and update() lock the node relation of their target right after
the application, so a removal of that table or view either ends first and
the item is refused, or waits and takes the item with it.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…plication

clearParent() filters on the application, so it uses its index, and it
only runs when the deleted item is a group. The mapper chunks with a
named constant.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
The order save runs one UPDATE for each item whose position or group
changed, and nothing for an unchanged order. The redundant checks for
updated fields are gone, as the mapper skips an unchanged entity itself.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
destroy() gets the limit the other writes have, and the order save and
the item update go from 60 to 20 per minute.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
create() and update() take the TablesMenuTarget union the response uses,
so a typed client passes {pageId}, {nodeRelId} or {url} as it is. The
spec also gains the ETag and If-Match of the menu order and its 409.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
#3211 and #3212 take 2.5.0-dev.1 and 2.5.0-dev.2 and land first, so the
menu migration runs on instances already on either of them.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…or Psalm

Psalm refused the menu and order responses because the ETag passed to the
constructor typed the headers as required while the documented union makes
them optional; the header is now added to the response. The node relation
a menu item opens is read into a local before it is locked, so its type is
an int.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
… the menu item mapper

The test of a write to a page of an application that is gone built the page
service without the menu item mapper it now takes, and checks that no menu
item is touched either.

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>
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/app-menu-model branch from 7d1eec4 to 52f43fc Compare November 21, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants