Limits
What keeps the server up when anyone on the internet may call it: who may sign up, how often a client may call, how big a request may be, and what the server holds on to, on disk, in memory, in open files and threads, and in calls to the PLC directory. What every method shares, and how the server is checked, is in The PDS: accounts and their records.
Some of this is the reference’s, and the harness holds the server to it: the request caps, invite codes, the rate limits, and which methods an app password’s session may call. The rest is this server’s own design, which the reference has no counterpart for. Where the harness can see it, it checks it against this page; where it cannot, the server’s own tests do.
The methods: com.atproto.server.createInviteCode, createInviteCodes and
getAccountInviteCodes.
Environment
Section titled “Environment”Besides those The PDS: accounts and their records, Accounts and Federation: what a relay reads list:
| Variable | Description | Default |
|---|---|---|
PDS_INVITE_REQUIRED | true or false: whether createAccount needs an invite code | false |
PDS_ADMIN_PASSWORD | the password of the admin methods’ Basic auth; unset or empty, no request is the admin | unset |
PDS_RATE_LIMITS_ENABLED | true or false: whether the rate limits below apply | true |
PDS_BLOB_QUOTA_BYTES | the bytes of blobs an account may hold | 1073741824 (1 GiB) |
PDS_BLOB_TTL_SECS | how long an upload no record references is held | 3600 |
PDS_BLOB_UPLOAD_LIMIT | the bytes of a blob uploadBlob takes (Blobs), and of a space repo’s archive com.atproto.space.importRepo takes (Spaces: a repo whole, its blobs, and migration), as the reference names it; describeServer answers it as blobUploadLimit | 5242880 (5 MiB, the reference’s) |
PDS_MIN_FREE_BYTES | the free space below which writes are refused | 268435456 (256 MiB) |
PDS_MAX_REPO_IMPORT_SIZE | the bytes of the CAR file com.atproto.repo.importRepo takes (Moving an account between servers), as the reference names it. The default is what the reference’s own installer gives it (the upload limit it sets, which bounds its imports too); the reference’s bare default, 5 MiB, would refuse most accounts’ repositories | 314572800 (300 MiB) |
PDS_DID_CACHE_SECS | how long a DID document is held before it is fetched again: an account’s, from the directory or, for a did:web, its host (Moving an account between servers), a service token’s issuer’s (Moving an account between servers, createAccount), and the key of a spaces token’s issuer, read again after its answer past this (Spaces: credentials, “Issuers’ keys”) | 3600 |
PDS_DID_CACHE_MAX_SECS | how long the key of a spaces token’s issuer is used at all: past PDS_DID_CACHE_SECS, a call is answered with it while it is read again; past this, it is read again first (Spaces: credentials, “Issuers’ keys”) | 86400 (a day) |
PDS_TRUSTED_PROXIES | the proxies before the server, whose X-Forwarded-For it reads: addresses and CIDR ranges, IPv4 or IPv6, separated by commas (127.0.0.1,10.0.0.0/8,::1); unset or empty, none | unset |
A value that does not parse, such as a negative number or yes, makes
pds serve exit 1, with why on standard error.
Request size
Section titled “Request size”A JSON request body is refused with 413 PayloadTooLargeError, after the
token is checked and before anything else, when it is longer than:
-
1000000 bytes, for
createRecord,putRecordandapplyWrites, ofcom.atproto.repoand ofcom.atproto.spacealike; -
16777216 bytes (16 MiB), for
importSpaceMeta, whose body is a space meta archive (application/octet-stream), not JSON;Note: no spec bounds it, so this server’s own bound, large enough for any space’s members and writers.
-
153600 bytes (150 KiB), for every other method with a JSON input.
A body of exactly the limit is taken. It is the same whether the body has a
Content-Length or comes chunked. A request the server forwards
(Proxying, service auth and preferences) is held to 153600 bytes too, whatever its method or its
Content-Type: one longer is 413 PayloadTooLargeError once its token is
checked, and is not sent on. The harness sends nothing that long to be
forwarded: what the reference does with one is not compared. uploadBlob
takes up to PDS_BLOB_UPLOAD_LIMIT bytes, as Blobs says, and so does
com.atproto.space.importRepo, whose body is a space repo’s STAR archive
(application/octet-stream), as Spaces: a repo whole, its blobs, and migration says: its bound is
the reference’s, the same variable, and is checked
after its token and Content-Type. com.atproto.repo.importRepo takes up
to PDS_MAX_REPO_IMPORT_SIZE bytes, checked at the same point
(Moving an account between servers). The name is PayloadTooLargeError, not the
PayloadTooLarge an upload or an importRepo too big answers: that is
the reference’s.
POST /mcp refuses a body longer than 1048576 bytes with HTTP 413, before
it reads it as JSON-RPC.
A request answered before its body was read to its end, whatever the
answer (an OAuth body refused by its Content-Length, OAuth: the authorization server; a
request refused for its CSRF token or its origin; an upload past its limit;
a path not served), keeps its connection when its Content-Length leaves
at most 4 MiB of the body unread: the server reads the rest after the
answer and throws it away, and then takes the next request. A body with
more left than that, or sent chunked, is not
read on: its answer says Connection: close, and the connection is
closed after it. A JSON body refused for its size is read too, up to 4 MiB
past its limit, before it is answered. A client that keeps its
connections open (HTTP/1.1) so never sends its next request on a
connection the server is closing unless the answer said so.
Commits
Section titled “Commits”- An
applyWritesof more than 200 writes is400 InvalidRequest. It is checked after the token, the input, and therepo(The PDS: accounts and their records), so it may be403 AccountNotFoundor401 AuthenticationRequiredfirst, and before the swap, the$types, and anything else of the writes. 200 is taken, and so is none. - A commit whose
#commitevent would hold more than 2000000 bytes ofblocksis refused with400 InvalidRequest, and nothing of it is kept. So every#commithas at most 200 ops and 2000000 bytes of blocks, assubscribeRepos’s lexicon says, andtooBigis always false.
Invite codes
Section titled “Invite codes”An invite code lets one or more accounts be created. The admin makes them;
createAccount uses them.
The admin
Section titled “The admin”createInviteCode and createInviteCodes, and the admin’s reads _logs
and _stats (Operations), take Authorization: Basic,
with the user admin and the password PDS_ADMIN_PASSWORD. Anything else
is 401 AuthenticationRequired: no Authorization, a Bearer token of any
kind, another user or password, a Basic value that does not decode, and
any request at all while PDS_ADMIN_PASSWORD is unset or empty (the
reference reads an empty one as unset too). The auth is checked
before the input: wrong auth with wrong input is 401. The password is
compared in constant time.
createInviteCode{useCount, forAccount?}makes one code, whichuseCountaccounts may be created with, and answers{code}.forAccountis a DID, which need not be an account’s here; without it, the code is the admin’s,admin. AuseCountof 0 or below is taken, and makes a code no account can be created with.createInviteCodes{codeCount, useCount, forAccounts?}makescodeCountcodes for each DID offorAccounts, or foradminwithout it, and answers{codes: [{account, codes}]}, one entry for each, in the order given, its codes in the order made. An emptyforAccountsanswers{codes: []}; acodeCountof 0 or below, each entry with no codes.
A code is <PDS_HOSTNAME with each . made ->-<5>-<5>, two groups of five
characters, each a lower case letter or a digit 2 to 7, random:
localhost-ab2cd-3efgh. Each is kept with the account it is for, admin
as its maker, available (its useCount), when it was made, and its uses.
getAccountInviteCodes
Section titled “getAccountInviteCodes”getAccountInviteCodes takes an access token of a session made with the
account’s password, of scope com.atproto.access. An app password’s
session is 400 InvalidToken, as are a Basic header and a refresh token;
no token is 401 AuthMissing; an OAuth token is 403 Forbidden
(OAuth: access tokens on every method, and what scopes allow). It answers {codes}: the codes whose
forAccount is the token’s account, each
{"code": "localhost-ab2cd-3efgh", "available": 2, "disabled": false, "forAccount": "<did>", "createdBy": "admin", "createdAt": "<datetime>", "uses": [{"usedBy": "<did>", "usedAt": "<datetime>"}]}uses newest first. includeUsed, by default true, set to false leaves
out the codes with as many uses as available, or more. createAvailable
makes no codes: the server has no codes that accounts earn over time. The
order of the codes is not compared. A deactivated, taken-down or deleted
account’s call is as Account lifecycle says (“Its own
calls”).
createAccount with a code
Section titled “createAccount with a code”describeServer answers inviteCodeRequired, PDS_INVITE_REQUIRED. Where
createAccount’s checks (Accounts) meet the code:
- Required. After step 2, the password’s length, a missing or empty
inviteCodeis400 InvalidInviteCode, before the email is checked. After step 4, the handle’s checks, a code that is not available is400 InvalidInviteCode, before a handle or email another account has (step 5) and beforedid(step 6). - Not required. An empty or missing
inviteCodeis the same as none. A code given that is not available is400 InvalidInviteCodeafter step 6, where step 7 is.
A code is available when the server made it, exactly as given (in upper
case it is another), and fewer accounts were created with it than its
available. An account created with a code is a use of it: {usedBy: the new DID, usedAt: when}. Several createAccounts at once with one code
create no more accounts than it has uses left. A refused createAccount
uses nothing.
Codes, their uses, and what getAccountInviteCodes answers survive the
server being killed, as an account does (Durability): a code it
answered, and a use by an account it answered.
App passwords’ sessions
Section titled “App passwords’ sessions”A session made with an app password, privileged or not, may call every
method an account’s own sessions may, but createAppPassword and
getAccountInviteCodes, and importRepo, requestPlcOperationSignature
and signPlcOperation (Moving an account between servers): those are 400 InvalidToken for
it, whatever the input (Sessions). updateHandle and
submitPlcOperation take it, as the reference does: an app may change the
account’s handle.
Rate limits
Section titled “Rate limits”With PDS_RATE_LIMITS_ENABLED, each limit below lets a key so many points
in a window, the reference’s:
| Limit | Methods | Key | Points | Window |
|---|---|---|---|---|
| signup | createAccount | client address | 100 | 300 s |
| login, day | createSession, and the sign-in of OAuth’s authorization page (OAuth: the authorization server) | identifier, as sent, -, client address | 300 | 86400 s |
| login | the same | the same | 30 | 300 s |
| handle | updateHandle | the token’s DID | 10 | 300 s |
| handle, day | updateHandle | the token’s DID | 50 | 86400 s |
| uploads | uploadBlob | the token’s DID | 1000 | 86400 s |
| writes, hour | createRecord, putRecord, deleteRecord, applyWrites | the token’s DID | 5000 | 3600 s |
| writes, day | the same | the token’s DID | 35000 | 86400 s |
| sync | getRepo | client address | 6000 | 300 s |
requestEmailConfirmation, requestEmailUpdate, requestPasswordReset, resetPassword | as EMAIL.md’s “Rate limits” says | |||
| account deletion | requestAccountDelete, deleteAccount | as LIFECYCLE.md’s “Rate limits” says | ||
| global | every other XRPC method, the admin’s reads _logs and _stats (Operations), the account’s OAuth routes (OAuth: the account's own sessions and devices) and passkey routes (Passkeys), and paths under /xrpc/ the server does not serve, which it forwards (Proxying, service auth and preferences) | client address | 3000 | 300 s |
A call costs one point of each limit of its method and of global, but for
writes: createRecord costs 3 of each writes limit, putRecord 2,
deleteRecord 1, and applyWrites 3 for each create, 2 for each update and
1 for each delete in it, and nothing of them for an empty batch.
refreshSession, deleteSession, app passwords and describeRepo, among
others, have only global; getRepo has only sync. /.well-known/ and
other paths outside /xrpc/, and a method called with the other HTTP
method, cost nothing.
OAuth’s sign-in is not XRPC: it costs one point of each login limit and
nothing else, and is refused as OAuth: the authorization server says once past one (“Rate
limits” there). A createSession and a sign-in of the same identifier from
the same address count together.
- When. A call to a method the server serves costs its points once its
parameters, its token and its input have been checked, before anything
else the method checks: input the lexicon refuses, a body too big, and a
bad token cost nothing; a handle already taken, a wrong password, an
account not found, and 201 writes do. A path under
/xrpc/the server does not serve costs its point first, before it is forwarded or refused, and before anything is fetched for it: itsatproto-proxytarget is resolved, and an OAuth token looked at, only once it has paid. A method the server serves by asking another service (getProfile,getPreferences,getFeedand the others Proxying, service auth and preferences lists) costs its point once its token, and what an OAuth session’s scope needs of the service it goes to, are checked, before anything goes out. The space authority’s methods (createSpace,getSpace,updateSpace,deleteSpace,removeWriter,putMembers,removeMembers,listMembers,exportSpaceMeta,importSpaceMeta) are no different: input the lexicon refuses, or animportSpaceMetaof anotherContent-Type, costs nothing; a policy of no type the server keeps, a space not the caller’s, a space not found, and an archive that does not read do. So withimportRepo: anotherContent-Typeor a body too big costs nothing, and an archive that does not read, another account’s, or a space not found does. A call whose token is service auth (notifyCredentialsRevoked,notifyRepoUpdate), a delegation token or a client attestation (authorizeSpaceSync), or a space credential (the space methods that take one, the space repo’s reads among them) costs its points before anything is fetched to check that token: once the checks its page puts before its issuer’s DID document (or attestation issuer’s metadata) is read have passed, and before it is read. Those earlier refusals (no token, one that is not a JWT, anlxmnot the method’s, anissthat is not a DID, input the lexicon refuses where it is checked first) cost nothing; any refusal after costs its points: an issuer whose document cannot be read, a signature that does not verify, a credential’s HTTP signature. Over its limit, such a call is429with nothing fetched. - Over. A call that takes a limit past its points is
429 RateLimitExceededand does nothing else; it still costs its points, against every limit of its method. - Windows. Each limit’s window for a key starts at the key’s first call that costs a point, and lasts the window’s seconds; its points are then all back. Limits are kept in memory: a restart starts them afresh.
- The client address is the connection’s address, unless that address
is one of
PDS_TRUSTED_PROXIES: then it is read fromX-Forwarded-For, as those proxies report it: the last address in the header that is not one ofPDS_TRUSTED_PROXIES, reading from the end; the first if all are; and the connection’s address with no header, or one whose last entry is not an address. A header from any other connection is ignored: a client that reaches the server directly cannot choose its key. An IPv4 address in IPv6 form (::ffff:203.0.113.1) is the IPv4 address. WithPDS_TRUSTED_PROXIESthe reference’s own list,127.0.0.0/8,::1/128, 169.254.0.0/16,fe80::/10,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7, the server reads the header as the reference does:X-Forwarded-For: 203.0.113.1, 10.0.0.5from127.0.0.1is203.0.113.1, and203.0.113.1, 198.51.100.7is198.51.100.7. The reference trusts that list always (Express’strust proxyofloopback,linklocalanduniquelocal): it reads the header of a connection from a loopback or private address, and keys a connection from a public address by that address, whatever its header says. This server trusts no proxy unless told: behind one, setPDS_TRUSTED_PROXIESto its address.
Every answer of a call that cost points, error or not, has these headers, from the limit with the fewest points left, the first in the table’s order where two tie:
| Header | Value |
|---|---|
RateLimit-Limit | its points |
RateLimit-Remaining | the points it has left, 0 at least |
RateLimit-Reset | when its window ends, in whole seconds since the epoch, rounded down |
RateLimit-Policy | <points>;w=<window in seconds>, as 100;w=300 |
Access-Control-Expose-Headers | RateLimit-Limit, RateLimit-Reset, RateLimit-Remaining, RateLimit-Policy |
A 429 has them from the limit it went past, the first in the table’s
order if more than one, and Retry-After, the seconds until that window
ends, rounded up, with , Retry-After added to
Access-Control-Expose-Headers.
An answer that exposes headers of its own, as a space repo’s
Atproto-Space-Commit or Atproto-Space-Record, Signature-Input and
Signature (The space repo), names them first,
then these.
Through MCP, a tool call costs what its method’s call costs, keyed as that
call would be; over a limit, it is the tool execution error
{error: "RateLimitExceeded"}. Without PDS_RATE_LIMITS_ENABLED, no call
costs anything, and no answer has these headers.
OAuth access tokens
Section titled “OAuth access tokens”A call with an OAuth access token (OAuth: access tokens on every method, and what scopes allow) costs what the same
call with the account’s password session costs, keyed by the token’s DID in
the same buckets: writes, uploads and handle changes made with a password
session and with OAuth tokens of the account count together. A call refused
for its proof, its token, or a scope checked with the token (getSession
with a bad proof, listAppPasswords or getAccountInviteCodes, never
allowed to OAuth, an uploadBlob of a media type the scope does not allow)
costs nothing, not even of global, but a call to a path the server does
not serve, which pays its point before its token is looked at (above); a
write refused for its scope costs a
write’s points, as its scope is checked with its input. Its answers carry
the headers above, and, as every answer to a call whose token and proof
passed, its DPoP-Nonce; a 429 too. OAuth’s own endpoints and pages are
not XRPC, and cost nothing of these limits but OAuth’s sign-in, which
costs the login limits (above, and OAuth: the authorization server, “Rate limits”).
Passwords
Section titled “Passwords”A password hash (scrypt, at createAccount, createSession,
createAppPassword, resetPassword and OAuth’s sign-in) is costly by
design, so:
-
At most as many are computed at once as the machine has cores; the rest wait their turn. They run on threads of their own: no write, fsync or blob read waits behind them. Every hash the server computes, for any method or page, is one of these.
-
createSessionand OAuth’s sign-in compute the same hashes for an identifier no account has as for one an account has, and at most two whatever the number of the account’s app passwords.Note: so their time does not show which identifiers are accounts’.
-
createSessionanswers no sooner than 350 ms after its input was checked, whether it succeeds or not, as the reference does; OAuth’s sign-in no sooner than 400 ms, as the reference’s does (OAuth: the authorization server).
Sessions and app passwords
Section titled “Sessions and app passwords”- A session past its expiry is dropped: when the account’s sessions are
next touched, by
createSession,refreshSession,deleteSessionorrevokeAppPassword, and when the account is first used after the server starts. - An account keeps at most 100 sessions. A new one that would make 101,
by
createSession,createAccountorrefreshSession, drops the account’s sessions that expire soonest, the old token of a refresh in its two-hour grace first, until there are 100. Expiries are whole seconds: the server may choose which of several that expire in the same second goes. A dropped session’s refresh token is400 ExpiredToken, as onedeleteSessionended. - An account has at most 50 app passwords.
createAppPasswordof a 51st is400 TooManyAppPasswords, after its token and input are checked and before its name is. - Refreshing a session any number of times leaves the data directory no larger than what the server keeps and a constant of slack: the settled bound of The store: what is kept, the backfill window, and the bounds.
-
Quota. The blobs an account holds, referenced by a record or not, may come to
PDS_BLOB_QUOTA_BYTESin all. An upload that would take them past it is400 BlobQuotaExceeded, after its token, type and size are checked (Blobs), and stores nothing. Bytes the account already holds cost nothing again. A blob the account stops holding frees its bytes. -
Unreferenced uploads. An upload no record references is held for
PDS_BLOB_TTL_SECSfrom when it was last uploaded. After that the account no longer holds it: a ref to it is400 BlobNotFound, its bytes count against no quota, and its file, or its object in a bucket (Blobs), is deleted within a minute. A record referencing it within that time keeps it, as Blobs says. This holds across restarts: an upload that outlived its time while the server was down is gone when it starts.Note: the reference never deletes such an upload (it keeps it, unserved, for good).
Before a write, the server checks the free space of the filesystem
PDS_DATA_DIR is on, as at most a second ago. Below PDS_MIN_FREE_BYTES,
the write is 507 InsufficientStorage, after its token and input are
checked and its rate limits counted, and before anything else; it changes
nothing. A write here is every call that keeps something: createAccount,
createSession, refreshSession, deleteSession, createAppPassword,
revokeAppPassword, updateHandle, createRecord, putRecord,
deleteRecord, applyWrites, uploadBlob, com.atproto.repo.importRepo
(Moving an account between servers), createInviteCode, createInviteCodes and
putPreferences; and of the spaces (SPACES*.md),
com.atproto.space’s createRecord, putRecord, deleteRecord,
applyWrites, clearRecords, createSpace, updateSpace, deleteSpace,
removeWriter, importSpaceMeta, importRepo, authorizeSpaceSync (it
spends a delegation token, and keeps a registration), notifyCredentialsRevoked
and notifyRepoUpdate, and com.atproto.memberspace’s putMembers and
removeMembers. OAuth keeps things too, and is held to the
same floor as OAuth: the authorization server says (“Free space”): a PAR kept, the authorization
page and its API, the token endpoint and revocation; a call with an OAuth
token is a write or a read as the same call with a password session is.
Reads go on as before, and the firehose too.
The server never aborts on a failed read or write of its data. A write
whose append or file fails all the same (the disk filled between the check
and the write, or no file descriptor was left) is 500 InternalServerError and leaves nothing of itself: the log it was appended
to is cut back to before it, and the next write goes on from there. A
createAccount whose account’s log cannot be made writes nothing to the
server’s other logs either: the account does not exist, then or after a
restart.
At start the server makes PDS_DATA_DIR mode 0700, whatever it was.
Every directory it makes in it is 0700, and every file 0600, whatever
the umask: the JWT key, the logs, which hold every account’s signing key
and password hash, and the blobs.
Open files and threads
Section titled “Open files and threads”What the server holds open does not grow with the number of accounts, but
with the file descriptors the process may have. As it starts it raises its
limit of them (RLIMIT_NOFILE) to the most it is allowed, the hard limit,
and a share is a quarter of that, no fewer than 16 and no more than
4096: 64 under a limit of 256.
- At most a share of accounts’ logs are open at once; the rest are opened when needed, and the least recently used closed to make room. Each open log is one file descriptor, and is synced through it.
- At most a share of accounts’ tables are open at once, each one file descriptor: a table is opened again when it is next read, and the least recently read closed to make room. A repository or a space repo being sent holds its table’s file until it is sent.
- At start, the accounts are recovered on at most as many threads as the machine has cores. A thread or a file it cannot have is waited for or retried, never a panic.
So the server starts, and serves every account, with any number of accounts under a limit of 256 file descriptors.
Firehose
Section titled “Firehose”- A client sends nothing a subscription reads. A message from it of up to
4096 bytes is ignored, as the reference ignores every one. A frame or
message longer than that closes the connection with close code
1009, read as far as its header: the rest is not read. So a client still sending a long message when the connection closes may see it end with no close frame (1006). - One client address (as rate limits read it) may hold 16 subscriptions
at once, and the server 1024 in all. One more is
429 RateLimitExceeded, as XRPC answers it, before the upgrade. A subscription closed by either end, or whose connection is lost, is no longer held.
The PLC directory
Section titled “The PLC directory”-
Documents. The server keeps the DID document of each of its accounts as it last fetched it from the directory, and serves it in
describeRepoforPDS_DID_CACHE_SECS; after that, the nextdescribeRepofetches it again. When the server posts an operation for a DID, the account’s genesis or a handle change, it fetches the document after, and serves that one from then on. One DID’s document is fetched at most once at a time: calls that want it meanwhile wait for that fetch. WithPDS_DID_CACHE_SECS=0, everydescribeRepofetches it. -
At once. At most 8 requests to the directory are in flight at once, of every kind: posting operations, reading logs and documents, and settling a handle change after a restart (Identity). Another waits for one to end; one that has waited 15 s is answered as if the directory could not be reached. Only the directory at
PDS_PLC_URLtakes these slots. -
Connections. A read from the directory, of a document or a log, goes over a connection an earlier read left open, if the directory keeps one open; the server keeps one unused for up to 90 seconds. A read that fails on its way, as when the directory closes that connection just as the read is sent, is sent once more over a connection of its own. A post goes over a connection of its own, which no request used before it.
Note: a read changes nothing, so sending it again is safe, and a connection kept saves its setting up, a round trip and a TLS handshake to a directory across the world. A post that fails on its way may have been taken, so it is never sent where the directory may be closing the connection under it.
-
did:webdocuments are not the directory’s: wherever the server reads one (a service a request is forwarded to, Proxying, service auth and preferences; an issuer of service auth, a delegation token or an attestation, a managing app or a syncer,SPACES*.md), it is fetched from its own host, at most 16 at once across the server, apart from the directory’s 8. Another waits for one to end; one that has waited 10 s is as a document that cannot be fetched.Note: so no number of slow
did:webhosts keeps the server from the directory.
Requests out
Section titled “Requests out”Every request the server sends to a URL others name (Proxying, service auth and preferences, “SSRF
protection”: forwarded requests, did:web documents, OAuth clients’
documents, spaces’ notifications) takes one of 256 slots, held until its
answer is read or given up: at most 256 are in flight at once. Another waits
for one to end; one that has waited 10 s is as a request that got no
answer: 502 UpstreamFailure for a forwarded request, a document that
cannot be fetched, a notification failed for now. How much of an answer is
read, and for how long, is in Proxying, service auth and preferences.
Timeouts
Section titled “Timeouts”- A connection that has not sent a whole request head within 10 s of opening, or of the last answer on it, is closed.
- A request whose body sends nothing for 30 s is closed, with no answer.
- A subscription, once upgraded, has neither.
getBlocks
Section titled “getBlocks”getBlocks costs what the CIDs it names cost, not what the repository
holds: each CID is looked up in an index of the repository’s blocks, and a
CID it does not hold is found missing without reading the tree.
How it is checked
Section titled “How it is checked”harness/checks/limits.mjs. Every run starts the server with
PDS_ADMIN_PASSWORD the reference’s, PDS_TRUSTED_PROXIES the list the
reference trusts (above), so that both read the harness’s
X-Forwarded-For alike, and, but for --limits,
PDS_RATE_LIMITS_ENABLED=false and PDS_DID_CACHE_SECS=0, as the
reference runs without rate limits and the harness has it fetch a document
again after each change. In every run, against the reference:
applyWritesof 201 to 250 writes, with and without other faults, and of exactly 200;createRecord,putRecord,applyWrites,deleteRecordandcreateAppPasswordwith bodies at their limit and one byte over, sent with aContent-Lengthand chunked.- Invite codes, with codes not required:
createInviteCodeandcreateInviteCodeswith the admin’s auth, wrong auth, a token, or none, and wrong input;createAccountwith a code that is available, used up, of no uses, never made, or empty; andgetAccountInviteCodesof each account, withincludeUsedor not, with an app password’s session, or none. Codes are named on each side by the order they were made, as DIDs are, and the codes listed compared sorted by those names; each must be of the form above, and itscreatedAtandusedAtwithin a second of the request. - An app password’s session, privileged or not, on
updateHandle,createAppPasswordandgetAccountInviteCodes. createSessionwith an identifier no account has, a wrong password, and the right one: each answer, on each side, no sooner than 350 ms after it was sent; and OAuth’s sign-in likewise, no sooner than 400 ms, and with a body one byte past 100 KiB,413(OAuth: the authorization server).- OAuth’s sign-in and PAR with a body one byte past 100 KiB, a sign-in of
a few bytes refused for its CSRF token, and
createRecordone byte past its cap, each sent with aContent-Lengthon a connection of its own: on the server the connection answers/xrpc/_healthsent on it 100 ms later; on the reference, that, or the answer saysConnection: close. Statuses compared.
With --crash-every, after each restart, the codes each account lists, and
a code made before the kill, used after it.
node compare.mjs --invites -- <server> starts the reference with invite
codes required and the server with PDS_INVITE_REQUIRED=true, and compares
describeServer, createAccount without a code and with a code that is
not available at each of its checks, codes of several uses, used up and of
none, several createAccounts at once with a code of one use, and
getAccountInviteCodes after.
node compare.mjs --limits -- <server> starts the reference with its rate
limits and the server with PDS_RATE_LIMITS_ENABLED=true, both with
PDS_BLOB_UPLOAD_LIMIT 6291459 (6 MiB and 3 bytes), and holds the server
to the reference:
- each limit of the table, sent from client addresses of its own in
X-Forwarded-Foruntil it is past:createAccountrefused for a handle already taken,createSessionwith a wrong password, by the identifier in another case and from another address,updateHandleto a reserved handle,uploadBlob,applyWritesof 200 creates,describeServerforglobal, andrefreshSession, a path not served, a method forwarded andgetPreferencesonceglobalis past; a method forwarded with a token and without,getProfile,putPreferencesandgetPreferences, eachglobal’s (Proxying, service auth and preferences); input the lexicon refuses, which costs nothing; and addresses in a chain; and Email’s:requestEmailConfirmation16 times from one account, then from another address, andrequestEmailUpdatethe same on that account, its limits apart;requestPasswordReset51 times from one address, by an account’s email and by one no account has, then from another; andresetPasswordwith a token never made, 51 times from one address, then from another; and Account lifecycle’s:requestAccountDelete16 times from one account, then from another address, anddeleteAccountwith a token never mailed, 51 times from one address, then from another. Status,errorand the headers above are compared,RateLimit-ResetandRetry-Afterto within 2 seconds. - with OAuth (
harness/checks/oauth-limits.mjs): OAuth’s endpoints, pages and metadata, 50 times each from one address and 3100 PARs, thendescribeServerfrom it; writes, uploads and handle changes by password and with OAuth tokens of one account, and refused for their scope; calls refused for their proof, token or scope, betweendescribeServers; and 3001getSessions with an OAuth token from one address, then one with a bad proof; then a call forwarded with aDPoPtoken never given, whoseatproto-proxynames adid:webthe check serves:429, with nothing fetched of thatdid:webon either side. Whether there is aDPoP-Nonce, andWWW-Authenticate’s error, are compared too. - a call forwarded to a
did:webwhose document is a redirect to a good one: on both sides500, the redirect not followed. describeServer’sblobUploadLimit; anduploadBlobof a body one byte past 5 MiB, of one at the limit and of one a byte past it, each sent with aContent-Lengthor chunked, the answers compared whole.
and then to this page alone:
- the data directory, made
0755before the server starts: after the run, it is0700, and every directory in it0700and file0600; - the 101st session of an account, made by refreshing, drops the one that expires soonest, whose refresh came a second before the others’; the 51st app password is refused;
- with
PDS_BLOB_UPLOAD_LIMITas above, a spaceimportRepo, sent asapplication/vnd.dasl.star, of a body one byte past 5 MiB, which is no archive,400 InvalidRepoFile, and of one a byte past the limit,413 PayloadTooLarge; - with
PDS_BLOB_QUOTA_BYTESandPDS_BLOB_TTL_SECSset small: an upload past the quota, one of bytes already held, an upload referenced in time and one not, which isBlobNotFoundafter its time and frees its quota, and after a restart too; - restarted with
PDS_MIN_FREE_BYTESabove any disk’s free space: every write above is507, reads answer (getPreferencesamong them), and the server keeps running; then restarted without it, writes land; and of OAuth, a PAR and a refresh507 temporarily_unavailable, agetSessionwith an OAuth token answered; - restarted without
PDS_TRUSTED_PROXIES, threedescribeServers withX-Forwarded-Fors of their own count in one bucket, the connection’s; trusting127.0.0.1alone,X-Forwarded-For: a, 10.0.0.5is10.0.0.5’s; - restarted with
PDS_ADMIN_PASSWORDempty,createInviteCodewithadmin:and with the usual password, each401 AuthenticationRequired; - OAuth’s sign-in in the login limits: 20 wrong passwords by
createSessionand 10 by the sign-in, for one identifier from one address, then the right one429by either, and taken in upper case and from another address; 1000 PARs kept from one address, the 1001st429, and one from another address kept (OAuth: the authorization server); notifyCredentialsRevokedwith service auth from adid:webthe check serves: refused for its signature withRateLimit-Remaining2999, and, onceglobalis past for its address,429with nothing fetched;- 20
notifyCredentialsRevokeds whosedid:webissuers take the connection and never answer, and meanwhile acreateAccountanswered within 5 s; - a call forwarded to a
did:webwhose document is 70000 bytes,500; and to one whose service answers 17 MiB,502 UpstreamFailure; - 256 calls forwarded to the AppView, each answered its headers and then
a byte a second: a 257th is
502 UpstreamFailure9.5 to 13 s after it was sent, never reaching the AppView; once the 256 are let finish, each200, a call forwarded is200within 5 s; - on a subscription, messages of 5 bytes and 1 KiB ignored, events still
sent; on the server’s, one of 4096 bytes ignored, one of 4097 closing it
with
1009, and one of 2 MiB closing it; 16 subscriptions from one address, and a 17th refused, and one from another address taken; - the server’s requests to the directory, through a proxy that counts and
delays them and records what each connection carried: none for
describeRepoof an account it made, the new handle’s document at once afterupdateHandle, no more than 8 in flight while 24 accounts are made at once, and, of 6 accounts made one after another, each post the first request on a connection of its own and the reads over fewer connections than there are reads; and threeauthorizeSpaceSyncs, each with a delegation token fromgetDelegationTokenof an account here, of a public space another account here made: each200, with nothing read of the user’s document; and one with a tokengetDelegationTokengave an account deleted since (Account lifecycle), its document read (Spaces: credentials, “Issuers’ keys”); - a connection that sends half a request head, closed within 15 s, and a request whose body stops, closed within 40 s;
- 300 accounts made, each given three records of 140000 bytes, past what
a log holds before it is compacted into a table (The store: what is kept, the backfill window, and the bounds), the
server killed and started again under
ulimit -n 256: it serves, every account answersgetLatestCommitandgetRecordof the first of those records, as written, and an early and a late account take writes; 20 more accounts made under the limit are each200or500, the server never exits, and after a restart the ones answered500do not exist.
The server’s own tests check what the harness cannot see: the hashes
computed at once and their threads, OAuth’s sign-in’s among them, expired
sessions dropped, a write that fails for a full disk leaving nothing of
itself, the 2000000-byte commit, the threads at start, that getBlocks
reads no more of a large repository than of a small one, the 16 did:web
fetches at once, PAR’s 20000 requests from all addresses, and the DPoP
proofs held in memory alone.