Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

16.9 KB
Raw Blame
//! Frontend dev-server orchestration: generate the instance env, wait for the
//! backend to be reachable through the proxy, then launch Vite pointed
//! at the proxy origin.

use std::io::Read;
use std::os::unix::process::CommandExt;
use std::process::{Child, Command, Stdio};
use std::sync::{Arc, Mutex};
use std::thread::JoinHandle;

use anyhow::{Context, Result};

use super::instance::{Instance, Port};
use super::{Mode, proxy, repo_root, stage::Stage};

/// The app dir where the Vite dev server runs.
fn app_dir() -> std::path::PathBuf {
    repo_root().join("apps/web")
}

fn prepare_dependencies(stage: &Stage) -> Result<()> {
    let mut prepare = Command::new("bun");
    prepare.current_dir(app_dir()).args(["run", "dev:prepare"]);
    stage.run("Preparing frontend dependencies", &mut prepare)
}

/// Host-facing frontend URL.
pub fn url(instance: &Instance) -> String {
    format!("http://localhost:{}/app", instance.port(Port::Frontend))
}

/// Browser-facing origin for development redirects and integration callbacks.
pub fn https_origin(instance: &Instance) -> Result<String> {
    Ok(format!(
        "https://{}:{}",
        super::tls::hostname()?,
        instance.port(Port::Proxy)
    ))
}

/// Browser-facing development URL, using the machine certificate and proxy.
pub fn https_url(instance: &Instance) -> Result<String> {
    Ok(format!("{}/app/", https_origin(instance)?))
}

/// Frontend URL when the proxy serves the static bundle (headless stacks): the
/// app lives on the single proxy origin, not a dev-server port.
pub fn static_url(instance: &Instance) -> String {
    format!("{}/app/", proxy::url(instance))
}

/// Where the instance's static frontend build is staged. Mounted read-only into
/// the proxy container at `/srv/frontend` (see `gen_compose::add_proxy_service`).
/// Staged per instance — not served from `dist/` directly — so concurrent
/// instances in one checkout can't clobber each other's running frontend, and a
/// later `bun run build` can't mutate a live stack out from under itself.
pub fn static_dir(instance: &Instance) -> std::path::PathBuf {
    instance.artifact_dir().join("frontend")
}

/// Build the app bundle for headless serving and stage it into the instance
/// dir. The build mirrors `just build-dev`
/// (dev-mode bundle, production optimizations), except the backend origin is
/// the `same-origin` sentinel — resolved from `location.origin` at runtime — so
/// the one bundle works on localhost and through any tunneled hostname.
///
/// Setting `VITE_LOCAL_BACKEND_ORIGIN` also keeps `import.meta.env.DEV` true
/// in the static bundle (see `keepImportMetaDev` in apps/web/scripts). `vite build`
/// otherwise compiles DEV from `NODE_ENV=production`, which drops local-only
/// paths such as passwordless auto-login (`just run_local` uses `vite serve`,
/// where DEV is already true). Headless `stack up` sets the same origin env.
///
/// `VITE_LOCAL_ONLY` makes the bundle count as local, as the dev server does
/// through `import.meta.hot`, so local-only flags, routes and tools match
/// `just run_local`.
pub fn build_static(stage: &Stage, instance: &Instance, mode: Mode) -> Result<()> {
    prepare_dependencies(stage)?;
    let dist = {
        let mut cmd = Command::new("bun");
        cmd.current_dir(app_dir())
            .args(["run", "--bun", "build"])
            .env("MODE", "development")
            .env("NODE_ENV", "production")
            .env("VITE_LOCAL_SERVERS", "ALL")
            .env("VITE_LOCAL_BACKEND_ORIGIN", "same-origin")
            .env("VITE_LOCAL_ONLY", "true");
        if mode.spec().runs_local_infra {
            cmd.env("VITE_AI_EDITING_WORKER_URL", "/ai-editing");
        }
        stage.run("Building frontend bundle", &mut cmd)?;
        app_dir().join("dist")
    };
    if stage.is_dry_run() {
        return Ok(());
    }
    if !dist.join("index.html").exists() {
        anyhow::bail!(
            "no index.html in {} — frontend build did not produce a bundle",
            dist.display()
        );
    }
    stage.run_step("Staging frontend bundle", || {
        let staged = static_dir(instance);
        if staged.exists() {
            std::fs::remove_dir_all(&staged)
                .with_context(|| format!("clearing {}", staged.display()))?;
        }
        instance.ensure_artifact_dir()?;
        let status = Command::new("cp")
            .arg("-a")
            .arg(&dist)
            .arg(&staged)
            .status()
            .context("running cp -a")?;
        anyhow::ensure!(status.success(), "cp -a exited with {status}");
        Ok(())
    })
}

/// The env the dev server runs with. Both local and dev point the whole app at
/// the Vite origin, which forwards backend routes to the instance proxy. The
/// modes differ in what the services talk to (local infra vs dev resources).
///
/// When a trace collector is up (`--traces`), point the OTel exporter at the
/// analytics-proxy through the same proxy origin (`/i/otlp`), so tracing works
/// for any instance (named instances have no host-port binding for the proxy)
/// and exercises the real browser -> proxy -> collector path. Left unset
/// otherwise. This overrides the bare-dev defaults in apps/web/.env.local
/// (Vite lets process env win).
fn dev_env(instance: &Instance, mode: Mode, traces_enabled: bool) -> Result<Vec<(String, String)>> {
    let mut env = vec![
        (
            "PORT".to_string(),
            instance.port(Port::Frontend).to_string(),
        ),
        ("VITE_LOCAL_SERVERS".to_string(), "ALL".to_string()),
        ("MACRO_LOCAL_HOSTNAME".to_string(), super::tls::hostname()?),
        (
            "NODE_EXTRA_CA_CERTS".to_string(),
            proxy::ca_pem().display().to_string(),
        ),
        (
            "VITE_LOCAL_BACKEND_ORIGIN".to_string(),
            "same-origin".to_string(),
        ),
        (
            "MACRO_LOCAL_BACKEND_PROXY".to_string(),
            proxy::url(instance),
        ),
        (
            "MACRO_LOCAL_BACKEND_ROUTES".to_string(),
            proxy::frontend_path_prefixes().join(","),
        ),
    ];
    if mode.spec().runs_local_infra {
        env.push((
            "VITE_AI_EDITING_WORKER_URL".to_string(),
            "/ai-editing".to_string(),
        ));
    }
    if traces_enabled {
        env.push((
            "VITE_OTEL_EXPORTER_URL".to_string(),
            "/i/otlp/v1/traces".to_string(),
        ));
        // Tag frontend telemetry with the same env the Datadog agent uses
        // (DD_ENV, default `local`), so the summary's traces/logs links —
        // filtered by that env — actually match the emitted spans/records.
        env.push((
            "VITE_OTEL_ENV".to_string(),
            macro_env_var::maybe_read_env("DD_ENV").unwrap_or_else(|| "local".into()),
        ));
    }
    env.push((
        "VITE_ENABLE_BROWSER_OTEL".to_string(),
        traces_enabled.to_string(),
    ));
    Ok(env)
}

/// Poll the backend (auth health, through the proxy) until ready.
pub fn wait_backend_ready(stage: &Stage, instance: &Instance) -> Result<()> {
    let url = format!("{}/auth/health", proxy::url(instance));
    let cacert = proxy::ca_pem();
    let script = format!(
        "for i in $(seq 1 600); do curl -fsS --cacert '{cacert}' --max-time 3 {url} >/dev/null 2>&1 && exit 0; sleep 0.2; done; echo 'backend not ready'; exit 1",
        cacert = cacert.display()
    );
    let mut cmd = Command::new("bash");
    cmd.arg("-lc").arg(script);
    stage.run("Waiting for backend (proxy /auth/health)", &mut cmd)
}

/// A listening Vite port does not prove the containerized proxy can reach it.
/// Verify the browser's route before announcing that the stack is ready.
fn wait_frontend_proxy_ready(stage: &Stage, instance: &Instance) -> Result<()> {
    let mut cmd = Command::new("curl");
    cmd.args([
        "--fail",
        "--silent",
        "--show-error",
        "--retry",
        "8",
        "--retry-connrefused",
        "--retry-delay",
        "1",
        "--retry-max-time",
        "45",
        "--max-time",
        "5",
        "--output",
        "/dev/null",
        "--cacert",
    ])
    .arg(proxy::ca_pem())
    .arg(format!("{}/app/", proxy::url(instance)));
    stage
        .run("Checking frontend through HTTPS proxy", &mut cmd)
        .with_context(|| {
            format!(
                "HTTPS proxy could not serve the frontend. Check proxy logs and Docker-to-host \
                 firewall access to host.docker.internal:{} (Vite's port). \
                 Direct Vite URL: {}",
                instance.port(Port::Frontend),
                url(instance)
            )
        })
}

/// A running frontend dev server plus its captured output, so an unexpected
/// exit can be explained (the output is otherwise suppressed).
pub struct Frontend {
    pub process: FrontendProcess,
    command: Command,
    port: u16,
}

/// One dev-server process and its captured output, replaced on restart.
pub struct FrontendProcess {
    pub child: Child,
    captured: Arc<Mutex<Vec<u8>>>,
    drains: Vec<JoinHandle<()>>,
}

impl Frontend {
    /// Restart only Vite, preserving the command, environment, and instance port.
    /// Killing the old process group also recovers a stuck in-process reload.
    pub fn restart(&mut self, stage: &Stage) -> Result<()> {
        self.shutdown();
        self.process = spawn(stage, &mut self.command, self.port)?;
        Ok(())
    }

    /// Stop the current dev-server process group.
    pub fn shutdown(&mut self) {
        self.process.shutdown();
    }

    /// Return the last output from an exited dev server.
    pub fn tail_output(&mut self, lines: usize) -> String {
        self.process.tail_output(lines)
    }
}

impl FrontendProcess {
    /// Stop the dev server and all its children. We put Vite and its children
    /// in their own process group at spawn — so signal the
    /// GROUP (negative pid). SIGKILL is enough: the kernel releases the port the
    /// moment the processes die. Then reap Vite and join the drain threads (their
    /// pipes close, so they exit).
    pub fn shutdown(&mut self) {
        if matches!(self.child.try_wait(), Ok(None)) {
            let pgid = self.child.id() as i32;
            // SAFETY: a plain `kill(2)`; an invalid/already-dead group is a harmless
            // ESRCH. The negative pid targets the whole process group.
            unsafe {
                libc::kill(-pgid, libc::SIGKILL);
            }
        }
        let _ = self.child.wait();
        for h in self.drains.drain(..) {
            let _ = h.join();
        }
    }

    /// Join the drain threads and return the last `lines` lines of the dev
    /// server's captured output (for diagnosing why it exited).
    pub fn tail_output(&mut self, lines: usize) -> String {
        for h in self.drains.drain(..) {
            let _ = h.join();
        }
        let buf = self.captured.lock().unwrap_or_else(|e| e.into_inner());
        tail_str(&String::from_utf8_lossy(&buf), lines)
    }
}

impl Drop for FrontendProcess {
    fn drop(&mut self) {
        self.shutdown();
    }
}

fn tail_str(s: &str, n: usize) -> String {
    let lines: Vec<&str> = s.lines().collect();
    let start = lines.len().saturating_sub(n);
    lines[start..].join("\n")
}

/// Start the frontend dev server and wait until *our* child is serving. Output
/// is captured (suppressed — the vite banner would duplicate the summary's URL)
/// but retained so an unexpected exit can be diagnosed. Returns `None` in
/// dry-run mode.
pub fn start(
    stage: &Stage,
    instance: &Instance,
    mode: Mode,
    traces_enabled: bool,
) -> Result<Option<Frontend>> {
    if mode.spec().wait_backend_before_frontend {
        wait_backend_ready(stage, instance)?;
    }
    if stage.is_dry_run() {
        stage.note(&format!(
            "Dry run: would start frontend at {}",
            url(instance)
        ));
        return Ok(None);
    }
    let port = instance.port(Port::Frontend);
    // A successful connect means something is already listening — almost
    // certainly a stale dev server from a previous run. (A bind probe is
    // unreliable: std's TcpListener sets SO_REUSEADDR, so it binds right
    // alongside the squatter.) Bail clearly rather than spawn a bun that can't
    // bind and dies with a confusing late "exited (status 1)".
    if std::net::TcpStream::connect_timeout(
        &([127, 0, 0, 1], port).into(),
        std::time::Duration::from_millis(300),
    )
    .is_ok()
    {
        anyhow::bail!(
            "frontend port {port} is already in use — likely a stale dev server from a \
             previous run. Free it (`lsof -ti tcp:{port} | xargs kill`) and retry."
        );
    }
    prepare_dependencies(stage)?;

    // Vite's node-http-proxy WebSocket upgrades hang under Bun (including
    // 1.3.13). Use Node for the dev server, while keeping Bun for dependencies
    // and builds: https://github.com/oven-sh/bun/issues/10441.
    let mut cmd = Command::new("node");
    cmd.current_dir(app_dir())
        .arg(repo_root().join("node_modules/vite/bin/vite.js"))
        .args(["-c", "vite.config.ts"])
        // Run Vite directly in its OWN process group. Avoiding the `bun run`
        // package-script wrapper keeps the listener in the process we own.
        .process_group(0)
        // Open-but-empty stdin (piped, held open, never written): vite sees a
        // non-TTY stdin so it won't bind its own keypress shortcuts (no fight
        // with our hotkey loop), but it never reaches EOF — Stdio::null is EOF
        // immediately, which makes vite shut itself down right after boot.
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped());
    for (k, v) in dev_env(instance, mode, traces_enabled)? {
        cmd.env(k, v);
    }
    let process = spawn(stage, &mut cmd, port)?;
    wait_frontend_proxy_ready(stage, instance)?;
    Ok(Some(Frontend {
        process,
        command: cmd,
        port,
    }))
}

fn spawn(stage: &Stage, cmd: &mut Command, port: u16) -> Result<FrontendProcess> {
    let mut child = cmd.spawn().context("launching the Vite dev server")?;

    // Drain stdout+stderr into a buffer on their own threads (a full pipe would
    // otherwise block Vite); the output stays hidden unless the server exits.
    // stdin is intentionally NOT taken — its write end stays open so Vite never
    // sees stdin EOF.
    let captured = Arc::new(Mutex::new(Vec::new()));
    let mut drains = Vec::new();
    if let Some(mut out) = child.stdout.take() {
        let buf = Arc::clone(&captured);
        drains.push(std::thread::spawn(move || drain_into(&mut out, &buf)));
    }
    if let Some(mut err) = child.stderr.take() {
        let buf = Arc::clone(&captured);
        drains.push(std::thread::spawn(move || drain_into(&mut err, &buf)));
    }

    // Wait until OUR child is serving: poll the port, but fail fast (with Vite's
    // output) if the child exits first. A bare port poll would mistake a stale
    // server already on the port for "ready" while our child has died.
    let addr: std::net::SocketAddr = ([127, 0, 0, 1], port).into();
    let startup = stage.run_step("Starting frontend", || {
        // Cold starts may rebuild optimized Wasm packages before Vite launches.
        for _ in 0..600 {
            // Settle first: a failed bind (e.g. port already in use) makes vite
            // exit near-instantly, so if the child is still alive after this it
            // genuinely bound the port — rather than us connecting to a stale
            // server squatting it.
            std::thread::sleep(std::time::Duration::from_millis(300));
            if let Some(status) = child.try_wait()? {
                anyhow::bail!(
                    "frontend dev server exited during startup ({status})\n\
                     (if the port is in use, free it: `lsof -ti tcp:{port} | xargs kill`)"
                );
            }
            if std::net::TcpStream::connect_timeout(&addr, std::time::Duration::from_millis(300))
                .is_ok()
            {
                return Ok(());
            }
        }
        anyhow::bail!("frontend dev server did not become ready after 180 seconds")
    });

    if let Err(error) = startup {
        let pgid = child.id() as i32;
        // SAFETY: the child leads the process group created above. ESRCH is
        // harmless when Vite already exited.
        unsafe {
            libc::kill(-pgid, libc::SIGKILL);
        }
        let _ = child.wait();
        for handle in drains.drain(..) {
            let _ = handle.join();
        }
        let out = tail_str(&String::from_utf8_lossy(&captured.lock().unwrap()), 30);
        anyhow::bail!("{error}\nfrontend output (last lines):\n{out}");
    }

    Ok(FrontendProcess {
        child,
        captured,
        drains,
    })
}

/// Copy a child pipe into the shared capture buffer until EOF.
fn drain_into(reader: &mut impl Read, buf: &Mutex<Vec<u8>>) {
    let mut chunk = [0u8; 4096];
    while let Ok(n) = reader.read(&mut chunk) {
        if n == 0 {
            break;
        }
        if let Ok(mut b) = buf.lock() {
            b.extend_from_slice(&chunk[..n]);
        }
    }
}

#[cfg(test)]
mod test;