resolve vcc:// virtual chunk locations against repo config

src/format/flatbuffers/repo-parser.ts

@@ -5,6 +5,7 @@
  */
 
 import { ByteBuffer } from "flatbuffers";
+import * as flexbuffers from "flatbuffers/js/flexbuffers.js";
 import { Repo as FbsRepo } from "./generated/repo.js";
 import { decompress } from "fzstd";
 import {
@@ -23,6 +24,12 @@ export interface ParsedRepo {
   repo: FbsRepo;
   specVersion: number;
   snapshotsLength: number; // Cached for bounds checking
+  /**
+   * Map of Virtual Chunk Container name → `url_prefix` for resolving
+   * relative `vcc://name/path` chunk locations. Empty when the repo has
+   * no named containers (unnamed/legacy entries are excluded).
+   */
+  virtualChunkContainers: Map<string, string>;
 }
 
 /**
@@ -60,8 +67,55 @@ export function parseRepo(data: Uint8Array): ParsedRepo {
   }
 
   const snapshotsLength = repo.snapshotsLength();
+  const virtualChunkContainers = parseVirtualChunkContainers(repo);
 
-  return { repo, specVersion, snapshotsLength };
+  return { repo, specVersion, snapshotsLength, virtualChunkContainers };
+}
+
+/**
+ * Extract named Virtual Chunk Containers from the flexbuffers-encoded
+ * RepositoryConfig on the repo table.
+ *
+ * Only containers with a non-null `name` are included — unnamed/legacy
+ * containers cannot be referenced by `vcc://` URLs.
+ *
+ * Returns an empty map when the config is absent, malformed, or has no
+ * named containers. Parsing failures are swallowed because virtual chunk
+ * resolution is a best-effort path; callers that actually hit a `vcc://`
+ * location with no matching name will surface a clear error at fetch time.
+ */
+function parseVirtualChunkContainers(repo: FbsRepo): Map<string, string> {
+  const result = new Map<string, string>();
+  const configBytes = repo.configArray();
+  if (!configBytes || configBytes.length === 0) return result;
+
+  let config: unknown;
+  try {
+    const ab = configBytes.buffer.slice(
+      configBytes.byteOffset,
+      configBytes.byteOffset + configBytes.byteLength,
+    ) as ArrayBuffer;
+    config = flexbuffers.toObject(ab);
+  } catch {
+    return result;
+  }
+
+  if (!isRecord(config)) return result;
+  const containers = config.virtual_chunk_containers;
+  if (!isRecord(containers)) return result;
+
+  for (const container of Object.values(containers)) {
+    if (!isRecord(container)) continue;
+    const { name, url_prefix: urlPrefix } = container;
+    if (typeof name !== "string" || typeof urlPrefix !== "string") continue;
+    result.set(name, urlPrefix);
+  }
+
+  return result;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /**

src/reader/repository.ts

@@ -364,7 +364,10 @@ export class Repository {
       if (!snapshotId) {
         throw new Error(`Branch not found: ${name}`);
       }
-      return ReadSession.open(this.storage, snapshotId, options);
+      return ReadSession.open(this.storage, snapshotId, {
+        ...options,
+        virtualChunkContainers: repoInfo.virtualChunkContainers,
+      });
     }
 
     // V1 fallback - file-based lookup
@@ -398,7 +401,10 @@ export class Repository {
       if (!snapshotId) {
         throw new Error(`Tag not found: ${name}`);
       }
-      return ReadSession.open(this.storage, snapshotId, options);
+      return ReadSession.open(this.storage, snapshotId, {
+        ...options,
+        virtualChunkContainers: repoInfo.virtualChunkContainers,
+      });
     }
 
     // V1 fallback - file-based lookup
@@ -437,7 +443,14 @@ export class Repository {
       typeof snapshotId === "string"
         ? decodeObjectId12(snapshotId)
         : snapshotId;
-    return ReadSession.open(this.storage, id, options);
+    // Load repo info opportunistically so v2 sessions get VCC resolution;
+    // v1 repos return null here and sessions run with an empty container map.
+    const repoInfo = await this.loadRepoInfo(options);
+    const virtualChunkContainers = repoInfo?.virtualChunkContainers;
+    return ReadSession.open(this.storage, id, {
+      ...options,
+      ...(virtualChunkContainers && { virtualChunkContainers }),
+    });
   }
 
   /**

src/reader/session.ts

@@ -108,18 +108,22 @@ export class ReadSession {
   private nextFetchClientId = 1;
   private rangeCoalescerIds?: WeakMap<RangeCoalescingFn, number>;
   private nextRangeCoalescerId = 1;
+  /** VCC name → url_prefix map for resolving `vcc://` chunk locations. */
+  private virtualChunkContainers: Map<string, string>;
 
   private constructor(
     storage: Storage,
     snapshot: Snapshot,
     specVersion: SpecVersion,
     maxManifestCacheSize: number = 100,
+    virtualChunkContainers?: Map<string, string>,
   ) {
     this.storage = storage;
     this.snapshot = snapshot;
     this.specVersion = specVersion;
     this.manifestCache = new LRUCache(maxManifestCacheSize);
     this.manifestLoader = singleFlight(this.manifestCache);
+    this.virtualChunkContainers = virtualChunkContainers ?? new Map();
   }
 
   private getFetchClientKey(fetchClient: FetchClient | undefined): string {
@@ -250,7 +254,10 @@ export class ReadSession {
   static async open(
     storage: Storage,
     snapshotId: Uint8Array,
-    options?: RequestOptions & { maxManifestCacheSize?: number },
+    options?: RequestOptions & {
+      maxManifestCacheSize?: number;
+      virtualChunkContainers?: Map<string, string>;
+    },
   ): Promise<ReadSession> {
     const { snapshot, specVersion } = await ReadSession.loadSnapshot(
       storage,
@@ -262,6 +269,7 @@ export class ReadSession {
       snapshot,
       specVersion,
       options?.maxManifestCacheSize,
+      options?.virtualChunkContainers,
     );
   }
 
@@ -628,9 +636,13 @@ export class ReadSession {
 
       case "virtual": {
         // Virtual chunks reference external URLs
-        // Translate cloud storage URLs to HTTPS endpoints
-        const httpUrl = translateToHttpUrl(
+        // Expand any vcc://name/path → absolute URL, then translate s3:// etc. → HTTPS
+        const absoluteLocation = expandVccUrl(
           payload.location,
+          this.virtualChunkContainers,
+        );
+        const httpUrl = translateToHttpUrl(
+          absoluteLocation,
           options?.azureAccount,
         );
 
@@ -712,8 +724,12 @@ export class ReadSession {
         const absoluteStart = payload.offset + rangeStart;
         const expectedSize = rangeEnd - rangeStart;
 
-        const httpUrl = translateToHttpUrl(
+        const absoluteLocation = expandVccUrl(
           payload.location,
+          this.virtualChunkContainers,
+        );
+        const httpUrl = translateToHttpUrl(
+          absoluteLocation,
           options?.azureAccount,
         );
 
@@ -803,6 +819,58 @@ function compareUtf8Bytes(a: string, b: string): number {
   return bytesA.length - bytesB.length;
 }
 
+/** URL scheme for relative Virtual Chunk Container references. */
+const VCC_SCHEME = "vcc://";
+
+/**
+ * Expand a `vcc://name/relative/path` chunk location to an absolute URL using
+ * the repo's Virtual Chunk Container map. Pass-through for any location that
+ * doesn't start with `vcc://`.
+ *
+ * When the map is empty (e.g. a `ReadSession` constructed without a
+ * `Repository`), vcc:// locations pass through unchanged so a caller's
+ * `fetchClient` can still handle them. When the map is non-empty but the
+ * referenced name is missing, we throw — that signals a real config /
+ * manifest mismatch the caller should surface.
+ *
+ * Persisted repo configs may contain legacy/migrated prefixes without a
+ * trailing slash. Normalize those before joining so `vcc://name/path`
+ * resolves under the configured container root instead of being appended to
+ * the last prefix segment.
+ *
+ * @throws Error when the URL is malformed or the name is unknown despite a
+ *   populated container map.
+ */
+export function expandVccUrl(
+  location: string,
+  containers: Map<string, string>,
+): string {
+  if (!location.startsWith(VCC_SCHEME)) return location;
+
+  const rest = location.slice(VCC_SCHEME.length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    throw new Error(
+      `Invalid vcc:// URL "${location}": missing "/" after container name`,
+    );
+  }
+
+  const name = rest.slice(0, slash);
+  const relativePath = rest.slice(slash + 1);
+  const urlPrefix = containers.get(name);
+  if (urlPrefix === undefined) {
+    if (containers.size === 0) return location;
+    throw new Error(
+      `Unknown virtual chunk container "${name}" referenced by ${location}`,
+    );
+  }
+
+  const normalizedPrefix = urlPrefix.endsWith("/")
+    ? urlPrefix
+    : `${urlPrefix}/`;
+  return normalizedPrefix + relativePath;
+}
+
 /**
  * Translate cloud storage URLs to HTTP(S) endpoints for public buckets.
  *

tests/format/flatbuffers/repo-parser.test.ts

@@ -16,6 +16,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Path to v2 test repository
 const TEST_REPO_V2_PATH = join(__dirname, "../../data/test-repo-v2");
+const TEST_REPO_V2_MIGRATED_PATH = join(
+  __dirname,
+  "../../data/test-repo-v2-migrated",
+);
 
 describe("repo-parser", () => {
   describe("parseRepo", () => {
@@ -92,6 +96,29 @@ describe("repo-parser", () => {
     });
   });
 
+  describe("virtualChunkContainers", () => {
+    it("is empty when the only container has no name", () => {
+      // test-repo-v2 is created via `ic.VirtualChunkContainer("s3://testbucket/", store)`
+      // with no `name=` argument, so its single container is unnamed (name: null)
+      // and MUST be excluded from the vcc:// resolution map.
+      const repoData = readFileSync(join(TEST_REPO_V2_PATH, "repo"));
+      const repo = parseRepo(repoData);
+      expect(repo.virtualChunkContainers.size).toBe(0);
+    });
+
+    it("includes every named container from a migrated v2 repo", () => {
+      // test-repo-v2-migrated was produced by upgrading a v1 repo, which seeds
+      // the config with the built-in named containers for each scheme.
+      const repoData = readFileSync(join(TEST_REPO_V2_MIGRATED_PATH, "repo"));
+      const repo = parseRepo(repoData);
+      expect(repo.virtualChunkContainers.get("s3")).toBe("s3://testbucket");
+      expect(repo.virtualChunkContainers.get("gcs")).toBe("gcs");
+      expect(repo.virtualChunkContainers.get("az")).toBe("az");
+      expect(repo.virtualChunkContainers.get("tigris")).toBe("tigris");
+      expect(repo.virtualChunkContainers.get("file")).toBe("file");
+    });
+  });
+
   describe("binary search", () => {
     it("should handle UTF-8 branch names correctly", () => {
       const repoData = readFileSync(join(TEST_REPO_V2_PATH, "repo"));

tests/reader/session.test.ts

@@ -62,6 +62,7 @@ function createMockSession(options: {
   nodes?: NodeSnapshot[];
   storage?: MockStorage;
   specVersion?: SpecVersion;
+  virtualChunkContainers?: Map<string, string>;
 }): ReadSession {
   const mockSnapshot: Snapshot = {
     id: createMockSnapshotId(1) as any,
@@ -80,6 +81,8 @@ function createMockSession(options: {
   session.manifestCache = new Map();
   session.manifestLoader = singleFlight(session.manifestCache);
   session.nextFetchClientId = 1;
+  session.virtualChunkContainers =
+    options.virtualChunkContainers ?? new Map<string, string>();
 
   return session;
 }
@@ -650,6 +653,60 @@ describe("ReadSession", () => {
       expect(result).toBe(inlineData);
     });
 
+    it("expands vcc:// locations to the container's url_prefix before fetching", async () => {
+      const mockData = new Uint8Array(4);
+      const fetchClient = {
+        fetch: vi.fn().mockResolvedValue({
+          ok: true,
+          status: 206,
+          arrayBuffer: vi.fn().mockResolvedValue(mockData.buffer),
+        } as any),
+      };
+
+      const session = createMockSession({
+        nodes: [],
+        virtualChunkContainers: new Map([
+          ["my-data", "https://example.com/data/"],
+        ]),
+      }) as any;
+
+      const payload = {
+        type: "virtual" as const,
+        location: "vcc://my-data/chunks/abc.nc",
+        offset: 0,
+        length: 4,
+        checksumEtag: null,
+        checksumLastModified: 0,
+      };
+
+      await session.fetchChunkPayload(payload, { fetchClient });
+
+      expect(fetchClient.fetch).toHaveBeenCalledWith(
+        "https://example.com/data/chunks/abc.nc",
+        expect.objectContaining({ headers: { Range: "bytes=0-3" } }),
+      );
+    });
+
+    it("throws a clear error when a vcc:// URL references an unknown container", async () => {
+      const session = createMockSession({
+        nodes: [],
+        virtualChunkContainers: new Map([["known", "https://example.com/"]]),
+      }) as any;
+
+      const payload = {
+        type: "virtual" as const,
+        location: "vcc://missing/chunk",
+        offset: 0,
+        length: 4,
+        checksumEtag: null,
+        checksumLastModified: 0,
+      };
+
+      await expect(session.fetchChunkPayload(payload)).rejects.toThrow(
+        /Unknown virtual chunk container "missing"/,
+      );
+    });
+
     it("should slice native full-object fallback when Range is ignored", async () => {
       const fullObject = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
       const storage = new MockStorage({});