feat(server): Upload endpoint by jjbayer · Pull Request #5638 · getsentry/relay

jjbayer · 2026-02-13T14:44:02Z

This PR implements the first version of the /upload endpoint for large files.

It uses TUS-compliant headers, but in violation of the protocol only supports "Creation with Upload", not "Creation" with subsequent uploads.
The endpoint dispatches to either the upload service or the upstream relay.

TODO:

Wait for project config without subscription
Use separate credentials

Follow-up (?):

Let service handle project-wait?
...

Closes https://linear.app/getsentry/issue/INGEST-724/implement-minimal-tus-protocol.

Add a new `/api/{project_id}/upload/` endpoint that implements the TUS protocol "Creation With Upload" feature. This allows uploading data in a single POST request with TUS headers. The endpoint validates: - Tus-Resumable header (must be "1.0.0") - Upload-Length header (must match body size) - Upload-Metadata header (optional, base64-encoded key-value pairs) Actual upload storage is not yet implemented (marked with TODOs). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Process the upload body as a stream instead of buffering the entire upload into memory. This makes the endpoint suitable for large file uploads. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Split `upload.rs` into `upload/mod.rs` (endpoint handler) and `upload/tus.rs` (protocol constants, error types, metadata parsing). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… tests Replace ContentLengthMismatch (400) with PayloadTooLarge (413) when the streaming body exceeds the declared Upload-Length. Add integration tests covering: successful upload, missing/invalid TUS headers, and the 413 response for oversized bodies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add a new `limits.max_upload_size` config option and apply it as axum's DefaultBodyLimit on the TUS upload route. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…point

Fix the upload endpoint to properly handle results from both the upstream relay and the local upload service: - Sink::upload now returns Result<SinkResult, UploadError> with proper error types for each sink variant - Fix UploadError::UploadFailed to delegate to BadStoreRequest's IntoResponse (was calling .to_string() producing 200 OK) - Add UploadError variants for Forward, UploadService, ServiceUnavailable with appropriate status code mapping (503, 504, 500) - Fix handle_stream to create objectstore session with scoping and stream the body via put_stream - Add scoping field to UploadStream so objectstore can scope uploads - Change UploadStream response to AsyncResponse<Result<(), Error>> for proper error propagation - Remove dbg!() call and dead code Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Wrap UploadStream in Managed<> for proper outcome tracking: - Add expected_length field and implement Counted for UploadStream - Change FromMessage impl to accept Managed<UploadStream> - Create Managed<UploadStream> in the endpoint using envelope.wrap() to inherit scoping and outcome tracking metadata - Update handle_stream to accept/reject the Managed wrapper - On load-shed, properly reject the Managed instance Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Introduce ExactStream, a Sync streaming wrapper that validates the total byte count against the announced Upload-Length header. It returns an error if the stream provides more or fewer bytes than expected, catching protocol violations at the stream level rather than after buffering. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Move ExactStream from the upload service module to relay-server utils, making it generic over the inner stream type. The Stream impl requires S: Unpin, which is naturally satisfied by boxed streams (Pin<Box<…>>). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jjbayer · 2026-02-13T16:14:14Z

relay-server/src/endpoints/upload.rs

+        match self {
+            Error::Tus(_) => StatusCode::BAD_REQUEST,
+            Error::Request(error) => return error.into_response(),
+            Error::Upload(error) => match error {
+                upload::Error::Forward(error) => return error.into_response(),
+                upload::Error::Upstream(status) => status,
+                upload::Error::InvalidLocation | upload::Error::SigningFailed => {
+                    StatusCode::INTERNAL_SERVER_ERROR
+                }
+                upload::Error::ServiceUnavailable => StatusCode::SERVICE_UNAVAILABLE,
+                upload::Error::UploadService(service_error) => match service_error {
+                    ServiceError::Timeout => StatusCode::GATEWAY_TIMEOUT,
+                    ServiceError::LoadShed => StatusCode::SERVICE_UNAVAILABLE,
+                    ServiceError::UploadFailed(error) => match error {
+                        objectstore::Error::Reqwest(error) => match error.status() {
+                            Some(status) => status,
+                            None => StatusCode::INTERNAL_SERVER_ERROR,
+                        },
+                        _ => StatusCode::INTERNAL_SERVER_ERROR,
+                    },
+                    ServiceError::Uuid(_) => StatusCode::INTERNAL_SERVER_ERROR,
+                },
+            },
+        }


This is a large match expression, but I wanted control over the status codes in a single place.

I think it's perfectly fine like this.

jjbayer · 2026-02-13T16:15:35Z

relay-server/src/endpoints/upload.rs

+    if project.state().is_pending() {
+        state.project_cache_handle().fetch(public_key);
+        while project.state().is_pending() {
+            relay_log::trace!("Waiting for project state");
+            let _ = state.project_cache_handle().changes().recv().await;
+            project = state.project_cache_handle().get(public_key);
+        }
+    }


This should probably be a function exposed from the project cache, that does not need to check every update.

I'd not ship this, I'd first figure out a better way to await a project config, this may be quite the footgun and potentially DoS vector.

relay-server/src/utils/upload.rs

relay-server/src/utils/stream.rs

jjbayer · 2026-02-16T08:32:23Z

relay-server/src/endpoints/mod.rs

        .route("/api/{project_id}/events/{event_id}/attachments/", post(attachments::handle))
-        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config));
+        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config))
+        .route("/api/{project_id}/upload/", upload::route(config));


We only support "creation with upload", so we don't need /upload/{id}/ for now.

Random bikeshedding about the name, I assume you went with upload to be independent of attachments and other things, generically uploading data? Any other options you considered?

jjbayer · 2026-02-16T08:33:26Z

relay-server/src/envelope/content_type.rs

+    /// `application/vnd.sentry.attachment-ref`
+    AttachmentRef,


I added this because I need it for my pseudo-envelope, but we're going to need it anyway to allow SDKs / downstream relays to send placeholders for uploads.

Is this actually used anywhere yet?

jjbayer · 2026-02-16T08:34:38Z

relay-server/src/utils/forward.rs

+                if has_source(&e, |source| {
+                    source
+                        .downcast_ref::<http_body_util::LengthLimitError>()
+                        .is_some()
+                        || source
+                            .downcast_ref::<io::Error>()
+                            .is_some_and(|e| e.kind() == io::ErrorKind::FileTooLarge)
+                }) {


This is getting annoying, I'm open to better ideas how to unpack this error.

Best idea I have is a macro :/

jjbayer · 2026-02-16T08:39:30Z

relay-server/src/endpoints/upload.rs

+///
+/// This is currently the easiest way to guarantee that the upload gets checked the same way as
+/// the envelope.
+async fn check_request(


I'm willing to refactor this to work without envelopes, I believe I'm still missing the state.memory_checker().check_memory() from handle_envelope, so the check is incomplete anyway.

I think this is fine for a start, but we should consider changing this. Either a separate path or better a generic path which can work with envelopes and other items at the same time.

relay-server/src/utils/upload.rs

loewenheim · 2026-02-16T11:10:28Z

relay-server/src/endpoints/upload.rs

+        match self {
+            Error::Tus(_) => StatusCode::BAD_REQUEST,
+            Error::Request(error) => return error.into_response(),
+            Error::Upload(error) => match error {
+                upload::Error::Forward(error) => return error.into_response(),
+                upload::Error::Upstream(status) => status,
+                upload::Error::InvalidLocation | upload::Error::SigningFailed => {
+                    StatusCode::INTERNAL_SERVER_ERROR
+                }
+                upload::Error::ServiceUnavailable => StatusCode::SERVICE_UNAVAILABLE,
+                upload::Error::UploadService(service_error) => match service_error {
+                    ServiceError::Timeout => StatusCode::GATEWAY_TIMEOUT,
+                    ServiceError::LoadShed => StatusCode::SERVICE_UNAVAILABLE,
+                    ServiceError::UploadFailed(error) => match error {
+                        objectstore::Error::Reqwest(error) => match error.status() {
+                            Some(status) => status,
+                            None => StatusCode::INTERNAL_SERVER_ERROR,
+                        },
+                        _ => StatusCode::INTERNAL_SERVER_ERROR,
+                    },
+                    ServiceError::Uuid(_) => StatusCode::INTERNAL_SERVER_ERROR,
+                },
+            },
+        }


I think it's perfectly fine like this.

loewenheim · 2026-02-16T11:15:09Z

relay-server/src/endpoints/upload.rs

+        .await
+        .map_err(Error::from)?;


This looks like it should already be handled by the ?.

Suggested change

.await

.map_err(Error::from)?;

.await?;

loewenheim · 2026-02-16T11:23:19Z

relay-server/src/utils/tus.rs

+    }
+
+    let content_type = headers.get(hyper::header::CONTENT_TYPE);
+    if content_type.is_none_or(|ct| ct != EXPECTED_CONTENT_TYPE) {


For the version check you do a comparison with Some(&TUS_VERSION). I would settle on one of the two idioms.

loewenheim · 2026-02-16T11:27:29Z

relay-server/src/envelope/item.rs

    /// Returns the attachment payload size.
    ///
    /// For AttachmentV2, returns only the size of the actual payload, excluding the attachment meta.
    /// For Attachment, returns the size of entire payload.
    ///
    /// **Note:** This relies on the `meta_length` header which might not be correct as such this
    /// is best effort.


This docstring could use a sentence about the newly added case.

loewenheim · 2026-02-16T11:29:09Z

relay-server/src/envelope/item.rs

    #[serde(flatten, skip_serializing_if = "Option::is_none")]
    parent_id: Option<ParentId>,

+    /// Size of the attachment this reference rate limits.


I don't entirely understand the reference to rate limiting here.

loewenheim · 2026-02-16T11:49:58Z

relay-server/src/utils/upload.rs

+                uri.as_bytes(),
+                &SignatureHeader {
+                    timestamp: Some(Utc::now()),
+                    signature_algorithm: None, //Some(SignatureAlgorithm::Prehashed),


What does this comment mean?

loewenheim · 2026-02-16T11:55:10Z

relay-server/Cargo.toml

 url = { workspace = true, features = ["serde"] }
 uuid = { workspace = true, features = ["v5"] }
 zstd = { workspace = true }
+http.workspace = true


Nit: Might want to sort this alphabetically and use the conventional formatting.

loewenheim · 2026-02-16T11:55:32Z

relay/Cargo.toml

 uuid = { workspace = true }
 reqwest = { workspace = true, features = ["gzip", "native-tls-vendored"] }
 mimalloc = { workspace = true, features = ["v3", "override", "debug_in_debug"] }
+http.workspace = true


See relay-server/Cargo.toml.

loewenheim · 2026-02-16T11:58:23Z

tests/integration/test_upload.py

+    response = relay.post(
+        "/api/%s/upload/?sentry_key=%s"
+        % (project_id, mini_sentry.get_dsn_public_key(project_id)),
+        headers={
+            "Tus-Resumable": "1.0.0",
+            "Upload-Length": str(len(data)),
+            "Content-Type": "application/offset+octet-stream",
+        },
+        data=data,
+    )


This uploads the payload to relay, which forwards it to mini_sentry, which has a dummy implementation of the upload route. Is that correct?

loewenheim · 2026-02-16T12:01:10Z

tests/integration/test_upload.py

+    (length,) = query_params["length"]
+    assert length == "11"
+    (signature,) = query_params["signature"]
+    print(signature)


Is this intentionally left in the test?

relay-server/src/endpoints/upload.rs

tests/integration/test_upload.py

relay-server/src/endpoints/upload.rs

Dav1dde · 2026-02-16T12:29:41Z

relay-server/src/endpoints/mod.rs

        .route("/api/{project_id}/events/{event_id}/attachments/", post(attachments::handle))
-        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config));
+        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config))
+        .route("/api/{project_id}/upload/", upload::route(config));


Random bikeshedding about the name, I assume you went with upload to be independent of attachments and other things, generically uploading data? Any other options you considered?

relay-server/src/endpoints/upload.rs

Dav1dde · 2026-02-16T12:33:03Z

relay-server/src/endpoints/mod.rs

        .route("/api/{project_id}/events/{event_id}/attachments/", post(attachments::handle))
-        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config));
+        .route("/api/{project_id}/unreal/{sentry_key}/", unreal::route(config))
+        .route("/api/{project_id}/upload/", upload::route(config));


Possibly we should do some versioning for this endpoint?

Dav1dde · 2026-02-16T12:35:03Z

relay-server/src/endpoints/upload.rs

+    response.headers_mut().insert(
+        tus::UPLOAD_OFFSET,
+        HeaderValue::from_str(&upload_length.to_string())
+            .expect("integer should always be a valid header"),


Nit: In most (?) places we just turn this into error responses to not have a panic path, I'd also consider this here or make a utility which converts integers to headers so we have an auditable place.

Dav1dde · 2026-02-16T12:36:26Z

relay-server/src/endpoints/upload.rs

+///
+/// This is currently the easiest way to guarantee that the upload gets checked the same way as
+/// the envelope.
+async fn check_request(


I think this is fine for a start, but we should consider changing this. Either a separate path or better a generic path which can work with envelopes and other items at the same time.

Dav1dde · 2026-02-16T12:50:32Z

relay-server/src/utils/upload.rs

+        let signature = config
+            .credentials()
+            .ok_or(Error::SigningFailed)?
+            .secret_key


I think we should provision separate credentials here, right now different Relay instances can have different credentials, but now they wouldn't be able to verify validity. This also limits us from giving the credentials to a different layer of Relays.

Dav1dde · 2026-02-16T12:51:58Z

relay-server/src/utils/upload.rs

+            key,
+            length,
+        } = self;
+        format!("/api/{project_id}/upload/{key}/?length={length}")


If this is the best way to do this via TUS, I guess we have to, but this feels wrong, and I'd much rather have something much more explicit.

Dav1dde · 2026-02-16T12:53:08Z

relay-server/src/envelope/content_type.rs

+    /// `application/vnd.sentry.attachment-ref`
+    AttachmentRef,


Is this actually used anywhere yet?

Dav1dde · 2026-02-16T12:54:08Z

relay-server/src/utils/upload.rs

+        format!("/api/{project_id}/upload/{key}/?length={length}")
+    }
+
+    fn try_sign(self, config: &Config) -> Result<SignedLocation, Error> {


This seems to be entirely untested and no test to verify the signature, including timestamps etc.

Dav1dde · 2026-02-16T12:54:32Z

relay-server/src/utils/upload.rs

+}
+
+/// An identifier for the upload.
+pub struct Location {


There is a lot of logic attached here, with signing etc. I think it'd be great to add all this to the docs.

This reverts commit b5024e3.

…s-upload-endpoint

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-17T12:08:05Z

relay-server/src/services/projects/cache/state.rs

+            let notify = Arc::clone(&guard.notify);
+            drop(guard); // don't hold the guard across await points
+            notify.notified().await;
+        }


Race condition in ready_project_inner may miss notification

Medium Severity

In ready_project_inner, the Notified future is created (via notify.notified()) after checking is_pending() and dropping the guard. Tokio's notify_waiters() uses a counter-based mechanism — a Notified future only captures notifications that occur after it's created. If set_project_state fires notify_waiters() between drop(guard) and notify.notified(), the notification is permanently missed, causing the loop to block until timeout or the next periodic project refresh. Moving notified() creation to before the is_pending() check would close this race window.

jjbayer and others added 30 commits February 10, 2026 09:17

wip

815b4f4

sync_wrapper and internal error

ef77cec

fix integration tests, stream body, apply size limit

e55d13a

fix

dbe25d3

fix tests

26ef7ce

review comments

d329d7e

ref(server): Make TUS upload endpoint use streaming body

d744261

Process the upload body as a stream instead of buffering the entire upload into memory. This makes the endpoint suitable for large file uploads. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ref(server): Move TUS helpers into separate module

da06030

Split `upload.rs` into `upload/mod.rs` (endpoint handler) and `upload/tus.rs` (protocol constants, error types, metadata parsing). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cleanup

d50d56c

feat(config): Add max_upload_size limit (1 GiB) for TUS uploads

19b53de

Add a new `limits.max_upload_size` config option and apply it as axum's DefaultBodyLimit on the TUS upload route. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

wip

a185060

Merge remote-tracking branch 'origin/master' into feat/tus-upload-end…

37b2db3

…point

wip: Fast path rate limit

20dd201

wip: upload service

fe2a7a7

cleanup

312b06d

fix tests

403f844

wip: signature

65cf89d

wait for project

70bd998

wip

a6bc8e7

rm managed

86420ee

wip: util module

a6074f6

it compiles

8ef4537

0 warnings

be9862d

fix two tests

7dcf499

jjbayer commented Feb 13, 2026

View reviewed changes

jjbayer changed the base branch from master to test/wait-for-log February 13, 2026 16:18

jjbayer marked this pull request as ready for review February 13, 2026 16:18

jjbayer requested a review from a team as a code owner February 13, 2026 16:18

cursor bot reviewed Feb 13, 2026

View reviewed changes

relay-server/src/utils/upload.rs Show resolved Hide resolved

relay-server/src/utils/stream.rs Show resolved Hide resolved

jjbayer commented Feb 16, 2026

View reviewed changes

jjbayer added 2 commits February 16, 2026 12:38

more tests

0bd1af7

fix 400 for bad Upload-Length

54dff95

loewenheim reviewed Feb 16, 2026

View reviewed changes

jjbayer added 2 commits February 16, 2026 13:16

restructure

86cf1ad

authenticate forward request

4ae4f80

sentry bot reviewed Feb 16, 2026

View reviewed changes

relay-server/src/endpoints/upload.rs Outdated Show resolved Hide resolved

cursor bot reviewed Feb 16, 2026

View reviewed changes

tests/integration/test_upload.py Show resolved Hide resolved

tests/integration/test_upload.py Outdated Show resolved Hide resolved

relay-server/src/endpoints/upload.rs Outdated Show resolved Hide resolved

End stream on error

22eb1c1

Dav1dde reviewed Feb 16, 2026

View reviewed changes

jjbayer added 6 commits February 16, 2026 15:32

TODOs

f722d6f

feat(projects): Wait for project config

b5024e3

rm capture_logs

352a059

Revert "feat(projects): Wait for project config"

51c7580

This reverts commit b5024e3.

rewrite with notify

c6c3db4

lint

e0d7f78

jjbayer mentioned this pull request Feb 17, 2026

feat(projects): Wait for project config #5642

Open

jjbayer added 7 commits February 17, 2026 12:36

doc

c598c70

Merge remote-tracking branch 'origin/feat/project-await' into feat/tu…

3dd85b9

…s-upload-endpoint

Merge remote-tracking branch 'origin/feat/project-await' into feat/tu…

07418c2

…s-upload-endpoint

fix: fetch

39602a9

use get_ready

2c0a827

Merge remote-tracking branch 'origin/feat/project-await' into feat/tu…

8297199

…s-upload-endpoint

clean up tests

019f149

cursor bot reviewed Feb 17, 2026

View reviewed changes

Conversation

jjbayer commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

loewenheim Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 17, 2026

jjbayer commented Feb 13, 2026 •

edited

Loading

loewenheim Feb 16, 2026 •

edited

Loading

Race condition in `ready_project_inner` may miss notification