@foldkit/node 0.0.0 → 0.1.0

package/README.md

@@ -30,6 +30,8 @@ NodeRuntime.runMain(Node.serve({ port, origin }))
 `origin` is the public URL of the deployment. When it is `None`, the adapter
 uses `http://localhost:<port>`. Set it behind a proxy or TLS terminator so the
 server entry receives the public `Request.url`.
+The supplied value must be an HTTP or HTTPS origin without credentials, a path,
+query, or fragment. Invalid values fail during startup.
 
 The adapter serves matching client files only for `GET` and `HEAD`. It sends
 the Vite-base `index.html` path, such as `/app/index.html` for `/app/`, and

package/dist/node.d.ts

@@ -6,7 +6,9 @@ export type ServeOptions = Readonly<{
     port: Config.Config<number>;
     /**
      * The origin Config for requests that reach the Fetch handler. Use `None`
-     * to derive `http://localhost:<port>` from the resolved port.
+     * to derive `http://localhost:<port>` from the resolved port. A supplied
+     * origin must use HTTP or HTTPS and have no credentials, path, query, or
+     * fragment.
      */
     origin: Config.Config<Option.Option<string>>;
     /**

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EAIN,MAAM,EACN,aAAa,EAEb,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,eAAe,EAIhB,MAAM,aAAa,CAAA;AAqCpB,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAC,CAAA;AAmTF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAa,YAAY,4IACP,CAAA"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EAIN,MAAM,EACN,aAAa,EAEb,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,eAAe,EAIhB,MAAM,aAAa,CAAA;AAmCpB,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAC,CAAA;AAoWF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAa,YAAY,4IACqC,CAAA"}

package/dist/node.js

@@ -7,8 +7,10 @@ import { dirname, isAbsolute, posix, relative, resolve, sep } from 'node:path';
 import { Readable } from 'node:stream';
 import { ReadableStream } from 'node:stream/web';
 import { pathToFileURL } from 'node:url';
-import { NodeHttpPlatform, NodeHttpServer, NodeHttpServerRequest, NodeServices, } from '@effect/platform-node';
+import { NodeHttpServer, NodeHttpServerRequest } from '@effect/platform-node';
 const DEFAULT_MANIFEST_PATH = 'dist/server/foldkit.build.json';
+const INVALID_ORIGIN_MESSAGE = 'origin must be an HTTP or HTTPS origin without credentials, path, query, or fragment';
+const ORIGIN_SYNTAX = /^https?:\/\/[^/?#\\\s@]+\/?$/i;
 const FoldkitBuildManifest = Schema.Struct({
     schemaVersion: Schema.Literals([1]),
     client: Schema.String,
@@ -22,26 +24,43 @@ const isRouteNotFound = (error) => error.reason._tag === 'RouteNotFound';
 const hostSettledResponse = () => HttpServerResponse.setHeader(HttpServerResponse.empty({
     status: Server.HOST_METHOD_ANSWERS.refusedStatus,
 }), 'allow', Server.HOST_METHOD_ANSWERS.allow);
-const basePathFrom = (basePath) => {
-    const resolvedBasePath = basePath ?? '/';
-    let url;
-    try {
-        url = new URL(resolvedBasePath, 'http://localhost');
+const isPublicOriginUrl = (url) => (url.protocol === 'http:' || url.protocol === 'https:') &&
+    url.username === '' &&
+    url.password === '' &&
+    url.pathname === '/' &&
+    url.search === '' &&
+    url.hash === '';
+const originFrom = (origin) => Effect.gen(function* () {
+    if (!ORIGIN_SYNTAX.test(origin)) {
+        return yield* Effect.fail(new Error(INVALID_ORIGIN_MESSAGE));
     }
-    catch {
-        throw new Error('basePath must be a root-relative path ending with `/`');
+    const url = yield* Effect.try({
+        try: () => new URL(origin),
+        catch: () => new Error(INVALID_ORIGIN_MESSAGE),
+    });
+    if (!isPublicOriginUrl(url)) {
+        return yield* Effect.fail(new Error(INVALID_ORIGIN_MESSAGE));
     }
-    if (!resolvedBasePath.startsWith('/') ||
-        resolvedBasePath.startsWith('//') ||
-        resolvedBasePath.includes('\\') ||
-        !resolvedBasePath.endsWith('/') ||
-        url.origin !== 'http://localhost' ||
-        url.search !== '' ||
-        url.hash !== '') {
-        throw new Error('basePath must be a root-relative path ending with `/`');
+    return url.origin;
+});
+const isRootRelativeBasePath = (basePath, url) => basePath.startsWith('/') &&
+    !basePath.startsWith('//') &&
+    !basePath.includes('\\') &&
+    basePath.endsWith('/') &&
+    url.origin === 'http://localhost' &&
+    url.search === '' &&
+    url.hash === '';
+const basePathFrom = (basePath) => Effect.gen(function* () {
+    const resolvedBasePath = basePath ?? '/';
+    const url = yield* Effect.try({
+        try: () => new URL(resolvedBasePath, 'http://localhost'),
+        catch: () => new Error('basePath must be a root-relative path ending with `/`'),
+    });
+    if (!isRootRelativeBasePath(resolvedBasePath, url)) {
+        return yield* Effect.fail(new Error('basePath must be a root-relative path ending with `/`'));
     }
     return url.pathname;
-};
+});
 const staticPathFor = (pathname, basePath) => {
     if (basePath === '/') {
         return pathname;
@@ -51,51 +70,65 @@ const staticPathFor = (pathname, basePath) => {
     }
     return `/${pathname.slice(basePath.length)}`;
 };
-const decodeManifest = (content) => Effect.try({
-    try: () => JSON.parse(content),
-    catch: cause => new Error('foldkit.build.json is not valid JSON', { cause }),
-}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(FoldkitBuildManifest)));
+const decodeManifest = (content) => Effect.gen(function* () {
+    const parsed = yield* Effect.try({
+        try: () => JSON.parse(content),
+        catch: cause => new Error('foldkit.build.json is not valid JSON', { cause }),
+    });
+    return yield* Schema.decodeUnknownEffect(FoldkitBuildManifest)(parsed);
+});
 const buildPaths = (manifestPath, manifest, rootDirectory) => {
     const serverDirectory = dirname(manifestPath);
     const normalizedServerDirectory = posix.normalize(manifest.server);
     if (rootDirectory === undefined &&
         (normalizedServerDirectory === '..' ||
             normalizedServerDirectory.startsWith('../'))) {
-        throw new Error('foldkit.build.json describes a server directory outside the Vite root. Pass rootDirectory so @foldkit/node can locate the client output.');
+        return Effect.fail(new Error('foldkit.build.json describes a server directory outside the Vite root. Pass rootDirectory so @foldkit/node can locate the client output.'));
     }
     const resolvedRootDirectory = rootDirectory === undefined
         ? resolve(serverDirectory, relative(manifest.server, '.'))
         : resolve(process.cwd(), rootDirectory);
     const expectedServerDirectory = resolve(resolvedRootDirectory, manifest.server);
     if (expectedServerDirectory !== serverDirectory) {
-        throw new Error(`rootDirectory resolves ${manifest.server} to ${expectedServerDirectory}, but the manifest is at ${serverDirectory}`);
+        return Effect.fail(new Error(`rootDirectory resolves ${manifest.server} to ${expectedServerDirectory}, but the manifest is at ${serverDirectory}`));
     }
-    return {
+    return Effect.succeed({
         clientDirectory: resolve(resolvedRootDirectory, manifest.client),
         fetchHandlerPath: resolve(serverDirectory, manifest.serverEntry),
-    };
+    });
 };
-const readBuildPaths = (manifestPath, rootDirectory) => Effect.tryPromise({
-    try: () => readFile(manifestPath, 'utf8'),
-    catch: cause => new Error(`could not read Foldkit build manifest at ${manifestPath}`, {
-        cause,
-    }),
-}).pipe(Effect.flatMap(decodeManifest), Effect.map(manifest => buildPaths(manifestPath, manifest, rootDirectory)));
-const loadFetchHandler = (fetchHandlerPath) => Effect.tryPromise({
-    try: () => import(pathToFileURL(fetchHandlerPath).href),
-    catch: cause => new Error(`could not load the Foldkit fetch handler at ${fetchHandlerPath}. Run \`vite build\` first.`, { cause }),
-}).pipe(Effect.flatMap(loaded => isFetchModule(loaded)
-    ? Effect.succeed(loaded.default)
-    : Effect.fail(new Error(`${fetchHandlerPath} must default-export a Web fetch handler`))));
+const readBuildPaths = (manifestPath, rootDirectory) => Effect.gen(function* () {
+    const content = yield* Effect.tryPromise({
+        try: () => readFile(manifestPath, 'utf8'),
+        catch: cause => new Error(`could not read Foldkit build manifest at ${manifestPath}`, {
+            cause,
+        }),
+    });
+    const manifest = yield* decodeManifest(content);
+    return yield* buildPaths(manifestPath, manifest, rootDirectory);
+});
+const loadFetchHandler = (fetchHandlerPath) => Effect.gen(function* () {
+    const loaded = yield* Effect.tryPromise({
+        try: () => import(pathToFileURL(fetchHandlerPath).href),
+        catch: cause => new Error(`could not load the Foldkit fetch handler at ${fetchHandlerPath}. Run \`vite build\` first.`, { cause }),
+    });
+    if (!isFetchModule(loaded)) {
+        return yield* Effect.fail(new Error(`${fetchHandlerPath} must default-export a Web fetch handler`));
+    }
+    return loaded.default;
+});
 const fetchResponse = (app, request, requestUrl) => Effect.gen(function* () {
     const signal = yield* Effect.abortSignal;
     const webRequest = yield* HttpServerRequest.toWeb(request, { signal });
+    // NOTE: A rejected Fetch handler promise is an unhandled application
+    // defect. Expected application failures should be returned as Responses.
     const response = yield* Effect.promise(() => app.fetch(new Request(requestUrl, webRequest)));
     const headers = new Headers(response.headers);
     const setCookieHeaders = headers.getSetCookie();
     headers.delete('set-cookie');
+    const nodeResponse = NodeHttpServerRequest.toServerResponse(request);
     if (setCookieHeaders.length > 0) {
-        NodeHttpServerRequest.toServerResponse(request).setHeader('set-cookie', setCookieHeaders);
+        nodeResponse.setHeader('set-cookie', setCookieHeaders);
     }
     const responseOptions = {
         status: response.status,
@@ -118,7 +151,6 @@ const fetchResponse = (app, request, requestUrl) => Effect.gen(function* () {
         },
         cancel: reason => webReader.cancel(reason),
     }));
-    const nodeResponse = NodeHttpServerRequest.toServerResponse(request);
     const destroyBody = () => nodeBody.destroy();
     nodeResponse.once('close', destroyBody);
     nodeBody.once('close', () => nodeResponse.off('close', destroyBody));
@@ -131,16 +163,17 @@ const confinedStaticFiles = (clientDirectory) => Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const httpPlatform = yield* HttpPlatform.HttpPlatform;
     const root = yield* fileSystem.realPath(clientDirectory);
-    const confinedRealPath = (path) => Effect.flatMap(fileSystem.realPath(path), canonicalPath => {
+    const confinedRealPath = (path) => Effect.gen(function* () {
+        const canonicalPath = yield* fileSystem.realPath(path);
         const fromRoot = relative(root, canonicalPath);
         const isContained = fromRoot === '' ||
             (fromRoot !== '..' &&
                 !fromRoot.startsWith(`..${sep}`) &&
                 !isAbsolute(fromRoot));
         if (isContained) {
-            return Effect.succeed(canonicalPath);
+            return canonicalPath;
         }
-        return Effect.fail(PlatformError.systemError({
+        return yield* Effect.fail(PlatformError.systemError({
             _tag: 'NotFound',
             module: 'FileSystem',
             method: 'realPath',
@@ -157,13 +190,12 @@ const confinedStaticFiles = (clientDirectory) => Effect.gen(function* () {
     });
     return yield* HttpStaticServer.make({ root, index: undefined }).pipe(Effect.provideService(FileSystem.FileSystem, confinedFileSystem), Effect.provideService(HttpPlatform.HttpPlatform, confinedPlatform));
 });
-const makeHandler = (options) => Effect.gen(function* () {
-    const port = yield* options.port;
-    const origin = Option.getOrElse(yield* options.origin, () => `http://localhost:${globalThis.String(port)}`);
+const makeHandler = (options, port) => Effect.gen(function* () {
+    const origin = yield* originFrom(Option.getOrElse(yield* options.origin, () => `http://localhost:${globalThis.String(port)}`));
     const manifestPath = resolve(process.cwd(), options.manifestPath ?? DEFAULT_MANIFEST_PATH);
     const paths = yield* readBuildPaths(manifestPath, options.rootDirectory);
+    const basePath = yield* basePathFrom(options.basePath);
     const app = yield* loadFetchHandler(paths.fetchHandlerPath);
-    const basePath = basePathFrom(options.basePath);
     const staticFiles = yield* confinedStaticFiles(paths.clientDirectory);
     return HttpServerRequest.HttpServerRequest.use(request => {
         const requestUrl = Server.resolveRequestUrl(request.url, origin);
@@ -193,7 +225,7 @@ const makeHandler = (options) => Effect.gen(function* () {
         return Effect.provideService(response, HttpServerRequest.HttpServerRequest, staticRequest ?? fetchRequest);
     }).pipe(Effect.interruptible);
 });
-const serverLayer = (options) => Layer.unwrap(Effect.map(makeHandler(options), handler => HttpServer.serve(handler))).pipe(HttpServer.withLogAddress, Layer.provide(NodeHttpServer.layerConfig(createServer, { port: options.port })), Layer.provide(NodeHttpPlatform.layer), Layer.provide(NodeServices.layer));
+const serverLayer = (options, port) => Layer.unwrap(Effect.map(makeHandler(options, port), handler => HttpServer.serve(handler))).pipe(HttpServer.withLogAddress, Layer.provide(NodeHttpServer.layer(createServer, { port })));
 /**
  * Starts a Node HTTP server for a built Foldkit application.
  *
@@ -201,4 +233,4 @@ const serverLayer = (options) => Layer.unwrap(Effect.map(makeHandler(options), h
  * and HEAD requests, and sends every other application request to the emitted
  * Web Fetch handler. Interrupting the returned Effect closes the HTTP server.
  */
-export const serve = (options) => Layer.launch(serverLayer(options));
+export const serve = (options) => Effect.flatMap(options.port, port => Layer.launch(serverLayer(options, port)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/node",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Node.js host adapter for Foldkit server-rendered applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,10 +26,10 @@
   "devDependencies": {
     "@types/node": "26.4.0",
     "effect": "4.0.0",
+    "foldkit": "0.167.0",
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "foldkit": "0.166.0"
+    "vitest": "^4.1.11"
   },
   "keywords": [
     "foldkit",