fix: support virtual-hosted S3 URLs for avatar storage (#330)

Avatar images failed to load with 403 on Tigris and newer AWS S3 buckets
because getAvatarUrl only constructed path-style URLs. Modern S3-compatible
providers require virtual-hosted URLs (bucket.domain/key).

Add NEXT_PUBLIC_STORAGE_DOMAIN env var to signal URL style:
- If set: virtual-hosted URL (Tigris, AWS S3)
- If not set: path-style URL (MinIO, LocalStack) - backward compatible

Add vitest and tests for getAvatarUrl behavior.

Co-authored-by: Sachin Divekar <sachin.divekar@remiges.tech>

apps/web/package.json

@@ -10,6 +10,8 @@
     "format": "prettier --check . --ignore-path ../../.gitignore",
     "lint": "eslint",
     "start": "pnpm with-env next start",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "with-env": "dotenv -e ../../.env --",
     "lingui:extract": "lingui extract",
@@ -86,7 +88,8 @@
     "jiti": "^1.21.6",
     "prettier": "catalog:",
     "tailwindcss": "catalog:",
-    "typescript": "catalog:"
+    "typescript": "catalog:",
+    "vitest": "^3.0.0"
   },
   "prettier": "@kan/prettier-config"
 }

apps/web/src/utils/helpers.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("next-runtime-env", () => ({
+  env: vi.fn(),
+}));
+
+import { env } from "next-runtime-env";
+import { getAvatarUrl } from "./helpers";
+
+const mockEnv = env as ReturnType<typeof vi.fn>;
+
+describe("getAvatarUrl", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns empty string for null input", () => {
+    expect(getAvatarUrl(null)).toBe("");
+  });
+
+  it("returns empty string for empty string input", () => {
+    expect(getAvatarUrl("")).toBe("");
+  });
+
+  it("returns URL unchanged if already absolute http", () => {
+    expect(getAvatarUrl("http://example.com/avatar.jpg")).toBe(
+      "http://example.com/avatar.jpg",
+    );
+  });
+
+  it("returns URL unchanged if already absolute https", () => {
+    expect(getAvatarUrl("https://example.com/avatar.jpg")).toBe(
+      "https://example.com/avatar.jpg",
+    );
+  });
+
+  describe("path-style URLs (MinIO/LocalStack)", () => {
+    it("constructs path-style URL when STORAGE_DOMAIN is not set", () => {
+      mockEnv.mockImplementation((key: string) => {
+        const vars: Record<string, string> = {
+          NEXT_PUBLIC_STORAGE_URL: "http://s3.localtest.me:9000",
+          NEXT_PUBLIC_AVATAR_BUCKET_NAME: "kan",
+        };
+        return vars[key];
+      });
+
+      expect(getAvatarUrl("user123/avatar.jpg")).toBe(
+        "http://s3.localtest.me:9000/kan/user123/avatar.jpg",
+      );
+    });
+  });
+
+  describe("virtual-hosted URLs (Tigris/AWS S3)", () => {
+    it("constructs virtual-hosted URL when STORAGE_DOMAIN is set", () => {
+      mockEnv.mockImplementation((key: string) => {
+        const vars: Record<string, string> = {
+          NEXT_PUBLIC_STORAGE_DOMAIN: "fly.storage.tigris.dev",
+          NEXT_PUBLIC_AVATAR_BUCKET_NAME: "kan-avatars",
+          NEXT_PUBLIC_STORAGE_URL: "https://fly.storage.tigris.dev",
+        };
+        return vars[key];
+      });
+
+      expect(getAvatarUrl("user123/avatar.jpg")).toBe(
+        "https://kan-avatars.fly.storage.tigris.dev/user123/avatar.jpg",
+      );
+    });
+  });
+});

apps/web/src/utils/helpers.ts

@@ -52,5 +52,13 @@ export const getAvatarUrl = (imageOrKey: string | null) => {
     return imageOrKey;
   }
 
-  return `${env("NEXT_PUBLIC_STORAGE_URL")}/${env("NEXT_PUBLIC_AVATAR_BUCKET_NAME")}/${imageOrKey}`;
+  const bucket = env("NEXT_PUBLIC_AVATAR_BUCKET_NAME");
+  const storageDomain = env("NEXT_PUBLIC_STORAGE_DOMAIN");
+
+  if (storageDomain) {
+    return `https://${bucket}.${storageDomain}/${imageOrKey}`;
+  }
+
+  const storageUrl = env("NEXT_PUBLIC_STORAGE_URL");
+  return `${storageUrl}/${bucket}/${imageOrKey}`;
 };