[Bug]: Misleading documentation on Middleware::afterException() return type

[donquixote]

⚠️ This issue respects the following points: ⚠️

• [X] This is a bug, not a question or a configuration/webserver/proxy issue.
• [X] This issue is not already reported on Github (I've searched it).
• [X] Nextcloud Server is up to date. See Maintenance and Release Schedule for supported versions.
• [X] Nextcloud Server is running on 64bit capable CPU, PHP and OS.
• [X] I agree to follow Nextcloud's Code of Conduct.

Bug description

The documentation on OCP\AppFramework\Http\Response\Middleware::afterException() has mixed information about whether it may return NULL.

    /**
     * This is being run when either the beforeController method or the
     * controller method itself is throwing an exception. The middleware is
     * asked in reverse order to handle the exception and to return a response.
     * If the response is null, it is assumed that the exception could not be
     * handled and the error will be thrown again
     *
     * @param Controller $controller the controller that is being called
     * @param string $methodName the name of the method that will be called on
     *                           the controller
     * @param \Exception $exception the thrown exception
     * @throws \Exception the passed in exception if it can't handle it
     * @return Response a Response object in case that the exception was handled
     * @since 6.0.0
     */
    public function afterException($controller, $methodName, \Exception $exception) {
        throw $exception;
    }

The doc text suggests that NULL is allowed.

     * If the response is null, it is assumed that the exception could not be
     * handled and the error will be thrown again

But the return type declaration says only Response is allowed:

     * @throws \Exception the passed in exception if it can't handle it
     * @return Response a Response object in case that the exception was handled

The MiddlewareDispatcher::afterException() will break if the middleware returns NULL:

    public function afterException(Controller $controller, string $methodName, \Exception $exception): Response {
        for ($i = $this->middlewareCounter - 1; $i >= 0; $i--) {
            $middleware = $this->middlewares[$i];
            try {
                return $middleware->afterException($controller, $methodName, $exception);
            } catch (\Exception $exception) {
                continue;
            }
        }
        throw $exception;
    }

Steps to reproduce

1. Write your own class extending OCP\AppFramework\Http\Response\Middleware, and use it.
2. Let afterException() return NULL, as might be allowed when looking at the wrong part of the documentation.

Expected behavior

MiddlwareDispatcher will skip the middleware.

Actual behavior

TypeError: OC\AppFramework\Middleware\MiddlewareDispatcher::afterException(): Return value must be of type OCP\AppFramework\Http\Response, null returned

Installation method

None

Operating system

None

PHP engine version

None

Web server

None

Database engine version

None

Is this bug present after an update or on a fresh install?

None

Are you using the Nextcloud Server Encryption module?

None

What user-backends are you using?

• [ ] Default user-backend (database)
• [ ] LDAP/ Active Directory
• [ ] SSO - SAML
• [ ] Other

Configuration report

No response

List of activated Apps

(This is not really relevant, but here you go)

Enabled:
  - activity: 2.17.0
  - circles: 25.0.0
  - cloud_federation_api: 1.8.0
  - comments: 1.15.0
  - contactsinteraction: 1.6.0
  - dashboard: 7.5.0
  - dav: 1.24.0
  - federatedfilesharing: 1.15.0
  - federation: 1.15.0
  - files: 1.20.1
  - files_pdfviewer: 2.6.0
  - files_rightclick: 1.4.0
  - files_sharing: 1.17.0
  - files_trashbin: 1.15.0
  - files_versions: 1.18.0
  - firstrunwizard: 2.14.0
  - groupfolders: 13.1.0
  - logreader: 2.10.0
  - lookup_server_connector: 1.13.0
  - nextcloud_announcements: 1.14.0
  - notifications: 2.13.1
  - oauth2: 1.13.0
  - password_policy: 1.15.0
  - photos: 2.0.1
  - privacy: 1.9.0
  - provisioning_api: 1.15.0
  - recommendations: 1.4.0
  - related_resources: 1.0.3
  - serverinfo: 1.15.0
  - settings: 1.7.0
  - sharebymail: 1.15.0
  - support: 1.8.0
  - survey_client: 1.13.0
  - systemtags: 1.15.0
  - text: 3.6.0
  - theming: 2.0.1
  - twofactor_backupcodes: 1.14.0
  - updatenotification: 1.15.0
  - user_status: 1.5.0
  - viewer: 1.9.0
  - weather_status: 1.5.0
  - workflowengine: 2.7.0
  - workspace: 1.3.1
Disabled:
  - admin_audit
  - bruteforcesettings
  - encryption
  - files_external
  - suspicious_login
  - twofactor_totp
  - user_ldap

Nextcloud Signing status

No response

Nextcloud Logs

No response

Additional info

No response

[donquixote]

Solution

I see two options:

1. Fix the doc comment and make sure that NULL is not allowed.
2. Allow NULL, and support it in MiddlwareDispatcher. Perhaps this would need changes in more code places.

[donquixote]

Btw, I don't know if "Bug report" was correct here, but it seemed like the least wrong option.

[donquixote]

Context

One of the apps I use has a middleware that indeed returns NULL. I will communicate with the authors separately, no need to go into detail here.

[joshtrichards]

Cc: @ChristophWurst