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
4 changes: 3 additions & 1 deletion apps/cli-docs/src/fragments/commands/local.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ If nothing is listening on the port, a server is started in the background and s

The Local daemon behind `--session` is the exception: it only takes session traffic. When it holds port 8969, a plain `local run` captures on a free port and says so. An SDK that hard-codes 8969 won't reach that port, so make sure it reads `SENTRY_SPOTLIGHT`. Add `--session <name>` to capture into the daemon instead. With an explicit `--port` that the daemon holds, the command stops with an error.

The same goes for a port held by another process that isn't a Local or Spotlight server, such as `python -m http.server 8969`: a plain `local run` captures on a free port and says so, and with an explicit `--port`, or with `local serve`, the command stops with an error that names the port.
The same goes for a port held by another process that isn't a Local or Spotlight server, such as `python -m http.server 8969` or a listener that doesn't answer HTTP: a plain `local run` captures on a free port and says so, and with an explicit `--port`, or with `local serve`, the command stops with an error that names the port.

A `local serve` from Sentry CLI 0.35 to 0.40 doesn't identify itself as a Local server, so newer versions treat it as another process. Upgrade it to attach to it.

With no command, `local run` picks one from the project, in this order:

Expand Down
107 changes: 67 additions & 40 deletions packages/cli/src/commands/local/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ async function startBackgroundServer({
* daemon drops traffic that isn't for a session without a word, so the
* notice says to use SENTRY_SPOTLIGHT.
*
* @param reason - Why the default port is taken, e.g. "is in use"
* @param reason - Why the default port is taken, e.g. "is held by another process"
*/
function freePortNotice(
defaultPort: number,
Expand All @@ -318,9 +318,10 @@ function freePortNotice(
/**
* Get a live event tail on `host:port`, whichever way is available.
*
* Prefers attaching to whatever already holds the port so we never compete
* with it, and falls back to attaching if the bind loses a race. `run` wraps
* the user's dev command, so a busy port must never be fatal here.
* Prefers attaching to a receiver that already holds the port so we never
* compete with it, and probes again if the bind loses a race. Anything else on
* the port fails with a port-in-use error, unless `freePortIfHeld` lets this
* run capture on a free port instead.
*/
async function openEventTail({
port,
Expand All @@ -333,42 +334,52 @@ async function openEventTail({
}: EventTailOptions): Promise<EventTail> {
const url = formatLocalServerUrl(host, port);

let running = false;
// Why this run captures on a free port instead of `port`, if it does.
let heldNotice: ((boundPort: number) => string) | undefined;
try {
running = await isServerRunning(url);
} catch (err) {
if (!(freePortIfHeld && err instanceof ValidationError)) throw err;
if (err.field === PORT_HELD_BY_DAEMON_FIELD) {
// The daemon's receiver only takes session traffic, and it stays up
// while it retains sessions, so a plain run gets its own receiver.
heldNotice = (bound) =>
`${freePortNotice(port, bound, "is held by the Local daemon")} Add --session <name> to capture into the daemon instead.`;
} else if (err.field === PORT_IN_USE_FIELD) {
// A server that is not a receiver would drop every event.
heldNotice = (bound) =>
freePortNotice(port, bound, "is held by another process");
} else {
/**
* Whether a receiver to attach to holds `port`, or, when `freePortIfHeld`
* lets this run move off a held port, why it captures on a free one instead.
*/
const probe = async (): Promise<{
running: boolean;
heldNotice?: (boundPort: number) => string;
}> => {
try {
return { running: await isServerRunning(url) };
} catch (err) {
if (!(freePortIfHeld && err instanceof ValidationError)) throw err;
if (err.field === PORT_HELD_BY_DAEMON_FIELD) {
// The daemon's receiver only takes session traffic, and it stays up
// while it retains sessions, so a plain run gets its own receiver.
return {
running: false,
heldNotice: (bound) =>
`${freePortNotice(port, bound, "is held by the Local daemon")} Add --session <name> to capture into the daemon instead.`,
};
}
if (err.field === PORT_IN_USE_FIELD) {
// A server that is not a receiver would drop every event.
return {
running: false,
heldNotice: (bound) =>
freePortNotice(port, bound, "is held by another process"),
};
}
throw err;
}
}
};

if (running) {
const attach = async (): Promise<EventTail> => {
await configureExistingRetention(url, maxEnvelopes);
logger.info(`Connected to existing server at ${bold(url)}`);
return attachToExistingServer({
activeFilters,
showAttributes,
url,
useJson,
});
}
};

if (!heldNotice) {
logger.info("No server detected, starting one in the background...");
}
try {
const start = async (
heldNotice: ((boundPort: number) => string) | undefined,
): Promise<EventTail> => {
const bg = await startBackgroundServer({
maxEnvelopes,
port: heldNotice ? 0 : port,
Expand All @@ -382,19 +393,31 @@ async function openEventTail({
}
logger.info(`Background server listening on ${bold(bg.url)}`);
return bg;
};

const first = await probe();
if (first.running) {
logger.info(`Connected to existing server at ${bold(url)}`);
return await attach();
}
if (!first.heldNotice) {
logger.info("No server detected, starting one in the background...");
}
try {
return await start(first.heldNotice);
} catch (err) {
if (!(err instanceof ValidationError && err.field === PORT_IN_USE_FIELD)) {
throw err;
}
await configureExistingRetention(url, maxEnvelopes);
// Something grabbed the port between the probe and the bind.
logger.warn(`Port ${port} is in use; attaching to it instead`);
return attachToExistingServer({
activeFilters,
showAttributes,
url,
useJson,
});
// Something grabbed the port between the probe and the bind. Attach only
// if it is a receiver; anything else would drop every event.
const second = await probe();
if (second.running) {
logger.warn(`Port ${port} is in use; attaching to it instead`);
return await attach();
}
if (!second.heldNotice) throw err;
return await start(second.heldNotice);
}
}

Expand Down Expand Up @@ -1020,7 +1043,9 @@ async function listenForVerify(
);
}
const bound = await tryListen(app, 0, host, { retries: 0 });
logger.info(freePortNotice(DEFAULT_PORT, bound.port, "is in use"));
logger.info(
freePortNotice(DEFAULT_PORT, bound.port, "is held by another process"),
);
return { ...bound, fellBack: true };
}
}
Expand Down Expand Up @@ -1205,7 +1230,9 @@ async function* runWithVerify(
if (fellBack) {
// An SDK that ignores SENTRY_SPOTLIGHT still sends to the busy default
// port, so it reaches whatever holds that port instead of this receiver.
logger.warn(freePortNotice(DEFAULT_PORT, boundPort, "is in use"));
logger.warn(
freePortNotice(DEFAULT_PORT, boundPort, "is held by another process"),
);
}
throw new VerifyFailedError(
`Verification timed out after ${verifyTimeout}s — no events received from the SDK`,
Expand Down
101 changes: 82 additions & 19 deletions packages/cli/src/commands/local/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import { isLoopbackHost } from "./loopback.js";
*/

import type { Server } from "node:http";
import { connect } from "node:net";
import { basename } from "node:path";
import { setTimeout as sleep } from "node:timers/promises";
import { serve } from "@hono/node-server";
Expand Down Expand Up @@ -697,27 +698,46 @@ export function tryListen(
}

/**
* Ask `${url}/health` who holds the port: `none` for a transport failure
* (connection refused, timeout), `daemon` for a Sentry Local daemon,
* `receiver` for a Local or Spotlight receiver, which sends the
* {@link SERVER_IDENTIFIER} header even on an error status, and `foreign` for
* any other HTTP server.
* Ask `${url}/health` who holds the port:
* - `none`: the connection was refused, so nothing listens there, or the
* address cannot be reached at all, which the bind then reports itself.
* - `daemon`: a Sentry Local daemon.
* - `receiver`: a Local or Spotlight receiver, which sends the
* {@link SERVER_IDENTIFIER} header even on an error status.
* - `foreign`: any other HTTP server, including one whose `/health`
* redirects, since the probe does not follow redirects.
* - `unresponsive`: something accepted the connection but gave no HTTP
* answer in time: a silent or slow listener, a non-HTTP or TLS server.
*
* Port 0 asks the OS for a free port, so nothing holds it and it is not
* probed. When fetch fails some other way, such as a port that fetch refuses
* to dial ("bad port"), a plain TCP connect decides whether anything listens.
*/
export async function probeLocalHealth(
url: string,
timeoutMs: number,
): Promise<"none" | "daemon" | "receiver" | "foreign"> {
): Promise<"none" | "daemon" | "receiver" | "foreign" | "unresponsive"> {
const { hostname, port } = new URL(url);
if (port === "0") return "none";
let res: Response;
try {
res = await fetch(`${url}/health`, {
redirect: "manual",
signal: AbortSignal.timeout(timeoutMs),
});
} catch (err) {
logger.debug(
`No existing server at ${url}`,
err instanceof Error ? err.message : String(err),
);
return "none";
const message = err instanceof Error ? err.message : String(err);
const timedOut = err instanceof Error && err.name === "TimeoutError";
if (
NO_HOLDER_CODES.has(fetchCauseCode(err)) ||
(!timedOut &&
!(await acceptsTcpConnection(hostname, Number(port || 80), timeoutMs)))
) {
logger.debug(`No existing server at ${url}`, message);
return "none";
}
logger.debug(`Server at ${url} gave no HTTP answer to /health`, message);
return "unresponsive";
Comment thread
MathurAditya724 marked this conversation as resolved.
Resolved
Comment thread
MathurAditya724 marked this conversation as resolved.
Resolved
}
await res.body?.cancel();
if (res.headers.get("X-Sentry-Local-Mode") === "daemon") return "daemon";
Expand All @@ -742,9 +762,9 @@ export async function probeLocalHealth(
* 2xx: Spotlight's own sidecar can answer `/health` with a 5xx while still
* holding the port and ingesting envelopes, and attaching to it is right.
*
* Only a transport-level failure (connection refused, timeout) counts as
* "no server". Any other HTTP server, such as `python -m http.server`, throws
* a port-in-use error: attaching to it would lose every event.
* Only a refused connection counts as "no server". Any other holder, such as
* `python -m http.server` or a listener that never answers `/health`, throws a
* port-in-use error: attaching to it would lose every event.
*/
export async function isServerRunning(url: string): Promise<boolean> {
const holder = await probeLocalHealth(url, 2000);
Expand All @@ -754,7 +774,7 @@ export async function isServerRunning(url: string): Promise<boolean> {
PORT_HELD_BY_DAEMON_FIELD,
);
}
if (holder === "foreign") {
if (holder === "foreign" || holder === "unresponsive") {
throw portInUseError(Number(new URL(url).port || 80));
}
return holder === "receiver";
Expand Down Expand Up @@ -864,12 +884,55 @@ function isAbortError(err: unknown): boolean {
);
}

/**
* Connect failures that mean nothing can hold the port: it was refused, the
* host does not resolve, or the address is unreachable or not local. The
* bind gives the accurate error for a bad --host, not "port in use".
*/
const NO_HOLDER_CODES = new Set<string | undefined>([
"ECONNREFUSED",
"ENOTFOUND",
"EAI_AGAIN",
"EHOSTUNREACH",
"ENETUNREACH",
"EADDRNOTAVAIL",
]);

/** Whether anything accepts a TCP connection at `hostname`:`port`. */
function acceptsTcpConnection(
hostname: string,
port: number,
timeoutMs: number,
): Promise<boolean> {
return new Promise((resolve) => {
const socket = connect({
host: hostname.replace(/^\[(.*)\]$/, "$1"),
port,
timeout: timeoutMs,
});
const done = (accepted: boolean) => {
socket.destroy();
resolve(accepted);
};
socket.once("connect", () => done(true));
socket.once("error", () => done(false));
socket.once("timeout", () => done(false));
});
}

/** The `code` of a failed `fetch`'s cause, such as `ECONNREFUSED`. */
function fetchCauseCode(err: unknown): string | undefined {
const cause = err instanceof Error ? err.cause : undefined;
return cause instanceof Error &&
"code" in cause &&
typeof cause.code === "string"
? cause.code
: undefined;
}

/** Whether a failed `fetch` found nothing listening at the address. */
export function isConnectionRefused(err: unknown): boolean {
const cause = err instanceof Error ? err.cause : undefined;
return (
cause instanceof Error && "code" in cause && cause.code === "ECONNREFUSED"
);
return fetchCauseCode(err) === "ECONNREFUSED";
}

/** Sleep with abort support, suppressing abort errors. */
Expand Down
Loading
Loading