From 5e428a2e93db0d27092b6586e855ac6fb9101c12 Mon Sep 17 00:00:00 2001 From: "mochida.toru" Date: Mon, 14 Sep 2026 16:08:49 +0900 Subject: [PATCH 1/2] feat: support SOCKS5/SOCKS4 proxies via fetch-socks Set HTTPS_PROXY, HTTP_PROXY, or ALL_PROXY to a socks5://, socks5h://, socks4://, or socks4a:// URL to route outbound requests through a SOCKS proxy instead of a plain HTTP proxy. NO_PROXY exclusions do not apply to SOCKS proxies. Co-Authored-By: Claude Sonnet 5 --- .../docs/guides/environment-variables.mdx | 16 ++- packages/backlog-utils/package.json | 1 + .../backlog-utils/src/http-dispatcher.test.ts | 115 +++++++++++++++++- packages/backlog-utils/src/http-dispatcher.ts | 60 ++++++++- pnpm-workspace.yaml | 8 ++ 5 files changed, 195 insertions(+), 5 deletions(-) diff --git a/apps/docs/src/content/docs/guides/environment-variables.mdx b/apps/docs/src/content/docs/guides/environment-variables.mdx index 2e08244..4977787 100644 --- a/apps/docs/src/content/docs/guides/environment-variables.mdx +++ b/apps/docs/src/content/docs/guides/environment-variables.mdx @@ -34,10 +34,13 @@ description: |- : OAuth 認証で使用するコールバックサーバーのポート番号。デフォルトは `5033`。別のアプリケーションとポートが競合する場合に変更できます。 `HTTPS_PROXY` / `HTTP_PROXY` -: アウトバウンドの HTTPS / HTTP リクエストを指定したプロキシ経由でルーティングします(例: `http://proxy.corp.example.com:8080`)。社内プロキシ環境や制限されたネットワークでの利用に必要です。 +: アウトバウンドの HTTPS / HTTP リクエストを指定したプロキシ経由でルーティングします(例: `http://proxy.corp.example.com:8080`)。社内プロキシ環境や制限されたネットワークでの利用に必要です。`socks5://`(`socks5h`/`socks4`/`socks4a` も可)の URL を指定すると、SOCKS プロキシ経由でルーティングします(例: `socks5://user:pass@127.0.0.1:1080`)。 + +`ALL_PROXY` +: `HTTPS_PROXY` / `HTTP_PROXY` が未設定のときに使われるプロキシ(主に SOCKS プロキシ用)。スキームは `HTTPS_PROXY` / `HTTP_PROXY` と同じです。 `NO_PROXY` -: プロキシをバイパスするホストをカンマ区切りで指定します(例: `internal.example.com,localhost`)。サブドメイン(`.example.com`)、ポート指定(`example.com:8080`)、ワイルドカード(`*`)にも対応しています。 +: プロキシをバイパスするホストをカンマ区切りで指定します(例: `internal.example.com,localhost`)。サブドメイン(`.example.com`)、ポート指定(`example.com:8080`)、ワイルドカード(`*`)にも対応しています。SOCKS プロキシには適用されません。 ## よく使うパターン @@ -71,6 +74,15 @@ BACKLOG_SPACE = "your-space.backlog.com" BACKLOG_PROJECT = "YOUR_PROJECT" ``` +### SOCKS5 プロキシ経由での利用 + +SSH トンネルなどで立てた SOCKS5 プロキシ経由で bee を使う場合は、`HTTPS_PROXY` に `socks5://` の URL を指定します。 + +```sh +export HTTPS_PROXY=socks5://127.0.0.1:1080 +bee issue list +``` + ### CI/CD での利用 非対話環境では `BACKLOG_API_KEY` を設定して使います。詳しくは [CI/CD での利用](/bee/integrations/ci-cd/) を参照してください。 diff --git a/packages/backlog-utils/package.json b/packages/backlog-utils/package.json index 1de5601..8aeee5d 100644 --- a/packages/backlog-utils/package.json +++ b/packages/backlog-utils/package.json @@ -9,6 +9,7 @@ "@repo/config": "workspace:*", "backlog-js": "catalog:", "consola": "catalog:", + "fetch-socks": "catalog:", "open": "catalog:", "undici": "catalog:", "valibot": "catalog:" diff --git a/packages/backlog-utils/src/http-dispatcher.test.ts b/packages/backlog-utils/src/http-dispatcher.test.ts index 314872c..262d897 100644 --- a/packages/backlog-utils/src/http-dispatcher.test.ts +++ b/packages/backlog-utils/src/http-dispatcher.test.ts @@ -1,4 +1,4 @@ -import { beforeEach, describe, expect, it, vi } from "vite-plus/test"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test"; vi.mock("consola", () => import("@repo/test-utils/mock-consola")); @@ -13,19 +13,130 @@ vi.mock("undici", () => { }; }); +vi.mock("fetch-socks", () => { + const socksDispatcher = vi.fn(() => ({ + compose: vi.fn(function (this: unknown) { + return this; + }), + })); + return { socksDispatcher }; +}); + +const PROXY_ENV_VARS = [ + "HTTPS_PROXY", + "https_proxy", + "HTTP_PROXY", + "http_proxy", + "ALL_PROXY", + "all_proxy", +]; + describe("installHttpDispatcher", () => { + const originalEnv: Record = {}; + beforeEach(() => { vi.clearAllMocks(); + for (const name of PROXY_ENV_VARS) { + originalEnv[name] = process.env[name]; + delete process.env[name]; + } + }); + + afterEach(() => { + for (const name of PROXY_ENV_VARS) { + if (originalEnv[name] === undefined) { + delete process.env[name]; + } else { + process.env[name] = originalEnv[name]; + } + } }); - it("calls setGlobalDispatcher with a composed EnvHttpProxyAgent", async () => { + it("calls setGlobalDispatcher with a composed EnvHttpProxyAgent when no SOCKS proxy is configured", async () => { const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici"); + const { socksDispatcher } = await import("fetch-socks"); const { installHttpDispatcher } = await import("./http-dispatcher"); installHttpDispatcher(); expect(EnvHttpProxyAgent).toHaveBeenCalled(); expect(vi.mocked(EnvHttpProxyAgent).prototype.compose).toHaveBeenCalled(); + expect(socksDispatcher).not.toHaveBeenCalled(); + expect(setGlobalDispatcher).toHaveBeenCalled(); + }); + + it("falls back to EnvHttpProxyAgent when HTTPS_PROXY is a plain http(s) URL", async () => { + process.env.HTTPS_PROXY = "http://proxy.example.com:8080"; + + const { EnvHttpProxyAgent } = await import("undici"); + const { socksDispatcher } = await import("fetch-socks"); + const { installHttpDispatcher } = await import("./http-dispatcher"); + + installHttpDispatcher(); + + expect(EnvHttpProxyAgent).toHaveBeenCalled(); + expect(socksDispatcher).not.toHaveBeenCalled(); + }); + + it("uses a SOCKS5 dispatcher when HTTPS_PROXY is a socks5:// URL", async () => { + process.env.HTTPS_PROXY = "socks5://user:pass@127.0.0.1:1080"; + + const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici"); + const { socksDispatcher } = await import("fetch-socks"); + const { installHttpDispatcher } = await import("./http-dispatcher"); + + installHttpDispatcher(); + + expect(socksDispatcher).toHaveBeenCalledWith({ + type: 5, + host: "127.0.0.1", + port: 1080, + userId: "user", + password: "pass", + }); + expect(EnvHttpProxyAgent).not.toHaveBeenCalled(); expect(setGlobalDispatcher).toHaveBeenCalled(); }); + + it("defaults to port 1080 and supports socks4a when no port is given", async () => { + process.env.ALL_PROXY = "socks4a://10.0.0.1"; + + const { socksDispatcher } = await import("fetch-socks"); + const { installHttpDispatcher } = await import("./http-dispatcher"); + + installHttpDispatcher(); + + expect(socksDispatcher).toHaveBeenCalledWith({ + type: 4, + host: "10.0.0.1", + port: 1080, + }); + }); + + it("prefers HTTPS_PROXY over ALL_PROXY", async () => { + process.env.HTTPS_PROXY = "socks5://primary.example.com:1080"; + process.env.ALL_PROXY = "socks5://fallback.example.com:1080"; + + const { socksDispatcher } = await import("fetch-socks"); + const { installHttpDispatcher } = await import("./http-dispatcher"); + + installHttpDispatcher(); + + expect(socksDispatcher).toHaveBeenCalledWith( + expect.objectContaining({ host: "primary.example.com" }), + ); + }); + + it("ignores an invalid proxy URL and falls back to EnvHttpProxyAgent", async () => { + process.env.HTTPS_PROXY = "not-a-valid-url"; + + const { EnvHttpProxyAgent } = await import("undici"); + const { socksDispatcher } = await import("fetch-socks"); + const { installHttpDispatcher } = await import("./http-dispatcher"); + + installHttpDispatcher(); + + expect(EnvHttpProxyAgent).toHaveBeenCalled(); + expect(socksDispatcher).not.toHaveBeenCalled(); + }); }); diff --git a/packages/backlog-utils/src/http-dispatcher.ts b/packages/backlog-utils/src/http-dispatcher.ts index b107b78..d301fe0 100644 --- a/packages/backlog-utils/src/http-dispatcher.ts +++ b/packages/backlog-utils/src/http-dispatcher.ts @@ -1,14 +1,72 @@ +import { socksDispatcher } from "fetch-socks"; import { EnvHttpProxyAgent, setGlobalDispatcher } from "undici"; import { createLoggingInterceptor } from "./http-logger"; +type SocksProxyOptions = { + type: 4 | 5; + host: string; + port: number; + userId?: string; + password?: string; +}; + +const SOCKS_PROXY_TYPES: Record = { + "socks4:": 4, + "socks4a:": 4, + "socks5:": 5, + "socks5h:": 5, +}; + +const readProxyEnv = (name: string): string | undefined => + process.env[name] || process.env[name.toLowerCase()]; + +/** + * Parses HTTPS_PROXY / HTTP_PROXY / ALL_PROXY into SOCKS proxy options, if + * one of them is set to a socks4(a)/socks5(h) URL (e.g. `socks5://host:port`). + */ +const resolveSocksProxy = (): SocksProxyOptions | undefined => { + const raw = + readProxyEnv("HTTPS_PROXY") ?? readProxyEnv("HTTP_PROXY") ?? readProxyEnv("ALL_PROXY"); + if (!raw) { + return undefined; + } + + let url: URL; + try { + url = new URL(raw); + } catch { + return undefined; + } + + const type = SOCKS_PROXY_TYPES[url.protocol]; + if (!type) { + return undefined; + } + + return { + type, + host: url.hostname, + port: Number(url.port) || 1080, + ...(url.username && { userId: decodeURIComponent(url.username) }), + ...(url.password && { password: decodeURIComponent(url.password) }), + }; +}; + /** Installs the global fetch dispatcher with logging and proxy support. * * Respects the standard HTTP proxy environment variables: * HTTPS_PROXY / https_proxy, HTTP_PROXY / http_proxy, * NO_PROXY / no_proxy (comma-separated list of hosts to bypass). + * + * Also supports SOCKS4(a)/SOCKS5(h) proxies: set HTTPS_PROXY, HTTP_PROXY, or + * ALL_PROXY / all_proxy to a `socks5://host:port` URL (or socks4/socks4a/socks5h). + * NO_PROXY exclusions do not apply to SOCKS proxies. */ const installHttpDispatcher = (): void => { - const agent = new EnvHttpProxyAgent().compose(createLoggingInterceptor()); + const socksProxy = resolveSocksProxy(); + const agent = socksProxy + ? socksDispatcher(socksProxy).compose(createLoggingInterceptor()) + : new EnvHttpProxyAgent().compose(createLoggingInterceptor()); setGlobalDispatcher(agent); }; diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 152a7c9..238b1de 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -18,6 +18,13 @@ peerDependencyRules: vite: "*" vitest: "*" + # fetch-socks depends on undici with the unpinned range `>=7`, so without + # this it resolves its own undici@8.x alongside the workspace's undici@7.x + # -- two structurally incompatible `Dispatcher` types make + # `.compose()`/`setGlobalDispatcher()` fail to typecheck. Pin it to the same + # major as the catalog's `undici` entry above; remove both together. + fetch-socks>undici: ^7.29.0 + catalog: "@astrojs/starlight": ^0.41.7 "@tsconfig/node-lts": ^24.0.1 @@ -33,6 +40,7 @@ catalog: # same change that drops Node 20 from engines and the CI matrix. commander: ^14.0.3 consola: ^3.4.2 + fetch-socks: ^1.3.3 is-unicode-supported: ^2.1.0 jiti: ^2.7.0 marked: ^18.0.10 From ae96ae742f24e505a5abef4ee24a88e54ae48eef Mon Sep 17 00:00:00 2001 From: "mochida.toru" Date: Wed, 30 Sep 2026 16:04:31 +0900 Subject: [PATCH 2/2] fix: adapt SOCKS proxy support to the Vite+ toolchain migration Rebased onto main's toolchain migration (#167): regenerate the lockfile, move the fetch-socks>undici override into the overrides section (it had landed under peerDependencyRules during the rebase's auto-merge), satisfy the new tsgolint prefer-nullish-coalescing rule, and drop the now-redundant vi.clearAllMocks() (clearMocks is on by default under vite-plus/test). Co-Authored-By: Claude Sonnet 5 --- .../backlog-utils/src/http-dispatcher.test.ts | 1 - packages/backlog-utils/src/http-dispatcher.ts | 2 +- pnpm-lock.yaml | 36 +++++++++++++++++++ pnpm-workspace.yaml | 13 ++++--- 4 files changed, 43 insertions(+), 9 deletions(-) diff --git a/packages/backlog-utils/src/http-dispatcher.test.ts b/packages/backlog-utils/src/http-dispatcher.test.ts index 262d897..c800be4 100644 --- a/packages/backlog-utils/src/http-dispatcher.test.ts +++ b/packages/backlog-utils/src/http-dispatcher.test.ts @@ -35,7 +35,6 @@ describe("installHttpDispatcher", () => { const originalEnv: Record = {}; beforeEach(() => { - vi.clearAllMocks(); for (const name of PROXY_ENV_VARS) { originalEnv[name] = process.env[name]; delete process.env[name]; diff --git a/packages/backlog-utils/src/http-dispatcher.ts b/packages/backlog-utils/src/http-dispatcher.ts index d301fe0..a4c66ad 100644 --- a/packages/backlog-utils/src/http-dispatcher.ts +++ b/packages/backlog-utils/src/http-dispatcher.ts @@ -18,7 +18,7 @@ const SOCKS_PROXY_TYPES: Record = { }; const readProxyEnv = (name: string): string | undefined => - process.env[name] || process.env[name.toLowerCase()]; + process.env[name] ?? process.env[name.toLowerCase()]; /** * Parses HTTPS_PROXY / HTTP_PROXY / ALL_PROXY into SOCKS proxy options, if diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 31fe714..92e7218 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -33,6 +33,9 @@ catalogs: consola: specifier: ^3.4.2 version: 3.4.2 + fetch-socks: + specifier: ^1.3.3 + version: 1.3.3 is-unicode-supported: specifier: ^2.1.0 version: 2.1.0 @@ -76,6 +79,7 @@ catalogs: overrides: vite@*: npm:@voidzero-dev/vite-plus-core@1.0.0 vitest@*: 5.0.1 + fetch-socks>undici: ^7.29.0 importers: @@ -173,6 +177,9 @@ importers: consola: specifier: 'catalog:' version: 3.4.2 + fetch-socks: + specifier: 'catalog:' + version: 1.3.3 open: specifier: 'catalog:' version: 11.0.1 @@ -2130,6 +2137,9 @@ packages: picomatch: optional: true + fetch-socks@1.3.3: + resolution: {integrity: sha512-jI22jzTf7x3GAcUoZARwuxKBPotb3PFkemVWqxlF2qV55FhRytRJrn95HeLoUMq2vkIbY3aQqNYytvZKqUoMaQ==} + fflate@0.8.3: resolution: {integrity: sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==} @@ -2290,6 +2300,10 @@ packages: inline-style-parser@0.2.7: resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==} + ip-address@10.7.2: + resolution: {integrity: sha512-7H/2gFSIitxc0hG3nOI1glS8QLo/EHBFFLk8vEUjXY/xu0AdL8jZ9U1IzO2PUm0d2D/ofQcAifb0g6OBkt8U7w==} + engines: {node: '>= 12'} + iron-webcrypto@1.2.1: resolution: {integrity: sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==} @@ -3006,10 +3020,18 @@ packages: engines: {node: '>=20.19.5', npm: '>=10.8.2'} hasBin: true + smart-buffer@4.2.0: + resolution: {integrity: sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==} + engines: {node: '>= 6.0.0', npm: '>= 3.0.0'} + smol-toml@1.8.0: resolution: {integrity: sha512-kCZr2V3ch9i00x8zXRhjUNVcjG9ijES5dDudkXvUVCT5QlJNQWElSJdZqyPemffHoLNUYwOcou0Fy+ojN0uHSQ==} engines: {node: '>= 18'} + socks@2.8.10: + resolution: {integrity: sha512-e0VyvkVTwVYViNovRkZ9aodhxVlyoMn7eJhVUPxZ+eK9P/7CBkxvvsBOHqFPEH416726W8tLXXXjKwqgTErrCQ==} + engines: {node: '>= 10.0.0', npm: '>= 3.0.0'} + source-map-js@1.2.1: resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} engines: {node: '>=0.10.0'} @@ -4997,6 +5019,11 @@ snapshots: optionalDependencies: picomatch: 4.0.7 + fetch-socks@1.3.3: + dependencies: + socks: 2.8.10 + undici: 7.29.0 + fflate@0.8.3: {} find-process@2.1.1: @@ -5303,6 +5330,8 @@ snapshots: inline-style-parser@0.2.7: {} + ip-address@10.7.2: {} + iron-webcrypto@1.2.1: {} is-absolute-url@5.0.0: {} @@ -6450,8 +6479,15 @@ snapshots: arg: 5.0.2 sax: 1.5.0 + smart-buffer@4.2.0: {} + smol-toml@1.8.0: {} + socks@2.8.10: + dependencies: + ip-address: 10.7.2 + smart-buffer: 4.2.0 + source-map-js@1.2.1: {} source-map@0.7.6: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 238b1de..3cdc74d 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -9,6 +9,12 @@ onlyBuiltDependencies: overrides: vite@*: "catalog:" vitest@*: "catalog:" + # fetch-socks depends on undici with the unpinned range `>=7`, so without + # this it resolves its own undici@8.x alongside the workspace's undici@7.x + # -- two structurally incompatible `Dispatcher` types make + # `.compose()`/`setGlobalDispatcher()` fail to typecheck. Pin it to the same + # major as the catalog's `undici` entry below; remove both together. + fetch-socks>undici: ^7.29.0 peerDependencyRules: allowAny: @@ -18,13 +24,6 @@ peerDependencyRules: vite: "*" vitest: "*" - # fetch-socks depends on undici with the unpinned range `>=7`, so without - # this it resolves its own undici@8.x alongside the workspace's undici@7.x - # -- two structurally incompatible `Dispatcher` types make - # `.compose()`/`setGlobalDispatcher()` fail to typecheck. Pin it to the same - # major as the catalog's `undici` entry above; remove both together. - fetch-socks>undici: ^7.29.0 - catalog: "@astrojs/starlight": ^0.41.7 "@tsconfig/node-lts": ^24.0.1