Skip to content

Tests: S3ObjectStorageBackend integration via LocalStack #297

@pathosDev

Description

@pathosDev

Spawned from the coverage analysis after the chat-sample sweep.

The gap

src/persistence/object-storage/S3ObjectStorageBackend.ts sits
at 8 % line coverage — only the constructor + a couple of
guards are exercised. Every actual SDK call path is dead in CI:

  • putObject / getObject / headObject / deleteObject
  • multipart-upload paths (large blobs)
  • presigned-URL generation
  • error mapping (NoSuchKey, AccessDenied, throttling retry, etc.)

The peer file FilesystemObjectStorageBackend.ts is at 100 % —
its tests fully exercise the contract via real filesystem calls.
S3 needs the equivalent.

Scope

  • Add tests/integration/persistence/object-storage/S3ObjectStorageBackend.test.ts
    (path assumes Tests: split tests/ into unit/ + integration/ subtrees #295 has landed; otherwise drop in
    tests/unit/persistence/object-storage/ under a LIVE_S3=1
    guard).
  • Use LocalStack as the S3 mock: localstack/localstack:3-amd64,
    port 4566. Boots in ~3 s, supports the AWS S3 API surface we
    care about.
  • Test matrix should mirror FilesystemObjectStorageBackend.test.ts
    so the two backends are demonstrably interchangeable:
    • Round-trip put → get → delete.
    • HEAD checks for ETag / Content-Length / Last-Modified.
    • Concurrent-write conflict resolution.
    • Multipart-upload for blobs > the threshold.
    • Encryption + compression integration (the existing
      Encryption.test.ts + Compression.test.ts patterns).

Acceptance criteria

  • S3ObjectStorageBackend.ts line coverage ≥ 85 %.
  • Test runs against LocalStack in CI.
  • Skips cleanly when Docker is unavailable.
  • All test cases that the filesystem backend has are mirrored
    for S3 (modulo a few "filesystem-only" tests like
    directory traversal).

Out of scope

  • Real AWS smoke-test against a live AWS account. Anyone wanting
    that runs the test with S3_ENDPOINT=https://s3.amazonaws.com
    • their own credentials — no separate code path needed.
  • LocalStack Pro features (IAM-policy enforcement,
    KMS-with-real-CMKs, etc.).

Notes

This is also the natural unblocker for #292 (chat-sample file
uploads) — once the S3 backend is well-tested, wiring it into the
chat sample as an attachment store has solid foundations.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions