6. Reaching the outside

# Fetches a link's title and description for the new-asset form. This is the
# first function that reaches outside: `network` is the whole allowlist —
# api.microlink.io answers, every other host is refused at the egress. It
# touches no collection, so no `admin:` either.
invoke: "user != nil"
network: [api.microlink.io]

// preview: given a URL, ask api.microlink.io for the page's title and
// description. `network: [api.microlink.io]` is the whole allowlist — fetch
// anywhere else and the egress refuses the connection; that's the sandbox
// doing the work, not the code.
import type { Context } from "../lib/types.ts";

export default async function handler(ctx: Context) {
  const { url } = ctx.input as { url: string };

  const res = await fetch(`https://api.microlink.io?url=${encodeURIComponent(url)}`, {
    headers: { accept: "application/json" },
  });
  if (!res.ok) {
    // ctx.error is the caller's answer, so only 4xx exists here; 424 says
    // "the dependency failed", not "the function crashed".
    throw ctx.error(424, "preview_failed", `the preview service answered ${res.status}`);
  }
  const payload = await res.json();
  if (payload.status !== "success") {
    throw ctx.error(424, "preview_failed", payload.error?.message ?? "no metadata for that page");
  }
  const { title, description } = payload.data ?? {};
  return { title: title ?? null, description: description ?? null };
}

// Run with `make functions-testing-test` (Deno; no MongoDB, backd or network).
//
// `network:` is enforced at the egress, outside the function — a unit test
// can't see it. What the test can do is replace globalThis.fetch and check
// the code that surrounds the call.
import { createContext, FunctionError } from "../../../../../../clients/functions-testing/src/index.js";
import handler from "./index.ts";

async function withFetch(fake: (url: string) => Promise<Response>, run: () => Promise<void>) {
  const real = globalThis.fetch;
  globalThis.fetch = fake as typeof fetch;
  try {
    await run();
  } finally {
    globalThis.fetch = real;
  }
}

Deno.test("returns title and description, sending the url to the allowlisted host", async () => {
  let asked = "";
  await withFetch(async (url) => {
    asked = url;
    return new Response(JSON.stringify({ status: "success", data: { title: "backd docs", description: "the manual" } }), { status: 200 });
  }, async () => {
    const { ctx } = createContext({ input: { url: "https://backd.example/docs" } });
    const out = (await handler(ctx as never)) as { title: string | null; description: string | null };
    if (out.title !== "backd docs" || out.description !== "the manual") throw new Error(JSON.stringify(out));
  });
  if (!asked.startsWith("https://api.microlink.io?url=") || !asked.includes(encodeURIComponent("https://backd.example/docs"))) {
    throw new Error(`fetched ${asked}`);
  }
});

Deno.test("a failed fetch becomes 424 preview_failed (ctx.error is 4xx only)", async () => {
  await withFetch(async () => new Response("down", { status: 503 }), async () => {
    const { ctx } = createContext({ input: { url: "https://anything.example" } });
    try {
      await handler(ctx as never);
      throw new Error("should have refused");
    } catch (e) {
      const err = e as FunctionError;
      if (err.status !== 424 || err.code !== "preview_failed") throw e;
    }
  });
});

for f in main/_functions/preview/function.yaml main/_functions/preview/index.ts main/_functions/preview/input.schema.json main/_functions/preview/index.test.ts; do
  mkdir -p "config/shelf/$(dirname "$f")"
  curl -fsSL "https://fernandezvara.github.io/backd/tutorial/config/shelf/$f" -o "config/shelf/$f"
done

docker compose run --rm functions-build && docker compose restart backd