Extend reference API for (future) frontend picker

[julien-nc]

refs #31667

We forgot something in the specs: the fontend only knows the list of registered widgets to render references. We need more information for the available providers (title, icon etc...) to feed the reference picker. I can think of 2 ways to go:

• provide more information when registering the reference widget in the frontend (feels weird because widgets are just for rendering, the picker stuff should be independent)
• add a new "registerProvider" function to vue-richtext
• add an API endpoint to get info on the available providers

I went with the API endpoint. (Or did I miss something obvious?)

• 2 new interfaces:
  • IDiscoverableReferenceProvider for reference providers that can be discovered by the frontend
  • ISearchableReferenceProvider for discoverable ones that support search
• 1 new method to get those providers in ReferenceManager
• 1 new route/controller method

So, a reference provider can support multiple search providers. Thinking out loud: We need to be careful to properly render heterogeneous search results in the frontend.

[github-advanced-security]

Psalm found more than 10 potential problems in the proposed changes. Check the Files changed tab for more details.

[julien-nc]

Oh I forgot to mention: in the reference-discovery of integration_github those 2 new provider interfaces are implemented.

[julien-nc]

@juliushaertl Where can we listen to RenderReferenceEvent to provide the provider list as an initial state?

In other words, in server, where can we call (and where does it makes sense to call) IRegistrationContext::registerEventListener(RenderReferenceEvent::class, ...) ?

I've seen similar-ish stuff in lib/base.php but it didn't feel right/straightforward to put it there...

[juliushaertl]

Same feeling that there could be a better place but I also added one to base.php in the first PR:

server/lib/base.php

Line 927 in 052dcde

private static function registerFileReferenceEventListener() {

So maybe we just stick with that for now.

[julien-nc]

Thanks, gotta problem though. Just added 311527e

I don't know why but I can't inject IInitialState in the listener class. Server logs say:

Could not load event listener service OC\\Collaboration\\Reference\\RenderReferenceEventListener:
Could not resolve initialStateService! Class \"initialStateService\" does not exist. 
Make sure the class is auto-loadable by the Nextcloud server container

But initialStateService is just the name of the listener class attribute 🤔

I don't get why IReferenceManager can be injected just fine. I tried to use \OC::$server->get() in the listener's handle() method, same problem.

I also tried injecting \OCP\Server (which works) and then use it to get IInitialState. Slightly better error log message but still no luck:

Could not resolve OCP\\AppFramework\\Services\\IInitialState! Class can not be instantiated

Any idea?

[juliushaertl]

IInitialState is only available within an apps context through the apps DI container.

However you can inject the IInitialStateService directly e.g. as in

server/lib/private/Template/JSConfigHelper.php

Line 298 in 2d98cd1

$this->initialStateService->provideInitialState('core', 'config', $config);

[julien-nc]

@juliushaertl Thanks. Done, works.

I thought base.php was in the 'core' app context 😁.

I didn't try to inject IInitialStateService because it's deprecated. Any problem with that?

[juliushaertl]

I didn't try to inject IInitialStateService because it's deprecated. Any problem with that?

At least there is no replacement yet for core parts that need to inject initial state. And the new interface just wraps the deprecated, so while apps should use the new one, the deprecated one should still be fine within the affected core code base.

[julien-nc]

I don't get the remaining psalm check failure:

Error: lib/private/Collaboration/Reference/RenderReferenceEventListener.php:45:21: 
InvalidArgument: Incompatible types found for T 
(OCP\Collaboration\Reference\RenderReferenceEvent is not in OCP\EventDispatcher\Event)
(see https://psalm.dev/004)

It's fine for

server/lib/private/Collaboration/Reference/File/FileReferenceEventListener.php

Lines 42 to 44 in 4d04030

	$eventDispatcher->addServiceListener(NodeDeletedEvent::class, FileReferenceEventListener::class);
	$eventDispatcher->addServiceListener(ShareDeletedEvent::class, FileReferenceEventListener::class);
	$eventDispatcher->addServiceListener(ShareCreatedEvent::class, FileReferenceEventListener::class);

[julien-nc]

@juliushaertl This is ready for review IMO. Nothing more to add for now.

Some recent additions to this PR:

• a new OCS API endpoint to update the "last used timestamp" of a provider
• inject the provider timestamps with initial state on RenderReferenceEvent

[juliushaertl]

Pushed a fix for the psalm error

[julien-nc]

@marcelklehr @juliushaertl Thanks for the review.

[juliushaertl]

Rebased and squashed the fixup commits and updated the autoloader.

[nickvergessen]

Please document in #34692

[DaphneMuller]

hello @julien-nc
Thank you so much for your work on this pull request! This ticket seems to have the tag 'pending documentation'.
Is there any chance you could clarify what documentation is missing? Is this for admins or for app developers?

[DaphneMuller]

Hello!
Thank you for your work on this! I noticed that your PR still has the label 'documentation'. I'm not sure if you already had a look at the documentation for your PR, but at Nextcloud we strive to document changes that affect other app developers or other admins before the release takes place, and I'm pinging you with the hope to get this done.

Are you familiar with our documentation process already?
Changes that affect app developers should be documented here:
https://docs.nextcloud.com/server/27/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.html

Changes that affect administrators should be documented here:
https://docs.nextcloud.com/server/latest/admin_manual/release_notes/upgrade_to_27.html

While I understand sometimes it's handy to merge fast to get your changes in, it would be great if next time you could try to add the documentation before merging. You can find more information on that here:
https://docs.nextcloud.com/server/27/developer_manual/prologue/compatibility_app_ecosystem.html#documentation-procedures-of-changes-that-affect-app-developers

If all your documentation efforts are done, please remove the label 'pending documentation' and check the checkbox in your opening note and I'll stop bugging you :)

Many thanks in advance and thanks again for your work!