Concepts
Media Message Pipeline
The upload, processing, storage, reference, and delivery flow that keeps large media files out of the core message path.
Concepts Covered
- Media uploads
- Object storage
- Media references
- Resumable upload
- Thumbnail generation
- Processing pipelines
- Authorization
- Orphan cleanup
Definition
A media message pipeline is the flow that handles large files such as images, videos, voice notes, and documents without pushing raw binary data through the core message system.
Text messages are small. Media files are not.
If the messaging pipeline tries to carry large files directly through realtime gateways, queues, delivery workers, and message tables, it becomes slow, expensive, and fragile.
The usual design is to upload media separately, then send a lightweight message that references the uploaded object.
The Pain That Forces A Separate Pipeline
A text message might be a few hundred bytes. A video can be tens or hundreds of megabytes.
If a chat system sends raw media through the same path as text:
client -> realtime gateway -> message service -> queue -> delivery workers -> recipients
then large files can overload components that were designed for low-latency metadata.
Problems appear quickly:
- gateways hold long-lived upload connections
- message queues carry huge payloads
- database rows become bloated
- retries resend large files
- slow uploads block message acceptance
- mobile clients restart uploads after network drops
The core chat system should deliver durable message metadata. Media storage and processing need their own path.
Mental Model
The chat message should carry a reference, not the file.
message_id: m_42
type: image
media_object_id: media_123
caption: "deployment diagram"
The media object lives in object storage or a media storage service. The message stores enough metadata for recipients to know what exists and how to fetch it.
This separation lets the system scale message delivery and media transfer differently.
Common Flow
A practical media send flow:
1. Client asks media service for upload authorization.
2. Client uploads file to object storage or upload service.
3. Media service records metadata: size, type, hash, owner.
4. Optional processors create thumbnails, previews, scans, or transcodes.
5. Client sends chat message containing media_object_id.
6. Recipients receive the message metadata.
7. Recipients download media through authorized URLs or media proxies.
The message itself stays small. Delivery workers do not need to move the binary file through the message queue.
Why Upload First
Uploading before sending avoids putting a large, failure-prone operation inside the message write path.
If media upload fails, no message needs to be created.
If message send fails after upload succeeds, the media object can be cleaned up later as an orphan.
If processing is delayed after message send, recipients can see a placeholder while thumbnails, scans, or downloads become available.
This separation gives the system more control over retries, storage cost, moderation, and user experience.
Resumable Uploads
Mobile uploads fail often. Large files should support resumable or chunked upload so the client does not restart from zero every time the network changes.
The system may track:
- upload session ID
- chunk ranges received
- expected file size
- content hash
- expiration time
- owner user and device
Resumability is especially important for videos, documents, and weak mobile networks.
Media Processing
Media often needs background processing:
- thumbnail generation
- image dimension extraction
- video transcoding
- virus or policy scanning
- perceptual hashing
- metadata stripping
- retention and lifecycle rules
This work should happen outside the core message acceptance transaction. Processing pipelines need their own queues, retries, dead-letter handling, and backpressure controls.
Authorization And Access
Media downloads need authorization. A media URL should not accidentally give permanent public access to private chat content.
Common approaches include:
- short-lived signed URLs
- media proxy endpoints
- encrypted objects
- access checks before issuing download URLs
- separate thumbnail and original-file permissions
Authorization becomes tricky when users leave groups, messages are deleted, or devices sync old history.
Operational Reality
Important signals:
- upload success rate
- upload resume rate
- average and p99 upload size
- processing queue depth
- thumbnail generation latency
- scan failure rate
- orphaned media count
- download error rate
- storage growth and lifecycle deletion
Failure modes:
- upload succeeds but message send fails, creating orphaned media
- message send succeeds but media processing is delayed
- recipient receives a media reference before authorization is ready
- large downloads overload media servers
- processing queue falls behind and thumbnails stay missing
- media metadata is deleted before all message references expire
- raw media is accidentally routed through realtime gateways
Related Topics
Knowledge links
Use these links to understand what to know first, where this idea appears, and what to study next.
Prerequisites
Read these first if this topic feels unfamiliar.
Used In Systems
System studies where this idea appears in context.
Related Concepts
Core ideas that connect to this topic.
Related Patterns
Reusable architecture moves built from these ideas.