@livestore/utils-dev 0.4.0-dev.9 → 0.5.0-dev.0

package/src/node/{DockerComposeService/DockerComposeService.test.ts → DockerCompose/DockerCompose.test.ts}

@@ -1,39 +1,42 @@
 import path from 'node:path'
+
+import { expect } from 'vitest'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
 import { Duration, Effect, Layer, Stream } from '@livestore/utils/effect'
 import { PlatformNode } from '@livestore/utils/node'
-import { Vitest } from '@livestore/utils-dev/node-vitest'
-import { expect } from 'vitest'
-import { type DockerComposeArgs, DockerComposeService } from './DockerComposeService.ts'
+
+import * as DockerCompose from './DockerCompose.ts'
 
 const testTimeout = 30_000
 const testFixturePath = path.join(import.meta.dirname, 'test-fixtures')
 
-const DockerComposeTest = (args: Partial<DockerComposeArgs> = {}) =>
-  DockerComposeService.Default({
+const DockerComposeTest = (args: Partial<DockerCompose.Options> = {}) =>
+  DockerCompose.layer({
     cwd: testFixturePath,
     ...args,
   })
 
-Vitest.describe('DockerComposeService', { timeout: testTimeout }, () => {
+Vitest.describe('DockerCompose', { timeout: testTimeout }, () => {
   Vitest.describe('Basic Operations', () => {
-    const withBasicTest = (args: Partial<DockerComposeArgs> = {}) =>
+    const withBasicTest = (args: Partial<DockerCompose.Options> = {}) =>
       Vitest.makeWithTestCtx({
         timeout: testTimeout,
-        makeLayer: () => DockerComposeTest(args).pipe(Layer.provide(PlatformNode.NodeContext.layer)),
+        makeLayer: () => DockerComposeTest(args).pipe(Layer.provide(PlatformNode.NodeServices.layer)),
       })
 
-    Vitest.scopedLive('can pull docker images', (test) =>
+    Vitest.live('can pull docker images', (test) =>
       Effect.gen(function* () {
-        const dockerCompose = yield* DockerComposeService
+        const dockerCompose = yield* DockerCompose.DockerCompose
 
         // Test that pull operation works (should succeed for hello-world image)
         yield* dockerCompose.pull
       }).pipe(withBasicTest()(test)),
     )
 
-    Vitest.scopedLive('can start and stop docker compose services', (test) =>
+    Vitest.live('can start and stop docker compose services', (test) =>
       Effect.gen(function* () {
-        const dockerCompose = yield* DockerComposeService
+        const dockerCompose = yield* DockerCompose.DockerCompose
 
         // Start the service
         yield* dockerCompose.start({ detached: true })
@@ -43,9 +46,9 @@ Vitest.describe('DockerComposeService', { timeout: testTimeout }, () => {
       }).pipe(withBasicTest({ serviceName: 'hello-world' })(test)),
     )
 
-    Vitest.scopedLive('can get logs from docker compose services', (test) =>
+    Vitest.live('can get logs from docker compose services', (test) =>
       Effect.gen(function* () {
-        const dockerCompose = yield* DockerComposeService
+        const dockerCompose = yield* DockerCompose.DockerCompose
 
         // Start the service first
         yield* dockerCompose.start({ detached: true })
@@ -62,15 +65,15 @@ Vitest.describe('DockerComposeService', { timeout: testTimeout }, () => {
   })
 
   Vitest.describe('Health Check Operations', () => {
-    const withHealthCheckTest = (args: Partial<DockerComposeArgs> = {}) =>
+    const withHealthCheckTest = (args: Partial<DockerCompose.Options> = {}) =>
       Vitest.makeWithTestCtx({
         timeout: testTimeout,
-        makeLayer: () => DockerComposeTest(args).pipe(Layer.provide(PlatformNode.NodeContext.layer)),
+        makeLayer: () => DockerComposeTest(args).pipe(Layer.provide(PlatformNode.NodeServices.layer)),
       })
 
-    Vitest.scopedLive('handles health check timeout gracefully', (test) =>
+    Vitest.live('handles health check timeout gracefully', (test) =>
       Effect.gen(function* () {
-        const dockerCompose = yield* DockerComposeService
+        const dockerCompose = yield* DockerCompose.DockerCompose
 
         // Test starting with a health check that will timeout (invalid URL)
         const result = yield* dockerCompose
@@ -81,10 +84,10 @@ Vitest.describe('DockerComposeService', { timeout: testTimeout }, () => {
               timeout: Duration.seconds(2),
             },
           })
-          .pipe(Effect.either)
+          .pipe(Effect.result)
 
         // Should fail due to health check timeout
-        expect(result._tag).toBe('Left')
+        expect(result._tag).toBe('Failure')
       }).pipe(withHealthCheckTest({ serviceName: 'hello-world' })(test)),
     )
   })

package/src/node/DockerCompose/DockerCompose.ts

@@ -0,0 +1,328 @@
+import { objectToString, omitUndefineds } from '@livestore/utils'
+import {
+  ChildProcess,
+  ChildProcessSpawner,
+  Context,
+  Duration,
+  Effect,
+  Fiber,
+  Layer,
+  type PlatformError,
+  Schedule,
+  Schema,
+  type Scope,
+  Stream,
+} from '@livestore/utils/effect'
+
+export class DockerComposeError extends Schema.TaggedError<DockerComposeError>(
+  '~@livestore/utils-dev/DockerComposeError',
+)('DockerComposeError', {
+  cause: Schema.Defect(),
+  note: Schema.String,
+  /** Compose env of the failed invocation, if any — structured instead of string-formatted into `note`. */
+  env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}) {}
+
+export interface Options {
+  readonly cwd: string
+  readonly serviceName?: string
+  /** Unique project name to isolate this compose instance. If not provided, a random one is generated. */
+  readonly projectName?: string
+}
+
+export interface StartOptions {
+  readonly detached?: boolean
+  readonly env?: Record<string, string>
+  readonly healthCheck?: {
+    readonly url: string
+    readonly timeout?: Duration.Duration
+    readonly interval?: Duration.Duration
+  }
+}
+
+export interface LogsOptions {
+  readonly follow?: boolean
+  readonly tail?: number
+  readonly since?: string
+}
+
+export interface Service {
+  readonly pull: Effect.Effect<void, DockerComposeError | PlatformError.PlatformError>
+  readonly start: (
+    options?: StartOptions,
+  ) => Effect.Effect<void, DockerComposeError | PlatformError.PlatformError, Scope.Scope>
+  readonly stop: Effect.Effect<void, DockerComposeError | PlatformError.PlatformError>
+  readonly down: (options?: {
+    readonly env?: Record<string, string>
+    readonly volumes?: boolean
+    readonly removeOrphans?: boolean
+  }) => Effect.Effect<void, DockerComposeError | PlatformError.PlatformError>
+  readonly logs: (
+    options?: LogsOptions,
+  ) => Stream.Stream<string, DockerComposeError | PlatformError.PlatformError, Scope.Scope>
+  /** The unique project name used to isolate this compose instance */
+  readonly projectName: string
+}
+
+const generateProjectName = (): string => `ls-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+export class DockerCompose extends Context.Service<DockerCompose, Service>()('@livestore/utils-dev/DockerCompose') {}
+
+export const make = (args: Options) =>
+  Effect.gen(function* () {
+    const { cwd, serviceName } = args
+    const projectName = args.projectName ?? generateProjectName()
+
+    const commandExecutorContext = yield* Effect.context<ChildProcessSpawner.ChildProcessSpawner>()
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+
+    const baseComposeArgs = ['-p', projectName]
+
+    const composeCommand = (args: ReadonlyArray<string>, options: ChildProcess.CommandOptions = {}) =>
+      ChildProcess.make('docker', ['compose', ...baseComposeArgs, ...args], { ...options, cwd })
+
+    const envOptions = (
+      env: Record<string, string> | undefined,
+    ): Pick<ChildProcess.CommandOptions, 'env' | 'extendEnv'> => (env === undefined ? {} : { env, extendEnv: true })
+
+    const pull = Effect.gen(function* () {
+      yield* Effect.log(`Pulling Docker Compose images in ${cwd}`)
+
+      const process = yield* spawner.spawn(composeCommand(['pull'], { stdout: 'pipe', stderr: 'pipe' }))
+
+      const stdoutFiber = yield* process.stdout.pipe(
+        Stream.decodeText({ encoding: 'utf8' }),
+        Stream.runFold(
+          () => '',
+          (acc, chunk) => acc + chunk,
+        ),
+        // Drain subprocess output immediately so the child cannot block while we wait for its exit code.
+        Effect.forkChild,
+      )
+
+      const stderrFiber = yield* process.stderr.pipe(
+        Stream.decodeText({ encoding: 'utf8' }),
+        Stream.runFold(
+          () => '',
+          (acc, chunk) => acc + chunk,
+        ),
+        // Drain subprocess output immediately so the child cannot block while we wait for its exit code.
+        Effect.forkChild,
+      )
+
+      const exitCode = yield* process.exitCode
+      const stdout = yield* Fiber.join(stdoutFiber)
+      const stderr = yield* Fiber.join(stderrFiber)
+
+      const exitCodeNumber = Number(exitCode)
+
+      if (exitCodeNumber !== 0) {
+        const stdoutLog = stdout.length > 0 ? stdout : '<empty stdout>'
+        const stderrLog = stderr.length > 0 ? stderr : '<empty stderr>'
+        const failureMessage = [
+          `Docker compose pull failed with exit code ${exitCodeNumber} in ${cwd}`,
+          `stdout:\n${stdoutLog}`,
+          `stderr:\n${stderrLog}`,
+        ].join('\n')
+
+        yield* Effect.logError(failureMessage)
+
+        return yield* new DockerComposeError({
+          cause: new Error(`Docker compose pull failed with exit code ${exitCodeNumber}`),
+          note: failureMessage,
+        })
+      }
+
+      yield* Effect.log(`Successfully pulled Docker Compose images`)
+    }).pipe(
+      Effect.retry({
+        schedule: Schedule.exponentialBackoff10Sec,
+        while: Schema.is(DockerComposeError),
+      }),
+      Effect.withSpan('pullDockerComposeImages'),
+      Effect.scoped,
+    )
+
+    const start = Effect.fn('startDockerCompose')(function* (options: StartOptions = {}) {
+      const { detached = true, healthCheck } = options
+
+      const startArgs = ['up']
+      if (detached === true) startArgs.push('-d')
+      if (serviceName !== undefined) startArgs.push(serviceName)
+
+      const process = yield* spawner
+        .spawn(composeCommand(startArgs, { ...envOptions(options.env), stderr: 'inherit', stdout: 'inherit' }))
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new DockerComposeError({
+                cause,
+                note: `Failed to start Docker Compose services in ${cwd}`,
+              }),
+          ),
+        )
+
+      const exitCode = yield* process.exitCode
+
+      if (Number(exitCode) !== 0) {
+        return yield* new DockerComposeError({
+          cause: new Error(`Docker compose exited with code ${exitCode}`),
+          note: `Docker Compose failed to start with exit code ${exitCode}`,
+          env: options.env,
+        })
+      }
+
+      if (healthCheck !== undefined) {
+        yield* performHealthCheck(healthCheck).pipe(Effect.provide(commandExecutorContext))
+      }
+
+      yield* Effect.log(`Docker Compose services started successfully in ${cwd}`)
+    })
+
+    const stop = Effect.gen(function* () {
+      yield* Effect.log(`Stopping Docker Compose services in ${cwd}`)
+
+      const stopArgs = serviceName === undefined ? ['stop'] : ['stop', serviceName]
+      const exitCode = yield* spawner.exitCode(composeCommand(stopArgs))
+
+      if (Number(exitCode) !== 0) {
+        return yield* new DockerComposeError({
+          cause: new Error(`Docker compose stop exited with code ${exitCode}`),
+          note: `Failed to stop Docker Compose services`,
+        })
+      }
+
+      yield* Effect.log(`Docker Compose services stopped successfully`)
+    }).pipe(Effect.withSpan('stopDockerCompose'))
+
+    const logs = (options: LogsOptions = {}) =>
+      Effect.gen(function* () {
+        const { follow = false, tail, since } = options
+
+        const logsArgs = ['logs']
+        if (follow === true) logsArgs.push('-f')
+        if (tail !== undefined) logsArgs.push('--tail', tail.toString())
+        if (since !== undefined) logsArgs.push('--since', since)
+        if (serviceName !== undefined) logsArgs.push(serviceName)
+
+        const process = yield* spawner.spawn(composeCommand(logsArgs)).pipe(
+          Effect.mapError(
+            (cause) =>
+              new DockerComposeError({
+                cause,
+                note: `Failed to read Docker Compose logs in ${cwd}`,
+              }),
+          ),
+        )
+
+        return process.stdout.pipe(
+          Stream.decodeText({ encoding: 'utf8' }),
+          Stream.splitLines,
+          Stream.mapError(
+            (cause) =>
+              new DockerComposeError({
+                cause,
+                note: `Error reading Docker Compose logs in ${cwd}`,
+              }),
+          ),
+        )
+      }).pipe(Stream.unwrap)
+
+    const down = Effect.fn('downDockerCompose')(function* (options?: {
+      readonly env?: Record<string, string>
+      readonly volumes?: boolean
+      readonly removeOrphans?: boolean
+    }) {
+      yield* Effect.log(`Tearing down Docker Compose services in ${cwd}`)
+
+      const downArgs = ['down']
+      if (options?.volumes === true) downArgs.push('-v')
+      if (options?.removeOrphans === true) downArgs.push('--remove-orphans')
+      if (serviceName !== undefined) downArgs.push(serviceName)
+
+      const exitCode = yield* spawner.exitCode(composeCommand(downArgs, envOptions(options?.env)))
+
+      if (Number(exitCode) !== 0) {
+        return yield* new DockerComposeError({
+          cause: new Error(`Docker compose down exited with code ${exitCode}`),
+          note: `Failed to tear down Docker Compose services`,
+        })
+      }
+
+      yield* Effect.log(`Docker Compose services torn down successfully`)
+    })
+
+    // Register cleanup finalizer to ensure containers are removed when scope closes
+    yield* Effect.addFinalizer(() =>
+      down({ volumes: true, removeOrphans: true }).pipe(
+        Effect.tap(() => Effect.log(`Docker Compose cleanup completed for project ${projectName}`)),
+        Effect.catchCause((cause) =>
+          Effect.log('Docker Compose cleanup failed for project', projectName, objectToString(cause)),
+        ),
+      ),
+    )
+
+    return DockerCompose.of({ pull, start, stop, down, logs, projectName })
+  })
+
+export const layer = (options: Options) => Layer.effect(DockerCompose, make(options))
+
+const performHealthCheck = ({
+  url,
+  timeout = Duration.minutes(2),
+  interval = Duration.seconds(2),
+}: {
+  url: string
+  timeout?: Duration.Duration
+  interval?: Duration.Duration
+}): Effect.Effect<void, DockerComposeError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope> =>
+  Effect.gen(function* () {
+    yield* Effect.log(`Performing health check on ${url}`)
+
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+
+    const checkHealth = spawner.exitCode(ChildProcess.make('curl', ['-f', '-s', url])).pipe(
+      Effect.map((code: number) => code === 0),
+      Effect.orElseSucceed(() => false),
+    )
+
+    const healthCheck = checkHealth.pipe(
+      Effect.repeat({
+        while: (healthy: boolean) => healthy === false,
+        schedule: Schedule.fixed(interval),
+      }),
+      Effect.timeout(timeout),
+      Effect.mapError(
+        () =>
+          new DockerComposeError({
+            cause: new Error('Health check timeout'),
+            note: `Health check failed for ${url} after ${Duration.toMillis(timeout)}ms`,
+          }),
+      ),
+    )
+
+    yield* healthCheck
+    yield* Effect.log(`Health check passed for ${url}`)
+  })
+
+// Convenience function for scoped Docker Compose operations with automatic cleanup
+export const startDockerComposeServicesScoped = (
+  args: Options & {
+    healthCheck?: StartOptions['healthCheck']
+  },
+): Effect.Effect<
+  void,
+  DockerComposeError | PlatformError.PlatformError,
+  DockerCompose | ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    const dockerCompose = yield* DockerCompose
+
+    // Start the services
+    yield* dockerCompose.start({
+      ...omitUndefineds({ healthCheck: args.healthCheck !== undefined ? args.healthCheck : undefined }),
+    })
+
+    // Add cleanup finalizer to the current scope
+    yield* Effect.addFinalizer(() => dockerCompose.stop.pipe(Effect.orDie))
+  })

package/src/node/DockerCompose/mod.ts

@@ -0,0 +1 @@
+export * as DockerCompose from './DockerCompose.ts'

package/src/node/DockerCompose/test-fixtures/docker-compose.yml

@@ -0,0 +1,4 @@
+services:
+  hello-world:
+    image: hello-world
+    profiles: [manual] # Don't auto-start this service