feat(core): Add framework-agnostic tunnel handler#18892
Merged
Conversation
Contributor
node-overhead report 🧳Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.
|
Member
So the issue with I think having an agnostic tunnel implementation is worth having, but perhaps we should introduce a One thing to keep in mind is different implementations of the tunnel feature depends heavily on the framework itself, in Next.js it is implemented as simple re-write rules, so we almost don't have any runtime logic for it on the serve-side. cc @Lms24 |
Collaborator
This is not the case because of tree-shaking. We have the If a helper like this ends up in the Node SDK it won't be usable in non-Node based SDKs. |
timfish
reviewed
Jan 20, 2026
packages/core/src/utils/tunnel.ts
Outdated
| // This prevents SSRF attacks where attackers send crafted envelopes | ||
| // with malicious DSNs pointing to arbitrary hosts | ||
| const isAllowed = allowedDsnComponents.some( | ||
| allowed => allowed.host === dsnComponents.host && allowed.projectId === dsnComponents.projectId, |
Collaborator
There was a problem hiding this comment.
I'm not sure it's enough to just check the host matches. We should have a list of allowed DSNs and only forward when they match.
Member
Author
There was a problem hiding this comment.
Yeah the allowedDsnComponents are passed from the outside and they're exactly that - a list of allowed DSNs.
Member
Author
There was a problem hiding this comment.
maybe instead of turning them in components we should pass them as string arrays and do a plain string comparison?
Lms24
reviewed
Feb 12, 2026
Member
There was a problem hiding this comment.
I kinda like this approach over #14137 because it returns the response to the caller. We need to make sure that the client SDK receives Sentry's response to correctly handle rate limits to avoid backpressure build ups of rate-limited data. This way, the client SDK will apply the rate limits on its end and stop sending stuff to the tunnel endpoint. (Tim, let me know if I misinterpreted your PR and we do in fact handle rate limiting)
I have one request though: Let's split this PR up into the core change that adds the helper and then the Tanstack Start stuff on top. We should also add tests for the core handler alone. I'd recommend we take inspiration from #14137 on the integration test front.
| * No-op stub for client-side builds. | ||
| * The actual implementation is server-only, but this stub is needed to prevent build errors. | ||
| */ | ||
| export function createTunnelHandler( |
Member
There was a problem hiding this comment.
l: is this really the case? Do we have to create stubs from all of our server exports in TSS? (cc @nicohrubec)
packages/core/src/utils/tunnel.ts
Outdated
| * @returns Promise resolving to status, body, and contentType | ||
| */ | ||
| export async function handleTunnelRequest( | ||
| body: string | Uint8Array, |
Member
There was a problem hiding this comment.
l: I think we should always assume bytes here, to avoid callers accidentally already strinfifying compressed/binary payloads
Suggested change
| body: string | Uint8Array, | |
| body: Uint8Array, |
packages/core/src/utils/tunnel.ts
Outdated
| */ | ||
| export async function handleTunnelRequest( | ||
| body: string | Uint8Array, | ||
| allowedDsnComponents: Array<DsnComponents>, |
Member
There was a problem hiding this comment.
I'd also refactor this a bit to an options object parameter (for future proofing) and as you suggested, make it accept a list of DSN strings. This should be easier for users to use. For us internally, it should make no difference.
Collaborator
No you're totally right. This is a better approach! I think ideally we also want a wrapper with If we auto setup tunneling to frameworks (like nextjs does) we should use some random ID rather than |
Member
Yup that would be ideal. My thinking was that some frameworks use different kinds of
+1 for the random id but let's be careful about full auto setup. AFAIK, we don't auto enable |
…ackage This will be added in a different PR, separate from the core util function
…uest and return Response
…instead of returning a request
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request extracts the tunnel handler logic from the Next.js SDK into a framework-agnostic core utility function in @sentry/core. The tunnel handler validates incoming Sentry envelopes against allowed DSNs and forwards them to the Sentry ingest endpoint, providing SSRF protection. The implementation supports the broader goal of standardizing tunnel functionality across multiple framework SDKs (Next.js, Remix, SvelteKit, Nuxt, Astro, etc.).
Changes:
- Adds
handleTunnelRequestfunction to@sentry/core/utils/tunnel.tsas a framework-agnostic tunnel handler - Adds comprehensive test suite for the tunnel handler covering various success and error scenarios
- Exports the new tunnel handler and its options type from
@sentry/core - Adds a client-side stub for
createTunnelHandlerin TanStack Start React package
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| packages/core/src/utils/tunnel.ts | Core tunnel handler implementation with DSN validation and envelope forwarding |
| packages/core/test/lib/utils/tunnel.test.ts | Test suite covering tunnel handler functionality |
| packages/core/src/index.ts | Exports for the tunnel handler function and options type |
| packages/tanstackstart-react/src/client/index.ts | Client-side no-op stub (appears to be unused/leftover code) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Codecov Results 📊Generated by Codecov Action |
Contributor
size-limit report 📦
|
…est URL The tunnel handler was manually constructing the Sentry ingest URL without the required auth query parameters (sentry_key, sentry_version), causing requests to fail authentication. Use getEnvelopeEndpointWithUrlEncodedAuth which properly constructs the URL with all required parameters. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wrap parseEnvelope in try-catch so malformed request bodies return a 400 Bad Request instead of throwing an unhandled error. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
11 tasks
There was a problem hiding this comment.
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.
Lms24
reviewed
Feb 19, 2026
Member
Lms24
left a comment
There was a problem hiding this comment.
Thanks Lazar! One more cleanup task, then let's merge this!
Lms24
approved these changes
Feb 19, 2026
Contributor
Semver Impact of This PR🟡 Minor (new features) 📋 Changelog PreviewThis is how your changes will appear in the changelog. Breaking Changes 🛠
New Features ✨Astro
Core
Deno
Deps
Hono
Nestjs
Nextjs
Node
Other
Bug Fixes 🐛Browser
Cloudflare
Core
Deps
Hono
Nestjs
Nextjs
Node Core
Nuxt
Tanstackstart React
Other
Documentation 📚New Release
Other
Internal Changes 🔧Agents
Changelog
Ci
Cloudflare
Core
Deps
Deps Dev
E2e
Fix Security Vulnerability
Github
Lint
Llm
Nextjs
Nuxt
Repo
Skills
Triage Skill
Other
Other
🤖 This preview updates automatically when you update the PR. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Update
After talking to the team, we decided to scope this PR only to the core util function, and handle framework adapters in other PRs. For that reason, I've deleted the initial TanStack Start adapter.
original PR description:
Overview
Right now only the Next.js SDK has a built-in tunnel handler on the backend side, but this PR aims to extract the tunnel handling logic in plain JavaScript in
@sentry/core, and provide framework-specific adapters.Framework-specific adapters checklist
Questions for the team
@sentry/corea good home for the framework-agnostic tunnel handler function?TODOs
Closes #19394 (added automatically)