Merge pull request #5095 from cardstack/cs-11344-error-with-blackjack-game

Resolve cross-realm file links instead of erroring

Author: lukemelia

packages/realm-server/tests/card-endpoints-test.ts

@@ -4363,6 +4363,120 @@ module(basename(__filename), function () {
     });
   });
 
+  module('cross-realm file links', function (hooks) {
+    // A card instantiated from the catalog (e.g. a blackjack game) keeps a
+    // linksTo(FileDef) reference to an image file that lives in the catalog
+    // realm. When the card is served from a different realm, loadLinks resolves
+    // that reference via the cross-realm fetch path. Regression for CS-11344:
+    // that path used to assume every cross-realm link target was a card and
+    // threw "instance ... is not a card document" on a file-meta target,
+    // surfacing as an HTTP 500.
+    const providerRealmURL = 'http://127.0.0.1:5531/test/';
+    const consumerRealmURL = 'http://127.0.0.1:5532/test/';
+    let consumerRequest: RealmRequest;
+
+    setupPermissionedRealmsCached(hooks, {
+      realms: [
+        {
+          realmURL: providerRealmURL,
+          permissions: {
+            '*': ['read', 'write', 'realm-owner'],
+            '@node-test_realm:localhost': ['read', 'realm-owner'],
+          },
+          fileSystem: {
+            'instructions.md': '# Cross-realm instructions',
+          },
+        },
+        {
+          realmURL: consumerRealmURL,
+          permissions: {
+            '*': ['read', 'write', 'realm-owner'],
+            '@node-test_realm:localhost': ['read', 'realm-owner'],
+          },
+          fileSystem: {
+            'skill-card.gts': `
+              import { CardDef, field, contains, linksTo } from "https://cardstack.com/base/card-api";
+              import StringField from "https://cardstack.com/base/string";
+              import { MarkdownDef } from "https://cardstack.com/base/markdown-file-def";
+
+              export class SkillCard extends CardDef {
+                @field cardTitle = contains(StringField);
+                @field instructionsSource = linksTo(MarkdownDef);
+              }
+            `,
+            'skill.json': {
+              data: {
+                attributes: {
+                  cardTitle: 'Cross-realm skill',
+                },
+                relationships: {
+                  instructionsSource: {
+                    links: {
+                      self: `${providerRealmURL}instructions.md`,
+                    },
+                  },
+                },
+                meta: {
+                  adoptsFrom: {
+                    module: rri('./skill-card'),
+                    name: 'SkillCard',
+                  },
+                },
+              },
+            },
+          },
+        },
+      ],
+      onRealmSetup({ realms }) {
+        let latestRealms = realms.slice(-2);
+        consumerRequest = withRealmPath(
+          supertest(latestRealms[1].realmHttpServer),
+          new URL(consumerRealmURL),
+        );
+      },
+    });
+
+    hooks.afterEach(() => {
+      resetCatalogRealms();
+    });
+
+    test('serves a card linking to a file in another realm', async function (assert) {
+      let response = await consumerRequest
+        .get('/skill')
+        .set('Accept', 'application/vnd.card+json');
+
+      assert.strictEqual(
+        response.status,
+        200,
+        `HTTP 200 status: ${response.text}`,
+      );
+
+      let doc = response.body as LooseSingleCardDocument;
+      let relationship = doc.data.relationships
+        ?.instructionsSource as Relationship;
+      assert.deepEqual(
+        relationship?.data,
+        {
+          type: 'file-meta',
+          id: `${providerRealmURL}instructions.md`,
+        },
+        'cross-realm file relationship references the file-meta target',
+      );
+
+      let included = doc.included ?? [];
+      let linkedFile = included.find(
+        (resource) => resource.id === `${providerRealmURL}instructions.md`,
+      );
+      assert.ok(linkedFile, 'includes the cross-realm file-meta resource');
+      assert.strictEqual(
+        linkedFile?.type,
+        'file-meta',
+        'cross-realm linked resource is a file-meta resource',
+      );
+      assert.strictEqual(linkedFile?.attributes?.name, 'instructions.md');
+    });
+  });
+
   module('Query-backed relationships runtime resolver', function (hooks) {
     const providerRealmURL = 'http://127.0.0.1:5521/test/';
     const consumerRealmURL = 'http://127.0.0.1:5522/test/';

packages/runtime-common/realm-index-query-engine.ts

@@ -55,6 +55,7 @@ import {
 } from './code-ref';
 import {
   isSingleCardDocument,
+  isSingleFileMetaDocument,
   type SingleCardDocument,
   type LinkableCollectionDocument,
   isLinkableCollectionDocument,
@@ -1178,7 +1179,7 @@ export class RealmIndexQueryEngine {
     urls: string[],
     invocationId: string,
     layerIndex: number,
-  ): Promise<Map<string, CardResource<Saved>>> {
+  ): Promise<Map<string, CardResource<Saved> | FileMetaResource>> {
     let entries = await Promise.all(
       urls.map(async (url) => {
         let response: Response;
@@ -1201,20 +1202,24 @@ export class RealmIndexQueryEngine {
           throw await CardError.fromFetchResponse(url, response);
         }
         let json = await response.json();
-        if (!isSingleCardDocument(json)) {
-          throw new Error(
-            `instance ${url} is not a card document. it is: ${JSON.stringify(
-              json,
-              null,
-              2,
-            )}`,
-          );
+        // Cross-realm links can target either a card or a file (e.g. a card
+        // instantiated from a catalog still links to the catalog's image
+        // file). Both kinds are valid linked resources; only an unrecognized
+        // payload is an error.
+        if (isSingleCardDocument(json) || isSingleFileMetaDocument(json)) {
+          let linkResource: CardResource<Saved> | FileMetaResource = {
+            ...json.data,
+            ...{ links: { self: json.data.id } },
+          };
+          return [url, linkResource] as const;
         }
-        let linkResource: CardResource<Saved> = {
-          ...json.data,
-          ...{ links: { self: json.data.id } },
-        };
-        return [url, linkResource] as const;
+        throw new Error(
+          `linked resource ${url} is not a card or file document. it is: ${JSON.stringify(
+            json,
+            null,
+            2,
+          )}`,
+        );
       }),
     );
     return new Map(entries);
@@ -1635,7 +1640,7 @@ export class RealmIndexQueryEngine {
       let batchStart = Date.now();
       let instanceMap: Map<string, InstanceOrError>;
       let fileMap: Map<string, IndexedFile>;
-      let crossRealmMap: Map<string, CardResource<Saved>>;
+      let crossRealmMap: Map<string, CardResource<Saved> | FileMetaResource>;
       try {
         [instanceMap, fileMap, crossRealmMap] = await Promise.all([
           inRealmCardURLs.size > 0
@@ -1656,7 +1661,9 @@ export class RealmIndexQueryEngine {
                 invocationId,
                 currentLayerIndex,
               )
-            : Promise.resolve(new Map<string, CardResource<Saved>>()),
+            : Promise.resolve(
+                new Map<string, CardResource<Saved> | FileMetaResource>(),
+              ),
         ]);
       } catch (err: unknown) {
         let message =