diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/ratelimiting.md | 2 | ||||
| -rw-r--r-- | docs/api/throttling.md | 35 | ||||
| -rw-r--r-- | docs/configuration/advanced.md | 37 | ||||
| -rw-r--r-- | docs/faq.md | 4 | ||||
| -rw-r--r-- | docs/federation/behaviors/request_throttling.md | 3 | ||||
| -rw-r--r-- | docs/index.md | 2 |
6 files changed, 75 insertions, 8 deletions
diff --git a/docs/api/ratelimiting.md b/docs/api/ratelimiting.md index 09b554093..2bdcdf2ba 100644 --- a/docs/api/ratelimiting.md +++ b/docs/api/ratelimiting.md @@ -1,4 +1,4 @@ -# Rate Limit +# Request Rate Limiting To mitigate abuse + scraping of your instance, IP-based HTTP rate limiting is in place. diff --git a/docs/api/throttling.md b/docs/api/throttling.md new file mode 100644 index 000000000..a2386053a --- /dev/null +++ b/docs/api/throttling.md @@ -0,0 +1,35 @@ +# Request Throttling + +GoToSocial uses request throttling to limit the number of open connections to the API of your instance. This is designed to prevent your instance from accidentally being DDOS'd (aka [the hug of death](https://en.wikipedia.org/wiki/Slashdot_effect)) if a post gets boosted or replied to by an account with many thousands of followers. + +Throttling means that only a limited number of HTTP requests to the API will be handled concurrently, in order to provide a snappy response to each request and move on quickly. The rationale is that it's better to handle fewer requests quickly, than to try to handle all incoming requests at once and take multiple seconds per request. + +Throttling limits are applied across router groups, similar to the way that [rate limiting](./ratelimiting.md) is organized, so if one part of the API is currently being throttled, that doesn't mean they all are. + +Throttling limits are calculated based on the number of CPUs available to GoToSocial, and the configuration value `advanced-throttling-multiplier`. The calculation is performed as follows: + +- In-process queue limit = number of CPUs * CPU multiplier. +- Backlog queue limit = in-process queue limit * CPU multiplier. + +This leads to the following values for the default multiplier (8): + +```text +1 cpu = 08 in-process, 064 backlog +2 cpu = 16 in-process, 128 backlog +4 cpu = 32 in-process, 256 backlog +8 cpu = 64 in-process, 512 backlog +``` + +New requests that overflow the in-process limit are held in the backlog queue, and processed as soon as a spot is freed up (ie., when a currently in-process request is finished). Requests that cannot be processed, and cannot fit in the backlog queue will be responded to with http code [503 - Service Unavailable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503), and the `Retry-After` header will be set to `30` (seconds), to indicate that the caller should try again later. + +Requests are not held in the backlog queue indefinitely: if requests in the backlog cannot be processed within 30 seconds of being received, they will also receive a code 503 and a 30s retry-after. + +## Throttling FAQs + +### Can I tune the request throttling? + +Yes, just change the value of `advanced-throttling-multiplier` higher (if you have very powerful CPUs) or lower (if you have relatively less powerful CPUs). + +### Can I disable the request throttling? + +Yes. To do so, just set `advanced-throttling-multiplier` to `0` or less. This will disable HTTP request throttling entirely, and instead attempt to process all incoming requests at once. This is useful in cases where you want to do request throttling using an external service or a reverse-proxy, and you don't want GoToSocial to interfere with your setup. diff --git a/docs/configuration/advanced.md b/docs/configuration/advanced.md index f4b8c5ffa..7cf962903 100644 --- a/docs/configuration/advanced.md +++ b/docs/configuration/advanced.md @@ -36,9 +36,8 @@ These are set to sensible defaults, so most server admins won't need to touch th # Default: "lax" advanced-cookies-samesite: "lax" -# Int. Amount of requests to permit from a single IP address within a span of 5 minutes. -# If this amount is exceeded, a 429 HTTP error code will be returned. -# See https://docs.gotosocial.org/en/latest/api/swagger/#rate-limit. +# Int. Amount of requests to permit per router grouping from a single IP address within +# a span of 5 minutes. If this amount is exceeded, a 429 HTTP error code will be returned. # # If you find yourself adjusting this limit because it's regularly being exceeded, # you should first verify that your settings for `trusted-proxies` (above) are correct. @@ -50,6 +49,34 @@ advanced-cookies-samesite: "lax" # If you set this to 0 or less, rate limiting will be disabled entirely. # # Examples: [1000, 500, 0] -# Default: 1000 -advanced-rate-limit-requests: 1000 +# Default: 300 +advanced-rate-limit-requests: 300 + +# Int. Amount of open requests to permit per CPU, per router grouping, before applying http +# request throttling. Any requests beyond the calculated limit are held in a backlog queue for +# up to 30 seconds before either being processed or timing out. Requests that don't fit in the backlog +# queue will have status 503 returned to them, and the header 'Retry-After' will be set to 30 seconds. +# +# Open request limit is available CPUs * multiplier; backlog queue limit is limit * multiplier. +# +# Example values for multiplier 8: +# +# 1 cpu = 08 open, 064 backlog +# 2 cpu = 16 open, 128 backlog +# 4 cpu = 32 open, 256 backlog +# +# Example values for multiplier 4: +# +# 1 cpu = 04 open, 016 backlog +# 2 cpu = 08 open, 032 backlog +# 4 cpu = 16 open, 064 backlog +# +# A multiplier of 8 is a sensible default, but you may wish to increase this for instances +# running on very performant hardware, or decrease it for instances using v. slow CPUs. +# +# If you set this to 0 or less, http request throttling will be disabled entirely. +# +# Examples: [8, 4, 9, 0] +# Default: 8 +advanced-throttling-multiplier: 8 ``` diff --git a/docs/faq.md b/docs/faq.md index 1d523ee69..b5e1d0e8e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -8,7 +8,9 @@ - **Why aren't my posts showing up on other servers?** First check the visibility as noted above. TODO: explain how to debug common federation issues -- **Why am I getting frequent error responses?** GoToSocial is configured to use per-IP [rate limiting](https://docs.gotosocial.org/en/latest/api/ratelimiting/) by default, but in certain situations it can't accurately identify the remote IP and will treat all connections as coming from the same place. In those cases, the rate limiting needs to be disabled or reconfigured. +- **Why am I getting frequent http 429 error responses?** GoToSocial is configured to use per-IP [rate limiting](./api/ratelimiting.md) by default, but in certain situations it can't accurately identify the remote IP and will treat all connections as coming from the same place. In those cases, the rate limiting needs to be disabled or reconfigured. + +- **Why am I getting frequent http 503 error responses?** Code 503 is returned to callers when your instance is under heavy load and requests are being throttled. This behavior can be tuned as desired, or turned off entirely, see [here](./api/throttling.md). - **My instance is deployed and I'm logged in to a client but my timelines are empty, what's up there?** To see posts, you have to start following people! Once you've followed a few people and they've posted or boosted things, you'll start seeing them in your timelines. Right now GoToSocial doesn't have a way of 'backfilling' posts -- that is, fetching previous posts from other instances -- so you'll only see new posts of people you follow. If you want to interact with an older post of theirs, you can copy the link to the post from their web profile, and paste it in to your client's search bar. diff --git a/docs/federation/behaviors/request_throttling.md b/docs/federation/behaviors/request_throttling.md new file mode 100644 index 000000000..e44e26811 --- /dev/null +++ b/docs/federation/behaviors/request_throttling.md @@ -0,0 +1,3 @@ +# Request Throttling and Rate Limiting + +GoToSocial applies rate limiting and http request throttling to the ActivityPub API endpoints (inboxes, user endpoints, emojis, etc). For more details on this, please see the [throttling](../../api/throttling.md) and [rate limiting](../../api/ratelimiting.md) documents. diff --git a/docs/index.md b/docs/index.md index 911768cc2..3d75eb1ac 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,7 +34,7 @@ It began as a solo project, and then picked up steam as more developers became i ## Known Issues -Since GoToSocial is still in alpha, there are plenty of bugs. We use [GitHub issues](https://github.com/superseriousbusiness/gotosocial/issues?q=is%3Aissue+is%3Aopen+label%3Abug) to track these. The [FAQ](docs/faq.md) also describes some of the features that haven't been implemented yet. +Since GoToSocial is still in alpha, there are plenty of bugs. We use [GitHub issues](https://github.com/superseriousbusiness/gotosocial/issues?q=is%3Aissue+is%3Aopen+label%3Abug) to track these. The [FAQ](./faq.md) also describes some of the features that haven't been implemented yet. ### Client App Issues |