@tranquilload/core 0.1.0 → 0.1.1

package/src/multipart/index.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect, it } from "@effect/vitest"
 import { Cause, Effect, Exit, Option } from "effect"
+import { afterEach, vi } from "vitest"
 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 { uploadMultipart, type ResumeState } from "./index.js"
 import { uploadMultipartEffect } from "./upload-stream.js"
 
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
 // Helper: create a ReadableStream from a Uint8Array
 const fromBytes = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
   new ReadableStream({
@@ -281,3 +286,161 @@ describe("uploadMultipart — Dual API entry point", () => {
     })
   )
 })
+
+describe("uploadMultipart — resumeState surface", () => {
+  it.effect("resumeState resolves with correct shape on fresh init (no digest)", () =>
+    Effect.gen(function* () {
+      const { result, resumeState } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        initiate: () => ({ uploadId: "fresh-up-1" }),
+        pipelineIdentity: "ident-1",
+        uploadPart: () => "etag-1",
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      const state = yield* Effect.promise(() => resumeState)
+      expect(state).toEqual({
+        version: 1,
+        uploadId: "fresh-up-1",
+        chunkSize: 10,
+        pipelineIdentity: "ident-1",
+        contentDigestCaptured: false,
+      })
+    })
+  )
+
+  it.effect("resumeState includes contentDigest when getContentDigest is provided (fresh init)", () =>
+    Effect.gen(function* () {
+      const { result, resumeState } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        initiate: () => ({ uploadId: "fresh-up-2" }),
+        getContentDigest: () => "digest-xyz",
+        uploadPart: () => "etag-1",
+        completeUpload: () => {},
+      })
+
+      yield* Effect.promise(() => result)
+      const state = yield* Effect.promise(() => resumeState)
+      expect(state).toMatchObject({
+        version: 1,
+        uploadId: "fresh-up-2",
+        contentDigest: "digest-xyz",
+        contentDigestCaptured: true,
+      })
+    })
+  )
+
+  it.effect("resumeState resolves with the passed resumeFrom shape on resume", () =>
+    Effect.gen(function* () {
+      const passed: ResumeState = {
+        version: 1,
+        uploadId: "stored-up-1",
+        chunkSize: 10,
+        contentDigestCaptured: false,
+      }
+      const { result, resumeState, uploadId } = uploadMultipart({
+        stream: fromBytes(new Uint8Array(10).fill(1)),
+        chunkSize: 10,
+        uploadPart: () => "etag-1",
+        completeUpload: () => {},
+        resumeFrom: passed,
+      })
+
+      // uploadId resolves synchronously (AC22) — no need to await `result`
+      const id = yield* Effect.promise(() => uploadId)
+      expect(id).toBe("stored-up-1")
+
+      yield* Effect.promise(() => result)
+      const state = yield* Effect.promise(() => resumeState)
+      expect(state).toBe(passed)
+    })
+  )
+})
+
+describe("uploadMultipart — legacy-pattern warn", () => {
+  it("warns once when initiate + reconcile + no resumeFrom (AC16)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+    const { result } = uploadMultipart({
+      stream: fromBytes(new Uint8Array(10).fill(1)),
+      chunkSize: 10,
+      initiate: () => ({ uploadId: "u-1" }),
+      reconcileCompletedParts: () => [{ partNumber: 1, etag: "etag-1" }],
+      uploadPart: () => "should-not-be-called",
+      completeUpload: () => {},
+    })
+    await result
+
+    const legacyWarns = warnSpy.mock.calls.filter((c) =>
+      typeof c[0] === "string" && c[0].startsWith("Tranquilload: detected legacy resume pattern")
+    )
+    expect(legacyWarns).toHaveLength(1)
+  })
+
+  it("does NOT warn when resumeFrom is provided alongside initiate + reconcile (AC17)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+    const { result } = uploadMultipart({
+      stream: fromBytes(new Uint8Array(10).fill(1)),
+      chunkSize: 10,
+      initiate: () => ({ uploadId: "ignored" }),
+      reconcileCompletedParts: () => [{ partNumber: 1, etag: "etag-1" }],
+      uploadPart: () => "should-not-be-called",
+      completeUpload: () => {},
+      resumeFrom: {
+        version: 1,
+        uploadId: "stored",
+        chunkSize: 10,
+        contentDigestCaptured: false,
+      },
+    })
+    await result
+
+    const legacyWarns = warnSpy.mock.calls.filter((c) =>
+      typeof c[0] === "string" && c[0].startsWith("Tranquilload: detected legacy resume pattern")
+    )
+    expect(legacyWarns).toHaveLength(0)
+  })
+
+  it("warns even when reconcileCompletedParts returns an empty array (AC18)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+    const { result } = uploadMultipart({
+      stream: fromBytes(new Uint8Array(10).fill(1)),
+      chunkSize: 10,
+      initiate: () => ({ uploadId: "u-1" }),
+      reconcileCompletedParts: () => [],
+      uploadPart: () => "etag-1",
+      completeUpload: () => {},
+    })
+    await result
+
+    const legacyWarns = warnSpy.mock.calls.filter((c) =>
+      typeof c[0] === "string" && c[0].startsWith("Tranquilload: detected legacy resume pattern")
+    )
+    expect(legacyWarns).toHaveLength(1)
+  })
+
+  it("warns when pipeline is set without pipelineIdentity (AC24)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+    const noopTransform: Transform = (stream) => stream
+
+    const { result } = uploadMultipart({
+      stream: fromBytes(new Uint8Array(10).fill(1)),
+      chunkSize: 10,
+      pipeline: noopTransform,
+      uploadPart: () => "etag-1",
+      completeUpload: () => {},
+    })
+    await result
+
+    const identityWarns = warnSpy.mock.calls.filter((c) =>
+      typeof c[0] === "string" && c[0].includes("pipeline is set but pipelineIdentity is not")
+    )
+    expect(identityWarns).toHaveLength(1)
+  })
+})

package/src/multipart/index.ts

@@ -3,10 +3,10 @@ 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"
+import { uploadMultipartEffect, type CompletedPart, type ResumeState, type UploadMultipartOptions } from "./upload-stream.js"
 
 export type UploadResult = UploadCompleted
-export type { CompletedPart, UploadMultipartOptions }
+export type { CompletedPart, ResumeState, UploadMultipartOptions }
 
 export interface Progress {
   readonly bytesUploaded: number
@@ -18,6 +18,9 @@ export interface MultipartPublicOptions extends UploadMultipartOptions {
   readonly pipeline?: Transform | Effect.Effect<Transform, unknown, unknown>
 }
 
+const NO_RESUME_CONTEXT_ERROR_MESSAGE =
+  "uploadMultipart: resumeState is only available when `initiate` or `resumeFrom` is provided"
+
 export const uploadMultipart = (
   options: MultipartPublicOptions
 ): {
@@ -25,7 +28,34 @@ export const uploadMultipart = (
   result: Promise<UploadResult>
   getProgress: (() => Promise<Progress>) & { effect: Effect.Effect<Progress> }
   uploadId: Promise<string>
+  resumeState: Promise<ResumeState>
 } => {
+  // Legacy-pattern detection: warns unconditionally so first-time-after-upgrade
+  // users also see the migration message (per G3 — empty reconcile would have
+  // hidden the warning under the old "warn when reconcile returned >= 1" rule).
+  if (
+    options.initiate !== undefined &&
+    options.reconcileCompletedParts !== undefined &&
+    options.resumeFrom === undefined
+  ) {
+    console.warn(
+      "Tranquilload: detected legacy resume pattern. You're passing `initiate` " +
+        "and `reconcileCompletedParts` without `resumeFrom: ResumeState`. The new " +
+        "API requires the persisted ResumeState to validate chunkSize/pipeline/" +
+        "digest match across sessions. See MIGRATION.md for migration steps."
+    )
+  }
+  // Pipeline-without-identity: the resume validation cannot detect a pipeline
+  // mismatch across sessions when the user runs a pipeline but provides no
+  // identity. We warn so the user is aware their resume safety is reduced.
+  if (options.pipeline !== undefined && options.pipelineIdentity === undefined) {
+    console.warn(
+      "Tranquilload: pipeline is set but pipelineIdentity is not. Without an " +
+        "identity, the resume validation cannot detect a pipeline mismatch " +
+        "across sessions. See README → Resume Safety."
+    )
+  }
+
   const refProgress = Effect.runSync(
     Ref.make<Progress>({
       bytesUploaded: 0,
@@ -38,6 +68,32 @@ export const uploadMultipart = (
     resolveUploadId = resolve
   })
 
+  let resolveResumeState!: (s: ResumeState) => void
+  let rejectResumeState!: (e: unknown) => void
+  let resumeStateSettled = false
+  const resumeStatePromise: Promise<ResumeState> = new Promise<ResumeState>((resolve, reject) => {
+    resolveResumeState = (s) => {
+      if (resumeStateSettled) return
+      resumeStateSettled = true
+      resolve(s)
+    }
+    rejectResumeState = (e) => {
+      if (resumeStateSettled) return
+      resumeStateSettled = true
+      reject(e)
+    }
+  })
+  // Avoid unhandled-rejection warnings: callers may not await resumeState.
+  resumeStatePromise.catch(() => {})
+
+  // Resume branch: resolve uploadId AND resumeState synchronously before the
+  // stream runs. uploadId per AC22; resumeState per Task 4.1 (the lib has no
+  // new state to add — the user already has the value they passed in).
+  if (options.resumeFrom !== undefined) {
+    resolveUploadId(options.resumeFrom.uploadId)
+    resolveResumeState(options.resumeFrom)
+  }
+
   const collected: Promise<ReadonlyArray<UploadEvent>> = (async () => {
     // Step 1: resolve pipeline to get the processed stream
     let processedStream = options.stream
@@ -60,7 +116,24 @@ export const uploadMultipart = (
     const program = uploadMultipartEffect({ ...options, stream: processedStream }).pipe(
       Stream.tap((event) => {
         if (event._tag === "UploadInitiated") {
-          return Effect.sync(() => resolveUploadId(event.uploadId))
+          // Fresh-init branch: resolve uploadId on the event, and build the
+          // ResumeState from the event payload + caller-supplied fields.
+          return Effect.sync(() => {
+            resolveUploadId(event.uploadId)
+            const state: ResumeState = {
+              version: 1,
+              uploadId: event.uploadId,
+              chunkSize: options.chunkSize,
+              ...(options.pipelineIdentity !== undefined
+                ? { pipelineIdentity: options.pipelineIdentity }
+                : {}),
+              ...(event.contentDigest !== undefined
+                ? { contentDigest: event.contentDigest }
+                : {}),
+              contentDigestCaptured: options.getContentDigest !== undefined,
+            }
+            resolveResumeState(state)
+          })
         }
         if (event._tag === "PartCompleted") {
           return Ref.update(refProgress, (p) => ({
@@ -82,7 +155,19 @@ export const uploadMultipart = (
   })()
 
   // Rejection is surfaced via `result`; suppress the propagated rejection from .finally()
-  collected.finally(() => resolveUploadId("")).catch(() => {})
+  collected
+    .then(() => {
+      // Success-but-no-context: neither initiate nor resumeFrom produced state.
+      if (!resumeStateSettled) {
+        rejectResumeState(new Error(NO_RESUME_CONTEXT_ERROR_MESSAGE))
+      }
+    })
+    .catch((err) => {
+      if (!resumeStateSettled) {
+        rejectResumeState(err)
+      }
+    })
+    .finally(() => resolveUploadId(""))
 
   // events: ReadableStream built from collected array; closes cleanly on error
   const events = new ReadableStream<UploadEvent>({
@@ -112,7 +197,13 @@ export const uploadMultipart = (
     { effect: Ref.get(refProgress) }
   )
 
-  return { events, result, getProgress, uploadId: uploadIdPromise }
+  return {
+    events,
+    result,
+    getProgress,
+    uploadId: uploadIdPromise,
+    resumeState: resumeStatePromise,
+  }
 }
 
 // Effect escape hatch — LoggerService layer left open for user composition

package/src/multipart/upload-stream.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from "@effect/vitest"
 import { Cause, Effect, Fiber, Ref, Schedule, Stream, TestClock } from "effect"
-import { AbortError, CircuitOpenError, CompleteUploadError, MaxRetriesExceededError, PartUploadError, PresignedUrlError, ReconcileError } from "../errors/upload-error.js"
+import { AbortError, CircuitOpenError, CompleteUploadError, MaxRetriesExceededError, PartUploadError, PresignedUrlError, ReconcileError, ResumeMismatchError } from "../errors/upload-error.js"
 import type { UploadEvent } from "../progress/upload-event.js"
 import { LoggerServiceLive } from "../services/logger-service.js"
-import { uploadMultipartEffect, type CompletedPart } from "./upload-stream.js"
+import { uploadMultipartEffect, type CompletedPart, type ResumeState } from "./upload-stream.js"
 
 const fromBytes = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
   new ReadableStream({ start: c => { c.enqueue(bytes); c.close() } })
@@ -333,4 +333,203 @@ describe("uploadMultipartEffect with circuitBreaker", () => {
       expect(err).toBeInstanceOf(CircuitOpenError)
     })
   )
+
+  describe("chunkSize validation", () => {
+    const baseOptions = {
+      stream: fromBytes(new Uint8Array(10)),
+      uploadPart: () => "etag",
+      completeUpload: () => {},
+    } as const
+
+    it("throws TypeError when chunkSize is 0", () => {
+      expect(() => uploadMultipartEffect({ ...baseOptions, chunkSize: 0 }))
+        .toThrow(TypeError)
+    })
+
+    it("throws TypeError when chunkSize is negative", () => {
+      expect(() => uploadMultipartEffect({ ...baseOptions, chunkSize: -1 }))
+        .toThrow(/positive finite number/)
+    })
+
+    it("throws TypeError when chunkSize is NaN", () => {
+      expect(() => uploadMultipartEffect({ ...baseOptions, chunkSize: NaN }))
+        .toThrow(/positive finite number/)
+    })
+
+    it("throws TypeError when chunkSize is Infinity", () => {
+      expect(() => uploadMultipartEffect({ ...baseOptions, chunkSize: Infinity }))
+        .toThrow(/positive finite number/)
+    })
+
+    it("accepts a positive integer chunkSize (control)", () => {
+      expect(() => uploadMultipartEffect({ ...baseOptions, chunkSize: 5 }))
+        .not.toThrow()
+    })
+  })
+})
+
+describe("ResumeState validation", () => {
+  const baseOptions = {
+    stream: new ReadableStream<Uint8Array>({ start: (c) => { c.enqueue(new Uint8Array(10)); c.close() } }),
+    chunkSize: 10,
+    uploadPart: () => "etag",
+    completeUpload: () => {},
+  } as const
+
+  const validResumeState = (overrides: Partial<ResumeState> = {}): ResumeState => ({
+    version: 1,
+    uploadId: "upload-stored-1",
+    chunkSize: 10,
+    contentDigestCaptured: false,
+    ...overrides,
+  })
+
+  it("throws TypeError when resumeFrom.uploadId is empty string", () => {
+    expect(() =>
+      uploadMultipartEffect({
+        ...baseOptions,
+        resumeFrom: validResumeState({ uploadId: "" }),
+      })
+    ).toThrow(/non-empty string/)
+  })
+
+  it("throws ResumeMismatchError(version_mismatch) when version != 1", () => {
+    let caught: unknown
+    try {
+      uploadMultipartEffect({
+        ...baseOptions,
+        // Cast: future v2 schema would pass typecheck, but here we force-test the v1 check.
+        resumeFrom: { ...validResumeState(), version: 2 as unknown as 1 },
+      })
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(ResumeMismatchError)
+    expect((caught as ResumeMismatchError).reason).toBe("version_mismatch")
+  })
+
+  it("throws ResumeMismatchError(chunksize_mismatch) when chunkSize differs", () => {
+    let caught: unknown
+    try {
+      uploadMultipartEffect({
+        ...baseOptions,
+        chunkSize: 10,
+        resumeFrom: validResumeState({ chunkSize: 5 }),
+      })
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(ResumeMismatchError)
+    expect((caught as ResumeMismatchError).reason).toBe("chunksize_mismatch")
+  })
+
+  it("throws ResumeMismatchError(pipeline_mismatch) when pipelineIdentity differs", () => {
+    let caught: unknown
+    try {
+      uploadMultipartEffect({
+        ...baseOptions,
+        pipelineIdentity: "gzip-v1",
+        resumeFrom: validResumeState({ pipelineIdentity: "deflate-v1" }),
+      })
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(ResumeMismatchError)
+    expect((caught as ResumeMismatchError).reason).toBe("pipeline_mismatch")
+  })
+
+  it("throws ResumeMismatchError(content_mismatch) when contentDigestCaptured=true but contentDigest is undefined (F9)", () => {
+    let caught: unknown
+    try {
+      uploadMultipartEffect({
+        ...baseOptions,
+        resumeFrom: validResumeState({
+          contentDigestCaptured: true,
+          contentDigest: undefined,
+        }),
+      })
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(ResumeMismatchError)
+    expect((caught as ResumeMismatchError).reason).toBe("content_mismatch")
+  })
+
+  it.effect("fails with ResumeMismatchError(content_mismatch) at runtime when digest value differs", () =>
+    Effect.gen(function* () {
+      const exit = yield* Stream.runCollect(
+        uploadMultipartEffect({
+          stream: new ReadableStream<Uint8Array>({ start: (c) => { c.enqueue(new Uint8Array(10)); c.close() } }),
+          chunkSize: 10,
+          uploadPart: () => "etag",
+          completeUpload: () => {},
+          resumeFrom: validResumeState({
+            contentDigest: "digest-original",
+            contentDigestCaptured: true,
+          }),
+          getContentDigest: () => "digest-different",
+        })
+      ).pipe(Effect.exit, Effect.provide(LoggerServiceLive))
+
+      expect(exit._tag).toBe("Failure")
+      const err = Cause.squash((exit as Extract<typeof exit, { _tag: "Failure" }>).cause)
+      expect(err).toBeInstanceOf(ResumeMismatchError)
+      expect((err as ResumeMismatchError).reason).toBe("content_mismatch")
+    })
+  )
+
+  it.effect("accepts a valid resumeFrom: no throw, uploadId honored, reconcile called", () =>
+    Effect.gen(function* () {
+      let initiateCalled = 0
+      let reconcileCalls = 0
+      const completedWith: { uploadId: string; parts: ReadonlyArray<CompletedPart> } = { uploadId: "", parts: [] }
+
+      const events = yield* Stream.runCollect(
+        uploadMultipartEffect({
+          stream: new ReadableStream<Uint8Array>({ start: (c) => { c.enqueue(new Uint8Array(20)); c.close() } }),
+          chunkSize: 10,
+          uploadPart: (n) => `fresh-etag-${n}`,
+          completeUpload: (uploadId, parts) => {
+            completedWith.uploadId = uploadId
+            completedWith.parts = parts
+          },
+          initiate: () => { initiateCalled++; return { uploadId: "should-not-be-used" } },
+          reconcileCompletedParts: () => {
+            reconcileCalls++
+            return [{ partNumber: 1, etag: "etag-reconciled-1" }]
+          },
+          resumeFrom: validResumeState({ uploadId: "upload-stored-1", chunkSize: 10 }),
+        })
+      ).pipe(
+        Effect.map((chunk) => Array.from(chunk)),
+        Effect.provide(LoggerServiceLive)
+      )
+
+      expect(initiateCalled).toBe(0)
+      expect(reconcileCalls).toBe(1)
+      expect(completedWith.uploadId).toBe("upload-stored-1")
+    })
+  )
+
+  it.effect("does NOT emit UploadInitiated on resume (G1)", () =>
+    Effect.gen(function* () {
+      const events = yield* Stream.runCollect(
+        uploadMultipartEffect({
+          stream: new ReadableStream<Uint8Array>({ start: (c) => { c.enqueue(new Uint8Array(10)); c.close() } }),
+          chunkSize: 10,
+          uploadPart: () => "etag-1",
+          completeUpload: () => {},
+          initiate: () => ({ uploadId: "ignored" }),
+          resumeFrom: validResumeState({ uploadId: "upload-stored-1", chunkSize: 10 }),
+        })
+      ).pipe(
+        Effect.map((chunk) => Array.from(chunk)),
+        Effect.provide(LoggerServiceLive)
+      )
+
+      expect(events.find((e) => e._tag === "UploadInitiated")).toBeUndefined()
+      // First event must come from the parts stream
+      expect(events[0]?._tag).toBe("PartCompleted")
+    })
+  )
 })