Web Host Metadata

RFC6415 defines how web hosts can expose their metadata through resources. Starting with Nextcloud 21, it’s possible to register handlers for HTTP requests to the .well-known/* route.

Writing a handler

A well known handler is a simple class that implements the \OCP\Http\WellKnown\IHandler interface.

<?php

declare(strict_types=1);

namespace OCA\MyApp\Http\WellKnown;

class Handler implements IHandler {

    public function handle(string $service, IRequestContext $context, ?IResponse $previousResponse): ?IResponse {
        // the handler-specific logic
    }

}

The basic concept is that every handler will be called consecutively. A handler can react to the request and return a new response object or modify the one of the previous handler. The first handler will get a $previousResponse of null. The second handler gets whatever the first handler returned, so either null or an instance of \OCP\Http\WellKnown\IResponse.

Example generic handler

<?php

declare(strict_types=1);

namespace OCA\MyApp\Http\WellKnown;

use OCP\AppFramework\Http\JSONResponse;
use OCP\Http\WellKnown\GenericResponse;
use OCP\Http\WellKnown\IHandler;
use OCP\Http\WellKnown\IRequestContext;
use OCP\Http\WellKnown\IResponse;
use OCP\IURLGenerator;

class GenericHandler implements IHandler {

    public function handle(string $service, IRequestContext $context, ?IResponse $previousResponse): ?IResponse {
        if ($service !== 'nextcloudtest') {
            // Not relevant to this handler

            return $previousResponse;
        }

        return new GenericResponse(
            new JSONResponse(['message' => 'hello']),
        );
    }
}

Example webfinger handler

The following example shows how an app could react to RFC6415 webfinger requests:

<?php

declare(strict_types=1);

namespace OCA\MyApp\Http\WellKnown;

use OCP\Http\WellKnown\IHandler;
use OCP\Http\WellKnown\IRequestContext;
use OCP\Http\WellKnown\IResponse;
use OCP\Http\WellKnown\JrdResponse;
use OCP\IURLGenerator;

class WebFingerHandler implements IHandler {

    /** @var IURLGenerator */
    private $urlGenerator;

    public function __construct(IURLGenerator $urlGenerator) {
        $this->urlGenerator = $urlGenerator;
    }

    public function handle(string $service, IRequestContext $context, ?IResponse $previousResponse): ?IResponse {
        if ($service !== 'webfinger') {
            // Not relevant to this handler

            return $previousResponse;
        }

        $subject = $context->getHttpRequest()->getParam('resource', '');
        $href = $this->urlGenerator->linkToRouteAbsolute('myapp.example.test');

        // Use the previous response and amend it, if possible
        $response = $previousResponse;
        if (!($response instanceof JrdResponse)) {
            // We override null or any other types
            $response = new JrdResponse($subject);
        }

        return $response->addLink('self', 'application/activity+json', $href);
    }
}

Handler registration

The handler class is registered via the bootstrap mechanism of the Application class.

<?php

declare(strict_types=1);

namespace OCA\MyApp\AppInfo;

use OCA\MyApp\Http\WellKnown\Handler;
use OCP\AppFramework\App;
use OCP\AppFramework\Bootstrap\IBootContext;
use OCP\AppFramework\Bootstrap\IBootstrap;
use OCP\AppFramework\Bootstrap\IRegistrationContext;

class Application extends App implements IBootstrap {

    public function register(IRegistrationContext $context): void {
        $context->registerWellKnownHandler(Handler::class);
    }

    public function boot(IBootContext $context): void {}

}