diff options
author | Christoph Wurst <christoph@winzerhof-wurst.at> | 2020-12-14 15:56:07 +0100 |
---|---|---|
committer | Christoph Wurst <christoph@winzerhof-wurst.at> | 2020-12-16 13:13:05 +0100 |
commit | 6995223b1ed202c7f8e920e83cb5b53efd7ce761 (patch) | |
tree | 76e839b9c3de3b4751a993f24f35f0cb93c0dbbd /lib/public/Http | |
parent | d37034f1612279b07c78284771ac73fbd5a2a407 (diff) | |
download | nextcloud-server-6995223b1ed202c7f8e920e83cb5b53efd7ce761.tar.gz nextcloud-server-6995223b1ed202c7f8e920e83cb5b53efd7ce761.zip |
Add well known handlers API
Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
Diffstat (limited to 'lib/public/Http')
-rw-r--r-- | lib/public/Http/WellKnown/GenericResponse.php | 51 | ||||
-rw-r--r-- | lib/public/Http/WellKnown/IHandler.php | 48 | ||||
-rw-r--r-- | lib/public/Http/WellKnown/IRequestContext.php | 46 | ||||
-rw-r--r-- | lib/public/Http/WellKnown/IResponse.php | 39 | ||||
-rw-r--r-- | lib/public/Http/WellKnown/JrdResponse.php | 170 |
5 files changed, 354 insertions, 0 deletions
diff --git a/lib/public/Http/WellKnown/GenericResponse.php b/lib/public/Http/WellKnown/GenericResponse.php new file mode 100644 index 00000000000..6efacc41c00 --- /dev/null +++ b/lib/public/Http/WellKnown/GenericResponse.php @@ -0,0 +1,51 @@ +<?php + +declare(strict_types=1); + +/* + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Http\WellKnown; + +use OCP\AppFramework\Http\Response; + +/** + * @since 21.0.0 + */ +final class GenericResponse implements IResponse { + + /** @var Response */ + private $response; + + /** + * @since 21.0.0 + */ + public function __construct(Response $response) { + $this->response = $response; + } + + /** + * @since 21.0.0 + */ + public function toHttpResponse(): Response { + return $this->response; + } +} diff --git a/lib/public/Http/WellKnown/IHandler.php b/lib/public/Http/WellKnown/IHandler.php new file mode 100644 index 00000000000..30fca0da5a2 --- /dev/null +++ b/lib/public/Http/WellKnown/IHandler.php @@ -0,0 +1,48 @@ +<?php + +declare(strict_types=1); + +/* + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Http\WellKnown; + +/** + * Interface for an app handler that reacts to requests to Nextcloud's well + * known URLs, e.g. to a WebFinger + * + * @ref https://tools.ietf.org/html/rfc5785 + * + * @since 21.0.0 + */ +interface IHandler { + + /** + * @param string $service the name of the well known service, e.g. 'webfinger' + * @param IRequestContext $context + * @param IResponse|null $previousResponse the response of the previous handler, if any + * + * @return IResponse|null a response object if the request could be handled, null otherwise + * + * @since 21.0.0 + */ + public function handle(string $service, IRequestContext $context, ?IResponse $previousResponse): ?IResponse; +} diff --git a/lib/public/Http/WellKnown/IRequestContext.php b/lib/public/Http/WellKnown/IRequestContext.php new file mode 100644 index 00000000000..d064c467d68 --- /dev/null +++ b/lib/public/Http/WellKnown/IRequestContext.php @@ -0,0 +1,46 @@ +<?php + +declare(strict_types=1); + +/* + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Http\WellKnown; + +use OCP\IRequest; + +/** + * The context object for \OCP\Http\IWellKnownHandler::handle + * + * Objects of this type will transport any optional information, e.g. the request + * object through which the app well known handler can obtain URL parameters + * + * @since 21.0.0 + */ +interface IRequestContext { + + /** + * @return IRequest + * + * @since 21.0.0 + */ + public function getHttpRequest(): IRequest; +} diff --git a/lib/public/Http/WellKnown/IResponse.php b/lib/public/Http/WellKnown/IResponse.php new file mode 100644 index 00000000000..8d7bc307252 --- /dev/null +++ b/lib/public/Http/WellKnown/IResponse.php @@ -0,0 +1,39 @@ +<?php + +declare(strict_types=1); + +/* + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Http\WellKnown; + +use OCP\AppFramework\Http\Response; + +/** + * @since 21.0.0 + */ +interface IResponse { + + /** + * @since 21.0.0 + */ + public function toHttpResponse(): Response; +} diff --git a/lib/public/Http/WellKnown/JrdResponse.php b/lib/public/Http/WellKnown/JrdResponse.php new file mode 100644 index 00000000000..3a387107e8e --- /dev/null +++ b/lib/public/Http/WellKnown/JrdResponse.php @@ -0,0 +1,170 @@ +<?php + +declare(strict_types=1); + +/* + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Http\WellKnown; + +use OCP\AppFramework\Http\JSONResponse; +use OCP\AppFramework\Http\Response; +use function array_filter; + +/** + * A JSON Document Format (JDF) response to a well-known request + * + * @ref https://tools.ietf.org/html/rfc6415#appendix-A + * @ref https://tools.ietf.org/html/rfc7033#section-4.4 + * + * @since 21.0.0 + */ +final class JrdResponse implements IResponse { + + /** @var string */ + private $subject; + + /** @var string|null */ + private $expires; + + /** @var string[] */ + private $aliases = []; + + /** @var (string|null)[] */ + private $properties = []; + + /** @var mixed[] */ + private $links; + + /** + * @param string $subject https://tools.ietf.org/html/rfc7033#section-4.4.1 + * + * @since 21.0.0 + */ + public function __construct(string $subject) { + $this->subject = $subject; + } + + /** + * @param string $expires + * + * @return $this + * + * @since 21.0.0 + */ + public function setExpires(string $expires): self { + $this->expires = $expires; + + return $this; + } + + /** + * Add an alias + * + * @ref https://tools.ietf.org/html/rfc7033#section-4.4.2 + * + * @param string $alias + * + * @return $this + * + * @since 21.0.0 + */ + public function addAlias(string $alias): self { + $this->aliases[] = $alias; + + return $this; + } + + /** + * Add a property + * + * @ref https://tools.ietf.org/html/rfc7033#section-4.4.3 + * + * @param string $property + * @param string|null $value + * + * @return $this + * + * @since 21.0.0 + */ + public function addProperty(string $property, ?string $value): self { + $this->properties[$property] = $value; + + return $this; + } + + /** + * Add a link + * + * @ref https://tools.ietf.org/html/rfc7033#section-8.4 + * + * @param string $rel https://tools.ietf.org/html/rfc7033#section-4.4.4.1 + * @param string|null $type https://tools.ietf.org/html/rfc7033#section-4.4.4.2 + * @param string|null $href https://tools.ietf.org/html/rfc7033#section-4.4.4.3 + * @param string[]|null $titles https://tools.ietf.org/html/rfc7033#section-4.4.4.4 + * @param string|null $properties https://tools.ietf.org/html/rfc7033#section-4.4.4.5 + * + * @psalm-param array<string,(string|null)>|null $properties https://tools.ietf.org/html/rfc7033#section-4.4.4.5 + * + * @return JrdResponse + * @since 21.0.0 + */ + public function addLink(string $rel, + ?string $type, + ?string $href, + ?array $titles = [], + ?array $properties = []): self { + $this->links[] = array_filter([ + 'rel' => $rel, + 'type' => $type, + 'href' => $href, + 'titles' => $titles, + 'properties' => $properties, + ]); + + return $this; + } + + /** + * @since 21.0.0 + */ + public function toHttpResponse(): Response { + return new JSONResponse(array_filter([ + 'subject' => $this->subject, + 'expires' => $this->expires, + 'aliases' => $this->aliases, + 'properties' => $this->properties, + 'links' => $this->links, + ])); + } + + /** + * Does this response have any data attached to it? + * + * @since 21.0.0 + */ + public function isEmpty(): bool { + return $this->expires === null + && empty($this->aliases) + && empty($this->properties) + && empty($this->links); + } +} |