Rate Limiting & Quotas
SkySend includes built-in rate limiting and upload quotas to protect against abuse. All variables are documented in the Environment Variables reference.
Every limit on this page counts per client address. An IPv6 client counts per /64 network, since a household, a phone or a server usually holds a whole /64 and could otherwise take a new address for every request. An IPv4 address that arrives mapped into IPv6 counts as that IPv4 address.
Rate Limiting
Rate limiting applies to all API endpoints using a sliding window algorithm per IP address. Controlled via RATE_LIMIT_WINDOW (milliseconds) and RATE_LIMIT_MAX (requests per window, default: 60 per minute).
Every request that opens an upload counts: the init of an upload in chunks and the WebSocket connection of an upload over WebSocket alike, for normal uploads and uploads into a file request. The chunks of an upload do not count, the server bounds them per upload instead.
Many people behind one address, like the staff of a company behind one NAT gateway, share one count. Raise RATE_LIMIT_MAX for such an instance. Behind a reverse proxy, set TRUST_PROXY=true, or every client counts as the proxy.
Every response includes rate limit headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1704067260000When the limit is exceeded, the server returns 429 Too Many Requests.
Upload Memory
Uploads over WebSocket hold what they receive in memory until it is written to storage. All of them together hold at most FILE_UPLOAD_WS_MEMORY_LIMIT, and uploads to S3 hold at most S3_MEMORY_LIMIT in parts on their way to the bucket and half of it again in parts still filling up, which wait on disk beyond that. Both default to a quarter of the memory the server may use, at most 256 MB. When a limit is reached, uploads wait and slow down instead of the server running out of memory, and none is turned away, so this does not depend on addresses. A WebSocket connection that does not start its upload within 30 seconds is closed, and one that stops in the middle of a frame is closed after two and a half minutes, which a sender at the slowest rate the progress rule allows never hits.
Upload Quotas
Upload quotas limit the total volume of data a single user can upload within a time window, preventing a single user from filling up the server's storage. Controlled via FILE_UPLOAD_QUOTA_BYTES and FILE_UPLOAD_QUOTA_WINDOW. Set FILE_UPLOAD_QUOTA_BYTES=0 to disable quotas (default).
An upload reserves its size in the quota when it starts and keeps it until it is stored or ends, so uploads running side by side cannot add up to more than the quota. An upload that fails or is cancelled gives its share back. Uploads into a file request count against the quota of the sender.
When the quota is used up, the server returns 429 Too Many Requests:
{
"error": "Upload quota exceeded. Try again later."
}An upload that would not fit into what is left of the quota gets 413 Content Too Large with "File size exceeds remaining quota.".
Privacy
Upload quotas use HMAC-SHA256 to hash IP addresses before storing them. The HMAC key lives in memory only and rotates daily, which means:
- No plaintext IP addresses are ever stored, and neither is the key, so a copy of the database or a backup cannot turn the hashes back into addresses
- IP hashes cannot be correlated across days
- When the key rotates, the entire quota store is cleared
- A restart starts every quota afresh
Daily File Request Limit
FILE_REQUEST_DAILY_LIMIT caps how many file requests one person creates per day. It counts the OIDC user when OIDC_PROTECT_REQUESTS puts creating behind the login, and the client IP otherwise. The day starts with the first request of that user or IP. Set it to 0 to disable the limit (default).
A request costs little by itself, but every one is an inbox that anyone with its link can fill. On a public instance, set the limit together with Upload Quotas, for example FILE_REQUEST_DAILY_LIMIT=100. Behind a reverse proxy, the limit needs TRUST_PROXY=true, or everyone shares the count of the proxy's IP.
When the limit is used up, creating a request returns 429 Too Many Requests, and the request form says when the next one is possible. The count lives in memory, with the IP HMAC-hashed by a key that is never stored, so a restart resets it.
Password Attempt Lockout
SkySend tracks failed password attempts per upload/note and per client IP. For an upload, the password check and a download with a wrong token count together, so a guesser cannot switch between them. After too many failures, that specific IP is locked out from that specific resource for a configurable duration. Controlled via PASSWORD_MAX_ATTEMPTS and PASSWORD_LOCKOUT_MS.
This is intentionally per-resource, not per-IP globally: a user mis-typing a password cannot block others from accessing unrelated uploads, and a shared IP (corporate NAT, VPN) cannot trigger a lockout for a resource they have not tried.
When locked, the server returns 429 Too Many Requests with a Retry-After header indicating the remaining wait in seconds.
Privacy
Client IP addresses are HMAC-SHA256 hashed with an ephemeral in-memory key before being stored. The key is generated fresh on startup and never persisted or logged - raw IPs are never retained.
IP Detection
SkySend determines the client IP using:
- The last address in the
X-Forwarded-Forheader, the one your reverse proxy added (ifTRUST_PROXY=trueand the connection comes fromTRUSTED_PROXIES) X-Real-IPheader (same conditions)- Direct socket address (fallback, also when the header holds no valid address)
TRUSTED_PROXIES defaults to loopback and the private networks, so a client that reaches the server port directly from the internet cannot pick its own address. See Reverse Proxy.
The addresses before the last one come from the client and are never trusted. Behind two proxies, like a CDN in front of your reverse proxy, the last address is the one of the CDN, so every visitor shares its count. Have your reverse proxy put the client address the CDN reports into X-Forwarded-For instead.
WARNING
Only enable TRUST_PROXY=true when running behind a trusted reverse proxy. Otherwise, clients can spoof their IP to bypass rate limits and quotas.