Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

16.9 KB
Raw Blame
import * as p from '@clack/prompts'
import { type Options as ExecaOptions, execa } from 'execa'
import pc from 'picocolors'
import { backendTaskCommand, PREPARE_DATABASE } from './backend.js'
import { hasMonorepoSpreePath } from './context.js'

export async function dockerCompose(args: string[], projectDir: string, options?: ExecaOptions) {
  try {
    return await execa('docker', ['compose', ...args], {
      cwd: projectDir,
      ...options,
    })
  } catch (error) {
    throw withDockerHint(error)
  }
}

// Docker's default address pools hold about 30 bridge networks, and every
// compose project keeps its `<name>_default` network after its containers
// stop — so a machine with many old projects fails to create a new one with
// a daemon message that names neither the cause nor the fix.
const ADDRESS_POOLS_EXHAUSTED = /all predefined address pools have been fully subnetted/i

function isAddressPoolExhausted(error: unknown): boolean {
  return ADDRESS_POOLS_EXHAUSTED.test(error instanceof Error ? error.message : String(error))
}

function withDockerHint(error: unknown): unknown {
  if (!isAddressPoolExhausted(error)) return error

  const message = error instanceof Error ? error.message : String(error)
  return new Error(
    `${message}\n\nDocker has no free network addresses left, usually because old projects left their networks behind. ` +
      `List them with ${pc.cyan('docker network ls')} and remove the ones you no longer need with ${pc.cyan('docker network rm <name>')}. ` +
      `${pc.cyan('docker network prune')} removes every network on this machine that no container is using, ` +
      'including networks other tools created and still expect to find.',
    { cause: error },
  )
}

// web and worker share one bundle_cache named volume and, in the dev compose,
// start concurrently. On a COLD volume Docker copies the image's populated
// /usr/local/bundle into it ("copy-up") the first time a container mounts it —
// per container, with no cross-container lock. Two concurrent copy-ups race on
// mkdir of the same nested gem-extension dirs and one loses with "file exists"
// (nondeterministic, first-boot only).
//
// Fix: bring `web` up alone first and wait for it. That single container wins
// the copy-up uncontended; by the time the rest of the stack starts the volume
// is non-empty, Docker's emptiness gate is false, and no further copy-up (hence
// no race) happens. `up -d` blocks until the container is started, which is
// when the copy-up runs (during mount setup, before the entrypoint), so the
// volume is populated once this resolves. On a warm volume it's a ~1s no-op.
//
// Best-effort: a failed prime (image not built yet, daemon hiccup) is swallowed
// so the caller's real `up` builds/pulls and surfaces the genuine error — we
// remove a race, we never mask a failure. The exception is a project network
// Docker cannot create: this is the first `up`, and `spree dev`'s foreground
// `up` streams stderr uncaptured, so this is the one place its hint can show.
export async function primeBundleVolume(
  projectDir: string,
  options?: { stdio?: 'inherit' | 'pipe' | 'ignore' },
): Promise<void> {
  const stdio = options?.stdio ?? 'inherit'
  try {
    await dockerCompose(['up', '-d', '--no-deps', 'web'], projectDir, {
      stdin: stdio,
      stdout: stdio,
      stderr: stdio === 'inherit' ? ['pipe', 'inherit'] : 'pipe',
    })
  } catch (error) {
    if (isAddressPoolExhausted(error)) throw error
  }
}

export async function captureTask(
  task: string,
  projectDir: string,
  env?: Record<string, string>,
): Promise<string> {
  const stdout = await dockerComposeCapture(backendTaskCommand(task), projectDir, { env })

  // Backend boot prints noise to stdout (e.g. "[Spree Events] ...") — strip it
  return stdout
    .split('\n')
    .filter((line) => !line.startsWith('['))
    .join('\n')
    .trim()
}

/**
 * The app services the project's compose file actually defines — ['web'] on
 * the Solid Queue single-container layout (jobs run inside Puma), ['web',
 * 'worker'] on Sidekiq-era projects. Commands target what exists instead of
 * hard-coding the old two-service shape.
 */
export async function appServices(projectDir: string): Promise<string[]> {
  try {
    const { stdout } = await execa('docker', ['compose', 'config', '--services'], {
      cwd: projectDir,
    })
    const services = stdout.split('\n').map((line) => line.trim())
    const app = ['web', 'worker'].filter((name) => services.includes(name))
    return app.length > 0 ? app : ['web']
  } catch {
    // A broken compose file surfaces on the real command that follows.
    return ['web']
  }
}

/**
 * Restart the app services in place when web is running, so a new Puma
 * process loads gems installed or updated since it booted. A stopped stack is
 * left stopped.
 */
export async function restartAppServices(projectDir: string, message: string): Promise<void> {
  if (!(await isServiceRunning('web', projectDir))) return
  p.log.step(pc.bold(message))
  await dockerCompose(['restart', ...(await appServices(projectDir))], projectDir, {
    stdio: 'inherit',
  })
}

/**
 * Whether compose has ever created a container (any state, including exited)
 * for this project.
 */
export async function hasProjectContainers(projectDir: string): Promise<boolean> {
  const { stdout } = await execa('docker', ['compose', 'ps', '-a', '-q'], { cwd: projectDir })
  return stdout.trim().length > 0
}

// Whether a compose service has a running container — used by commands that
// can fall back to `compose run` when the stack is down. A defined service
// with no containers exits 0 with empty output (the legitimate false case);
// anything that makes `compose ps` itself fail — daemon down, broken compose
// file, unknown service — throws, so the caller surfaces the real error
// instead of acting on a wrong "stopped" answer.
export async function isServiceRunning(service: string, projectDir: string): Promise<boolean> {
  const { stdout } = await execa('docker', ['compose', 'ps', service, '--format', '{{.State}}'], {
    cwd: projectDir,
  })
  return stdout.split('\n').some((line) => line.trim() === 'running')
}

// Docker Desktop, the Linux engine and the Windows named pipe each word a
// stopped daemon differently.
const DAEMON_DOWN =
  /Cannot connect to the Docker daemon|failed to connect to the docker API|error during connect/i

/**
 * The refusal shown when `docker compose` itself failed while probing the
 * stack (see isServiceRunning). A missing or stopped Docker gets a plain
 * "install/start Docker"; anything else shows Docker's own reason rather than
 * execa's command line.
 *
 * @param error the error `compose ps` threw
 * @param command the spree command to re-run, e.g. `spree upgrade`
 * @return the message lines
 */
export function dockerStackProblem(error: unknown, command: string): string[] {
  const { code, stderr, originalMessage, message } = error as {
    code?: string
    stderr?: string
    originalMessage?: string
    message?: string
  }
  if (code === 'ENOENT') {
    return [
      'Docker is not installed (the `docker` command was not found).',
      `Install Docker Desktop (or Docker Engine), then re-run ${pc.bold(command)}.`,
    ]
  }

  const output = String(stderr || originalMessage || message || '')
  if (DAEMON_DOWN.test(output)) {
    return [
      'Docker is not running.',
      `Start Docker Desktop (or the Docker service), then re-run ${pc.bold(command)}.`,
    ]
  }

  const reason = output.split('\n').find((line) => line.trim()) ?? ''
  return [
    'Could not inspect the Docker stack from this directory.',
    `  ${pc.dim(reason.trim())}`,
    '',
    `Run ${pc.bold(command)} from your project root (the directory holding the`,
    '.env file), and make sure Docker is running.',
  ]
}

export interface DockerComposeExecOptions {
  service?: string
  tty?: boolean
  // Run the command detached (`-d`): compose starts it inside the container and
  // returns immediately. The process shares the container's lifecycle — stop the
  // container and it dies with it. Used for the admin Tailwind watcher.
  detach?: boolean
  env?: Record<string, string>
}

// Run a command inside a service container. The foundation for `spree exec`,
// `spree task`, `spree test`, and `spree console`.
//
// Defaults to the `web` service and an interactive TTY. Pass `tty: false`
// (which adds `-T`) for non-interactive callers that capture stdout — those
// should use `captureTask` above, which already does this.
//
// stdio is inherited so the command behaves transparently: a Rails console
// stays interactive, a `bundle add` prints progress, an error exits with the
// inner command's exit code.
export async function dockerComposeExec(
  argv: string[],
  projectDir: string,
  options: DockerComposeExecOptions = {},
): Promise<void> {
  const { service = 'web', tty = true, detach = false, env } = options
  const args = ['compose', 'exec']
  if (detach) args.push('-d')
  if (!tty) args.push('-T')
  if (env) {
    for (const [key, value] of Object.entries(env)) {
      args.push('-e', `${key}=${value}`)
    }
  }
  args.push(service, ...argv)

  await execa('docker', args, { cwd: projectDir, stdio: 'inherit' })
}

export interface DockerComposeRunOptions {
  service?: string
  env?: Record<string, string>
  // Also buffer the child's stderr into the thrown ExecaError so the caller can
  // inspect failure output. Off by default: plain `stdio: 'inherit'` is right
  // for interactive sessions (a Rails console's TTY) and leaves stderr
  // unbuffered. db:reset opts in because it pattern-matches the Postgres error.
  captureStderr?: boolean
}

// Run a command in a one-off `compose run --rm` container — the twin of
// dockerComposeExec for when the service's long-running container is NOT up.
// Unlike `exec`, `run` builds a fresh container and (in Compose v2) starts the
// service's depends_on (postgres/mailpit), honoring their
// `condition: service_healthy` healthchecks before the command runs — so it
// works from a fully cold stack. We deliberately omit `--no-deps` (we WANT
// those deps started + health-waited) and `--service-ports` (these callers
// publish nothing, and skipping it avoids colliding with a running web's
// ports). `--rm` removes only this one-off container on exit; the deps it
// started are left warm for the next boot.
//
// stdio is inherited so the command stays transparent: an interactive console
// keeps its TTY, db:seed streams progress, and the inner exit code propagates.
// With `captureStderr`, stderr is teed to `['pipe', 'inherit']` — still printed
// live, but also buffered onto ExecaError.stderr (plain `'inherit'` would leave
// it undefined, so the caller's error inspection would see nothing).
export async function dockerComposeRun(
  argv: string[],
  projectDir: string,
  options: DockerComposeRunOptions = {},
): Promise<void> {
  const { service = 'web', env, captureStderr = false } = options
  const args = ['compose', 'run', '--rm']
  if (env) {
    for (const [key, value] of Object.entries(env)) {
      args.push('-e', `${key}=${value}`)
    }
  }
  args.push(service, ...argv)

  const stdio: ExecaOptions = captureStderr
    ? { stdin: 'inherit', stdout: 'inherit', stderr: ['pipe', 'inherit'] }
    : { stdio: 'inherit' }
  await execa('docker', args, { cwd: projectDir, ...stdio })
}

// The dev compose (an ejected project) starts `bin/rails server` directly,
// bypassing bin/docker-entrypoint and its db:prepare. Puma runs the Solid Queue
// supervisor in-process, and when the database does not exist yet the
// supervisor fails and takes Puma down with it — so on a fresh stack the web
// container exits before anything can `exec` into it. Prepare the database in
// a one-off container instead (no Puma) before the app server is brought up.
// Postgres is started and health-waited explicitly first: older dev compose
// files give web no depends_on, so `run` alone would not wait for it. Being the only container that mounts a
// cold bundle_cache volume, it also wins the copy-up uncontended, so no
// separate primeBundleVolume is needed after it. `--build` makes it use the
// current Dockerfile rather than a dev image left over from an earlier eject,
// and the `up -d` that follows reuses that image.
//
// stdio defaults to piped so a spinner caller stays clean and a failure still
// carries compose's output on the thrown error.
export async function prepareDatabase(
  projectDir: string,
  options?: { stdio?: 'inherit' | 'pipe' | 'ignore' },
): Promise<void> {
  const stdio = options?.stdio ?? 'pipe'
  await dockerCompose(['up', '-d', '--wait', 'postgres'], projectDir, { stdio })
  await dockerCompose(['run', '--rm', '--build', 'web', ...PREPARE_DATABASE], projectDir, {
    stdio,
  })
}

export interface DockerComposeExecOrRunOptions {
  service?: string
  env?: Record<string, string>
  // Extra line appended to the monorepo-edge refusal, after the generic
  // "run pnpm server:dev from the monorepo root" sentence — lets a caller add
  // command-specific context (e.g. bundle's "the edge stack heals gem drift").
  edgeHint?: string
}

// The single gate every app-facing command goes through: `exec` into the
// service's running container, or fall back to a one-off `compose run` when
// it's down. A monorepo edge project (SPREE_PATH in .env) is refused, because
// `run` materializes the project-local compose, which is not the running edge
// config — there the operator must use `pnpm server:*` from the monorepo root.
async function resolveComposeMode(
  projectDir: string,
  options: DockerComposeExecOrRunOptions = {},
): Promise<'exec' | 'run'> {
  const { service = 'web', edgeHint } = options

  if (await isServiceRunning(service, projectDir)) return 'exec'

  if (hasMonorepoSpreePath(projectDir)) {
    p.cancel(
      [
        `The ${service} container is not running, and this is a monorepo edge project.`,
        `Run ${pc.bold('pnpm server:dev')} from the monorepo root${edgeHint ? ` — ${edgeHint}` : ''}.`,
      ].join('\n'),
    )
    process.exit(1)
  }

  p.log.info(
    `${service} container is not running — using a one-off container (\`docker compose run\`) instead.`,
  )
  return 'run'
}

// Run a command in the service's container, transparently falling back to a
// one-off `compose run` when the long-running container is down. This is the
// shared shape behind every app-facing command (`spree migrate`, `spree
// test`, `spree console`, `spree task`, …): exec into the live container if
// it's up, otherwise boot a fresh one-off against the same warm DB/volumes.
export async function dockerComposeExecOrRun(
  argv: string[],
  projectDir: string,
  options: DockerComposeExecOrRunOptions = {},
): Promise<void> {
  const { service = 'web', env } = options

  if ((await resolveComposeMode(projectDir, options)) === 'exec') {
    await dockerComposeExec(argv, projectDir, { service, env })
  } else {
    await dockerComposeRun(argv, projectDir, { service, env })
  }
}

// Captured-output twin of dockerComposeExecOrRun, for callers that parse
// stdout (captureTask, `bundle list`). Non-interactive (`-T`) so a TTY never
// mangles the captured stream; compose's own progress noise goes to stderr,
// which stays off stdout and is buffered onto ExecaError for failure paths.
export async function dockerComposeCapture(
  argv: string[],
  projectDir: string,
  options: DockerComposeExecOrRunOptions = {},
): Promise<string> {
  const { service = 'web', env } = options
  const mode = await resolveComposeMode(projectDir, options)

  const args = ['compose', mode]
  if (mode === 'run') args.push('--rm')
  args.push('-T')
  if (env) {
    for (const [key, value] of Object.entries(env)) {
      args.push('-e', `${key}=${value}`)
    }
  }
  args.push(service, ...argv)

  // `compose up -d` can recreate a container moments before this runs — a
  // recovering project does exactly that — and `exec` into a container that
  // is still starting fails with "not running". That is transient, but the
  // error it surfaces ("Is it running? Start it with `spree dev`") sends the
  // operator after a stack that IS running, so retry briefly before failing.
  let lastError: unknown
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const { stdout } = await execa('docker', args, { cwd: projectDir })
      return stdout
    } catch (error) {
      lastError = error
      if (!isContainerNotReady(error)) throw error
      await new Promise((resolve) => setTimeout(resolve, 2000))
    }
  }
  throw lastError
}

/**
 * A compose `exec` that lost the race with a starting container, as opposed
 * to a command that ran and failed — only the former is worth retrying.
 */
function isContainerNotReady(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)
  return (
    /is not running/i.test(message) ||
    /no such container/i.test(message) ||
    /container .* is restarting/i.test(message)
  )
}

export async function streamLogs(service: string, projectDir: string): Promise<void> {
  await execa('docker', ['compose', 'logs', '-f', service], {
    cwd: projectDir,
    stdio: 'inherit',
  })
}