@tranquilload/core 0.1.0

package/src/multipart/circuit-breaker.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Effect } from "effect"
+import { CircuitOpenError } from "../errors/upload-error.js"
+import { makeCircuitBreaker } from "./circuit-breaker.js"
+
+const realDelay = (ms: number) => Effect.promise(() => new Promise<void>(r => setTimeout(r, ms)))
+
+describe("makeCircuitBreaker", () => {
+  it.effect("starts Closed and allows parts through", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 3, cooldown: 1000 })
+      yield* cb.guard
+    })
+  )
+
+  it.effect("opens circuit after threshold consecutive failures", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 2, cooldown: 1000 })
+      const event1 = yield* cb.onFailure
+      expect(event1).toBeNull()
+      const event2 = yield* cb.onFailure
+      expect(event2).not.toBeNull()
+      expect(event2!._tag).toBe("CircuitOpen")
+      expect(event2!.failedParts).toBe(2)
+    })
+  )
+
+  it.effect("guard fails with CircuitOpenError when circuit is Open", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 1, cooldown: 1000 })
+      yield* cb.onFailure
+      const result = yield* Effect.exit(cb.guard)
+      expect(result._tag).toBe("Failure")
+      const err = (result as any).cause.error
+      expect(err).toBeInstanceOf(CircuitOpenError)
+    })
+  )
+
+  it.effect("guard transitions Open → HalfOpen when cooldown elapsed", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 1, cooldown: 10 })
+      yield* cb.onFailure
+      yield* realDelay(25)
+      yield* cb.guard
+      yield* cb.onSuccess
+      yield* cb.guard
+    })
+  )
+
+  it.effect("onSuccess transitions HalfOpen → Closed", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 1, cooldown: 10 })
+      yield* cb.onFailure
+      yield* realDelay(25)
+      yield* cb.guard
+      yield* cb.onSuccess
+      yield* cb.guard
+      const event = yield* cb.onFailure
+      expect(event).not.toBeNull()
+    })
+  )
+
+  it.effect("onFailure in HalfOpen re-opens the circuit", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 1, cooldown: 10 })
+      yield* cb.onFailure
+      yield* realDelay(25)
+      yield* cb.guard
+      const event = yield* cb.onFailure
+      expect(event).not.toBeNull()
+      expect(event!._tag).toBe("CircuitOpen")
+    })
+  )
+
+  it.effect("failures below threshold do NOT open circuit", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 3, cooldown: 1000 })
+      const e1 = yield* cb.onFailure
+      const e2 = yield* cb.onFailure
+      expect(e1).toBeNull()
+      expect(e2).toBeNull()
+      yield* cb.guard
+    })
+  )
+
+  it.effect("onSuccess in Closed resets consecutive failure counter", () =>
+    Effect.gen(function* () {
+      const cb = yield* makeCircuitBreaker({ threshold: 2, cooldown: 1000 })
+      yield* cb.onFailure
+      yield* cb.onSuccess
+      const e = yield* cb.onFailure
+      expect(e).toBeNull()
+    })
+  )
+})

package/src/multipart/circuit-breaker.ts

@@ -0,0 +1,68 @@
+import { Effect, Ref } from "effect"
+import { CircuitOpenError } from "../errors/upload-error.js"
+import type { CircuitOpen } from "../progress/upload-event.js"
+
+export interface CircuitBreakerConfig {
+  readonly threshold: number
+  readonly cooldown: number
+}
+
+type CircuitState =
+  | { readonly _tag: "Closed"; readonly consecutiveFailures: number }
+  | { readonly _tag: "Open"; readonly openedAt: number }
+  | { readonly _tag: "HalfOpen" }
+
+export interface CircuitBreaker {
+  readonly guard: Effect.Effect<void, CircuitOpenError>
+  readonly onSuccess: Effect.Effect<void>
+  readonly onFailure: Effect.Effect<CircuitOpen | null>
+}
+
+export const makeCircuitBreaker = (config: CircuitBreakerConfig): Effect.Effect<CircuitBreaker> =>
+  Effect.gen(function* () {
+    const refState = yield* Ref.make<CircuitState>({ _tag: "Closed", consecutiveFailures: 0 })
+
+    const guard: Effect.Effect<void, CircuitOpenError> = Effect.gen(function* () {
+      const blocked = yield* Ref.modify(refState, (state): [boolean, CircuitState] => {
+        if (state._tag !== "Open") return [false, state]
+        const elapsed = Date.now() - state.openedAt
+        if (elapsed < config.cooldown) return [true, state]
+        return [false, { _tag: "HalfOpen" as const }]
+      })
+      if (blocked) {
+        return yield* Effect.fail(new CircuitOpenError(config.threshold))
+      }
+    })
+
+    const onSuccess: Effect.Effect<void> = Ref.update(refState, state =>
+      state._tag === "HalfOpen" || state._tag === "Closed"
+        ? { _tag: "Closed" as const, consecutiveFailures: 0 }
+        : state
+    )
+
+    const onFailure: Effect.Effect<CircuitOpen | null> = Ref.modify(refState, (state): [CircuitOpen | null, CircuitState] => {
+      if (state._tag === "Closed") {
+        const newFailures = state.consecutiveFailures + 1
+        if (newFailures >= config.threshold) {
+          const event: CircuitOpen = {
+            _tag: "CircuitOpen",
+            failedParts: newFailures,
+            timestamp: Date.now(),
+          }
+          return [event, { _tag: "Open" as const, openedAt: Date.now() }]
+        }
+        return [null, { _tag: "Closed" as const, consecutiveFailures: newFailures }]
+      }
+      if (state._tag === "HalfOpen") {
+        const event: CircuitOpen = {
+          _tag: "CircuitOpen",
+          failedParts: config.threshold,
+          timestamp: Date.now(),
+        }
+        return [event, { _tag: "Open" as const, openedAt: Date.now() }]
+      }
+      return [null, state]
+    })
+
+    return { guard, onSuccess, onFailure }
+  })

package/src/multipart/index.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Cause, Effect, Exit, Option } from "effect"
+import { AbortError, CompleteUploadError, InitiateUploadError } from "../errors/upload-error.js"
+import { compress } from "../pipeline/compress.js"
+import { compose, type Transform } from "../pipeline/middleware.js"
+import { uploadMultipart } from "./index.js"
+import { uploadMultipartEffect } from "./upload-stream.js"
+
+// Helper: create a ReadableStream from a Uint8Array
+const fromBytes = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+  new ReadableStream({
+    start(c) {
+      c.enqueue(bytes)
+      c.close()
+    },
+  })
+
+// Helper: read all events from the ReadableStream
+const readAllEvents = async <T>(rs: ReadableStream<T>): Promise<T[]> => {
+  const reader = rs.getReader()
+  const events: T[] = []
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    events.push(value)
+  }
+  return events
+}
+
+describe("uploadMultipart — Dual API entry point", () => {
+  it.effect("happy path: result resolves with UploadCompleted, events contains all events", () =>
+    Effect.gen(function* () {
+      const { result, events } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(20).fill(1)),
+        chunkSize: 10,
+        uploadPart: (n) => `etag-${n}`,
+        completeUpload: () => {},
+      })
+
+      const [uploadResult, evts] = yield* Effect.all([
+        Effect.promise(() => result),
+        Effect.promise(() => readAllEvents(events)),
+      ])
+
+      expect(uploadResult._tag).toBe("UploadCompleted")
+      expect(uploadResult.totalParts).toBe(2)
+
+      const partEvents = evts.filter((e) => e._tag === "PartCompleted")
+      expect(partEvents).toHaveLength(2)
+      expect(evts.find((e) => e._tag === "UploadCompleted")).toBeDefined()
+    })
+  )
+
+  it.effect("getProgress tracks bytesUploaded; totalBytes is Some when provided", () =>
+    Effect.gen(function* () {
+      const { result, getProgress } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(30).fill(1)),
+        chunkSize: 10,
+        uploadPart: () => "etag",
+        completeUpload: () => {},
+        totalBytes: 30,
+      })
+
+      yield* Effect.promise(() => result)
+
+      const progress = yield* Effect.promise(() => getProgress())
+      expect(progress.bytesUploaded).toBe(30)
+      expect(progress.totalBytes).toEqual(Option.some(30))
+    })
+  )
+
+  it.effect("getProgress returns None for totalBytes when not provided", () =>
+    Effect.gen(function* () {
+      const { result, getProgress } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        uploadPart: () => "etag",
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+
+      const progress = yield* Effect.promise(() => getProgress())
+      expect(progress.totalBytes).toEqual(Option.none())
+    })
+  )
+
+  it.effect("abort signal: result rejects with AbortError, events stream closes cleanly", () =>
+    Effect.gen(function* () {
+      const controller = new AbortController()
+      const { result, events } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        uploadPart: () =>
+          new Promise<string>((_resolve) => {
+            setTimeout(() => controller.abort(), 5)
+          }),
+        completeUpload: () => {},
+        signal: controller.signal,
+      })
+
+      // result rejects with AbortError
+      const resultExit = yield* Effect.exit(
+        Effect.tryPromise({
+          try: () => result,
+          catch: (e) => e,
+        })
+      )
+      expect(Exit.isFailure(resultExit)).toBe(true)
+      if (Exit.isFailure(resultExit)) {
+        const errOption = Cause.failureOption(resultExit.cause)
+        expect(errOption._tag).toBe("Some")
+        const err = (errOption as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(AbortError)
+        expect((err as AbortError)._tag).toBe("AbortError")
+      }
+
+      // events ReadableStream closes cleanly (no throw)
+      const evts = yield* Effect.promise(() => readAllEvents(events))
+      // Stream should close without throwing — length may be 0 (aborted before any parts complete)
+      expect(Array.isArray(evts)).toBe(true)
+    })
+  )
+
+  it(".effect property points to uploadMultipartEffect", () => {
+    expect(uploadMultipart.effect).toBe(uploadMultipartEffect)
+  })
+
+  it.effect("applies plain Transform pipeline before chunking (data reaches uploadPart transformed)", () =>
+    Effect.gen(function* () {
+      const received: Uint8Array[] = []
+      // Transform: replace every byte with 0xAA
+      const markerTransform: Transform = (stream) =>
+        stream.pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>({
+            transform(chunk, controller) {
+              controller.enqueue(new Uint8Array(chunk.length).fill(0xaa))
+            },
+          })
+        )
+
+      const { result } = uploadMultipart({
+        stream: new ReadableStream({
+          start(c) { c.enqueue(new Uint8Array([1, 2, 3])); c.close() },
+        }),
+        chunkSize: 3,
+        pipeline: markerTransform,
+        uploadPart: (_, chunk) => {
+          received.push(chunk)
+          return "etag-1"
+        },
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      expect(received).toHaveLength(1)
+      expect(Array.from(received[0]!)).toEqual([0xaa, 0xaa, 0xaa])
+    })
+  )
+
+  it.effect("applies Effect pipeline (compress) before chunking — PartCompleted.bytesUploaded reflects compressed size", () =>
+    Effect.gen(function* () {
+      const received: Uint8Array[] = []
+      const original = new Uint8Array([1, 2, 3, 4, 5])
+
+      const { result } = uploadMultipart({
+        stream: new ReadableStream({
+          start(c) { c.enqueue(original); c.close() },
+        }),
+        chunkSize: 4096, // large enough to receive all compressed output in one part
+        pipeline: compress("deflate-raw"),
+        uploadPart: (_, chunk) => {
+          received.push(chunk)
+          return "etag-1"
+        },
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      expect(received).toHaveLength(1)
+      // Compressed output is non-empty
+      expect(received[0]!.length).toBeGreaterThan(0)
+      // Compressed bytes differ from raw input
+      expect(Array.from(received[0]!)).not.toEqual(Array.from(original))
+    })
+  )
+
+  it.effect("compose(compress()) can be passed as pipeline — same as compress() directly", () =>
+    Effect.gen(function* () {
+      const received: Uint8Array[] = []
+
+      const { result } = uploadMultipart({
+        stream: new ReadableStream({
+          start(c) { c.enqueue(new Uint8Array([10, 20, 30])); c.close() },
+        }),
+        chunkSize: 4096,
+        pipeline: compose(compress("deflate-raw")),
+        uploadPart: (_, chunk) => {
+          received.push(chunk)
+          return "etag-1"
+        },
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      expect(received).toHaveLength(1)
+      expect(received[0]!.length).toBeGreaterThan(0)
+    })
+  )
+
+  it.effect("initiate callback: UploadInitiated event emitted first, uploadId resolves to correct value", () =>
+    Effect.gen(function* () {
+      const { result, events, uploadId } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        initiate: () => Promise.resolve({ uploadId: "upload-abc-123" }),
+        uploadPart: () => "etag-1",
+        completeUpload: (uid, _parts) => {
+          expect(uid).toBe("upload-abc-123")
+        },
+      })
+
+      yield* Effect.promise(() => result)
+      const resolvedId = yield* Effect.promise(() => uploadId)
+      expect(resolvedId).toBe("upload-abc-123")
+
+      const evts = yield* Effect.promise(() => readAllEvents(events))
+      const initiatedEvent = evts.find(e => e._tag === "UploadInitiated")
+      expect(initiatedEvent).toMatchObject({ _tag: "UploadInitiated", uploadId: "upload-abc-123" })
+      expect(evts[0]!._tag).toBe("UploadInitiated")
+
+      const completedEvent = evts.find(e => e._tag === "UploadCompleted")
+      expect(completedEvent).toMatchObject({ _tag: "UploadCompleted", uploadId: "upload-abc-123" })
+    })
+  )
+
+  it.effect("no initiate: no UploadInitiated event, uploadId resolves to empty string", () =>
+    Effect.gen(function* () {
+      const { result, events, uploadId } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        uploadPart: () => "etag-1",
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      const resolvedId = yield* Effect.promise(() => uploadId)
+      expect(resolvedId).toBe("")
+
+      const evts = yield* Effect.promise(() => readAllEvents(events))
+      expect(evts.find(e => e._tag === "UploadInitiated")).toBeUndefined()
+    })
+  )
+
+  it.effect("initiate failure: result rejects with InitiateUploadError, uploadId resolves to empty string", () =>
+    Effect.gen(function* () {
+      const cause = new Error("initiation failed")
+      const { result, uploadId } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        initiate: () => { throw cause },
+        uploadPart: () => "etag-1",
+        completeUpload: () => {},
+      })
+
+      const resultExit = yield* Effect.exit(
+        Effect.tryPromise({
+          try: () => result,
+          catch: (e) => e,
+        })
+      )
+      expect(Exit.isFailure(resultExit)).toBe(true)
+      if (Exit.isFailure(resultExit)) {
+        const err = (Cause.failureOption(resultExit.cause) as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(InitiateUploadError)
+        expect((err as InitiateUploadError).cause).toBe(cause)
+      }
+
+      const resolvedId = yield* Effect.promise(() => uploadId)
+      expect(resolvedId).toBe("")
+    })
+  )
+})

package/src/multipart/index.ts

@@ -0,0 +1,119 @@
+import { Cause, Effect, Exit, Option, Ref, Stream } from "effect"
+import type { UploadCompleted, UploadEvent } from "../progress/upload-event.js"
+import type { Transform } from "../pipeline/middleware.js"
+import { CompressionServiceLive } from "../services/compression-service.js"
+import { LoggerServiceLive } from "../services/logger-service.js"
+import { uploadMultipartEffect, type CompletedPart, type UploadMultipartOptions } from "./upload-stream.js"
+
+export type UploadResult = UploadCompleted
+export type { CompletedPart, UploadMultipartOptions }
+
+export interface Progress {
+  readonly bytesUploaded: number
+  readonly totalBytes: Option.Option<number>
+}
+
+export interface MultipartPublicOptions extends UploadMultipartOptions {
+  readonly totalBytes?: number
+  readonly pipeline?: Transform | Effect.Effect<Transform, unknown, unknown>
+}
+
+export const uploadMultipart = (
+  options: MultipartPublicOptions
+): {
+  events: ReadableStream<UploadEvent>
+  result: Promise<UploadResult>
+  getProgress: (() => Promise<Progress>) & { effect: Effect.Effect<Progress> }
+  uploadId: Promise<string>
+} => {
+  const refProgress = Effect.runSync(
+    Ref.make<Progress>({
+      bytesUploaded: 0,
+      totalBytes: options.totalBytes !== undefined ? Option.some(options.totalBytes) : Option.none(),
+    })
+  )
+
+  let resolveUploadId!: (id: string) => void
+  const uploadIdPromise: Promise<string> = new Promise<string>((resolve) => {
+    resolveUploadId = resolve
+  })
+
+  const collected: Promise<ReadonlyArray<UploadEvent>> = (async () => {
+    // Step 1: resolve pipeline to get the processed stream
+    let processedStream = options.stream
+    if (options.pipeline !== undefined) {
+      if (typeof options.pipeline === "function") {
+        processedStream = options.pipeline(options.stream)
+      } else {
+        // Effect pipeline — resolve with CompressionServiceLive
+        const transform = await Effect.runPromise(
+          Effect.provide(
+            options.pipeline as Effect.Effect<Transform, unknown, never>,
+            CompressionServiceLive
+          )
+        )
+        processedStream = transform(options.stream)
+      }
+    }
+
+    // Step 2: run upload with processedStream
+    const program = uploadMultipartEffect({ ...options, stream: processedStream }).pipe(
+      Stream.tap((event) => {
+        if (event._tag === "UploadInitiated") {
+          return Effect.sync(() => resolveUploadId(event.uploadId))
+        }
+        if (event._tag === "PartCompleted") {
+          return Ref.update(refProgress, (p) => ({
+            ...p,
+            bytesUploaded: p.bytesUploaded + event.bytesUploaded,
+          }))
+        }
+        return Effect.void
+      }),
+      Stream.provideLayer(LoggerServiceLive)
+    )
+
+    const exit = await Stream.runCollect(program).pipe(
+      Effect.map((chunk) => Array.from(chunk)),
+      Effect.runPromiseExit
+    )
+    if (Exit.isSuccess(exit)) return exit.value
+    return Promise.reject(Cause.squash(exit.cause))
+  })()
+
+  // Rejection is surfaced via `result`; suppress the propagated rejection from .finally()
+  collected.finally(() => resolveUploadId("")).catch(() => {})
+
+  // events: ReadableStream built from collected array; closes cleanly on error
+  const events = new ReadableStream<UploadEvent>({
+    async start(controller) {
+      try {
+        const evts = await collected
+        for (const event of evts) controller.enqueue(event)
+        controller.close()
+      } catch (_) {
+        // Close cleanly — upload errors surface via `result` only
+        controller.close()
+      }
+    },
+  })
+
+  // result: resolves with UploadCompleted, rejects with UploadError on failure
+  const result: Promise<UploadResult> = collected.then((evts) => {
+    const last = evts[evts.length - 1]
+    if (last === undefined) {
+      return Promise.reject(new Error("uploadMultipart: stream ended without emitting an event"))
+    }
+    return last as UploadResult
+  })
+
+  const getProgress = Object.assign(
+    (): Promise<Progress> => Effect.runPromise(Ref.get(refProgress)),
+    { effect: Ref.get(refProgress) }
+  )
+
+  return { events, result, getProgress, uploadId: uploadIdPromise }
+}
+
+// Effect escape hatch — LoggerService layer left open for user composition
+uploadMultipart.effect = uploadMultipartEffect