feat: support runtime proxy using route rules

[pi0]

🔗 Linked issue

#113

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Support runtime proxy using route rules and h3.proxyRequest (universally works with fetch)

{
  routeRules: {
    '/proxy/example': { proxy: 'https://example.com' },
    "/proxy/**": { proxy: '/api/**' },
  }
}

Local support is pending unjs/h3#321

For more advance usages, users can always create a route like routes/proxy/[...path].ts and directly use return proxyRequest(path, { target }) and have full control over path handling, etc.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codecov]

Codecov Report

Merging #926 (9506781) into main (aa5a2f4) will increase coverage by 0.32%.
The diff coverage is 54.54%.

@@            Coverage Diff             @@
##             main     #926      +/-   ##
==========================================
+ Coverage   67.40%   67.73%   +0.32%     
==========================================
  Files          59       59              
  Lines        5968     5979      +11     
  Branches      668      678      +10     
==========================================
+ Hits         4023     4050      +27     
+ Misses       1936     1920      -16     
  Partials        9        9              

Impacted Files	Coverage Δ
src/options.ts	87.74% <37.50%> (-1.18%)	⬇️
src/types/nitro.ts	100.00% <100.00%> (ø)
src/rollup/config.ts	92.59% <0.00%> (+0.46%)	⬆️
src/rollup/plugins/externals.ts	94.32% <0.00%> (+1.17%)	⬆️
src/utils/index.ts	54.22% <0.00%> (+6.46%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[yancyhuang]

Hi @pi0

Very wonderful feature!
BTW, does it support proxy web socket now? In ticket #113 you mentioned web socket proxy feature is on the way, not sure if it's released or not.

Thank you,
Yancy

[pi0]

@yancyhuang It is partially with devProxy options. We still need a unified layer for WS support in servers to make it happen.

[antlionguard]

Will path rewrite support come? Like devProxy.

rewrite: (path) => path.replace(/^\/api/, '')

or i'm missing something about this topic?

[pi0]

@antlionguard Something like this has same effect in route rules: "/proxied/api/**": "https://backend/**.

[jonkri]

We still need a unified layer for WS support in servers to make it happen.

Hi! 👋 Is there an issue that tracks this?

[blowsie]

@pi0 , Thanks for this.
Unless I missed something, whilst his feat is called "support runtime proxy using route rules", it only actually supports rules that are defined at build time.

Would it be possible to acheive something like this using variables?

export default defineNuxtConfig({
  routeRules: {
    '/api': { proxy: NUXT_API_PROXY },
  }
})

[pi0]

@blowsie For dynamic target, you should make a custom route handler and use sendProxy(event) utility. (please make an issue if wanted to know how, i might forget to respond here)

[imzedi]

@pi0, any way I can use the same for static build? (by ssr: false and "nuxt build --prerender)

[TheAlexLichter]

@imzedi With a static build, you platform or reverse proxy has to handle that as no "nuxt/nitro" server is running ☺️

[pi0]

BTW depends on the static deployment platform. One of proxy via route rule advantages is that we can technically generate platform (or reverse proxy) config.

[TheAlexLichter]

@pi0 e.g. for netlify you mean?

[pi0]

Yes like this we can use for static presets.

[imzedi]

Thanks @pi0 @manniL .
Got this whole point.
Anyhow we will need a server whether its CDN or serverless function provided by deployment platform or we manage our own.

[JoniLieh]

Hello, thanks for maintaining such an awesome library!
Is there support to proxy websockets like socket.io?
I'm using nuxt and this works, but not for websockets (even with ws: true)

"/socket.io/**": {
        proxy: {
          to: "http://backend:3001/**",
          headers: {
            "X-API-KEY": NUXT_API_SECRET,
          },
}

Thanks!

[keryigit]

This doesn't seem to work for websockets. The HTTP upgrade message is directly responded instead of forwarded to the proxy address.

[pi0]

@keryigit Can you please open new feature request so i don’t forget this? 🙏

[JoniLieh]

I've found a workaround with the tutorial by @manniL , its proxying normal requests and websockets (on the 2nd try) as well:

// /server/api/[...].ts
import { joinURL } from 'ufo'
import { createProxyMiddleware } from 'http-proxy-middleware';
import { defineEventHandler } from 'h3';

// Get the runtimeconfig proxy url
const runtimeConfig = useRuntimeConfig()
const proxyUrl = (runtimeConfig.proxyToUrl as string) || "http://localhost"
const proxyUrlWs = (runtimeConfig.proxyToUrlWs as string) || "ws://localhost:80"

const wsSecure = proxyUrlWs.startsWith('wss')

const wsProxy = createProxyMiddleware({
  target: proxyUrlWs, // Make sure this is correct
  ws: true,
  pathFilter: '/api/**',
  pathRewrite: { '^/api': '' },
  secure: wsSecure,
  // changeOrigin: true,
  on: {
    proxyReqWs: (proxyReq, req, socket, options, head) => {
      const wsPath = req.url;
      
      // Construct the full WebSocket URL
      const fullWsUrl = proxyUrlWs + wsPath;

      console.info(`${CurrentTimeStamp()}\t[${wsSecure ? 'WSS' : 'WS'}]`, fullWsUrl);
    }
  }
});

/**
 * PROXYING /api
 * https://github.com/manniL/alexander-lichter-proxy-nuxt/blob/main/server/api/%5B...%5D.ts
 * by manniL
 * 
 * /api/** -> target/**
 * 
 * proxies http and ws
 * for ws nitro.experimental.websocket must be false in nuxt.config.ts
 * @param event 
 */
export default defineEventHandler(async (event) => {
  var {
    node,
    path: _path,
    _method
  } = event;

  // Check if it's a websocket request
  // when a websocket request is detected, only the first event triggers this function dont know why
  // everything works correctly tho, except very first connection is not proxied
  if (node.req.headers.upgrade && node.req.headers.upgrade.toLowerCase() === 'websocket') {
    wsProxy(node.req, node.res);
    return;
  }

  // check the path
  const path = _path.replace(/^\/api\//, '') // /api/users -> users
  const target = joinURL(proxyUrl, path)

  console.info(`${CurrentTimeStamp()}\t[${_method}]`, target);

  // proxy it!
  return proxyRequest(event, target)
})

function CurrentTimeStamp(): string {
  const date = new Date();
  const formattedDate = date.toLocaleString('de-DE', {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
  });

  return formattedDate;
}

[pi0]

Made trackers for WS Proxy support:

• Support websocket proxy with proxy route rule #2886
• Utility to create proxy hooks unjs/crossws#93

[pi0]

@JoniLieh thanks for the response, but i don't recommend this solution, it will likely break with future versions of Nitro nor works with other runtimes..

[JoniLieh]

@pi0 Thanks for the info, its for nuxt as well.

• Which solution do you recommend to proxy websockets? :)