feat: allow proxy.bypass to be an async function

packages/core/src/index.ts

@@ -137,7 +137,9 @@ export type {
   PostCSSPlugin,
   PreviewOptions,
   PreconnectOption,
+  ProxyBypass,
   ProxyConfig,
+  ProxyFilter,
   ProxyOptions,
   PrintUrls,
   PublicDir,

packages/core/src/server/proxy.ts

@@ -60,7 +60,9 @@ export const createProxyMiddleware = async (
 
     const middleware: Middleware = async (req, res, next) => {
       const bypassUrl =
-        typeof opts.bypass === 'function' ? opts.bypass(req, res, opts) : null;
+        typeof opts.bypass === 'function'
+          ? await opts.bypass(req, res, opts)
+          : null;
 
       if (bypassUrl === false) {
         res.statusCode = 404;

packages/core/src/types/config.ts

@@ -265,7 +265,9 @@ export type ProxyBypass = (
   req: IncomingMessage,
   res: ServerResponse,
   proxyOptions: ProxyOptions,
-) => string | undefined | null | boolean;
+) => MaybePromise<string | undefined | null | boolean>;
+
+export type { ProxyFilter };
 
 export type ProxyOptions = HttpProxyOptions & {
   /**
@@ -274,6 +276,7 @@ export type ProxyOptions = HttpProxyOptions & {
    * - Return `true` to continue processing the request without proxy.
    * - Return `false` to produce a 404 error for the request.
    * - Return a path to serve from, instead of continuing to proxy the request.
+   * - Return a Promise to handle the request asynchronously.
    */
   bypass?: ProxyBypass;
   /**

website/docs/en/config/server/proxy.mdx

@@ -89,7 +89,7 @@ type ProxyOptions = HttpProxyOptions & {
     req: IncomingMessage,
     res: ServerResponse,
     proxyOptions: ProxyOptions,
-  ) => string | undefined | null | boolean;
+  ) => MaybePromise<string | undefined | null | boolean>;
   context?: Filter;
 };
 
@@ -104,21 +104,25 @@ In addition to the `http-proxy-middleware` option, Rsbuild also support the `byp
 
 ### bypass
 
-Bypass the proxy based on the return value of a function.
+Sometimes you don't want to proxy everything. It is possible to bypass the proxy based on the return value of a `bypass` function.
+
+In the function, you get access to the request, response, and proxy options.
 
 - Return `null` or `undefined` to continue processing the request with proxy.
 - Return `true` to continue processing the request without proxy.
 - Return `false` to produce a 404 error for the request.
 - Return a path to serve from, instead of continuing to proxy the request.
+- Return a Promise to handle the request asynchronously.
 
-```js
-// custom bypass
+E.g. for a browser request, you want to serve an HTML page, but for an API request, you want to proxy it. You could configure like this:
+
+```ts title="rsbuild.config.ts"
 export default {
   server: {
     proxy: {
       '/api': {
         target: 'http://localhost:3000',
-        bypass: function (req, res, proxyOptions) {
+        bypass(req, res, proxyOptions) {
           if (req.headers.accept.indexOf('html') !== -1) {
             console.log('Skipping proxy for browser request.');
             return '/index.html';

website/docs/zh/config/server/proxy.mdx

@@ -89,7 +89,7 @@ type ProxyOptions = HttpProxyOptions & {
     req: IncomingMessage,
     res: ServerResponse,
     proxyOptions: ProxyOptions,
-  ) => string | undefined | null | boolean;
+  ) => MaybePromise<string | undefined | null | boolean>;
   context?: Filter;
 };
 
@@ -104,21 +104,25 @@ type ProxyConfig =
 
 ### bypass
 
-根据函数的返回值绕过代理。
+一些情况下，你可能不想代理所有请求。可以通过 `bypass` 函数来绕过代理。
+
+在函数中，你可以访问到 request、response 和 proxy 选项。
 
 - 返回 `null` 或 `undefined` 会继续用代理处理请求。
 - 返回 `true` 会跳过代理继续处理请求。
 - 返回 `false` 会返回 404 错误。
 - 返回一个具体的服务路径，将会使用此路径替代原请求路径。
+- 返回一个 Promise，可以异步处理请求。
+
+例如，你可能希望对浏览器请求返回 HTML 页面，而对 API 请求则进行代理转发。你可以这样配置：
 
 ```js
-// 自定义 bypass 方法
 export default {
   server: {
     proxy: {
       '/api': {
         target: 'http://localhost:3000',
-        bypass: function (req, res, proxyOptions) {
+        bypass(req, res, proxyOptions) {
           if (req.headers.accept.indexOf('html') !== -1) {
             console.log('Skipping proxy for browser request.');
             return '/index.html';