Add OpenAPI

[provokateurin]

☑️ Resolves

Adds all the utilities and annotations required for OpenAPI.

🏁 Checklist

• ⛑️ Tests (unit and/or integration) are included or not required
• 📘 API documentation in docs/ has been updated or is not required
• 📗 User documentation in https://github.com/nextcloud/documentation/tree/master/user_manual/talk has been updated or is not required
• 🔖 Capability is added or not needed

[provokateurin]

I remember seeing a psalm failure with not enough memory at some point, I believe it's a memory leak that nukes psalm. Just giving it more ram didn't fix it, although I don't have this problem locally 🤔

[nickvergessen]

Psalm breakage is not acceptable.
Also locally it does no longer finish and runs out of memory after allocating 8GB !

[provokateurin]

Rebased on master to resolve conflicts and check if newer psalm version fixes the memory crash. Psalm still works perfectly on my machine 🤷‍♀️

[provokateurin]

Ok here are my investigation results:

1. Reproducing sucessfully on clean ubuntu:jammy and debian:bookworm docker images -> No ubuntu specific problem
2. Installed PHP 8.2 on ubuntu:jammy -> No PHP 8.1 specific problem
3. Reproducing successfully on a clean archlinux:latest docker image -> No non-ArchLinux specific problem
4. Copied my php.ini into the archlinux:latest docker image and the problem is still reproducible.

I will update this comment when I have new findings.

[nickvergessen]

I found out, that even with old dependencies the problem existed.

So I rebased this PR and turned around the stuff:

1. set up CI, dependency, etc.
2. then the doc modifications

Turns out, after 1 psalm still worked, but not after 2

So I started a git bisect:

$ git bisect log
git bisect start
# status: waiting for both good and bad commits
# good: [152a2cd9e04015eb0273ba77e128ea3ca69df1a3] Add OpenAPI CI
git bisect good 152a2cd9e04015eb0273ba77e128ea3ca69df1a3
# good: [152a2cd9e04015eb0273ba77e128ea3ca69df1a3] Add OpenAPI CI
git bisect good 152a2cd9e04015eb0273ba77e128ea3ca69df1a3
# bad: [8bb03633903b7b9d0b0550545858d2e06f38e6ae] Add annotations for PollController
git bisect bad 8bb03633903b7b9d0b0550545858d2e06f38e6ae
# good: [a7527f2ca7a812bece1944d4b573ebcafd56de29] Add annotations for ChatController
git bisect good a7527f2ca7a812bece1944d4b573ebcafd56de29
# good: [4cfc169c02f47418d79763e2da2c48dbed9da628] Add annotations for GuestController
git bisect good 4cfc169c02f47418d79763e2da2c48dbed9da628
# bad: [81588e0c022112ab054bb55cd420a47b199c0132] Add annotations for MatterbridgeController
git bisect bad 81588e0c022112ab054bb55cd420a47b199c0132
# good: [5c8a9f3b46980ee02ca3b13b0bbff11b01bc0b56] Add annotations for HostedSignalingServerController
git bisect good 5c8a9f3b46980ee02ca3b13b0bbff11b01bc0b56
# first bad commit: [81588e0c022112ab054bb55cd420a47b199c0132] Add annotations for MatterbridgeController

So I had a look at that commit and found the problem:
https://github.com/nextcloud/spreed/pull/10186/files#diff-4489f22fe309430bc8a3e0cc90a0410de61dd9b7b231d5b6f8680310f3b75ad5R59

	 * @return DataResponse<Http::STATUS_OK, SpreedMatterbridge&SpreedMatterbridgeProcessState, array{}>

from getBridgeOfRoom fixes the memory issue.

After some testing the following patch also fixes it:

diff --git a/lib/Controller/MatterbridgeController.php b/lib/Controller/MatterbridgeController.php
index 65e15eb1f..aac46265a 100644
--- a/lib/Controller/MatterbridgeController.php
+++ b/lib/Controller/MatterbridgeController.php
@@ -40,6 +40,7 @@ use OCP\IRequest;
  * @psalm-import-type SpreedMatterbridge from ResponseDefinitions
  * @psalm-import-type SpreedMatterbridgeParts from ResponseDefinitions
  * @psalm-import-type SpreedMatterbridgeProcessState from ResponseDefinitions
+ * @psalm-import-type SpreedMatterbridgeWithProcessState from ResponseDefinitions
  */
 class MatterbridgeController extends AEnvironmentAwareController {
 
@@ -56,7 +57,7 @@ class MatterbridgeController extends AEnvironmentAwareController {
        /**
         * Get bridge information of one room
         *
-        * @return DataResponse<Http::STATUS_OK, SpreedMatterbridge&SpreedMatterbridgeProcessState, array{}>
+        * @return DataResponse<Http::STATUS_OK, SpreedMatterbridgeWithProcessState, array{}>
         */
        #[NoAdminRequired]
        #[RequireLoggedInModeratorParticipant]
diff --git a/lib/ResponseDefinitions.php b/lib/ResponseDefinitions.php
index 49b82c41a..664aa7284 100644
--- a/lib/ResponseDefinitions.php
+++ b/lib/ResponseDefinitions.php
@@ -209,6 +209,8 @@ namespace OCA\Talk;
  *     running: bool,
  * }
  *
+ * @psalm-type SpreedMatterbridgeWithProcessState = SpreedMatterbridge&SpreedMatterbridgeProcessState
+ *
  * @psalm-type SpreedSignalingSettings = array{
  *     helloAuthParams: array{
  *         "1.0": array{

[nickvergessen]

So now that we are able to solve the problem, I will take over and migrate the responses to the expected namespace and see where we can simply the things.

[provokateurin]

Thanks for the debugging. The openapi-extractor still doesn't support reading the namespace as per nextcloud/openapi-extractor#11

[provokateurin]

Since this PR there have been a few fixes in openapi-extractor, so please upgrade it to the latest version before continuing.
It would be nice if I could reviewyour changes as well, since this whole thing is quite complex.

[nickvergessen]

The openapi-extractor still doesn't support reading the namespace as per nextcloud/openapi-extractor#11

Neither the version it seems (locking 0.0.1 while talk is at 18.0…). Will try to have a look

[provokateurin]

The version field does not indicate the version of the software but the version of the document instead. This is a common misconception, but the right way to do it (until I've found a better solution)

[nickvergessen]

The version field does not indicate the version of the software but the version of the document instead.

Okay, so it updates automatically everytime something changes? Or is hardcoded? Because it should reflect to breaking changes (api removed), etc I guess?

[nickvergessen]

After aligning with Kate in the chat, I squashed the fixups, kept my changes in individual commits for easier retrospective and rebased it.
So we can merge it and rebase all open PHP PRs