feat: add bypass list, bypass local addresses and username/password to proxy setting (#1059)

* fix: use fs/promises for settings

This PR switches from synchronous operations with the 'fs' module to asynchronous operations with
the 'fs/promises' module. It also corrects a small error with hostname migration.

* fix: add missing merge function of default and current config

* feat: add bypass list, bypass local addresses and username/password to proxy setting

This PR adds more options to the proxy setting, like username/password authentication, bypass list
of domains and bypass local addresses. The UX is taken from *arrs.

* fix: add error handling for proxy creating

* fix: remove logs

server/index.ts

@@ -23,6 +23,7 @@ import avatarproxy from '@server/routes/avatarproxy';
 import imageproxy from '@server/routes/imageproxy';
 import { appDataPermissions } from '@server/utils/appDataVolume';
 import { getAppVersion } from '@server/utils/appVersion';
+import createCustomProxyAgent from '@server/utils/customProxyAgent';
 import restartFlag from '@server/utils/restartFlag';
 import { getClientIp } from '@supercharge/request-ip';
 import { TypeormStore } from 'connect-typeorm/out';
@@ -38,7 +39,6 @@ import dns from 'node:dns';
 import net from 'node:net';
 import path from 'path';
 import swaggerUi from 'swagger-ui-express';
-import { ProxyAgent, setGlobalDispatcher } from 'undici';
 import YAML from 'yamljs';
 
 if (process.env.forceIpv4First === 'true') {
@@ -76,8 +76,8 @@ app
     restartFlag.initializeSettings(settings.main);
 
     // Register HTTP proxy
-    if (settings.main.httpProxy) {
+    if (settings.main.proxy.enabled) {
-      setGlobalDispatcher(new ProxyAgent(settings.main.httpProxy));
+      await createCustomProxyAgent(settings.main.proxy);
     }
 
     // Migrate library types

server/lib/settings/index.ts

@@ -99,6 +99,17 @@ interface Quota {
   quotaDays?: number;
 }
 
+export interface ProxySettings {
+  enabled: boolean;
+  hostname: string;
+  port: number;
+  useSsl: boolean;
+  user: string;
+  password: string;
+  bypassFilter: string;
+  bypassLocalAddresses: boolean;
+}
+
 export interface MainSettings {
   apiKey: string;
   applicationTitle: string;
@@ -119,7 +130,7 @@ export interface MainSettings {
   mediaServerType: number;
   partialRequestsEnabled: boolean;
   locale: string;
-  httpProxy: string;
+  proxy: ProxySettings;
 }
 
 interface PublicSettings {
@@ -326,7 +337,16 @@ class Settings {
         mediaServerType: MediaServerType.NOT_CONFIGURED,
         partialRequestsEnabled: true,
         locale: 'en',
-        httpProxy: '',
+        proxy: {
+          enabled: false,
+          hostname: '',
+          port: 8080,
+          useSsl: false,
+          user: '',
+          password: '',
+          bypassFilter: '',
+          bypassLocalAddresses: true,
+        },
       },
       plex: {
         name: '',

server/utils/customProxyAgent.ts

@@ -0,0 +1,111 @@
+import type { ProxySettings } from '@server/lib/settings';
+import logger from '@server/logger';
+import type { Dispatcher } from 'undici';
+import { Agent, ProxyAgent, setGlobalDispatcher } from 'undici';
+
+export default async function createCustomProxyAgent(
+  proxySettings: ProxySettings
+) {
+  const defaultAgent = new Agent();
+
+  const skipUrl = (url: string) => {
+    const hostname = new URL(url).hostname;
+
+    if (proxySettings.bypassLocalAddresses && isLocalAddress(hostname)) {
+      return true;
+    }
+
+    for (const address of proxySettings.bypassFilter.split(',')) {
+      const trimmedAddress = address.trim();
+      if (!trimmedAddress) {
+        continue;
+      }
+
+      if (trimmedAddress.startsWith('*')) {
+        const domain = trimmedAddress.slice(1);
+        if (hostname.endsWith(domain)) {
+          return true;
+        }
+      } else if (hostname === trimmedAddress) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
+  const noProxyInterceptor = (
+    dispatch: Dispatcher['dispatch']
+  ): Dispatcher['dispatch'] => {
+    return (opts, handler) => {
+      const url = opts.origin?.toString();
+      return url && skipUrl(url)
+        ? defaultAgent.dispatch(opts, handler)
+        : dispatch(opts, handler);
+    };
+  };
+
+  const token =
+    proxySettings.user && proxySettings.password
+      ? `Basic ${Buffer.from(
+          `${proxySettings.user}:${proxySettings.password}`
+        ).toString('base64')}`
+      : undefined;
+
+  try {
+    const proxyAgent = new ProxyAgent({
+      uri:
+        (proxySettings.useSsl ? 'https://' : 'http://') +
+        proxySettings.hostname +
+        ':' +
+        proxySettings.port,
+      token,
+      interceptors: {
+        Client: [noProxyInterceptor],
+      },
+    });
+
+    setGlobalDispatcher(proxyAgent);
+  } catch (e) {
+    logger.error('Failed to connect to the proxy: ' + e.message, {
+      label: 'Proxy',
+    });
+    setGlobalDispatcher(defaultAgent);
+    return;
+  }
+
+  try {
+    const res = await fetch('https://www.google.com', { method: 'HEAD' });
+    if (res.ok) {
+      logger.debug('HTTP(S) proxy connected successfully', { label: 'Proxy' });
+    } else {
+      logger.error('Proxy responded, but with a non-OK status: ' + res.status, {
+        label: 'Proxy',
+      });
+      setGlobalDispatcher(defaultAgent);
+    }
+  } catch (e) {
+    logger.error(
+      'Failed to connect to the proxy: ' + e.message + ': ' + e.cause,
+      { label: 'Proxy' }
+    );
+    setGlobalDispatcher(defaultAgent);
+  }
+}
+
+function isLocalAddress(hostname: string) {
+  if (hostname === 'localhost' || hostname === '127.0.0.1') {
+    return true;
+  }
+
+  const privateIpRanges = [
+    /^10\./, // 10.x.x.x
+    /^172\.(1[6-9]|2[0-9]|3[0-1])\./, // 172.16.x.x - 172.31.x.x
+    /^192\.168\./, // 192.168.x.x
+  ];
+  if (privateIpRanges.some((regex) => regex.test(hostname))) {
+    return true;
+  }
+
+  return false;
+}

server/utils/restartFlag.ts

@@ -14,7 +14,7 @@ class RestartFlag {
     return (
       this.settings.csrfProtection !== settings.csrfProtection ||
       this.settings.trustProxy !== settings.trustProxy ||
-      this.settings.httpProxy !== settings.httpProxy
+      this.settings.proxy.enabled !== settings.proxy.enabled
     );
   }
 }

src/components/Settings/SettingsMain/index.tsx

@@ -55,8 +55,17 @@ const messages = defineMessages('components.Settings.SettingsMain', {
   validationApplicationUrlTrailingSlash: 'URL must not end in a trailing slash',
   partialRequestsEnabled: 'Allow Partial Series Requests',
   locale: 'Display Language',
-  httpProxy: 'HTTP Proxy',
+  proxyEnabled: 'HTTP(S) Proxy',
-  httpProxyTip: 'Tooltip to write',
+  proxyHostname: 'Proxy Hostname',
+  proxyPort: 'Proxy Port',
+  proxySsl: 'Use SSL For Proxy',
+  proxyUser: 'Proxy Username',
+  proxyPassword: 'Proxy Password',
+  proxyBypassFilter: 'Proxy Ignored Addresses',
+  proxyBypassFilterTip:
+    "Use ',' as a separator, and '*.' as a wildcard for subdomains",
+  proxyBypassLocalAddresses: 'Bypass Proxy for Local Addresses',
+  validationProxyPort: 'You must provide a valid port',
 });
 
 const SettingsMain = () => {
@@ -84,9 +93,12 @@ const SettingsMain = () => {
         intl.formatMessage(messages.validationApplicationUrlTrailingSlash),
         (value) => !value || !value.endsWith('/')
       ),
-    httpProxy: Yup.string().url(
+    proxyPort: Yup.number().when('proxyEnabled', {
-      intl.formatMessage(messages.validationApplicationUrl)
+      is: (proxyEnabled: boolean) => proxyEnabled,
-    ),
+      then: Yup.number().required(
+        intl.formatMessage(messages.validationProxyPort)
+      ),
+    }),
   });
 
   const regenerate = async () => {
@@ -142,7 +154,14 @@ const SettingsMain = () => {
             partialRequestsEnabled: data?.partialRequestsEnabled,
             trustProxy: data?.trustProxy,
             cacheImages: data?.cacheImages,
-            httpProxy: data?.httpProxy,
+            proxyEnabled: data?.proxy?.enabled,
+            proxyHostname: data?.proxy?.hostname,
+            proxyPort: data?.proxy?.port,
+            proxySsl: data?.proxy?.useSsl,
+            proxyUser: data?.proxy?.user,
+            proxyPassword: data?.proxy?.password,
+            proxyBypassFilter: data?.proxy?.bypassFilter,
+            proxyBypassLocalAddresses: data?.proxy?.bypassLocalAddresses,
           }}
           enableReinitialize
           validationSchema={MainSettingsSchema}
@@ -164,7 +183,16 @@ const SettingsMain = () => {
                   partialRequestsEnabled: values.partialRequestsEnabled,
                   trustProxy: values.trustProxy,
                   cacheImages: values.cacheImages,
-                  httpProxy: values.httpProxy,
+                  proxy: {
+                    enabled: values.proxyEnabled,
+                    hostname: values.proxyHostname,
+                    port: values.proxyPort,
+                    useSsl: values.proxySsl,
+                    user: values.proxyUser,
+                    password: values.proxyPassword,
+                    bypassFilter: values.proxyBypassFilter,
+                    bypassLocalAddresses: values.proxyBypassLocalAddresses,
+                  },
                 }),
               });
               if (!res.ok) throw new Error();
@@ -445,27 +473,175 @@ const SettingsMain = () => {
                   </div>
                 </div>
                 <div className="form-row">
-                  <label htmlFor="httpProxy" className="checkbox-label">
+                  <label htmlFor="proxyEnabled" className="checkbox-label">
                     <span className="mr-2">
-                      {intl.formatMessage(messages.httpProxy)}
+                      {intl.formatMessage(messages.proxyEnabled)}
                     </span>
                     <SettingsBadge badgeType="advanced" className="mr-2" />
                     <SettingsBadge badgeType="restartRequired" />
-                    <span className="label-tip">
-                      {intl.formatMessage(messages.httpProxyTip)}
-                    </span>
                   </label>
                   <div className="form-input-area">
-                    <div className="form-input-field">
+                    <Field
-                      <Field id="httpProxy" name="httpProxy" type="text" />
+                      type="checkbox"
-                    </div>
+                      id="proxyEnabled"
-                    {errors.httpProxy &&
+                      name="proxyEnabled"
-                      touched.httpProxy &&
+                      onChange={() => {
-                      typeof errors.httpProxy === 'string' && (
+                        setFieldValue('proxyEnabled', !values.proxyEnabled);
-                        <div className="error">{errors.httpProxy}</div>
+                      }}
-                      )}
+                    />
                   </div>
                 </div>
+                {values.proxyEnabled && (
+                  <>
+                    <div className="form-row">
+                      <label htmlFor="proxyHostname" className="checkbox-label">
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxyHostname)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <div className="form-input-field">
+                          <Field
+                            id="proxyHostname"
+                            name="proxyHostname"
+                            type="text"
+                          />
+                        </div>
+                        {errors.proxyHostname &&
+                          touched.proxyHostname &&
+                          typeof errors.proxyHostname === 'string' && (
+                            <div className="error">{errors.proxyHostname}</div>
+                          )}
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label htmlFor="proxyPort" className="checkbox-label">
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxyPort)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <div className="form-input-field">
+                          <Field id="proxyPort" name="proxyPort" type="text" />
+                        </div>
+                        {errors.proxyPort &&
+                          touched.proxyPort &&
+                          typeof errors.proxyPort === 'string' && (
+                            <div className="error">{errors.proxyPort}</div>
+                          )}
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label htmlFor="proxySsl" className="checkbox-label">
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxySsl)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <Field
+                          type="checkbox"
+                          id="proxySsl"
+                          name="proxySsl"
+                          onChange={() => {
+                            setFieldValue('proxySsl', !values.proxySsl);
+                          }}
+                        />
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label htmlFor="proxyUser" className="checkbox-label">
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxyUser)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <div className="form-input-field">
+                          <Field id="proxyUser" name="proxyUser" type="text" />
+                        </div>
+                        {errors.proxyUser &&
+                          touched.proxyUser &&
+                          typeof errors.proxyUser === 'string' && (
+                            <div className="error">{errors.proxyUser}</div>
+                          )}
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label htmlFor="proxyPassword" className="checkbox-label">
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxyPassword)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <div className="form-input-field">
+                          <Field
+                            id="proxyPassword"
+                            name="proxyPassword"
+                            type="password"
+                          />
+                        </div>
+                        {errors.proxyPassword &&
+                          touched.proxyPassword &&
+                          typeof errors.proxyPassword === 'string' && (
+                            <div className="error">{errors.proxyPassword}</div>
+                          )}
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label
+                        htmlFor="proxyBypassFilter"
+                        className="checkbox-label"
+                      >
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(messages.proxyBypassFilter)}
+                        </span>
+                        <span className="label-tip ml-4">
+                          {intl.formatMessage(messages.proxyBypassFilterTip)}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <div className="form-input-field">
+                          <Field
+                            id="proxyBypassFilter"
+                            name="proxyBypassFilter"
+                            type="text"
+                          />
+                        </div>
+                        {errors.proxyBypassFilter &&
+                          touched.proxyBypassFilter &&
+                          typeof errors.proxyBypassFilter === 'string' && (
+                            <div className="error">
+                              {errors.proxyBypassFilter}
+                            </div>
+                          )}
+                      </div>
+                    </div>
+                    <div className="form-row">
+                      <label
+                        htmlFor="proxyBypassLocalAddresses"
+                        className="checkbox-label"
+                      >
+                        <span className="mr-2 ml-4">
+                          {intl.formatMessage(
+                            messages.proxyBypassLocalAddresses
+                          )}
+                        </span>
+                      </label>
+                      <div className="form-input-area">
+                        <Field
+                          type="checkbox"
+                          id="proxyBypassLocalAddresses"
+                          name="proxyBypassLocalAddresses"
+                          onChange={() => {
+                            setFieldValue(
+                              'proxyBypassLocalAddresses',
+                              !values.proxyBypassLocalAddresses
+                            );
+                          }}
+                        />
+                      </div>
+                    </div>
+                  </>
+                )}
                 <div className="actions">
                   <div className="flex justify-end">
                     <span className="ml-3 inline-flex rounded-md shadow-sm">