Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions apps/docs/src/content/docs/guides/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 プロキシには適用されません。

## よく使うパターン

Expand Down Expand Up @@ -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/) を参照してください。
Expand Down
1 change: 1 addition & 0 deletions packages/backlog-utils/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"@repo/config": "workspace:*",
"backlog-js": "catalog:",
"consola": "catalog:",
"fetch-socks": "catalog:",
"open": "catalog:",
"undici": "catalog:",
"valibot": "catalog:"
Expand Down
116 changes: 113 additions & 3 deletions packages/backlog-utils/src/http-dispatcher.test.ts
Original file line number Diff line number Diff line change
@@ -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"));

Expand All @@ -13,19 +13,129 @@ 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<string, string | undefined> = {};

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();
});
});
60 changes: 59 additions & 1 deletion packages/backlog-utils/src/http-dispatcher.ts
Original file line number Diff line number Diff line change
@@ -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<string, SocksProxyOptions["type"]> = {
"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);
};

Expand Down
36 changes: 36 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 7 additions & 0 deletions pnpm-workspace.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -33,6 +39,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
Expand Down