refactor: convert all links and assets to absolute when loaded

Author: blacha

src/http.ts

@@ -16,7 +16,7 @@ export async function fetchStac(
     if (response.ok) {
       return response
         .json()
-        .then((json) => maybeAddSelfLink(json, href.toString()));
+        .then((json) => makeStacUrlAbsolute(json, href.toString()));
     } else {
       throw new Error(`${method} ${href}: ${response.statusText}`);
     }
@@ -32,9 +32,8 @@ export async function fetchStacLink(link: StacLink, href?: string | undefined) {
   );
 }
 
-// eslint-disable-next-line
-function maybeAddSelfLink(value: any, href: string) {
-  if (!(value as StacValue)?.links?.find((link) => link.rel == "self")) {
+function maybeAddSelfLink(value: StacValue, href: string) {
+  if (!value?.links?.find((link) => link.rel == "self")) {
     const link = { href, rel: "self" };
     if (Array.isArray(value.links)) {
       value.links.push(link);
@@ -44,3 +43,71 @@ function maybeAddSelfLink(value: any, href: string) {
   }
   return value;
 }
+
+/**
+ * Attempt to convert links and asset URLS to absolute URLs while ensuring a self link exists.
+ *
+ * @param value Source stac item, collection, or catalog
+ * @param baseUrl base location of the STAC document
+ */
+export function makeStacUrlAbsolute<T extends StacValue>(
+  value: T,
+  baseUrl: string,
+): T {
+  maybeAddSelfLink(value, baseUrl);
+  const baseUrlObj = new URL(baseUrl);
+
+  if (value.links != null) {
+    for (const link of value.links) {
+      if (link.href == null) continue;
+      link.href = toAbsoluteUrl(link.href, baseUrlObj);
+    }
+  }
+
+  if (value.assets != null) {
+    for (const asset of Object.values(value.assets)) {
+      if (asset.href == null) continue;
+      asset.href = toAbsoluteUrl(asset.href, baseUrlObj);
+    }
+  }
+  return value;
+}
+
+/**
+ * Determine if the URL is absolute
+ * @returns true if absolute, false otherwise
+ */
+function isAbsolute(url: string) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Attempt to convert a possibly relative URL to an absolute URL
+ *
+ * If the URL is already absolute, it is returned unchanged.
+ *
+ * **WARNING**: if the URL is http it will be returned as URL encoded
+ *
+ * @param href
+ * @param baseUrl
+ * @returns absolute URL
+ */
+export function toAbsoluteUrl(href: string, baseUrl: URL): string {
+  if (isAbsolute(href)) return href;
+
+  const targetUrl = new URL(href, baseUrl);
+
+  if (targetUrl.protocol === "http:" || targetUrl.protocol === "https:") {
+    return targetUrl.toString();
+  }
+
+  // S3 links should not be encoded
+  if (targetUrl.protocol === "s3:") return decodeURI(targetUrl.toString());
+
+  return targetUrl.toString();
+}

tests/http.spec.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "vitest";
+import { makeStacUrlAbsolute, toAbsoluteUrl } from "../src/http";
+import { StacItem } from "stac-ts";
+
+test("should preserve UTF8 characters while making URLS absolute", async () => {
+  expect(toAbsoluteUrl("🦄.tiff", new URL("s3://some-bucket"))).equals(
+    "s3://some-bucket/🦄.tiff",
+  );
+  expect(
+    toAbsoluteUrl("https://foo/bar/🦄.tiff", new URL("s3://some-bucket")),
+  ).equals("https://foo/bar/🦄.tiff");
+  expect(
+    toAbsoluteUrl("../../../🦄.tiff", new URL("s3://some-bucket/🌈/path/a/b/")),
+  ).equals("s3://some-bucket/🌈/🦄.tiff");
+
+    expect(
+    toAbsoluteUrl('a+🦄.tiff', new URL("s3://some-bucket/🌈/")),
+  ).equals("s3://some-bucket/🌈/a+🦄.tiff");
+
+  expect(
+    toAbsoluteUrl("../../../🦄.tiff", new URL("https://some-url/🌈/path/a/b/")),
+  ).equals("https://some-url/%F0%9F%8C%88/%F0%9F%A6%84.tiff");
+  expect(
+    toAbsoluteUrl(
+      "foo/🦄.tiff?width=1024",
+      new URL("https://user@[2601:195:c381:3560::f42a]:1234/test"),
+    ),
+  ).equals(
+    "https://user@[2601:195:c381:3560::f42a]:1234/foo/%F0%9F%A6%84.tiff?width=1024",
+  );
+});
+
+test("should convert relative links to absolute", () => {
+  expect(
+    makeStacUrlAbsolute(
+      {
+        links: [
+          { href: "a/b/c", rel: "child" },
+          { href: "/d/e/f", rel: "child" },
+        ],
+      } as unknown as StacItem,
+      "https://example.com/root/item.json",
+    ).links,
+  ).deep.equals([
+    { href: "https://example.com/root/a/b/c", rel: "child" },
+    { href: "https://example.com/d/e/f", rel: "child" },
+    { href: "https://example.com/root/item.json", rel: "self" },
+  ]);
+});
+
+test("should convert relative assets to absolute", () => {
+  expect(
+    makeStacUrlAbsolute(
+      {
+        assets: {
+          tiff: { href: "./foo.tiff" },
+          thumbnail: { href: "../thumbnails/foo.png" },
+        },
+      } as unknown as StacItem,
+      "https://example.com/root/item.json",
+    ).assets,
+  ).deep.equals({
+    tiff: { href: "https://example.com/root/foo.tiff" },
+    thumbnail: { href: "https://example.com/thumbnails/foo.png" },
+  });
+});