Skip to content

Commit 7919b07

Browse files
nickvergessennickvergessen
authored
Merge pull request #15172 from nextcloud/techdebt/noid/request-headers
feat(request-headers): Document request headers
2 parents 7421cbc + 8d40104 commit 7919b07

18 files changed

Lines changed: 98 additions & 28 deletions

‎lib/Controller/AEnvironmentAwareOCSController.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ public function getResponseFormat(): string {
6363

6464
// if none is given try the first Accept header
6565
if ($format === null) {
66-
$headers = $this->request->getHeader('Accept');
66+
$headers = $this->request->getHeader('accept');
6767
/**
6868
* Default value of
6969
* @see OCSController::buildResponse()

‎lib/Controller/AvatarController.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
2626
use OCP\AppFramework\Http\Attribute\OpenAPI;
2727
use OCP\AppFramework\Http\Attribute\PublicPage;
28+
use OCP\AppFramework\Http\Attribute\RequestHeader;
2829
use OCP\AppFramework\Http\DataResponse;
2930
use OCP\AppFramework\Http\FileDisplayResponse;
3031
use OCP\Federation\ICloudIdManager;
@@ -129,6 +130,7 @@ public function emojiAvatar(string $emoji, ?string $color): DataResponse {
129130
#[NoCSRFRequired]
130131
#[AllowWithoutParticipantWhenPendingInvitation]
131132
#[RequireParticipantOrLoggedInAndListedConversation]
133+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
132134
public function getAvatar(bool $darkTheme = false): FileDisplayResponse {
133135
// Cache for 1 day
134136
$cacheDuration = 60 * 60 * 24;
@@ -162,6 +164,7 @@ public function getAvatar(bool $darkTheme = false): FileDisplayResponse {
162164
#[NoCSRFRequired]
163165
#[AllowWithoutParticipantWhenPendingInvitation]
164166
#[RequireParticipantOrLoggedInAndListedConversation]
167+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
165168
public function getAvatarDark(): FileDisplayResponse {
166169
return $this->getAvatar(true);
167170
}
@@ -181,6 +184,7 @@ public function getAvatarDark(): FileDisplayResponse {
181184
#[OpenAPI(scope: OpenAPI::SCOPE_FEDERATION)]
182185
#[NoAdminRequired]
183186
#[NoCSRFRequired]
187+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
184188
public function getUserProxyAvatarWithoutRoom(int $size, string $cloudId, bool $darkTheme = false): FileDisplayResponse {
185189
return $this->getUserProxyAvatar($size, $cloudId, $darkTheme);
186190
}
@@ -199,6 +203,7 @@ public function getUserProxyAvatarWithoutRoom(int $size, string $cloudId, bool $
199203
#[OpenAPI(scope: OpenAPI::SCOPE_FEDERATION)]
200204
#[NoAdminRequired]
201205
#[NoCSRFRequired]
206+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
202207
public function getUserProxyAvatarDarkWithoutRoom(int $size, string $cloudId): FileDisplayResponse {
203208
return $this->getUserProxyAvatar($size, $cloudId, true);
204209
}
@@ -221,6 +226,7 @@ public function getUserProxyAvatarDarkWithoutRoom(int $size, string $cloudId): F
221226
#[NoCSRFRequired]
222227
#[AllowWithoutParticipantWhenPendingInvitation]
223228
#[RequireLoggedInParticipant]
229+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
224230
public function getUserProxyAvatar(int $size, string $cloudId, bool $darkTheme = false): FileDisplayResponse {
225231
try {
226232
$resolvedCloudId = $this->cloudIdManager->resolveCloudId($cloudId);
@@ -281,6 +287,7 @@ public function getUserProxyAvatar(int $size, string $cloudId, bool $darkTheme =
281287
#[NoCSRFRequired]
282288
#[AllowWithoutParticipantWhenPendingInvitation]
283289
#[RequireLoggedInParticipant]
290+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
284291
public function getUserProxyAvatarDark(int $size, string $cloudId): FileDisplayResponse {
285292
return $this->getUserProxyAvatar($size, $cloudId, true);
286293
}

‎lib/Controller/BotController.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
3737
use OCP\AppFramework\Http\Attribute\OpenAPI;
3838
use OCP\AppFramework\Http\Attribute\PublicPage;
39+
use OCP\AppFramework\Http\Attribute\RequestHeader;
3940
use OCP\AppFramework\Http\DataResponse;
4041
use OCP\AppFramework\Utility\ITimeFactory;
4142
use OCP\Comments\MessageTooLongException;
@@ -73,13 +74,15 @@ public function __construct(
7374
* @return Bot
7475
* @throws \InvalidArgumentException When the request could not be linked with a bot
7576
*/
77+
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed used to generate the request signature')]
78+
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'Signature over the request body to verify authenticity')]
7679
protected function getBotFromHeaders(string $token, string $message): Bot {
77-
$random = $this->request->getHeader('X-Nextcloud-Talk-Bot-Random');
80+
$random = $this->request->getHeader('x-nextcloud-talk-bot-random');
7881
if (empty($random) || strlen($random) < 32) {
7982
$this->logger->error('Invalid Random received from bot response');
8083
throw new \InvalidArgumentException('Invalid Random received from bot response', Http::STATUS_BAD_REQUEST);
8184
}
82-
$checksum = $this->request->getHeader('X-Nextcloud-Talk-Bot-Signature');
85+
$checksum = $this->request->getHeader('x-nextcloud-talk-bot-signature');
8386
if (empty($checksum)) {
8487
$this->logger->error('Invalid Signature received from bot response');
8588
throw new \InvalidArgumentException('Invalid Signature received from bot response', Http::STATUS_BAD_REQUEST);

‎lib/Controller/CallController.php‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,9 @@
3333
use OCP\AppFramework\Db\DoesNotExistException;
3434
use OCP\AppFramework\Http;
3535
use OCP\AppFramework\Http\Attribute\BruteForceProtection;
36+
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
3637
use OCP\AppFramework\Http\Attribute\PublicPage;
38+
use OCP\AppFramework\Http\Attribute\RequestHeader;
3739
use OCP\AppFramework\Http\DataDownloadResponse;
3840
use OCP\AppFramework\Http\DataResponse;
3941
use OCP\AppFramework\Http\Response;
@@ -77,6 +79,7 @@ public function __construct(
7779
#[RequireModeratorOrNoLobby]
7880
#[RequireParticipant]
7981
#[RequireReadWriteConversation]
82+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
8083
public function getPeersForCall(): DataResponse {
8184
if ($this->room->isFederatedConversation()) {
8285
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\CallController $proxy */
@@ -129,7 +132,7 @@ public function getPeersForCall(): DataResponse {
129132
*/
130133
#[PublicPage]
131134
#[RequireModeratorParticipant]
132-
#[Http\Attribute\NoCSRFRequired]
135+
#[NoCSRFRequired]
133136
public function downloadParticipantsForCall(string $format = 'csv'): DataDownloadResponse|Response {
134137
$callStart = $this->room->getActiveSince()?->getTimestamp() ?? 0;
135138
if ($callStart === 0) {
@@ -223,6 +226,7 @@ protected function escapeFormulae(string $value): string {
223226
#[RequireModeratorOrNoLobby]
224227
#[RequireParticipant]
225228
#[RequireReadWriteConversation]
229+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
226230
public function joinCall(?int $flags = null, bool $silent = false, bool $recordingConsent = false, array $silentFor = []): DataResponse {
227231
try {
228232
$this->validateRecordingConsent($recordingConsent);
@@ -344,6 +348,7 @@ public function joinFederatedCall(string $sessionId, ?int $flags = null, bool $s
344348
#[RequireCallEnabled]
345349
#[RequireParticipant]
346350
#[RequirePermission(permission: RequirePermission::START_CALL)]
351+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
347352
public function ringAttendee(int $attendeeId): DataResponse {
348353
if ($this->room->isFederatedConversation()) {
349354
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\CallController $proxy */
@@ -424,6 +429,7 @@ public function sipDialOut(int $attendeeId): DataResponse {
424429
#[FederationSupported]
425430
#[PublicPage]
426431
#[RequireParticipant]
432+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
427433
public function updateCallFlags(int $flags): DataResponse {
428434
$session = $this->participant->getSession();
429435
if (!$session instanceof Session) {
@@ -496,6 +502,7 @@ public function updateFederatedCallFlags(string $sessionId, int $flags): DataRes
496502
#[FederationSupported]
497503
#[PublicPage]
498504
#[RequireParticipant]
505+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
499506
public function leaveCall(bool $all = false): DataResponse {
500507
$session = $this->participant->getSession();
501508
if (!$session instanceof Session) {

‎lib/Controller/ChatController.php‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
use OCP\AppFramework\Http;
5454
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
5555
use OCP\AppFramework\Http\Attribute\PublicPage;
56+
use OCP\AppFramework\Http\Attribute\RequestHeader;
5657
use OCP\AppFramework\Http\Attribute\UserRateLimit;
5758
use OCP\AppFramework\Http\DataResponse;
5859
use OCP\AppFramework\Services\IAppConfig;
@@ -215,6 +216,7 @@ protected function parseCommentToResponse(IComment $comment, ?Message $parentMes
215216
#[RequireParticipant]
216217
#[RequirePermission(permission: RequirePermission::CHAT)]
217218
#[RequireReadWriteConversation]
219+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
218220
public function sendMessage(string $message, string $actorDisplayName = '', string $referenceId = '', int $replyTo = 0, bool $silent = false): DataResponse {
219221
if ($this->room->isFederatedConversation()) {
220222
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -392,6 +394,7 @@ public function shareObjectToChat(string $objectType, string $objectId, string $
392394
#[PublicPage]
393395
#[RequireModeratorOrNoLobby]
394396
#[RequireParticipant]
397+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
395398
public function receiveMessages(int $lookIntoFuture,
396399
int $limit = 100,
397400
int $lastKnownMessageId = 0,
@@ -749,6 +752,7 @@ protected function prepareCommentsAsDataResponse(array $comments, int $lastCommo
749752
#[PublicPage]
750753
#[RequireModeratorOrNoLobby]
751754
#[RequireParticipant]
755+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
752756
public function getMessageContext(
753757
int $messageId,
754758
int $limit = 50): DataResponse {
@@ -839,6 +843,7 @@ protected function loadSelfReactions(array $messages, array $commentIdToIndex):
839843
#[RequireAuthenticatedParticipant]
840844
#[RequirePermission(permission: RequirePermission::CHAT)]
841845
#[RequireReadWriteConversation]
846+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
842847
public function deleteMessage(int $messageId): DataResponse {
843848
if ($this->room->isFederatedConversation()) {
844849
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -931,6 +936,7 @@ public function deleteMessage(int $messageId): DataResponse {
931936
#[RequireAuthenticatedParticipant]
932937
#[RequirePermission(permission: RequirePermission::CHAT)]
933938
#[RequireReadWriteConversation]
939+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
934940
public function editMessage(int $messageId, string $message): DataResponse {
935941
if ($this->room->isFederatedConversation()) {
936942
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -1037,6 +1043,7 @@ public function editMessage(int $messageId, string $message): DataResponse {
10371043
#[RequireModeratorOrNoLobby]
10381044
#[RequireLoggedInParticipant]
10391045
#[UserRateLimit(limit: 60, period: 3600)]
1046+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
10401047
public function setReminder(int $messageId, int $timestamp): DataResponse {
10411048
try {
10421049
// FIXME fail 400 when reminder is after expiration
@@ -1071,6 +1078,7 @@ public function setReminder(int $messageId, int $timestamp): DataResponse {
10711078
#[NoAdminRequired]
10721079
#[RequireModeratorOrNoLobby]
10731080
#[RequireLoggedInParticipant]
1081+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
10741082
public function getReminder(int $messageId): DataResponse {
10751083
try {
10761084
$this->validateMessageExists($messageId);
@@ -1104,6 +1112,7 @@ public function getReminder(int $messageId): DataResponse {
11041112
#[NoAdminRequired]
11051113
#[RequireModeratorOrNoLobby]
11061114
#[RequireLoggedInParticipant]
1115+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
11071116
public function deleteReminder(int $messageId): DataResponse {
11081117
try {
11091118
$this->validateMessageExists($messageId);
@@ -1290,6 +1299,7 @@ public function clearHistory(): DataResponse {
12901299
#[FederationSupported]
12911300
#[PublicPage]
12921301
#[RequireAuthenticatedParticipant]
1302+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
12931303
public function setReadMarker(?int $lastReadMessage = null): DataResponse {
12941304
$setToMessage = $lastReadMessage ?? $this->room->getLastMessageId();
12951305
if ($setToMessage === 0) {
@@ -1339,6 +1349,7 @@ public function setReadMarker(?int $lastReadMessage = null): DataResponse {
13391349
#[FederationSupported]
13401350
#[PublicPage]
13411351
#[RequireAuthenticatedParticipant]
1352+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
13421353
public function markUnread(): DataResponse {
13431354
if ($this->room->isFederatedConversation()) {
13441355
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -1515,6 +1526,7 @@ protected function getMessagesForRoom(array $messageIds): array {
15151526
#[RequireParticipant]
15161527
#[RequirePermission(permission: RequirePermission::CHAT)]
15171528
#[RequireReadWriteConversation]
1529+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
15181530
public function mentions(string $search, int $limit = 20, bool $includeStatus = false): DataResponse {
15191531
if ($this->room->isFederatedConversation()) {
15201532
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */

‎lib/Controller/FederationController.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ public function getResponseFormat(): string {
5252

5353
// if none is given try the first Accept header
5454
if ($format === null) {
55-
$headers = $this->request->getHeader('Accept');
55+
$headers = $this->request->getHeader('accept');
5656
/**
5757
* Default value of
5858
* @see OCSController::buildResponse()

‎lib/Controller/PollController.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
use OCP\AppFramework\Db\DoesNotExistException;
2929
use OCP\AppFramework\Http;
3030
use OCP\AppFramework\Http\Attribute\PublicPage;
31+
use OCP\AppFramework\Http\Attribute\RequestHeader;
3132
use OCP\AppFramework\Http\DataResponse;
3233
use OCP\AppFramework\Utility\ITimeFactory;
3334
use OCP\IRequest;
@@ -73,6 +74,7 @@ public function __construct(
7374
#[RequireParticipant]
7475
#[RequirePermission(permission: RequirePermission::CHAT)]
7576
#[RequireReadWriteConversation]
77+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
7678
public function createPoll(string $question, array $options, int $resultMode, int $maxVotes, bool $draft = false): DataResponse {
7779
if ($this->room->isFederatedConversation()) {
7880
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -158,6 +160,7 @@ public function createPoll(string $question, array $options, int $resultMode, in
158160
#[RequireParticipant]
159161
#[RequirePermission(permission: RequirePermission::CHAT)]
160162
#[RequireReadWriteConversation]
163+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
161164
public function updateDraftPoll(int $pollId, string $question, array $options, int $resultMode, int $maxVotes): DataResponse {
162165
if ($this->room->isFederatedConversation()) {
163166
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -220,6 +223,7 @@ public function updateDraftPoll(int $pollId, string $question, array $options, i
220223
#[FederationSupported]
221224
#[PublicPage]
222225
#[RequireModeratorParticipant]
226+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
223227
public function getAllDraftPolls(): DataResponse {
224228
if ($this->room->isFederatedConversation()) {
225229
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -250,6 +254,7 @@ public function getAllDraftPolls(): DataResponse {
250254
#[PublicPage]
251255
#[RequireModeratorOrNoLobby]
252256
#[RequireParticipant]
257+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
253258
public function showPoll(int $pollId): DataResponse {
254259
if ($this->room->isFederatedConversation()) {
255260
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -292,6 +297,7 @@ public function showPoll(int $pollId): DataResponse {
292297
#[PublicPage]
293298
#[RequireModeratorOrNoLobby]
294299
#[RequireParticipant]
300+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
295301
public function votePoll(int $pollId, array $optionIds = []): DataResponse {
296302
if ($this->room->isFederatedConversation()) {
297303
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -358,6 +364,7 @@ public function votePoll(int $pollId, array $optionIds = []): DataResponse {
358364
#[PublicPage]
359365
#[RequireModeratorOrNoLobby]
360366
#[RequireParticipant]
367+
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
361368
public function closePoll(int $pollId): DataResponse {
362369
if ($this->room->isFederatedConversation()) {
363370
/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */

0 commit comments

Comments
 (0)