ActivityPub Inbox Processing#

Overview#

InboxProcessorService is the BullMQ job processor for Misskey's ActivityPub inbox queue. It runs as Stage 2 of a two-stage pipeline: Stage 1 (ActivityPubServerService.inbox()) validates the HTTP request and enqueues the activity; Stage 2 performs cryptographic verification and dispatches the activity for processing 1.

The inbox queue runs at up to 16 concurrent workers (configurable via inboxJobConcurrency) with a 32/sec rate limit, using exponential backoff with a 1-minute base and 8-hour maximum 2.

Processing Lifecycle#

The process() method executes the following stages in order:

1. Pre-flight Checks 3#

• Extracts the hostname from signature.keyId (punycoded) and rejects blocked/non-allowed federation hosts 4.
• Rejects legacy acct: keyId format 5.
• For Delete activities targeting an actor, checks whether the actor exists locally; if not, skips silently to avoid unnecessary processing 6.

2. Remote Actor Resolution 7#

Actor resolution proceeds in two steps:

1. Key-first lookup — calls getAuthUserFromKeyId(signature.keyId), which queries the UserPublickey table by keyId (with a 12-hour cache). This works for actors already known to the local instance 8.

2. Actor URI fallback — if the keyId lookup returns null, calls getAuthUserFromApId(activity.actor), which resolves the actor URI via ApPersonService.resolvePerson() (will fetch remotely if needed) and retrieves the public key from a separate cache 9.

If either resolution raises a StatusError, error classification applies (see below). If resolution still fails, the job is permanently discarded via Bull.UnrecoverableError 10.

Note: PR #13470 (merged) proposed passing signature.keyId as a hint to getAuthUserFromApId() to improve key selection for actors with multiple keys (e.g., EdDSA additionalKeys). That PR's summary indicates the two-step lookup was collapsed into a single getAuthUserFromApId(actor, keyId) call; the snapshot above reflects an earlier version of the file.

3. HTTP Signature Verification 11#

• Verifies the signature via httpSignature.verifySignature(signature, authUser.key.keyPem) 12.
• Also asserts authUser.user.uri === activity.actor — the signing key owner must match the declared actor 13.
• If HTTP Signature fails but an embedded activity.signature object exists, falls back to LD-Signature (RsaSignature2017); see below 14.
• If HTTP Signature fails and no LD-Signature exists → Bull.UnrecoverableError 15.

4. LD-Signature Fallback 16#

Only RsaSignature2017 is supported; other types are immediately discarded 17.

Flow:

1. Strips activity.signature, JSON-LD compacts the activity, checks for forbidden directives 18.
2. Resolves the LD signer via getAuthUserFromKeyId(ldSignature.creator) 19.
3. Verifies via JsonLdService.verifyRsaSignature2017() 20.
4. Re-asserts authUser.user.uri === activity.actor and re-checks federation allowlist for the LD signer's host 21.

Bug fix (PR #17615): Prior to this fix, non-JsonLdError exceptions thrown inside verifyRsaSignature2017 would escape the catch block unwrapped, causing Bull to spuriously retry the job and emit error-level stack traces. The fix wraps all non-UnrecoverableError exceptions from that block into Bull.UnrecoverableError 22.

5. Activity ID Host Validation 23#

After signature is confirmed, asserts that activity.id is a string whose hostname matches the verified signer's host. Mismatches → Bull.UnrecoverableError.

6. Activity Dispatch 24#

Calls ApInboxService.performActivity(authUser.user, activity) 25.

The catch block around this call swallows several IdentifiableError cases — returning a string instead of throwing — to prevent unnecessary retries or failures for semantically valid but locally-skippable conditions:

All other exceptions propagate and trigger Bull's retry machinery 26.

7. Instance Stat Updates 27#

Run asynchronously via process.nextTick(): updates latestRequestReceivedAt, unsuspends auto-suspended instances, and triggers instance metadata refresh. Uses a CollapsedQueue to batch updates (5-minute window in production) and avoid thundering-herd writes 28.

Error Classification: StatusError vs Bull.UnrecoverableError#

StatusError (packages/backend/src/misc/status-error.ts) wraps HTTP-layer errors from remote fetches:

• isClientError: true for 4xx status codes.
• isRetryable: true when NOT a client error, or when the status is 429 (Too Many Requests).

Decision table for getAuthUserFromApId() errors in the inbox 29:

HTTP 429 was explicitly made retryable in PR #12917 to respect remote rate limits rather than permanently dropping activities.

Key Files#