Skip to content

Commit

Permalink
feat(devmanual): Document programmatic rate limiter
Browse files Browse the repository at this point in the history
Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
  • Loading branch information
ChristophWurst committed Sep 6, 2023
1 parent 88dc3cc commit 11578a6
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 1 deletion.
2 changes: 1 addition & 1 deletion developer_manual/basics/controllers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -848,7 +848,7 @@ A controller method that turns off all checks would look like this:
Rate limiting
-------------

Nextcloud supports rate limiting on a controller method basis. By default controller methods are not rate limited. Rate limiting should be used on expensive or security sensitive functions (e.g. password resets) to increase the overall security of your application.
Nextcloud supports rate limiting on a controller method basis and in a :ref:`programmatic way<programmatic-rate-limiting>`. By default controller methods are not rate limited. Rate limiting should be used on expensive or security sensitive functions (e.g. password resets) to increase the overall security of your application.

The native rate limiting will return a 429 status code to clients when the limit is reached and a default Nextcloud error page. When implementing rate limiting in your application, you should thus consider handling error situations where a 429 is returned by Nextcloud.

Expand Down
53 changes: 53 additions & 0 deletions developer_manual/digging_deeper/security.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,59 @@
Security
========

.. _programmatic-rate-limiting:

Rate Limiting
-------------

Rate limiting can be used to restrict how often someone can execute an operation in a defined time frame. For app framework controllers it is recommended to use rate limiting attributes.

Outside controllers, e.g. in DAV code, it's also possible to guard operations by :ref:`injecting<dependency-injection>` ``\OCP\Security\RateLimiting\ILimiter`` and registering requests *before* the operation:

.. code-block:: php
:emphasize-lines: 13-21, 27-36
<?php
use OCP\Security\RateLimiting\ILimiter;
class MyDavPlugin {
private ILimiter $limiter;
public function __construct(ILimiter $limiter) {
$this->limiter = $limiter;
}
public function calledAnonymously(): void {
try {
$this->limiter->registerAnonRequest(
'my-dav-plugin-anon',
5, // Allow five executions …
60 * 60, // … per hour
);
} catch (IRateLimitExceededException $exception) {
// Respond with a HTTP 429 error
}
// No rate limiting reached. Carry on.
}
public function calledByUser(IUser $user): void {
try {
$this->limiter->registerUserRequest(
'my-dav-plugin-user',
5, // Allow five executions …
60 * 60, // … per hour
$user
);
} catch (IRateLimitExceededException $exception) {
// Respond with a HTTP 429 error
}
// No rate limiting reached. Carry on.
}
}
Remote Host Validation
----------------------

Expand Down

0 comments on commit 11578a6

Please sign in to comment.