buncargo 1.0.29 → 3.2.0

package/src/core/quick-tunnel/constants.ts

@@ -0,0 +1,31 @@
+/**
+ * Paths and release metadata for the cloudflared binary.
+ * Derived from unjs/untun (MIT), originally forked from node-cloudflared.
+ */
+
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+export const CLOUDFLARED_VERSION =
+	process.env.CLOUDFLARED_VERSION || "2023.10.0";
+
+export const RELEASE_BASE =
+	"https://github.com/cloudflare/cloudflared/releases/";
+
+/** Directory for buncargo-managed cloudflared (avoid clashing with untun's node-untun). */
+export const cloudflaredBinPath = path.join(
+	tmpdir(),
+	"buncargo-cloudflared",
+	process.platform === "win32"
+		? `cloudflared.${CLOUDFLARED_VERSION}.exe`
+		: `cloudflared.${CLOUDFLARED_VERSION}`,
+);
+
+export const cloudflaredNotice = `
+🔥 Your installation of cloudflared software constitutes a symbol of your signature
+ indicating that you accept the terms of the Cloudflare License, Terms and Privacy Policy.
+
+❯ License: \`https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/license/\`
+❯ Terms: \`https://www.cloudflare.com/terms/\`
+❯ Privacy Policy: \`https://www.cloudflare.com/privacypolicy/\`
+`;

package/src/core/quick-tunnel/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Cloudflare Quick Tunnel via the cloudflared CLI (same approach as unjs/untun).
+ * License / download flow adapted from unjs/untun (MIT).
+ */
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { startCloudflaredTunnel } from "./cloudflared-process";
+import { cloudflaredBinPath, cloudflaredNotice } from "./constants";
+import { installCloudflared } from "./install";
+
+export interface QuickTunnelOptions {
+	url?: string;
+	port?: number | string;
+	hostname?: string;
+	protocol?: "http" | "https";
+	verifyTLS?: boolean;
+	acceptCloudflareNotice?: boolean;
+}
+
+export interface QuickTunnel {
+	getURL: () => Promise<string>;
+	close: () => Promise<void>;
+}
+
+function resolvedLocalUrl(opts: QuickTunnelOptions): string {
+	return (
+		opts.url ??
+		`${opts.protocol || "http"}://${opts.hostname ?? "localhost"}:${opts.port ?? 3000}`
+	);
+}
+
+function envAcceptsCloudflareNotice(): boolean {
+	const v = process.env.BUNCARGO_ACCEPT_CLOUDFLARE_NOTICE;
+	const u = process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE;
+	return v === "1" || v === "true" || u === "1" || u === "true";
+}
+
+async function promptInstallCloudflared(): Promise<boolean> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return false;
+	}
+	return new Promise((resolve) => {
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		rl.question(
+			"Do you agree with the above terms and wish to install the binary from GitHub? (y/N) ",
+			(answer) => {
+				rl.close();
+				resolve(/^y(es)?$/i.test(answer.trim()));
+			},
+		);
+	});
+}
+
+/**
+ * Start a Cloudflare quick tunnel to a local HTTP(S) URL.
+ * Returns undefined if the user declines the cloudflared install (when binary is missing).
+ */
+export async function startQuickTunnel(
+	opts: QuickTunnelOptions,
+): Promise<QuickTunnel | undefined> {
+	const url = resolvedLocalUrl(opts);
+
+	console.log(`Starting cloudflared tunnel to ${url}`);
+
+	if (!existsSync(cloudflaredBinPath)) {
+		console.log(cloudflaredNotice);
+		const canInstall =
+			opts.acceptCloudflareNotice ||
+			envAcceptsCloudflareNotice() ||
+			(await promptInstallCloudflared());
+		if (!canInstall) {
+			console.error("Skipping tunnel setup.");
+			return;
+		}
+		await installCloudflared();
+	}
+
+	const cfArgs: Record<string, string | number | null> = { "--url": url };
+	// Boolean flag: use `null` value so spawn does not pass a stray empty argv (see cloudflared-process).
+	if (!opts.verifyTLS) {
+		cfArgs["--no-tls-verify"] = null;
+	}
+	const tunnel = startCloudflaredTunnel(cfArgs);
+
+	const cleanup = async () => {
+		tunnel.stop();
+	};
+
+	return {
+		getURL: async () => await tunnel.url,
+		close: cleanup,
+	};
+}

package/src/core/quick-tunnel/install.ts

@@ -0,0 +1,160 @@
+/**
+ * Download cloudflared from GitHub releases.
+ * Derived from unjs/untun (MIT), originally forked from node-cloudflared.
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import https from "node:https";
+import path from "node:path";
+import {
+	CLOUDFLARED_VERSION,
+	cloudflaredBinPath,
+	RELEASE_BASE,
+} from "./constants";
+
+const LINUX_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	arm64: "cloudflared-linux-arm64",
+	arm: "cloudflared-linux-arm",
+	x64: "cloudflared-linux-amd64",
+	ia32: "cloudflared-linux-386",
+};
+
+const MACOS_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	arm64: "cloudflared-darwin-amd64.tgz",
+	x64: "cloudflared-darwin-amd64.tgz",
+};
+
+const WINDOWS_URL: Partial<Record<NodeJS.Architecture, string>> = {
+	x64: "cloudflared-windows-amd64.exe",
+	ia32: "cloudflared-windows-386.exe",
+};
+
+function resolveBase(version: string): string {
+	if (version === "latest") {
+		return `${RELEASE_BASE}latest/download/`;
+	}
+	return `${RELEASE_BASE}download/${version}/`;
+}
+
+export function installCloudflared(
+	to: string = cloudflaredBinPath,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	switch (process.platform) {
+		case "linux": {
+			return installLinux(to, version);
+		}
+		case "darwin": {
+			return installMacos(to, version);
+		}
+		case "win32": {
+			return installWindows(to, version);
+		}
+		default: {
+			throw new Error(`Unsupported platform: ${process.platform}`);
+		}
+	}
+}
+
+async function installLinux(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = LINUX_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, to);
+	fs.chmodSync(to, 0o755);
+	return to;
+}
+
+async function installMacos(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = MACOS_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, `${to}.tgz`);
+	if (process.env.DEBUG) {
+		console.log(`Extracting to ${to}`);
+	}
+	execSync(`tar -xzf ${path.basename(`${to}.tgz`)}`, {
+		cwd: path.dirname(to),
+	});
+	fs.unlinkSync(`${to}.tgz`);
+	fs.renameSync(`${path.dirname(to)}/cloudflared`, to);
+	return to;
+}
+
+async function installWindows(
+	to: string,
+	version = CLOUDFLARED_VERSION,
+): Promise<string> {
+	const file = WINDOWS_URL[process.arch];
+
+	if (file === undefined) {
+		throw new Error(`Unsupported architecture: ${process.arch}`);
+	}
+
+	await download(resolveBase(version) + file, to);
+	return to;
+}
+
+function download(url: string, to: string, redirect = 0): Promise<string> {
+	if (redirect === 0) {
+		if (process.env.DEBUG) {
+			console.log(`Downloading ${url} to ${to}`);
+		}
+	} else if (process.env.DEBUG) {
+		console.log(`Redirecting to ${url}`);
+	}
+
+	return new Promise((resolve, reject) => {
+		if (!fs.existsSync(path.dirname(to))) {
+			fs.mkdirSync(path.dirname(to), { recursive: true });
+		}
+
+		let done = true;
+		const file = fs.createWriteStream(to);
+		const request = https.get(url, (res) => {
+			if (res.statusCode === 302 && res.headers.location !== undefined) {
+				const redirection = res.headers.location;
+				done = false;
+				file.close(() => {
+					void download(redirection, to, redirect + 1).then(resolve, reject);
+				});
+				return;
+			}
+			res.pipe(file);
+		});
+
+		file.on("finish", () => {
+			if (done) {
+				file.close(() => {
+					resolve(to);
+				});
+			}
+		});
+
+		request.on("error", (err) => {
+			fs.unlink(to, () => {
+				reject(err);
+			});
+		});
+
+		file.on("error", (err) => {
+			fs.unlink(to, () => {
+				reject(err);
+			});
+		});
+
+		request.end();
+	});
+}

package/src/core/tunnel.ts

@@ -0,0 +1,165 @@
+import type { AppConfig, DevEnvironment, ServiceConfig } from "../types";
+import { startQuickTunnel } from "./quick-tunnel";
+
+export interface PublicExposeTarget {
+	kind: "service" | "app";
+	name: string;
+	port: number;
+}
+
+export interface PublicTunnel {
+	kind: "service" | "app";
+	name: string;
+	localUrl: string;
+	publicUrl: string;
+	close: () => Promise<void>;
+}
+
+interface TunnelBackendResult {
+	getURL?: () => Promise<string>;
+	url?: string;
+	publicUrl?: string;
+	tunnelUrl?: string;
+	close?: () => void | Promise<void>;
+	stop?: () => void | Promise<void>;
+	destroy?: () => void | Promise<void>;
+}
+
+function parseExposeNames(exposeValue?: string): Set<string> | null {
+	if (exposeValue === undefined) return null;
+	const names = exposeValue
+		.split(",")
+		.map((name) => name.trim())
+		.filter(Boolean);
+	return new Set(names);
+}
+
+/** Resolves public origin from tunnel backends (sync fields or untun-style async getURL). */
+async function resolvePublicUrl(
+	tunnel: TunnelBackendResult,
+): Promise<string | null> {
+	if (typeof tunnel.getURL === "function") {
+		return await tunnel.getURL();
+	}
+	return tunnel.url ?? tunnel.publicUrl ?? tunnel.tunnelUrl ?? null;
+}
+
+function toCloseFn(tunnel: TunnelBackendResult): () => Promise<void> {
+	const close = tunnel.close ?? tunnel.stop ?? tunnel.destroy;
+	if (!close) return async () => {};
+	return async () => {
+		await close();
+	};
+}
+
+export function resolveExposeTargets<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	env: DevEnvironment<TServices, TApps>,
+	exposeValue?: string,
+): {
+	targets: PublicExposeTarget[];
+	unknownNames: string[];
+	notEnabledNames: string[];
+} {
+	const requestedNames = parseExposeNames(exposeValue);
+	const knownTargets = new Map<string, PublicExposeTarget>();
+	const enabledTargets = new Map<string, PublicExposeTarget>();
+
+	for (const [name, config] of Object.entries(env.services)) {
+		const port = env.ports[name];
+		if (port === undefined) continue;
+		const target: PublicExposeTarget = { kind: "service", name, port };
+		knownTargets.set(name, target);
+		if (config.expose === true) {
+			enabledTargets.set(name, target);
+		}
+	}
+
+	for (const [name, config] of Object.entries(env.apps)) {
+		const port = env.ports[name];
+		if (port === undefined) continue;
+		const target: PublicExposeTarget = { kind: "app", name, port };
+		knownTargets.set(name, target);
+		if (config.expose === true) {
+			enabledTargets.set(name, target);
+		}
+	}
+
+	if (requestedNames === null) {
+		return {
+			targets: Array.from(enabledTargets.values()),
+			unknownNames: [],
+			notEnabledNames: [],
+		};
+	}
+
+	const unknownNames: string[] = [];
+	const notEnabledNames: string[] = [];
+	const targets: PublicExposeTarget[] = [];
+
+	for (const name of requestedNames) {
+		if (!knownTargets.has(name)) {
+			unknownNames.push(name);
+			continue;
+		}
+		const enabledTarget = enabledTargets.get(name);
+		if (!enabledTarget) {
+			notEnabledNames.push(name);
+			continue;
+		}
+		targets.push(enabledTarget);
+	}
+
+	return { targets, unknownNames, notEnabledNames };
+}
+
+export async function startPublicTunnels(
+	targets: PublicExposeTarget[],
+	options: {
+		start?: (input: {
+			url: string;
+		}) => Promise<TunnelBackendResult | undefined>;
+	} = {},
+): Promise<PublicTunnel[]> {
+	const start = options.start ?? ((input) => startQuickTunnel(input));
+	const tunnels: PublicTunnel[] = [];
+
+	try {
+		for (const target of targets) {
+			const localUrl = `http://localhost:${target.port}`;
+			const tunnel = (await start({
+				url: localUrl,
+			})) as TunnelBackendResult | undefined;
+			if (tunnel === undefined) {
+				throw new Error(
+					`Tunnel for "${target.name}" could not be started (cloudflared missing or install declined)`,
+				);
+			}
+			const publicUrl = await resolvePublicUrl(tunnel);
+			if (!publicUrl) {
+				throw new Error(
+					`Tunnel for "${target.name}" did not provide a public URL`,
+				);
+			}
+			tunnels.push({
+				kind: target.kind,
+				name: target.name,
+				localUrl,
+				publicUrl,
+				close: toCloseFn(tunnel),
+			});
+		}
+		return tunnels;
+	} catch (error) {
+		await stopPublicTunnels(tunnels);
+		throw error;
+	}
+}
+
+export async function stopPublicTunnels(
+	tunnels: PublicTunnel[],
+): Promise<void> {
+	await Promise.allSettled(tunnels.map((tunnel) => tunnel.close()));
+}

package/{core → src/core}/utils.ts

@@ -93,6 +93,7 @@ export function getEnvVar<
 			projectName: config.projectPrefix,
 			localIp,
 			portOffset: offset,
+			publicUrls: {},
 		},
 	);
 

package/{core → src/core}/watchdog.ts

@@ -120,6 +120,10 @@ export function getWatchdogPid(projectName: string): number | null {
  * Spawn watchdog as a detached process.
  * The watchdog monitors the heartbeat file and shuts down containers after idle timeout.
  */
+export function getWatchdogComposeArg(composeFile?: string): string {
+	return composeFile ? `-f "${composeFile}"` : "";
+}
+
 export async function spawnWatchdog(
 	projectName: string,
 	root: string,
@@ -162,7 +166,7 @@ export async function spawnWatchdog(
 			WATCHDOG_HEARTBEAT_FILE: getHeartbeatFile(projectName),
 			WATCHDOG_PID_FILE: pidFile,
 			WATCHDOG_TIMEOUT_MS: String(timeoutMinutes * 60 * 1000),
-			WATCHDOG_COMPOSE_ARG: composeFile ? `-f ${composeFile}` : "",
+			WATCHDOG_COMPOSE_ARG: getWatchdogComposeArg(composeFile),
 		},
 	});
 

package/src/docker/index.ts

@@ -0,0 +1 @@
+export * from "./runtime";

package/{core/docker.ts → src/docker/runtime.ts}

@@ -1,10 +1,10 @@
 import { execSync } from "node:child_process";
+import { sleep } from "../core/utils";
 import type {
 	BuiltInHealthCheck,
 	HealthCheckFn,
 	ServiceConfig,
 } from "../types";
-import { sleep } from "./utils";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
@@ -91,6 +91,13 @@ export interface StartContainersOptions {
 	composeFile?: string;
 }
 
+/**
+ * Build `-f` argument for docker compose.
+ */
+export function getComposeArg(composeFile?: string): string {
+	return composeFile ? `-f "${composeFile}"` : "";
+}
+
 /**
  * Start Docker Compose containers.
  */
@@ -105,7 +112,7 @@ export function startContainers(
 
 	if (verbose) console.log("🐳 Starting Docker containers...");
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const waitFlag = wait ? "--wait" : "";
 	const cmd = `docker compose ${composeArg} up -d ${waitFlag}`.trim();
 
@@ -143,7 +150,7 @@ export function stopContainers(
 		);
 	}
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const volumeFlag = removeVolumes ? "-v" : "";
 	const cmd = `docker compose ${composeArg} down ${volumeFlag}`.trim();
 
@@ -171,7 +178,7 @@ export function startService(
 
 	if (verbose) console.log(`🐳 Starting ${serviceName}...`);
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const cmd = `docker compose ${composeArg} up -d ${serviceName}`.trim();
 
 	execSync(cmd, {

package/src/docker-compose/generated-file.ts

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import type { DockerComposeGenerationOptions, ServiceConfig } from "../types";
+import { buildComposeModel } from "./model";
+import { composeToYaml } from "./yaml";
+
+export const DEFAULT_GENERATED_COMPOSE_FILE =
+	".buncargo/docker-compose.generated.yml";
+
+export function getGeneratedComposePath(
+	root: string,
+	docker?: DockerComposeGenerationOptions,
+): { absolutePath: string; composeFileArg: string } {
+	const generatedFile = docker?.generatedFile ?? DEFAULT_GENERATED_COMPOSE_FILE;
+	const absolutePath = isAbsolute(generatedFile)
+		? generatedFile
+		: resolve(root, generatedFile);
+	const relativePath = relative(root, absolutePath);
+	const composeFileArg =
+		relativePath && !relativePath.startsWith("..")
+			? relativePath
+			: absolutePath;
+	return { absolutePath, composeFileArg };
+}
+
+export function writeGeneratedComposeFile(
+	root: string,
+	services: Record<string, ServiceConfig>,
+	docker?: DockerComposeGenerationOptions,
+): string {
+	const { absolutePath, composeFileArg } = getGeneratedComposePath(
+		root,
+		docker,
+	);
+	const writeStrategy = docker?.writeStrategy ?? "always";
+	const shouldWrite = writeStrategy === "always" || !existsSync(absolutePath);
+	if (shouldWrite) {
+		const composeModel = buildComposeModel(services, docker);
+		const yaml = composeToYaml(composeModel);
+		mkdirSync(dirname(absolutePath), { recursive: true });
+		writeFileSync(absolutePath, yaml, "utf-8");
+	}
+
+	return composeFileArg;
+}

package/src/docker-compose/index.ts

@@ -0,0 +1,7 @@
+export {
+	DEFAULT_GENERATED_COMPOSE_FILE,
+	getGeneratedComposePath,
+	writeGeneratedComposeFile,
+} from "./generated-file";
+export { buildComposeModel } from "./model";
+export { composeToYaml } from "./yaml";