Implement an OCP API for Context Chat

[edward-ly]

How to use GitHub

• Please use the 👍 reaction to show that you are interested into the same feature.
• Please don't comment if you have no relevant information to add. It's just extra noise for everyone subscribed to this issue.
• Subscribe to receive notifications on status change and new comments.

Is your feature request related to a problem? Please describe.

The context_chat app PHP classes in the OCA\ContextChat\Public namespace as well as the ContentProviderRegisterEvent event are supposedly available for other apps to use. But since they are still under the app's private namespace, this is not exactly best practice and may cause dependency problems later down the road, when more and more apps will be implemented as context chat providers.

Describe the solution you'd like

Move the aforementioned classes to the server repository under the OCP\ContextChat namespace instead, and update the developer documentation accordingly.

Describe alternatives you've considered

(none)

Additional context

Some initial work was done for the Mail app but needs significant changes (note the UndefinedClass errors from Psalm):
nextcloud/mail#11150

cc @kyteinsky @marcelklehr @ChristophWurst

[marcelklehr]

Hey everyone,

I think it's ok to leave the APIs in the ContextChat namespace for the following reasons:

• We explicitly mark the used APIs as public in Context chat
• We commit to not break these APIs with updates
• There is precedent in Nextcloud for having inter-app dependencies with the Circles app, the Assistant app, the text app, the full text search apps, etc.

I see the following downsides to adding these APIs in server, now:

• Existing implementations need to be rewritten to use the new APIs
• new context chat integrations have to wait for nextcloud 32 to work

Which problems do you foresee by leaving things as they are?

[provokateurin]

We commit to not break these APIs with updates

With the same rules as OCP?

There is precedent in Nextcloud for having inter-app dependencies

Yes, and it's really bad. We should avoid it as much as possible and that we are already in this situation is not a justification for making it worse.

Existing implementations need to be rewritten to use the new APIs

You can make the OCA interface extend the OCP interface, then it's easy to migrate in other apps and you don't have duplicate and eventually out-of-sync code.

---

In my opinion we should have this in NCU first, as I have no idea how stable you are really going to make it. In general this might be the path we chose for every private API of apps: OCA -> NCU -> OCP

[come-nc]

Which problems do you foresee by leaving things as they are?

The API are not in nextcloud/ocp composer package, so the tooling of the apps, psalm and such, will not find the classes and complain. That means applications will have to use stubs instead.

It is indeed a recurring problem, quite frankly personaly I would be for allowing inter-app dependency and support it properly.
How do you manage it for context chat, how does a using application behaves if it’s not installed?

If we go this way you could have a nextcloud/context-chat-api or something to be used by depending applications the same way nextcloud/ocp is used.

[provokateurin]

If we go this way you could have a nextcloud/context-chat-api or something to be used by depending applications the same way nextcloud/ocp is used.

I think that would improve the current situation for apps like Circles, but we should not go this route for apps that could still be switched to have their interface in OCP.

[susnux]

We commit to not break these APIs with updates

Which would be in OCP: "3 years (9 Nextcloud releases)"

It is indeed a recurring problem, quite frankly personaly I would be for allowing inter-app dependency and support it properly.

This would be related to: #4531
I also like this idea but would need some way to at least get the stubs of that API - its already a mess with Circles / Teams.

[icewind1991]

I would rather have a generalized standard for app public api's (something like OCA\$appId\Public, or with attributes as described below) and generalized tooling for creating stubs etc for them.

Moving api's into OCP is a path not available/feasible for all applications (a set of inter-dependent 3rdparty apps that don't have widespread will probably not get their api's accepted into OCP).

[nickvergessen]

I think we should go "forward" and allow inter-app dependency when the app marks the class/app/method/interface/… with a #[OCP\AppFramework\Stable(since: $serverMajorVersionOrYYYY-MM, ?deprecated: $serverMajorVersionOrYYYY-MM, ?removal: $serverMajorVersionOrYYYY-MM)] attribute.

• Minimum required time between deprecation and removal is at least 3 Nextcloud Majors
• Heavy recommendation is 3 years like OCP
• Apps should(?) or must provide stubs similar to nextcloud-deps/ocp so apps can CI check compatibility with psalm/phpstan

I'm happy to draft the attribute and Demo it on Talk

[icewind1991]

👍 for using attributes, might also make sense to add similar ones to OCP instead of only have the @since etc

[icewind1991]

Separate from the "api stability" is the question around the dependency itself. We should probably have a way to mark those (info.xml seems most sensible), both for optional and required dependencies and display that properly in the app storage.

We can then automatically (after user confirmation) install any required app to prevent user confusion about why stuff isn't working after they enable an app.

[nickvergessen]

• On a related note I propose to split OCP into consumables and implementables: RFC: Split OCP into Consumable and Implementable to clarify intentions standards#15

[icewind1991]

I'll volunteer for looking into tooling to create stubs etc once we've settled on how to annotate things.

[provokateurin]

@icewind1991 I've already written some scripts to generate stubs and used it successfully in groupfolders and circles: https://github.com/provokateurin/php-stubs-updater