Framework-agnostic Tunnel Handler

[nikolovlazar]

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

• Next.js
• Remix
• SvelteKit
• Nuxt
• Astro
• Solid Start
• TanStack Start React
• Nest.js
• ...?

Questions for the team

• Is @sentry/core a good home for the framework-agnostic tunnel handler function?
• What framework-specific adapters am I missing in the checklist? (cloudflare, aws, google cloud services, vercel edge, bun, deno)
• How do we standardize this across all SDKs, not just JavaScript?

TODOs

• Finalize framework adapters list
• E2E tests

[github-actions]

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.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	8,944	-	9,154	-2%
GET With Sentry	1,776	20%	1,636	+9%
GET With Sentry (error only)	6,158	69%	6,034	+2%
POST Baseline	1,217	-	1,144	+6%
POST With Sentry	611	50%	549	+11%
POST With Sentry (error only)	1,054	87%	1,036	+2%
MYSQL Baseline	3,332	-	3,250	+3%
MYSQL With Sentry	506	15%	333	+52%
MYSQL With Sentry (error only)	2,726	82%	2,646	+3%

View base workflow run

[logaretm]

Is @sentry/core a good home for the framework-agnostic tunnel handler function?

So the issue with @sentry/core is that adding any code to it increases the bundle size across all the SDKs, so this will increase the bundle size of strictly client-side SDKs (e.g: Vue and React) without providing value to their users.

I think having an agnostic tunnel implementation is worth having, but perhaps we should introduce a @sentry/server-utils SDK similiar to the browser-utils one which would contain this logic, and only SSR SDKs can then use it to implement their tunnel utility.

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

[timfish]

So the issue with @sentry/core is that adding any code to it increases the bundle size across all the SDKs

This is not the case because of tree-shaking. We have the ServerRuntimeClient in @sentry/core and it doesn't impact front-end bundle size.

If a helper like this ends up in the Node SDK it won't be usable in non-Node based SDKs.

[timfish]

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.

[nikolovlazar]

Yeah the allowedDsnComponents are passed from the outside and they're exactly that - a list of allowed DSNs.

[nikolovlazar]

maybe instead of turning them in components we should pass them as string arrays and do a plain string comparison?