Support the ActivityPub Media Upload extension

[dahlia]

Client-to-server support arrived in Fedify 2.2 with setOutboxListeners() (#430), which lets an application accept ActivityPub C2S activities without exposing a bespoke API. But posting an activity is only half of what C2S clients need: they also upload binary media (images, video, audio), and that traffic deliberately does not travel through POST /outbox. The ActivityPub Media Upload extension exists precisely to fill this gap, so it is the natural next step now that the posting surface is in place. This implements it (#754).

Why it mirrors the outbox

The API intentionally follows the shape that setOutboxListeners() established, because the two endpoints are the same kind of thing: an authenticated C2S entry point whose server-side behavior is the application's business, not the framework's. setMediaUploader(path, callback) returns a setter with a single .authorize() hook, authorization runs before the callback, and a rejection produces 401 (overridable through the federation-level onUnauthorized), exactly as on the outbox. Keeping the surface familiar means anyone who already wired up outbox listeners can reason about media upload without learning a second mental model, and it preserves Fedify's consistent division of labor across C2S: the framework routes and authorizes, the application decides what to store and serve.

Why the endpoint is advertised explicitly rather than auto-injected

The endpoint is exposed through a new Context.getMediaUploaderUri(identifier), and the actor dispatcher places it under the new Endpoints.uploadMedia property itself:

federation.setActorDispatcher("/users/{identifier}", (ctx, identifier) =>
  new Person({
    id: ctx.getActorUri(identifier),
    endpoints: new Endpoints({
      uploadMedia: ctx.getMediaUploaderUri(identifier),
    }),
  }));

An earlier design auto-injected endpoints.uploadMedia into the actor document. It was dropped because it would be inconsistent with the rest of the framework: getInboxUri(), getOutboxUri(), and their siblings only expose URLs, while deciding what actually appears on the actor document is the actor dispatcher's responsibility. Silently writing one endpoint but not the others would be a surprising special case that erodes that rule. Instead, the framework warns at runtime, and @fedify/lint warns statically, when an uploader is registered but the actor fails to advertise the matching URI: the convention stays uniform, and the omission is still caught.

Why the callback returns Object | URL

The return type encodes the one decision the framework cannot make on the application's behalf: whether the uploaded resource is fetchable immediately or is still being processed. Returning an Object means “ready now”, so Fedify answers 201 Created with Location pointing at the object's id; returning a URL means “it will live here once processing finishes” (for example after transcoding), so it answers 202 Accepted with Location set to that URL. This is purely the HTTP-level distinction between 201 and 202, independent of whether the callback happens to be asynchronous. The type therefore accepts a plain value or a Promise, matching how every other value-returning Fedify callback behaves, rather than forcing a Promise return just because the realistic implementation awaits storage.

Why missing actors and id-less results are rejected

Two failure modes are closed off before they can turn into a misleading success. First, the handler resolves the actor dispatcher up front and returns 404, without ever invoking the callback, when the actor is absent or a Tombstone. The actor dispatcher is Fedify's source of truth for which actors exist, just as on the outbox path; without this guard an application could store media and return 201/202 for a user that never existed or was deleted. Second, an Object returned without an id produces 500 instead of a 201 that lacks Location. A 201 Created with no Location is unusable to the client (it cannot discover the object it just created), so failing loudly is strictly better than succeeding uselessly.

How the request is handled

The endpoint is registered as a mediaUploader route and handled before JSON-LD content negotiation, because a multipart/form-data upload has nothing to negotiate; this placement also lets any non-POST method resolve cleanly to 405 instead of a confusing negotiation 406. From there the handler runs body-state guards, a content-type check, actor resolution, authorization, parsing, and the callback. It deliberately resolves the actor before authorization, unlike the outbox: a request for a nonexistent or deleted actor receives 404 regardless of the authorize hook, and the upload body is not buffered for a bogus identifier (the actor's existence is already public via its actor URI, so this leaks nothing new). A new media_upload value in the fedify.endpoint metric attribute keeps these requests distinguishable in telemetry rather than lumping them into not_found.

Why the linting is shaped the way it is

Runtime warnings only fire once the offending code path actually executes, so the three new @fedify/lint rules move the same guarantees to development time. The two actor-side rules (actor-upload-media-property-required and actor-upload-media-property-mismatch) reuse the existing property-checking machinery and therefore behave like the established sharedInbox rules. The object-side rule (media-uploader-object-uri-required) is where the real care went, because “the returned id must derive from getObjectUri()“ is easy to state and easy to get subtly wrong. It inspects the returned expressions specifically, not the whole callback body, so a getObjectUri() call sitting in a dead branch cannot excuse a hard-coded return. For object returns it judges the effective id alone (the last id property wins, and a trailing spread is treated as unsafe), so a getObjectUri() call in some unrelated property such as url cannot launder a hard-coded id. And it requires the call's receiver to be the callback's own context parameter, so helper.getObjectUri(...) on some other object is not mistaken for the genuine one.

What is intentionally left to the application

Consistent with the philosophy adopted in #430, several responsibilities stay with the developer: storing the file, serving the uploaded object back as fetchable ActivityStreams (that is what setObjectDispatcher() is for), wrapping the result in a Create, and capping the upload size. On that last point, Fedify reads the multipart body into memory and imposes no size limit of its own, the same as the inbox and outbox. Rather than bolt on a one-off limit option, the documentation directs applications to enforce a maximum at the deployment layer (for example a reverse proxy's body-size setting), which is where Fedify already expects that boundary to sit.

Documentation

A new docs/manual/media-upload.md walks through the whole flow (registering the uploader, the 201/202 semantics, advertising the endpoint, and the error responses), and getMediaUploaderUri(), the endpoints.uploadMedia property, and the three lint rules are documented next to their existing siblings.

[netlify]

✅ Deploy Preview for fedify-json-schema canceled.

Name	Link
🔨 Latest commit	8fdd9a0
🔍 Latest deploy log	https://app.netlify.com/projects/fedify-json-schema/deploys/6a4f57bc2f43370008a2cfb3

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds ActivityPub media upload support across federation APIs, request handling, vocab, lint rules, tests, docs, and changelog entries. It introduces the media upload endpoint, URI helpers, endpoint advertisement, and validation around callback and actor configuration.

Changes

ActivityPub Media Upload feature

Layer / File(s)	Summary
Contracts and schema packages/fedify/src/federation/callback.ts, context.ts, federation.ts, packages/vocab/src/endpoints.yaml, vocab.test.ts	Adds the media uploader callback type, context URI helper, federation API surface, and the uploadMedia vocabulary property with round-trip coverage.
Builder registration and validation packages/fedify/src/federation/builder.ts, builder.test.ts	Adds media uploader builder state, route registration, build-time wiring, actor advertisement warnings, and path validation tests.
Request handling and routing packages/fedify/src/federation/handler.ts, middleware.ts, middleware.test.ts, packages/fedify/src/testing/context.ts, packages/testing/src/context.ts, packages/testing/src/mock.ts	Adds the media upload handler, routes POST requests to it, assigns the media_upload endpoint category, exposes ContextImpl.getMediaUploaderUri(), and extends testing helpers and middleware tests for request flow and warnings.
Lint rules and registration packages/lint/src/lib/const.ts, rules/*upload-media*, media-uploader-object-uri-required.ts, index.ts, mod.ts, oxlint.ts, tests/*, README.md	Adds uploadMedia rule metadata, three rule modules, plugin registration, and rule tests for media uploader validation.
Documentation and changelog docs/manual/media-upload.md, actor.md, context.md, lint.md, opentelemetry.md, .vitepress/config.mts, CHANGES.md	Adds the media upload manual page, sidebar entry, related docs, OpenTelemetry update, lint docs, and changelog entries.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• Support ActivityPub Media Upload extension via setMediaUploader() #754: Requests the same setMediaUploader() / endpoints.uploadMedia media upload feature implemented here.

Possibly related PRs

• fedify-dev/fedify#758: Shares route-template validation and RouterError plumbing that the new media uploader route registration relies on.

Suggested labels: type/feature, component/integration, activitypub/interop

Suggested reviewers: 2chanhaeng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding ActivityPub Media Upload support.
Description check	✅ Passed	The description is detailed and directly describes the media upload extension changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dahlia]

@codex review

[gemini-code-assist]

Code Review

This pull request introduces support for the ActivityPub Media Upload extension, allowing servers to accept client-to-server media uploads. It adds the setMediaUploader method to register a multipart/form-data upload endpoint, updates the Context to build the endpoint URI, and exposes the Endpoints.uploadMedia property. Additionally, three new lint rules are added to @fedify/lint to validate correct configuration. A review comment suggests adding a defensive check in the request handler to prevent a potential runtime crash if the media uploader callback returns a nullish value.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b6784f2edb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codecov]

Codecov Report

❌ Patch coverage is 81.22905% with 168 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...nt/src/rules/media-uploader-object-uri-required.ts	77.41%	41 Missing and 48 partials ⚠️
packages/fedify/src/federation/handler.ts	82.92%	29 Missing and 6 partials ⚠️
packages/testing/src/mock.ts	10.34%	26 Missing ⚠️
packages/fedify/src/federation/builder.ts	79.06%	8 Missing and 1 partial ⚠️
...src/rules/media-uploader-authorization-required.ts	94.33%	3 Missing and 3 partials ⚠️
packages/fedify/src/federation/middleware.ts	93.33%	2 Missing and 1 partial ⚠️

Files with missing lines	Coverage Δ
packages/fedify/src/testing/context.ts	73.75% <100.00%> (+0.33%)	⬆️
packages/lint/src/index.ts	100.00% <100.00%> (ø)
packages/lint/src/lib/const.ts	100.00% <100.00%> (ø)
packages/lint/src/mod.ts	100.00% <100.00%> (ø)
.../src/rules/actor-upload-media-property-mismatch.ts	100.00% <100.00%> (ø)
.../src/rules/actor-upload-media-property-required.ts	100.00% <100.00%> (ø)
packages/testing/src/context.ts	52.33% <100.00%> (+0.49%)	⬆️
packages/fedify/src/federation/middleware.ts	83.68% <93.33%> (+0.11%)	⬆️
...src/rules/media-uploader-authorization-required.ts	94.33% <94.33%> (ø)
packages/fedify/src/federation/builder.ts	62.37% <79.06%> (+0.73%)	⬆️
... and 3 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/fedify/src/federation/handler.ts`:
- Around line 1069-1081: The multipart parsing in handler.ts via
request.formData() has no built-in size or timeout cap, so add a documented
recommendation or configuration hook for deployers to enforce request-size
limits at the reverse-proxy/runtime layer. Update the handling around the
request.formData() path in the federation handler to make the limitation
explicit, and if possible expose a knob or note near the multipart parsing logic
so operators can bound uploads before they reach request.formData().
- Around line 1164-1176: The `handleMediaUpload` success path is missing error
handling around `result.toJsonLd(ctx)`, so a serialization/context-loader
failure escapes uncaught. Wrap the `toJsonLd` call in the same guarded
error-to-response flow used elsewhere in `handler.ts` (the multipart parse,
field validation, and callback failure paths), and convert any thrown exception
into a controlled 500-style response instead of letting it propagate through
`FederationImpl.fetch()`.

In `@packages/fedify/src/federation/middleware.test.ts`:
- Around line 3889-3914: The upload test helper only covers the `object` field
as a `Blob`, so the `handleMediaUpload` plain-string branch is untested. Add a
dedicated test in `middleware.test.ts` that builds a `FormData` with `file` plus
`object` appended as a raw JSON string, then calls the federation upload
endpoint and asserts the request is accepted. Use the existing
`createFederation`, `setActorDispatcher`, and `setMediaUploader` setup to place
the test near the current media upload coverage and explicitly exercise `typeof
objectField === "string"`.

In `@packages/lint/src/index.ts`:
- Around line 66-77: The new rule exports in the lint index are wired into rules
but are not enabled by the recommended config yet. Update recommendedRuleIds in
the index module to include the new rule identifiers alongside actorIdRequired
and actorIdMismatch if they should be part of the recommended preset, and verify
the symbol names match the imported rule modules such as
actorUploadMediaPropertyMismatch, actorUploadMediaPropertyRequired,
collectionFiltering, and mediaUploaderObjectUriRequired.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 517bf533-09de-4a78-bf40-c9661f49ede7

📥 Commits

Reviewing files that changed from the base of the PR and between 7b19967 and b6784f2.

⛔ Files ignored due to path filters (4)

• packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap is excluded by !**/*.snap
• packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap is excluded by !**/*.snap
• packages/vocab-tools/src/__snapshots__/class.test.ts.snap is excluded by !**/*.snap
• packages/vocab/src/__snapshots__/vocab.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (31)

• CHANGES.md
• docs/.vitepress/config.mts
• docs/manual/actor.md
• docs/manual/context.md
• docs/manual/lint.md
• docs/manual/media-upload.md
• docs/manual/opentelemetry.md
• packages/fedify/src/federation/builder.test.ts
• packages/fedify/src/federation/builder.ts
• packages/fedify/src/federation/callback.ts
• packages/fedify/src/federation/context.ts
• packages/fedify/src/federation/federation.ts
• packages/fedify/src/federation/handler.ts
• packages/fedify/src/federation/middleware.test.ts
• packages/fedify/src/federation/middleware.ts
• packages/fedify/src/testing/context.ts
• packages/lint/README.md
• packages/lint/src/index.ts
• packages/lint/src/lib/const.ts
• packages/lint/src/mod.ts
• packages/lint/src/oxlint.ts
• packages/lint/src/rules/actor-upload-media-property-mismatch.ts
• packages/lint/src/rules/actor-upload-media-property-required.ts
• packages/lint/src/rules/media-uploader-object-uri-required.ts
• packages/lint/src/tests/actor-upload-media-property-mismatch.test.ts
• packages/lint/src/tests/actor-upload-media-property-required.test.ts
• packages/lint/src/tests/media-uploader-object-uri-required.test.ts
• packages/testing/src/context.ts
• packages/testing/src/mock.ts
• packages/vocab/src/endpoints.yaml
• packages/vocab/src/vocab.test.ts

[dahlia]

@codex review

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for the ActivityPub Media Upload extension, allowing servers to accept client-to-server media uploads. It introduces the setMediaUploader method to register an upload endpoint, the getMediaUploaderUri method to build the endpoint URI, and a new media_upload metric category. Additionally, three new lint rules are added to @fedify/lint to ensure proper configuration of the media upload endpoint. Feedback on the changes suggests enhancing the unwrapExpression helper in the media-uploader-object-uri-required lint rule to support TSTypeAssertion and ParenthesizedExpression nodes, preventing potential false positives.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a5871f056

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dahlia]

@codex review

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for the ActivityPub Media Upload extension, enabling servers to accept client-to-server media uploads. It introduces setMediaUploader() to register the endpoint, getMediaUploaderUri() to retrieve its URI, and exposes the Endpoints.uploadMedia property. Additionally, three new lint rules are added to @fedify/lint to ensure correct configuration. Feedback on the changes suggests adding a defensive check in the request handler to ensure that the parsed JSON-LD object is not null before passing it to the callback, preventing potential runtime TypeErrors.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc80c9d5cf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dahlia]

@codex review

[dahlia]

@codex review

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for the ActivityPub Media Upload extension, enabling servers to accept client-to-server media uploads. Key changes include adding the setMediaUploader() method to Federation and FederationBuilder to register a multipart/form-data upload endpoint, and adding getMediaUploaderUri() to Context to build the endpoint URI advertised under Endpoints.uploadMedia. Additionally, three new lint rules (media-uploader-object-uri-required, actor-upload-media-property-required, and actor-upload-media-property-mismatch) have been added to @fedify/lint to ensure correct usage. Comprehensive tests, documentation, and vocabulary updates have also been included. There are no review comments, and I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 17cde6a644

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sij411]

Lint-rule edge case:

media-uploader-object-uri-required treats destructured getObjectUri calls as valid, e.g. async ({ getObjectUri }) => getObjectUri(...). However, the real ContextImpl. getObjectUri() method reads this.federation / this.canonicalOrigin, so destructuring the method loses its receiver and should throw at runtime. Unless these context methods are intentionally safe to call unbound, this rule may produce a falsse negative and the test case for destructured getObjectUri may be encouraging broken code. would it be safer to only accept ctx.getObjectUri(...) member calls on the callback's context parameter?

[dahlia]

@sij411 Good catch, thanks. I confirmed at runtime that destructuring getObjectUri off the context throws (TypeError: Cannot read properties of undefined (reading 'federation')), since the method reads this.federation/this.canonicalOrigin; the rule was passing provably broken code. Addressed in cb3ef37: the rule now accepts only ctx.getObjectUri(...) member calls on the callback's context parameter, and the destructured-alias test is inverted to expect a warning.

[dahlia]

@codex review

[dahlia]

/gemini review

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 8fdd9a06a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".