Skip to content
Merged
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
55 changes: 55 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1624,3 +1624,58 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu
- Inside DeepSeek Harness the request still ends in `dsh` after the
parentheses (D-087) while servers that read only that part are in use; the
agent segment says `dsh` too.

## D-093 Requests honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY

- Node's fetch ignores the proxy variables unless Node itself was started
with `NODE_USE_ENV_PROXY=1` (22.21+, 24+). Cursor's sandbox allows the
network only through a proxy it names in those variables, so every command
there failed at its first request (`oauth_network`), and the Meshy plugin
had to start the CLI with `NODE_USE_ENV_PROXY=1`, which needs a newer Node
than the CLI requires.
- At start, before any request, the CLI reads `https_proxy`, `HTTPS_PROXY`,
`http_proxy`, `HTTP_PROXY` and `no_proxy`, `NO_PROXY` (lowercase first, as
curl and undici do). When either proxy is set it installs a global
dispatcher once, so every fetch goes through it: the API, sign-in,
downloads, input URL checks, and the update check's child process, which
starts through the same entry point. Without a proxy variable nothing
changes.
- The dispatcher is undici's `EnvHttpProxyAgent`. `https:` URLs use
`HTTPS_PROXY` (a CONNECT tunnel) and fall back to `HTTP_PROXY`. `http:` URLs
go to an `http://` proxy as plain forwarded requests, as curl sends them, so
a proxy that only forwards still works. undici tunnels through an
`https://` proxy for every URL; curl would forward `http:` there, and the
only `http:` targets are a custom `MESHY_BASE_URL_*` (usually this machine,
which goes direct) and an input URL a user gives; Ark accepted this limit
on 2026-11-09 rather than a hand-written forwarding client. `NO_PROXY` is
passed as given, so `*` still means every host.
- This machine always goes direct: `localhost`, `127.0.0.0/8` and `::1`, as
Go's `net/http` does (Ark, 2026-11-09). A custom `MESHY_BASE_URL_*` on
loopback is a development server, and its credential would otherwise cross
the proxy in the clear. `NO_PROXY` cannot express a range, so a thin
dispatcher in front sends loopback hosts to a plain agent and everything
else to `EnvHttpProxyAgent`.
- A proxy value undici cannot use (not `http://` or `https://`, no host, a
query, a bad escape) does not fall back to going direct: every request
fails before it leaves, with an error that names the variable and never its
value, which may hold a password. The check builds the proxy agent undici
would build, so nothing it accepts is refused. Local commands still run.
Sign-in and downloads report the same message, and sign-in points at the
proxy variables rather than at another way to sign in.
- A request the proxy refuses (a CONNECT answered other than 200, a forwarded
request answered 407), or whose `https://` proxy fails the certificate check
(a name mismatch, which undici wraps as `UND_ERR_PRX_TLS`; an untrusted or
expired certificate, which arrives as its own errno), never reached Meshy:
the transport records it as never sent (`not_submitted`), not as a
submission whose outcome is unknown, and the error says it was the proxy.
Other TLS failures with the proxy (an `https://` proxy URL pointing at a
plain HTTP port, say) are still recorded as unknown, the conservative side.
undici reports refusals only by message; `tests/proxy.test.ts` pins the
messages of the version in the lockfile.
- undici is a dependency for this alone. Node's own `http.setGlobalProxyFromEnv`
does the same, but Node 22 does not have it (24.20 does); one code path
covers every Node the CLI supports (22.12+), and the global dispatcher is
what Node's built-in fetch uses on both 22 and 24.
- The transport's own rules are unchanged: it still follows no redirect and
refuses a URL outside its base. The proxy only carries the request, and for
`https:` URLs it sees a CONNECT tunnel, not the request.
1 change: 1 addition & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -541,6 +541,7 @@ URI is accepted when its bytes are a GLB.
| `MESHY_LOG_LEVEL` | `warn` |
| `MESHY_CLI_CLIENT` | unset — a tool that runs meshy-cli for its users names itself here (for example `meshy-dcc/0.2.2 (blender)`); appended to the User-Agent of every request. Inside DeepSeek Harness (`DSH_SHELL=1`) it defaults to `dsh` |
| `MESHY_CLI_AGENT` | unset — the AI agent running meshy-cli is detected from the variables it sets on its commands (Cursor, Claude Code, Codex, Copilot, Gemini CLI, Kiro CLI, OpenCode, Hermes, DeepSeek Harness, Cline, Roo Code, or any agent that sets `AI_AGENT`) and named in the User-Agent of API requests to Meshy (`meshy.ai`, `meshy.cn`) as `; agent <id>[/<surface>]` inside the parentheses; requests anywhere else, sign-in, input URL checks and asset downloads leave it out. Set a name (`grok-bot`, `claude-code/desktop`: lowercase letters, digits, `.`, `-`) to name it yourself, or `none` to leave it out. `meshy doctor` shows what was detected and from which variable |
| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | unset — when `HTTPS_PROXY` or `HTTP_PROXY` is set (lowercase spellings too, lowercase first), every request goes through that proxy: API calls, sign-in, downloads, input URL checks and the update check. `HTTPS_PROXY` covers `https:` URLs (through a CONNECT tunnel) and falls back to `HTTP_PROXY`; `http:` URLs go to an `http://` proxy as plain forwarded requests, as with curl (an `https://` proxy tunnels them too). `NO_PROXY` lists hosts that go direct (comma-separated; `*` for all), and this machine (`localhost`, `127.0.0.0/8`, `::1`) always does, so a local API's credential never crosses the proxy. A value that is not a usable `http://` or `https://` proxy URL stops every request with an error naming the variable (never its value), rather than going direct. A request the proxy refuses (a CONNECT not answered 200, a 407), or whose `https://` proxy fails its certificate check, was never sent. Needed inside sandboxes that allow the network only through a proxy, such as Cursor's |
| `MESHY_CLI_NO_UPDATE_NOTIFIER` | unset — any non-empty value disables update checks; CI envs (`CI`, `GITHUB_ACTIONS`, `BUILD_NUMBER`, `RUN_ID`) auto-skip |

## Update notifications
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
"dependencies": {
"commander": "^15.0.0",
"sharp": "^0.35.4",
"undici": "^7.30.2",
"zod": "^4.5.2"
},
"devDependencies": {
Expand Down
9 changes: 9 additions & 0 deletions pnpm-lock.yaml

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

6 changes: 5 additions & 1 deletion src/client/transport.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
import { mapHttpError, MeshyApiError } from "./errors.js";
import { logger } from "../internal/logger.js";
import { apiUserAgent } from "../internal/user-agent.js";
import { proxyFailure } from "../internal/proxy.js";

export type TransportPhase = "validate" | "connect" | "request" | "response" | "body" | "timeout" | "aborted";

Expand Down Expand Up @@ -154,6 +155,8 @@ function errnoOf(err: unknown): string | undefined {
const CONNECT_ERRNOS = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT", "ERR_TLS_CERT_ALTNAME_INVALID", "CERT_HAS_EXPIRED", "DEPTH_ZERO_SELF_SIGNED_CERT", "UNABLE_TO_VERIFY_LEAF_SIGNATURE", "SELF_SIGNED_CERT_IN_CHAIN"]);

function classifyFetchFailure(err: unknown, phase: TransportPhase): TransportPhase {
// Failed at the proxy, before the target (D-093).
if (proxyFailure(err)) return "connect";
const errno = errnoOf(err);
if (errno && CONNECT_ERRNOS.has(errno)) return "connect";
return phase;
Expand Down Expand Up @@ -223,9 +226,10 @@ export function createTransport(cfg: TransportConfig): Transport {
return new TransportError({ message: `request to ${path} timed out after ${timeoutMs}ms`, phase: "timeout", path, cause: err, credentialKind: cfg.credentialKind });
}
const errno = errnoOf(err);
const proxy = proxyFailure(err);
const msg = err instanceof Error ? err.message : String(err);
return new TransportError({
message: `network error calling ${path}: ${msg}${errno ? ` (${errno})` : ""}`,
message: proxy ? `${proxy} (calling ${path}); nothing was sent` : `network error calling ${path}: ${msg}${errno ? ` (${errno})` : ""}`,
phase: classifyFetchFailure(err, phase),
path,
errno,
Expand Down
6 changes: 5 additions & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
* - turn SIGINT / SIGTERM / SIGHUP into a cooperative abort (exit 130) instead of a hard kill;
* - route every failure — including Commander parse errors — through one
* exit that renders the v1 error envelope in the format the command would have used;
* - flush stdout before exiting.
* - flush stdout before exiting;
* - route every request through the proxy HTTPS_PROXY / HTTP_PROXY name.
*/

import type { Command } from "commander";
Expand All @@ -22,8 +23,11 @@ import { stopActiveProgress } from "./internal/progress.js";
import { errorEnvelope } from "./internal/result.js";
import { resolveFormat } from "./internal/runtime.js";
import { refreshCache, shouldRunUpdateCheck } from "./internal/update-notifier.js";
import { useProxyFromEnv } from "./internal/proxy.js";

async function main(): Promise<number> {
// Before any request, the update check's included (D-093).
await useProxyFromEnv();
const argv = process.argv;
if (argv.includes("--no-update-check")) {
// Children (none today, but any future spawn) inherit the opt-out.
Expand Down
9 changes: 5 additions & 4 deletions src/internal/device.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
import { HintedError } from "./errors.js";
import { USER_AGENT } from "./user-agent.js";
import type { TokenResponse } from "./oauth.js";
import { fetchErrorMessage, PROXY_HINT, proxyFailure } from "./proxy.js";

// ---------------------------------------------------------------------------
// Types
Expand Down Expand Up @@ -112,9 +113,9 @@ export async function deviceAuthorization(
});
} catch (err) {
throw new HintedError({
message: `Network error contacting device authorization endpoint: ${err instanceof Error ? err.message : String(err)}`,
message: `Network error contacting device authorization endpoint: ${fetchErrorMessage(err)}`,
code: "oauth_network",
hint: "Run: meshy auth login --with-key msy_...",
hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login --with-key msy_...",
});
}

Expand Down Expand Up @@ -227,9 +228,9 @@ async function deviceTokenOnce(
});
} catch (err) {
throw new HintedError({
message: `Network error polling device token: ${err instanceof Error ? err.message : String(err)}`,
message: `Network error polling device token: ${fetchErrorMessage(err)}`,
code: "oauth_network",
hint: "Run: meshy auth login",
hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login",
});
}

Expand Down
3 changes: 2 additions & 1 deletion src/internal/download.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ import { isInside, looksLikeFile, realpathLenient, resolveWithinRoot, safeExtens
import { USER_AGENT } from "./user-agent.js";
import { enumerateAssets, selectDefaultAssets, type Asset, type DefaultSelection, type SkipReason } from "./artifacts.js";
import { fileDigest, relinkMaterials, type MaterialLinkReport } from "./material-links.js";
import { fetchErrorMessage } from "./proxy.js";

/** Extensions sharp can transcode between. */
const CONVERTIBLE_IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "webp", "gif", "tiff", "tif", "avif"]);
Expand Down Expand Up @@ -147,7 +148,7 @@ export async function fetchToTemp(rawUrl: string, target: string, opts: FetchOpt
} catch (err) {
if (opts.signal?.aborted) throw new CliError({ code: "interrupted", message: `download of ${redact(url)} interrupted` });
if (controller.signal.aborted) throw new CliError({ code: "network", message: `download of ${redact(url)} timed out after ${limits.timeoutMs}ms` });
throw new CliError({ code: "network", message: `download of ${redact(url)} failed: ${err instanceof Error ? err.message : String(err)}`, cause: err });
throw new CliError({ code: "network", message: `download of ${redact(url)} failed: ${fetchErrorMessage(err)}`, cause: err });
}
if (r.status >= 300 && r.status < 400) {
const loc = r.headers.get("location");
Expand Down
3 changes: 2 additions & 1 deletion src/internal/file-input.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import type { MediaField, MediaKind } from "../client/resource-registry.js";
import { UsageError } from "./errors.js";
import { logger } from "./logger.js";
import { USER_AGENT } from "./user-agent.js";
import { fetchErrorMessage } from "./proxy.js";

export const DEFAULT_MEDIA_LIMITS = {
/** 50 MiB — an engineering default, not a Meshy product limit. */
Expand Down Expand Up @@ -179,7 +180,7 @@ async function preflightUrl(url: string, flagLabel: string, limits: MediaLimits,
controller.abort();
}
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
const msg = fetchErrorMessage(err);
if (timeout.aborted) throw new UsageError(`${flagLabel}: preflight of ${url} timed out after ${limits.preflightTimeoutMs}ms`);
throw new UsageError(`${flagLabel}: cannot reach ${url} (${msg})`);
}
Expand Down
5 changes: 3 additions & 2 deletions src/internal/oauth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import type { CredentialAccount } from "./credentials.js";
import { HintedError } from "./errors.js";
import { USER_AGENT } from "./user-agent.js";
import { renderCallbackPage } from "./oauth-page.js";
import { fetchErrorMessage, PROXY_HINT, proxyFailure } from "./proxy.js";

// ---------------------------------------------------------------------------
// PKCE helpers
Expand Down Expand Up @@ -350,9 +351,9 @@ async function postToken(
});
} catch (err) {
throw new HintedError({
message: `Network error contacting token endpoint: ${err instanceof Error ? err.message : String(err)}`,
message: `Network error contacting token endpoint: ${fetchErrorMessage(err)}`,
code: "oauth_network",
hint: "Run: meshy auth login",
hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login",
});
}

Expand Down
79 changes: 79 additions & 0 deletions src/internal/proxy-dispatcher.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
/**
* The undici side of D-093, loaded only when a proxy variable is set (see
* proxy.ts): checking proxy URLs as undici would use them, and the global
* dispatcher that sends this machine direct and everything else through
* EnvHttpProxyAgent.
*/

import { Agent, Dispatcher, EnvHttpProxyAgent, ProxyAgent, setGlobalDispatcher } from "undici";

import { isLoopbackHost, PROXY_INVALID_CODE, type ProxyFromEnv } from "./proxy.js";

/** Whether undici accepts value as a proxy URL: http(s), a host, nothing it cannot decode. */
export function isUsableProxyUrl(value: string): boolean {
try {
const { protocol, hostname } = new URL(value);
if ((protocol !== "http:" && protocol !== "https:") || hostname === "") return false;
void new ProxyAgent({ uri: value }).close();
return true;
} catch {
return false;
}
}

/**
* Sends requests for this machine (localhost, 127.0.0.0/8, ::1) direct and
* every other one through the proxy dispatcher. NO_PROXY cannot express a
* range, and appending hosts to it would break NO_PROXY=*.
*/
class LoopbackDirect extends Dispatcher {
constructor(
private readonly proxied: Dispatcher,
private readonly direct: Dispatcher,
) {
super();
}

override dispatch(opts: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
const origin = opts.origin === undefined ? undefined : new URL(String(opts.origin));
return (origin && isLoopbackHost(origin.hostname) ? this.direct : this.proxied).dispatch(opts, handler);
}

override close(): Promise<void>;
override close(callback: () => void): void;
override close(callback?: () => void): Promise<void> | void {
const done = Promise.all([this.proxied.close(), this.direct.close()]).then(() => undefined);
if (!callback) return done;
void done.then(callback);
}

override destroy(): Promise<void>;
override destroy(err: Error | null): Promise<void>;
override destroy(callback: () => void): void;
override destroy(err: Error | null, callback: () => void): void;
override destroy(errOrCallback?: Error | null | (() => void), callback?: () => void): Promise<void> | void {
const err = typeof errOrCallback === "function" ? null : (errOrCallback ?? null);
const cb = typeof errOrCallback === "function" ? errOrCallback : callback;
const done = Promise.all([this.proxied.destroy(err), this.direct.destroy(err)]).then(() => undefined);
if (!cb) return done;
void done.then(cb);
}
}

function invalidProxyError(variable: string): Error {
const err = new Error(`${variable} is not a valid proxy URL (expected http://host:port or https://host:port); fix or unset it`);
(err as { code?: string }).code = PROXY_INVALID_CODE;
return err;
}

/** Installs the global dispatcher for a proxy setting, or one whose every connection fails for an unusable one. */
export function installProxy(
proxy: Exclude<ProxyFromEnv, { kind: "none" }>,
install: (dispatcher: Dispatcher) => void = setGlobalDispatcher,
): void {
if (proxy.kind === "invalid") {
install(new Agent({ connect: (_opts, callback) => callback(invalidProxyError(proxy.variable), null) }));
return;
}
install(new LoopbackDirect(new EnvHttpProxyAgent({ ...proxy.settings, proxyTunnel: false }), new Agent()));
}
Loading
Loading