Phase 6: media

Implements PLAN.md Phase 6: the media repository. Clients upload files,
reserve an mxc:// URI and upload to it later, download and ask for
thumbnails, all through the authenticated media endpoints of Matrix 1.11;
other servers download this server's media through the federation media
endpoints, and media uploaded elsewhere is fetched over federation on
first use and kept.

internal/mediaapi is the component. Content goes into a BlobStore named
by its SHA-256, so the same file uploaded twice is stored once and the
hash doubles as the ETag; the metadata that maps an mxc:// URI onto a
blob is in media_repository and media_thumbnails. The local-filesystem
store writes to a temporary file and renames it into place once hashed,
so nothing ever refers to half a file. A storage driver can bring its own
store through storage.BlobProvider, which is where PocketBase's
filesystem abstraction (local or S3) plugs in with Phase 10.

Reserved uploads belong to the user who made them, take one upload,
lapse after a day, and are capped per user; a download of one waits for
its content, woken in memory the moment it arrives, for as long as
timeout_ms allows.

Thumbnails come from a fixed set of configured sizes, so a thousand
requested sizes cannot mean a thousand resizes. They are made on first
request and kept, never enlarge, honour a JPEG's EXIF orientation, and
point at the original when it already fits. The pixel count is checked
from the header before anything is decoded, at most four resizes run at
once, and concurrent requests for the same thumbnail share one.

Remote media is fetched through the signed client: the multipart/mixed
answer of Matrix 1.11, with a fallback to the legacy download endpoint
for servers that answer M_UNRECOGNIZED, and Location redirects followed
by a dialer that refuses loopback, private and link-local addresses.
Concurrent requests share one fetch, detached from the request that
started it. With federation off nothing is fetched, and what was cached
before is still served.

Downloads carry a sandboxing CSP, nosniff, inline Content-Disposition
only for the types the spec lists as safe, and private immutable caching.
The unauthenticated legacy download endpoints are off by default behind
media.legacy_unauthenticated_downloads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

server/internal/clientapi/clientapi.go

@@ -20,6 +20,7 @@ import (
 	"github.com/dariuszjaniak/warp/server/internal/config"
 	"github.com/dariuszjaniak/warp/server/internal/federation"
 	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/mediaapi"
 	"github.com/dariuszjaniak/warp/server/internal/ratelimit"
 	"github.com/dariuszjaniak/warp/server/internal/roomserver"
 	"github.com/dariuszjaniak/warp/server/internal/settings"
@@ -34,6 +35,8 @@ type ClientAPI struct {
 	users         *userapi.API
 	rooms         *roomserver.API
 	sync          *syncapi.API
+	media         *mediaapi.API
+	legacyMedia   bool
 	settings      *settings.Service
 	federation    *federation.Gate
 	remoteProfile RemoteProfiles
@@ -57,6 +60,10 @@ type ClientAPI struct {
 	// loop — the one place where rate limiting makes the load worse rather
 	// than better.
 	limitSync *ratelimit.Limiter
+
+	// limitMedia covers downloads and thumbnails, which a client asks for
+	// in bursts: every avatar in a room list at once.
+	limitMedia *ratelimit.Limiter
 }
 
 // Options configure the component.
@@ -85,6 +92,14 @@ type Options struct {
 	// pretending there is a stream to read.
 	Sync *syncapi.API
 
+	// Media is the media repository. Without it the media endpoints
+	// answer M_UNRECOGNIZED.
+	Media *mediaapi.API
+
+	// LegacyMediaDownloads serves the deprecated unauthenticated download
+	// and thumbnail endpoints too.
+	LegacyMediaDownloads bool
+
 	// Settings is the runtime-settings service; the registration switch is
 	// read from it on every registration attempt.
 	Settings *settings.Service
@@ -138,6 +153,8 @@ func New(opts Options) (*ClientAPI, error) {
 		users:         opts.Users,
 		rooms:         opts.Rooms,
 		sync:          opts.Sync,
+		media:         opts.Media,
+		legacyMedia:   opts.LegacyMediaDownloads,
 		settings:      opts.Settings,
 		federation:    opts.Federation,
 		remoteProfile: opts.RemoteProfiles,
@@ -159,11 +176,12 @@ func New(opts Options) (*ClientAPI, error) {
 		c.limitRoomCreate = ratelimit.New(bucket(opts.RateLimit.RoomCreate))
 		c.limitJoin = ratelimit.New(bucket(opts.RateLimit.Join))
 		c.limitSync = ratelimit.New(bucket(opts.RateLimit.Sync))
+		c.limitMedia = ratelimit.New(bucket(opts.RateLimit.Media))
 	} else {
 		c.limitDefault, c.limitLogin, c.limitRegister =
 			ratelimit.Disabled(), ratelimit.Disabled(), ratelimit.Disabled()
 		c.limitRoomCreate, c.limitJoin = ratelimit.Disabled(), ratelimit.Disabled()
-		c.limitSync = ratelimit.Disabled()
+		c.limitSync, c.limitMedia = ratelimit.Disabled(), ratelimit.Disabled()
 	}
 	return c, nil
 }
@@ -229,6 +247,7 @@ func (c *ClientAPI) RegisterRoutes(r *httputil.Router) {
 
 	c.registerRoomRoutes(r)
 	c.registerSyncRoutes(r)
+	c.registerMediaRoutes(r)
 }
 
 // registerSyncRoutes adds the endpoints the syncapi serves, if there is

server/internal/clientapi/media.go

@@ -0,0 +1,187 @@
+package clientapi
+
+import (
+	"net/http"
+
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/mediaapi"
+	"github.com/dariuszjaniak/warp/server/internal/userapi"
+)
+
+// The media endpoints. Uploads keep their Matrix 1.0 paths under
+// /_matrix/media; downloads and thumbnails are the authenticated
+// endpoints of Matrix 1.11 under /_matrix/client/v1/media. The
+// unauthenticated downloads they replaced are only served when
+// media.legacy_unauthenticated_downloads is on.
+const (
+	mediaV1 = "/_matrix/media/v1"
+	mediaV3 = "/_matrix/media/v3"
+)
+
+// registerMediaRoutes adds the media endpoints, if there is a media
+// repository.
+func (c *ClientAPI) registerMediaRoutes(r *httputil.Router) {
+	if c.media == nil {
+		return
+	}
+
+	// Uploads take the default bucket: they are rare, and each one is
+	// up to media.max_upload_bytes of disk.
+	c.authed(r, "POST "+mediaV3+"/upload", c.limitDefault, c.handleUpload)
+	c.authed(r, "POST "+mediaV1+"/create", c.limitDefault, c.handleCreateMedia)
+	c.authed(r, "PUT "+mediaV3+"/upload/{serverName}/{mediaID}", c.limitDefault, c.handleUploadTo)
+
+	c.authed(r, "GET "+v1+"/media/config", c.limitMedia, c.handleMediaConfig)
+	c.authed(r, "GET "+mediaV3+"/config", c.limitMedia, c.handleMediaConfig)
+
+	c.authed(r, "GET "+v1+"/media/download/{serverName}/{mediaID}", c.limitMedia, c.handleDownload)
+	c.authed(r, "GET "+v1+"/media/download/{serverName}/{mediaID}/{fileName}", c.limitMedia, c.handleDownload)
+	c.authed(r, "GET "+v1+"/media/thumbnail/{serverName}/{mediaID}", c.limitMedia, c.handleThumbnail)
+
+	if c.legacyMedia {
+		c.public(r, "GET "+mediaV3+"/download/{serverName}/{mediaID}", c.limitMedia, c.handleLegacyDownload)
+		c.public(r, "GET "+mediaV3+"/download/{serverName}/{mediaID}/{fileName}", c.limitMedia, c.handleLegacyDownload)
+		c.public(r, "GET "+mediaV3+"/thumbnail/{serverName}/{mediaID}", c.limitMedia, c.handleLegacyThumbnail)
+	}
+}
+
+type uploadResponse struct {
+	ContentURI string `json:"content_uri"`
+}
+
+// handleUpload implements POST /_matrix/media/v3/upload.
+func (c *ClientAPI) handleUpload(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	if err := c.checkUploadSize(r); err != nil {
+		return err
+	}
+	mxc, err := c.media.Upload(r.Context(), upload(r, auth))
+	if err != nil {
+		return mediaapi.HTTPError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, uploadResponse{ContentURI: mxc})
+	return nil
+}
+
+type createMediaResponse struct {
+	ContentURI      string `json:"content_uri"`
+	UnusedExpiresAt int64  `json:"unused_expires_at"`
+}
+
+// handleCreateMedia implements POST /_matrix/media/v1/create: an mxc://
+// URI now, its content later. A client uses it to put a message with an
+// attachment in the timeline before the attachment has finished
+// uploading.
+func (c *ClientAPI) handleCreateMedia(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	mxc, expires, err := c.media.Create(r.Context(), auth.UserID)
+	if err != nil {
+		return mediaapi.HTTPError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, createMediaResponse{ContentURI: mxc, UnusedExpiresAt: expires})
+	return nil
+}
+
+// handleUploadTo implements PUT /_matrix/media/v3/upload/{serverName}/{mediaId}.
+func (c *ClientAPI) handleUploadTo(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	if err := c.checkUploadSize(r); err != nil {
+		return err
+	}
+	err := c.media.UploadTo(r.Context(), r.PathValue("serverName"), r.PathValue("mediaID"), upload(r, auth))
+	if err != nil {
+		return mediaapi.HTTPError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, struct{}{})
+	return nil
+}
+
+// checkUploadSize refuses an upload that says up front it is too large,
+// before a byte of it is read. One that does not say is cut off by the
+// blob store at the same limit.
+func (c *ClientAPI) checkUploadSize(r *http.Request) error {
+	if r.ContentLength > c.media.MaxUploadBytes() {
+		return mediaapi.HTTPError(mediaapi.ErrTooLarge)
+	}
+	return nil
+}
+
+func upload(r *http.Request, auth userapi.Authenticated) mediaapi.Upload {
+	return mediaapi.Upload{
+		UserID:      auth.UserID,
+		ContentType: r.Header.Get("Content-Type"),
+		FileName:    r.URL.Query().Get("filename"),
+		Body:        r.Body,
+	}
+}
+
+type mediaConfigResponse struct {
+	UploadSize int64 `json:"m.upload.size"`
+}
+
+// handleMediaConfig implements GET /_matrix/client/v1/media/config and its
+// deprecated twin under /_matrix/media/v3.
+func (c *ClientAPI) handleMediaConfig(w http.ResponseWriter, _ *http.Request, _ userapi.Authenticated) error {
+	httputil.WriteJSON(w, http.StatusOK, mediaConfigResponse{UploadSize: c.media.MaxUploadBytes()})
+	return nil
+}
+
+// handleDownload implements GET /_matrix/client/v1/media/download/...
+func (c *ClientAPI) handleDownload(w http.ResponseWriter, r *http.Request, _ userapi.Authenticated) error {
+	return c.serveDownload(w, r, false)
+}
+
+// handleThumbnail implements GET /_matrix/client/v1/media/thumbnail/...
+func (c *ClientAPI) handleThumbnail(w http.ResponseWriter, r *http.Request, _ userapi.Authenticated) error {
+	return c.serveThumbnail(w, r, false)
+}
+
+// handleLegacyDownload implements the deprecated, unauthenticated
+// GET /_matrix/media/v3/download/..., honouring its allow_remote=false.
+func (c *ClientAPI) handleLegacyDownload(w http.ResponseWriter, r *http.Request) error {
+	return c.serveDownload(w, r, r.URL.Query().Get("allow_remote") == "false")
+}
+
+// handleLegacyThumbnail implements the deprecated, unauthenticated
+// GET /_matrix/media/v3/thumbnail/....
+func (c *ClientAPI) handleLegacyThumbnail(w http.ResponseWriter, r *http.Request) error {
+	return c.serveThumbnail(w, r, r.URL.Query().Get("allow_remote") == "false")
+}
+
+func (c *ClientAPI) serveDownload(w http.ResponseWriter, r *http.Request, localOnly bool) error {
+	wait, err := mediaapi.WaitParam(r)
+	if err != nil {
+		return err
+	}
+	content, err := c.media.Download(r.Context(), r.PathValue("serverName"), r.PathValue("mediaID"),
+		mediaapi.FetchOptions{Wait: wait, LocalOnly: localOnly})
+	if err != nil {
+		return mediaapi.HTTPError(err)
+	}
+	defer func() { _ = content.Body.Close() }()
+
+	// A file name in the path overrides the one it was uploaded with:
+	// that is what the path segment is for.
+	name := content.FileName
+	if override := r.PathValue("fileName"); override != "" {
+		name = override
+	}
+	mediaapi.ServeContent(w, r, content, name)
+	return nil
+}
+
+func (c *ClientAPI) serveThumbnail(w http.ResponseWriter, r *http.Request, localOnly bool) error {
+	req, err := mediaapi.ThumbnailParams(r)
+	if err != nil {
+		return err
+	}
+	wait, err := mediaapi.WaitParam(r)
+	if err != nil {
+		return err
+	}
+	content, err := c.media.Thumbnail(r.Context(), r.PathValue("serverName"), r.PathValue("mediaID"), req,
+		mediaapi.FetchOptions{Wait: wait, LocalOnly: localOnly})
+	if err != nil {
+		return mediaapi.HTTPError(err)
+	}
+	defer func() { _ = content.Body.Close() }()
+	mediaapi.ServeContent(w, r, content, mediaapi.ThumbnailFileName(content.ContentType))
+	return nil
+}