@skgo/sveltekit-adapter 0.19.0 → 0.22.0

package/index.d.ts

@@ -7,6 +7,10 @@ interface AdapterOptions {
 	 * @default 'build'
 	 */
 	out?: string;
+	/** Authored Go build-service package, relative to the app's Go module root.
+	 * Use RunPrerenderService to share renderer defaults with production SSR.
+	 * Defaults to the generated prerender entry. */
+	prerenderPackage?: string;
 	/**
 	 * Whether to write gzip and brotli copies of the assets and the prerendered
 	 * pages beside them. The Go server serves whichever the browser asked for.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@skgo/sveltekit-adapter",
-	"version": "0.19.0",
+	"version": "0.22.0",
 	"description": "SvelteKit adapter for skgo: builds a frontend that a Go binary renders and answers",
 	"keywords": [
 		"adapter",

package/skgo-adapter/entry.js

@@ -60,12 +60,12 @@ function handle_error(error) {
  * kit's remote wrappers read during a render are populated. is_in_render is
  * what makes kit refuse a command.
  */
-function make_state() {
+function make_state(req) {
 	return {
-		getClientAddress: () => '127.0.0.1',
+		getClientAddress: () => __skgo_client_address(),
 		error: false,
 		rerouted_url: null,
-		depth: 0,
+		depth: req.is_sub_request ? 1 : 0,
 		remote: {
 			data: null,
 			implicit: null,
@@ -171,7 +171,7 @@ function make_event(req, url, serialized) {
 			serialize: () => ''
 		},
 		fetch: create_fetch(req, url, serialized),
-		getClientAddress: () => req.client_address ?? '127.0.0.1',
+		getClientAddress: () => __skgo_client_address(),
 		locals: {},
 		params: req.params ?? {},
 		platform: undefined,
@@ -179,9 +179,9 @@ function make_event(req, url, serialized) {
 		route: { id: req.route_id ?? null },
 		setHeaders: () => {},
 		url,
-		isDataRequest: false,
-		isSubRequest: false,
-		isRemoteRequest: false,
+		isDataRequest: !!req.is_data_request,
+		isSubRequest: !!req.is_sub_request,
+		isRemoteRequest: !!req.is_remote_request,
 		tracing: { enabled: false }
 	};
 }
@@ -362,7 +362,7 @@ globalThis.__skgo_render = function (req_json) {
 	try {
 		const req = JSON.parse(req_json);
 		const url = new URL(req.url);
-		const state = make_state();
+		const state = make_state(req);
 		const serialized = new Set();
 		const event = make_event(req, url, serialized);
 		const fetched = [];

package/skgo-adapter/env.js

@@ -338,6 +338,8 @@ export function gojaEnvironment() {
 		load: {
 			order: 'pre',
 			handler(id) {
+				// Go owns handle at runtime; this build-only hook has no engine code.
+				if (/\/src\/hooks\.server\.(?:ts|js)(?:\?|$)/.test(id)) return 'export {};';
 				if (/\/\.svelte-kit\/skgo-env-(?:values\.js|runtime\.json)(?:\?|$)/.test(id)) {
 					throw new Error('skgo: environment build inputs are private');
 				}
@@ -978,6 +980,8 @@ export function gojaDevEnvironment({ outDir = '.svelte-kit' } = {}) {
 		load: {
 			order: 'pre',
 			handler(id) {
+				// Go owns handle at runtime; this build-only hook has no engine code.
+				if (/\/src\/hooks\.server\.(?:ts|js)(?:\?|$)/.test(id)) return 'export {};';
 				if (/\/\.svelte-kit\/skgo-env-(?:values\.js|runtime\.json)(?:\?|$)/.test(id)) {
 					throw new Error('skgo: environment build inputs are private');
 				}

package/skgo-adapter/prerender.d.ts

@@ -1,2 +1,6 @@
 /** Internal bridge used by generated declared-prerender input modules. */
 export function remoteInputs<Input = unknown>(module: string, name: string): Promise<Input[]>;
+
+/** Build-only logical request lifecycle used by generated server hooks. */
+export function requestHandle(event: import('@sveltejs/kit').RequestEvent, resolve: (event: import('@sveltejs/kit').RequestEvent, options?: import('@sveltejs/kit/hooks').ResolveOptions) => Promise<Response>): Promise<Response>;
+export function requestFetch(input: Parameters<import('@sveltejs/kit/hooks').HandleFetch>[0]): Promise<Response>;

package/skgo-adapter/prerender.js

@@ -7,15 +7,19 @@ import process from "node:process";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { isMainThread } from "node:worker_threads";
+import { isMainThread, BroadcastChannel, receiveMessageOnPort } from "node:worker_threads";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 const owners = new Map();
 const SERVICE_URL = "SKGO_PRERENDER_SERVICE_URL";
 const SERVICE_SECRET = "SKGO_PRERENDER_SERVICE_SECRET";
+const PREDICATE_CHANNEL = "SKGO_PRERENDER_PREDICATE_CHANNEL";
 const CALLBACK_TIMEOUT = 30_000;
 const STARTUP_TIMEOUT = 60_000;
 const SHUTDOWN_GRACE = 150;
 const CLEANUP_TIMEOUT = 5_000;
+const internalFetch = new AsyncLocalStorage();
+const cookieRelays = new WeakMap();
 function appRoot() {
   return resolve(process.cwd());
 }
@@ -98,6 +102,7 @@ function validateEnvelope(request, raw) {
   }
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("skgo prerender command returned a non-object response");
+  if (["begin", "response", "end", "endpoint", "cookies", "resolve-option"].includes(request.kind)) return;
   if (request.kind === "remote-inputs") {
     if (typeof value.inputs !== "string")
       throw new Error("skgo prerender inputs response has no devalue payload");
@@ -318,7 +323,7 @@ function startJob(owner, command, args, options = {}) {
 }
 
 /** The main build thread owns its compiler, HTTP service and scratch directory. */
-export function createPrerenderOwner(root = appRoot()) {
+export function createPrerenderOwner(root = appRoot(), prerenderPackage) {
   if (!isMainThread) return null;
   root = resolve(root);
   if (owners.has(root)) return owners.get(root);
@@ -328,7 +333,7 @@ export function createPrerenderOwner(root = appRoot()) {
   const owner = {
     root,
     cwd: resolve(root, manifest.prerender.root),
-    pkg: manifest.prerender.package,
+    pkg: prerenderPackage ?? manifest.prerender.package,
     jobs: new Set(),
     closing: false,
     failed: null,
@@ -336,10 +341,17 @@ export function createPrerenderOwner(root = appRoot()) {
     service: null,
     previousEnv: null,
     signals: new Map(),
+    pendingPredicates: new Map(),
     cleanupPromise: null,
     preparePromise: null,
     fail(error) {
       owner.failed ??= error;
+      for (const [id, cell] of owner.pendingPredicates) {
+        owner.channel?.postMessage({id, error: owner.failed.stack ?? owner.failed.message ?? String(owner.failed)});
+        Atomics.store(cell, 0, 1);
+        Atomics.notify(cell, 0);
+      }
+      owner.pendingPredicates.clear();
       return owner.cleanup().catch((cleanupError) => {
         owner.cleanupFailure = cleanupError;
         if (typeof owner.failed === "object" && owner.failed !== cleanupError) {
@@ -448,18 +460,48 @@ export function createPrerenderOwner(root = appRoot()) {
     publish() {
       if (owner.closing) throw owner.failed ?? new Error("skgo prerender owner closed");
       if (owner.previousEnv) return;
+      owner.channel = new BroadcastChannel(`skgo-prerender-${randomUUID()}`);
+      owner.channel.unref();
+      owner.channel.onmessage = async ({ data }) => {
+        if (data?.type === "failure") {
+          void owner.fail(new Error(data.error)).catch(reportOwnerFailure);
+          return;
+        }
+        if (data?.type !== "predicate") return;
+        const { id, cell, request } = data;
+        owner.pendingPredicates.set(id, cell);
+        let reply;
+        try {
+          if (owner.failed || owner.closing) throw owner.failed ?? new Error("skgo prerender owner closed");
+          const answer = JSON.parse(await invokeService({ ...request, kind: "resolve-option" }));
+          if (typeof answer.value !== "boolean") throw new Error("skgo prerender predicate returned no boolean");
+          reply = { id, value: answer.value };
+        } catch (error) {
+          reply = { id, error: error.stack ?? error.message ?? String(error) };
+        }
+        if (!owner.pendingPredicates.delete(id)) return;
+        // Wake before fail() can wait for the worker/service to stop.
+        owner.channel?.postMessage(reply);
+        Atomics.store(cell, 0, 1);
+        Atomics.notify(cell, 0);
+        if (reply.error) void owner.fail(new Error(reply.error)).catch(reportOwnerFailure);
+      };
       owner.previousEnv = new Map([
         [SERVICE_URL, process.env[SERVICE_URL]],
         [SERVICE_SECRET, process.env[SERVICE_SECRET]],
+        [PREDICATE_CHANNEL, process.env[PREDICATE_CHANNEL]],
       ]);
       process.env[SERVICE_URL] = owner.connection.url;
       process.env[SERVICE_SECRET] = owner.connection.secret;
+      process.env[PREDICATE_CHANNEL] = owner.channel.name;
     },
     cleanup() {
       if (owner.cleanupPromise) return owner.cleanupPromise;
       owner.closing = true;
       owner.cleanupPromise = (async () => {
         const errors = [];
+        owner.channel?.close();
+        owner.channel = null;
         for (const job of owner.jobs) {
           try {
             await stopJob(job, job === owner.service);
@@ -562,10 +604,10 @@ export function installPrerenderFailureBoundary(config, owner) {
 async function invokeService(request) {
   const url = process.env[SERVICE_URL];
   const secret = process.env[SERVICE_SECRET];
-  const identity = `${request.kind} ${request.module}/${request.name ?? ""}`;
+  const identity = request.kind === "resolve-option" ? `${request.option} resolve callback` : `${request.kind} ${request.module}/${request.name ?? ""}`;
   if (!url || !secret) throw new Error(`skgo prerender service unavailable for ${identity}`);
   const { kind, ...body } = request;
-  const path = { load: "/load", remote: "/remote", "remote-inputs": "/inputs" }[kind];
+  const path = { load: "/load", remote: "/remote", "remote-inputs": "/inputs", begin: "/begin", response: "/response", end: "/end", endpoint: "/endpoint", cookies: "/cookies", "resolve-option": "/resolve-option" }[kind];
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CALLBACK_TIMEOUT);
   try {
@@ -657,6 +699,7 @@ export async function remoteLoad(module, source, event) {
   const request = {
     kind: "load",
     module,
+    handle: event.platform?.skgoRequestHandle,
     url: event.url.href,
     routeId: event.route.id,
     params: {},
@@ -677,18 +720,7 @@ export async function remoteLoad(module, source, event) {
       `skgo: Go load failed during prerender: route ID ${event.route.id}, path ${event.url.pathname}, source ${source}: ${answer.failure}`,
     );
   }
-  for (const [name, values] of Object.entries(answer.headers ?? {}))
-    event.setHeaders({ [name]: values.join(", ") });
-  for (const cookie of answer.cookies ?? []) {
-    event.cookies.set(cookie.name, cookie.value, {
-      path: cookie.path,
-      ...(cookie.domain ? { domain: cookie.domain } : {}),
-      ...(cookie.maxAge ? { maxAge: cookie.maxAge } : {}),
-      httpOnly: cookie.httpOnly,
-      secure: cookie.secure,
-      sameSite: ["lax", "lax", "strict", "none"][cookie.sameSite] ?? "lax",
-    });
-  }
+  applyRequestEffects(event, answer);
   if (answer.data) {
     const pending = new Map();
     const revivers = {
@@ -728,6 +760,7 @@ export async function remoteFunction(module, name, arg, event) {
     kind: "remote",
     module,
     name,
+    handle: event.platform?.skgoRequestHandle,
     payload,
     url: event.url.href,
     headers,
@@ -745,3 +778,176 @@ export async function remoteFunction(module, name, arg, event) {
   }
   return result._;
 }
+
+
+function applyRequestEffects(event, answer) {
+  for (const [name, values] of Object.entries(answer.headers ?? {}))
+    event.setHeaders({ [name]: values.join(", ") });
+  for (const cookie of answer.cookies ?? [])
+    event.cookies.set(cookie.name, cookie.value, {
+      path: cookie.path, ...(cookie.domain ? { domain: cookie.domain } : {}),
+      ...(cookie.maxAge !== undefined ? { maxAge: cookie.maxAge } : {}), httpOnly: cookie.httpOnly,
+      ...(cookie.expires ? { expires: new Date(cookie.expires) } : {}),
+      ...(cookie.partitioned ? { partitioned: true } : {}),
+      ...(cookie.priority ? { priority: cookie.priority } : {}),
+      ...(cookie.raw ? { encode: (value) => value } : {}),
+      secure: cookie.secure, sameSite: [false, false, "lax", "strict", "none"][cookie.sameSite] ?? false,
+    });
+}
+
+/** Generated hooks.server calls this only while Kit is building. */
+export async function requestHandle(event, resolveRequest) {
+  // handleFetch's supplied fetch reaches this hook only for Kit subrequests.
+  const fetching = internalFetch.getStore();
+  if (fetching) fetching.internal = true;
+  const { manifest } = await import(pathToFileURL(join(appRoot(), ".svelte-kit/output/server/manifest-full.js")).href);
+  const prefix = manifest.app_path.slice(0, -manifest.app_dir.length);
+  const base = prefix ? "/" + prefix.slice(0, -1) : "";
+  const routes = await Promise.all(manifest.routes.map(async (route) => ({
+    id: route.id, pattern: route.pattern.source, params: route.params,
+    ...(route.page ? { page: route.page } : {}),
+    ...(route.endpoint ? { endpoint: { methods: Object.keys(await route.endpoint()).filter((key) => ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "QUERY", "fallback"].includes(key)).map((key) => key === "fallback" ? "*" : key) } } : {}),
+  })));
+  const route = routes.find((candidate) => candidate.id === event.route.id);
+  const { decode_pathname } = await import(pathToFileURL(join(kitRootFor(appRoot()), "src/utils/url.js")).href);
+  const answer = JSON.parse(await invokeService({
+    kind: "begin", method: event.request.method, url: event.request.url, logicalUrl: event.url.href,
+    headers: Object.fromEntries([...event.request.headers].map(([key, value]) => [key, [value]])),
+    body: event.request.method === "GET" || event.request.method === "HEAD" ? "" : Buffer.from(await event.request.clone().arrayBuffer()).toString("base64"),
+    routeId: event.route.id ?? "", routePattern: route?.pattern ?? "", routeParams: route?.params ?? [],
+    routePath: decode_pathname(event.url.pathname).slice(base.length) || "/",
+    isSubRequest: event.isSubRequest,
+    manifest: { appDir: manifest.app_dir, base, routes },
+  }));
+  const handle = answer.handle;
+  if (!handle) throw new Error("skgo prerender begin omitted request handle");
+  let ended = false;
+  const end = async () => {
+    if (ended) return;
+    ended = true;
+    await invokeService({ kind: "end", handle });
+  };
+  try {
+    applyRequestEffects(event, answer);
+    const { internal } = await runtime();
+    if (answer.redirect) throw new internal.Redirect(answer.redirect.status, answer.redirect.location);
+    if (answer.error) throw new internal.HttpError(answer.error);
+    let final = answer.response;
+    if (answer.resolve) {
+      event.platform ??= {};
+      event.platform.skgoRequestHandle = handle;
+      const options = {};
+      if (answer.options?.transform) options.transformPageChunk = async ({ html, done }) => {
+        try {
+          const result = JSON.parse(await invokeService({ kind: "resolve-option", option: "transform", handle, html, done }));
+          if (typeof result.html !== "string") throw new Error("skgo prerender transform returned no HTML");
+          return result.html;
+        } catch (error) { failPredicateRelay(error); }
+      };
+      if (answer.options?.filter) options.filterSerializedResponseHeaders = (name, value) => predicate(handle, "filter", { name, value });
+      if (answer.options?.preload) options.preload = (input) => predicate(handle, "preload", { input });
+      const response = await resolveRequest(event, options);
+      const headers = {};
+      for (const [name, value] of response.headers) headers[name] = [value];
+      if (response.headers.getSetCookie) headers["set-cookie"] = response.headers.getSetCookie();
+      const result = JSON.parse(await invokeService({kind: "response", handle, response: {
+        status: response.status, headers,
+        body: Buffer.from(await response.arrayBuffer()).toString("base64"),
+      }}));
+      if (result.redirect) throw new internal.Redirect(result.redirect.status, result.redirect.location);
+      if (result.error) throw new internal.HttpError(result.error);
+      final = result.response;
+    }
+    if (!final || !Number.isInteger(final.status)) throw new Error("skgo prerender request omitted final response");
+    const headers = new Headers();
+    for (const [name, values] of Object.entries(final.headers ?? {}))
+      for (const value of values ?? []) headers.append(name, value);
+    if (event.request.method === "HEAD" || [204, 205, 304].includes(final.status)) {
+      await end();
+      return new Response(null, { status: final.status, headers });
+    }
+    const bytes = Buffer.from(final.body ?? "", "base64");
+    let emitted = false;
+    const body = new ReadableStream({
+      async pull(controller) {
+        try {
+          if (!emitted) { emitted = true; controller.enqueue(bytes); }
+          else { await end(); controller.close(); }
+        } catch (error) { controller.error(error); }
+      },
+      cancel: end,
+    }, { highWaterMark: 0 });
+    return new Response(body, { status: final.status, headers });
+  } catch (error) {
+    await end();
+    throw error;
+  }
+}
+
+/** Kit has applied internal response cookies before its supplied fetch returns. */
+export async function requestFetch({ event, request, fetch }) {
+  const scope = { internal: false };
+  return internalFetch.run(scope, async () => {
+    const response = await fetch(request);
+    const cookies = response.headers.getSetCookie();
+    const handle = event.platform?.skgoRequestHandle;
+    if (scope.internal && handle && cookies.length) {
+      // Match the order in which Kit applied concurrent fetch responses.
+      const previous = cookieRelays.get(event.platform) ?? Promise.resolve();
+      const relay = previous.then(() => invokeService({ kind: "cookies", handle, url: request.url, cookies }));
+      cookieRelays.set(event.platform, relay);
+      await relay;
+    }
+    return response;
+  });
+}
+
+/** A generated server-route stub forwards only its build-time execution. */
+export async function remoteEndpoint(event) {
+  const answer = JSON.parse(await invokeService({kind: "endpoint", handle:event.platform?.skgoRequestHandle}));
+  applyRequestEffects(event,answer);
+  const response = answer.response;
+  if (!response || !Number.isInteger(response.status)) throw new Error("skgo prerender endpoint omitted response");
+  const headers = new Headers();
+  for (const [name,values] of Object.entries(response.headers ?? {}))
+    for (const value of values ?? []) headers.append(name,value);
+  const body = event.request.method === "HEAD" || [204,205,304].includes(response.status) ? null : Buffer.from(response.body ?? "","base64");
+  return new Response(body,{status:response.status,headers});
+}
+
+// The single Kit prerender worker executes predicates synchronously. Replies
+// carry the result; the cell is only the bounded completion notification.
+let predicateChannel;
+let predicateFailure;
+let predicateID = 0;
+const predicateCell = new Int32Array(new SharedArrayBuffer(4));
+function relayChannel() {
+  if (!predicateChannel) {
+    const name = process.env[PREDICATE_CHANNEL];
+    if (!name) throw new Error("skgo prerender predicate owner unavailable");
+    predicateChannel = new BroadcastChannel(name);
+    predicateChannel.unref();
+  }
+  return predicateChannel;
+}
+function failPredicateRelay(error) {
+  predicateFailure ??= error instanceof Error ? error : new Error(String(error));
+  try { relayChannel().postMessage({ type: "failure", error: predicateFailure.stack ?? predicateFailure.message }); } catch {}
+  throw predicateFailure;
+}
+function predicate(handle, option, args) {
+  if (predicateFailure) throw predicateFailure;
+  try {
+    const channel = relayChannel();
+    const id = ++predicateID;
+    Atomics.store(predicateCell, 0, 0);
+    channel.postMessage({ type: "predicate", id, cell: predicateCell, request: { handle, option, ...args } });
+    const status = Atomics.wait(predicateCell, 0, 0, CALLBACK_TIMEOUT);
+    if (status === "timed-out") throw new Error(`skgo prerender ${option} predicate timed out after ${CALLBACK_TIMEOUT}ms`);
+    const reply = receiveMessageOnPort(channel)?.message;
+    if (!reply || reply.id !== id || (typeof reply.value === "boolean") === (typeof reply.error === "string"))
+      throw new Error("skgo prerender predicate reply missing or malformed");
+    if (reply.error !== undefined) throw new Error(reply.error);
+    return reply.value;
+  } catch (error) { return failPredicateRelay(error); }
+}

package/skgo-adapter.js

@@ -18,6 +18,7 @@ import {
 	createPrerenderOwner,
 	installPrerenderFailureBoundary,
 	remoteFunction,
+ remoteEndpoint,
 	remoteLoad
 } from './skgo-adapter/prerender.js';
 import { gojaDevEnvironment, gojaDevUnchangedFiles, gojaEnvironment, goEnvironmentValues, nodeTable, SSR_TARGET } from './skgo-adapter/env.js';
@@ -58,10 +59,10 @@ const KIT_COMPONENTS = join(
  * serve a frontend that was built from a different set of Go functions than it
  * answers.
  *
- * @param {{ out?: string, precompress?: boolean }} [options]
+ * @param {{ out?: string, precompress?: boolean, prerenderPackage?: string }} [options]
  * @returns {import('@sveltejs/kit').Adapter}
  */
-export default function skgo({ out = 'build', precompress = true } = {}) {
+export default function skgo({ out = 'build', precompress = true, prerenderPackage } = {}) {
 	// The engine's bundle is a fourth environment of kit's own build. Kit reads
 	// `vite.plugins.post` while it assembles its config, long before `adapt`
 	// runs, so the plugin that declares the environment has to exist here; the
@@ -73,7 +74,7 @@ export default function skgo({ out = 'build', precompress = true } = {}) {
 		name: 'skgo-prerender-main-owner',
 		apply: 'build',
 		configResolved(config) {
-			prerenderOwner = createPrerenderOwner(process.cwd());
+			prerenderOwner = createPrerenderOwner(process.cwd(), prerenderPackage);
 			installPrerenderFailureBoundary(config, prerenderOwner);
 		},
 		// Kit captures its app environment in config/configResolved. Vite awaits
@@ -98,6 +99,7 @@ export default function skgo({ out = 'build', precompress = true } = {}) {
 		emulate() {
 			return {
 				platform: () => ({
+                    skgoPrerenderEndpoint(event) { return remoteEndpoint(event); },
 					async skgoPrerenderLoad(module, source, event) {
 						return remoteLoad(module, source, event);
 					},
@@ -129,6 +131,9 @@ export default function skgo({ out = 'build', precompress = true } = {}) {
 			checkServerLoads(allServerIds, generated.loads, generated.actions);
 
 			const endpoints = checkEndpoints(builder, generated.endpoints);
+			const prerenderedEndpoints = Object.fromEntries(builder.routes
+				.filter((route) => route.prerender === true && endpoints.has(route.id))
+				.map((route) => [route.id, endpoints.get(route.id)]));
 
 			builder.writeClient(`${out}/client`);
 			checkRemoteIds(`${out}/client`, generated.remotes, hashes);
@@ -195,6 +200,7 @@ export default function skgo({ out = 'build', precompress = true } = {}) {
 						// records in the node module it builds.
 						nodes: serverIds,
 						loads: generated.loads,
+						prerenderedEndpoints,
 						actions: [...new Set(generated.actions)].sort(),
 						ssr: describeSSR(builder, kit, nodes),
 						routes: kit._.routes.map((/** @type {any} */ route) => ({