@pablozaiden/webapp 0.6.3 → 0.6.6

package/docs/server.md

@@ -55,11 +55,18 @@ timestamps, and other server-managed fields under application control.
 `parseJson(req, schema)` parses and validates the body at runtime. Malformed JSON
 returns a 400 `invalid_json` response, while a JSON value that does not satisfy
 the schema returns a 400 `invalid_request_body` response with field details.
-Use `parseOptionalJson(req, schema)` only for endpoints that deliberately allow
-an empty body. Only a zero-byte body is considered absent; whitespace-only
-content is non-empty malformed JSON and is rejected just like any other
-malformed body. `parseUnknownJson` returns `unknown` and is intentionally
-unvalidated, so application handlers should prefer a schema-backed parser.
+Pass `{ maxBytes, requireContentType: true }` when an endpoint needs a
+bounded JSON body. The parser rejects a non-JSON content type with a 400
+`invalid_request_content_type` response, rejects an invalid `Content-Length`
+with a 400 `invalid_request_content_length` response, rejects declared and
+streamed bodies over `maxBytes` with a 413 `request_body_too_large` response,
+and cancels a streamed body as soon as the limit is exceeded. JSON media types
+with a `+json` suffix are accepted. Use `parseOptionalJson(req, schema)` only
+for endpoints that deliberately allow an empty body. Only a zero-byte body is
+considered absent; whitespace-only content is non-empty malformed JSON and is
+rejected just like any other malformed body. `parseUnknownJson` returns
+`unknown` and is intentionally unvalidated, so application handlers should
+prefer a schema-backed parser.
 
 The Notes TODO webhook uses an absent body (or an object without `title`) to
 apply its source-based fallback title. When an owner does not exist, that
@@ -106,6 +113,31 @@ Route context is user-aware:
 
 Use `ctx.filterOwned(records, getUserId)` and `ctx.requireOwned(record, getUserId)` when app records use a different ownership field. Return 404 for other-user resources so route responses do not reveal whether another user's id exists.
 
+## Supplying a validated runtime config
+
+`createWebAppServer` reads and validates `{PREFIX}_*` environment variables by
+default. An application that has already resolved a `RuntimeConfig` can pass it
+through `runtimeConfig` instead:
+
+```ts
+import { createWebAppServer, readRuntimeConfig } from "@pablozaiden/webapp/server";
+
+const runtimeConfig = readRuntimeConfig({ appName: "My App", envPrefix: "MY_APP" });
+const app = createWebAppServer({
+  appName: "My App",
+  envPrefix: "MY_APP",
+  runtimeConfig,
+  routes,
+});
+```
+
+The supplied config is used during every framework initialization step,
+including store selection, logging, authentication, document generation,
+request handling, and lifecycle setup. Its `appName` and `envPrefix` must match
+the constructor inputs. Do not mutate `app.config` after construction to
+replace constructor options; omit `runtimeConfig` when the framework should read
+the environment itself.
+
 Built-in endpoints include:
 
 | Endpoint | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.6.3",
+  "version": "0.6.6",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/build/build-binary.ts

@@ -3,6 +3,7 @@ import tailwindPlugin from "bun-plugin-tailwind";
 import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, resolve } from "node:path";
 import { findPackageRoot, resolveReactDomClient } from "../package-resolution";
+import { compileWebAppPublicAsset, type WebAppPublicAssetOptions } from "../server/public-assets";
 
 export const BUN_COMPILE_TARGETS = [
   "bun-linux-x64",
@@ -27,6 +28,7 @@ export interface BuildWebAppBinaryOptions {
   define?: Record<string, string>;
   web?: {
     entry?: string;
+    publicAssets?: WebAppPublicAssetOptions[];
     build?: {
       plugins?: BunPlugin[];
       define?: Record<string, string>;
@@ -35,6 +37,11 @@ export interface BuildWebAppBinaryOptions {
   };
 }
 
+interface CompiledPublicAsset {
+  path: string;
+  body: string;
+}
+
 function formatTargetValue(value: unknown): string {
   if (value === undefined) return "<missing>";
   if (typeof value === "string") return JSON.stringify(value);
@@ -125,6 +132,17 @@ configureWebAppRenderer(createRoot);
       }
       throw new Error("Browser build failed");
     }
+    const publicAssets: CompiledPublicAsset[] = [];
+    for (const publicAsset of options.web?.publicAssets ?? []) {
+      const body = await compileWebAppPublicAsset({
+        ...publicAsset,
+        define: { ...options.define, ...publicAsset.define },
+      });
+      publicAssets.push({
+        path: publicAsset.path,
+        body: Buffer.from(body).toString("base64"),
+      });
+    }
     const assets = browserBuild.outputs
       .filter((output) => extname(output.path).toLowerCase() !== ".map")
       .map((output) => {
@@ -142,6 +160,7 @@ configureWebAppRenderer(createRoot);
       });
     const compiledAssetsModule = resolve(cacheDir, "compiled-webapp-assets.ts");
     writeFileSync(compiledAssetsModule, `globalThis[Symbol.for("webapp.compiledClient")] = ${JSON.stringify({ packageRoot, assets })};
+globalThis[Symbol.for("webapp.compiledPublicAssets")] = ${JSON.stringify({ assets: publicAssets })};
 `);
     const compiledEntrypoint = resolve(cacheDir, "entrypoint.ts");
     writeFileSync(compiledEntrypoint, `import "./compiled-webapp-assets";

package/src/server/create-web-app-server.ts

@@ -41,7 +41,10 @@ function canUseSpaFallback(req: Request): boolean {
 }
 
 export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<TEvent>): WebAppServer<TEvent> {
-  const config = readRuntimeConfig({ appName: input.appName, envPrefix: input.envPrefix });
+  const config = input.runtimeConfig ?? readRuntimeConfig({ appName: input.appName, envPrefix: input.envPrefix });
+  if (config.appName !== input.appName || config.envPrefix !== input.envPrefix) {
+    throw new Error("runtimeConfig appName and envPrefix must match the createWebAppServer inputs");
+  }
   const store = input.store ?? sqliteWebAppStore({ dataDir: config.dataDir });
   store.initialize();
   const savedLogLevel = store.getLogLevelPreference();

package/src/server/index.ts

@@ -2,6 +2,7 @@ export * from "./runtime-config";
 export * from "./routes";
 export * from "./route-catalog";
 export * from "./responses";
+export * from "./public-assets";
 export * from "./create-web-app-server";
 export { getRequestBaseUrl, getRequestOriginInfo, type RequestOriginInfo } from "./auth/request-origin";
 export * from "./auth/store";

package/src/server/public-assets.ts

@@ -0,0 +1,115 @@
+import type { BunPlugin } from "bun";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { PublicRouteDefinition } from "./server-types";
+
+const COMPILED_PUBLIC_ASSETS_SYMBOL = Symbol.for("webapp.compiledPublicAssets");
+
+export interface WebAppPublicAssetOptions {
+  path: string;
+  entrypoint: string | URL;
+  contentType: string;
+  headers?: HeadersInit;
+  format?: "iife" | "esm";
+  define?: Record<string, string>;
+  plugins?: BunPlugin[];
+}
+
+interface CompiledPublicAsset {
+  path: string;
+  body: string;
+}
+
+interface CompiledPublicAssets {
+  assets: CompiledPublicAsset[];
+}
+
+function normalizePublicAssetPath(path: string): string {
+  const trimmed = path.trim();
+  if (!trimmed.startsWith("/") || trimmed.includes("?") || trimmed.includes("#")) {
+    throw new Error(`Public asset path must be an absolute URL path without a query or fragment: ${path}`);
+  }
+  return trimmed;
+}
+
+function resolveEntrypoint(entrypoint: string | URL): string {
+  if (entrypoint instanceof URL) {
+    if (entrypoint.protocol !== "file:") {
+      throw new Error(`Public asset entrypoint must be a local file path or file URL; received ${entrypoint.protocol} URL`);
+    }
+    return fileURLToPath(entrypoint);
+  }
+  if (isAbsolute(entrypoint)) {
+    return entrypoint;
+  }
+  return resolve(dirname(Bun.main || process.argv[1] || "."), entrypoint);
+}
+
+function responseHeaders(options: WebAppPublicAssetOptions): Record<string, string> {
+  const headers = new Headers(options.headers);
+  headers.set("content-type", options.contentType);
+  return Object.fromEntries(headers.entries());
+}
+
+function compiledPublicAsset(path: string): Uint8Array | undefined {
+  const value = (globalThis as { [key: symbol]: unknown })[COMPILED_PUBLIC_ASSETS_SYMBOL];
+  if (!value || typeof value !== "object" || !("assets" in value) || !Array.isArray(value.assets)) {
+    return undefined;
+  }
+  const asset = (value as CompiledPublicAssets).assets.find((candidate) => candidate.path === path);
+  if (!asset || typeof asset.body !== "string") {
+    return undefined;
+  }
+  return new Uint8Array(Buffer.from(asset.body, "base64"));
+}
+
+export async function compileWebAppPublicAsset(options: WebAppPublicAssetOptions): Promise<Uint8Array> {
+  const entrypoint = resolveEntrypoint(options.entrypoint);
+  const outputDirectory = mkdtempSync(join(tmpdir(), "webapp-public-asset-"));
+  try {
+    const result = await Bun.build({
+      entrypoints: [entrypoint],
+      outdir: outputDirectory,
+      target: "browser",
+      format: options.format ?? "iife",
+      splitting: false,
+      minify: true,
+      sourcemap: "none",
+      define: options.define,
+      plugins: options.plugins,
+    });
+    if (!result.success) {
+      for (const log of result.logs) {
+        console.error(log);
+      }
+      throw new Error(`Public asset build failed for ${entrypoint}`);
+    }
+    const output = result.outputs[0];
+    if (!output) {
+      throw new Error(`Public asset build produced no output for ${entrypoint}`);
+    }
+    return new Uint8Array(await output.arrayBuffer());
+  } finally {
+    rmSync(outputDirectory, { recursive: true, force: true });
+  }
+}
+
+export function createWebAppPublicAsset(options: WebAppPublicAssetOptions): PublicRouteDefinition {
+  const path = normalizePublicAssetPath(options.path);
+  const headers = responseHeaders(options);
+  let assetPromise: Promise<Uint8Array> | undefined;
+
+  return {
+    headers,
+    GET: async () => {
+      const embedded = compiledPublicAsset(path);
+      if (embedded) {
+        return embedded;
+      }
+      assetPromise ??= compileWebAppPublicAsset(options);
+      return await assetPromise;
+    },
+  };
+}

package/src/server/responses.ts

@@ -38,6 +38,36 @@ export class InvalidJsonError extends Error {
   }
 }
 
+export class InvalidRequestContentTypeError extends Error {
+  readonly code = "invalid_request_content_type";
+  readonly status = 400;
+
+  constructor() {
+    super("Request content type must be application/json");
+    this.name = "InvalidRequestContentTypeError";
+  }
+}
+
+export class InvalidRequestContentLengthError extends Error {
+  readonly code = "invalid_request_content_length";
+  readonly status = 400;
+
+  constructor() {
+    super("Request content length must be a non-negative integer");
+    this.name = "InvalidRequestContentLengthError";
+  }
+}
+
+export class RequestBodyTooLargeError extends Error {
+  readonly code = "request_body_too_large";
+  readonly status = 413;
+
+  constructor() {
+    super("Request body is too large");
+    this.name = "RequestBodyTooLargeError";
+  }
+}
+
 export interface RequestBodyValidationIssue {
   path: Array<string | number>;
   code: string;
@@ -61,7 +91,13 @@ export class InvalidRequestBodyError extends Error {
 }
 
 export function requestBodyErrorResponse(error: unknown): Response | undefined {
-  if (error instanceof InvalidJsonError || error instanceof InvalidRequestBodyError) {
+  if (
+    error instanceof InvalidJsonError
+    || error instanceof InvalidRequestContentTypeError
+    || error instanceof InvalidRequestContentLengthError
+    || error instanceof InvalidRequestBodyError
+    || error instanceof RequestBodyTooLargeError
+  ) {
     return errorResponse(error.status, error.code, error.message, "details" in error ? error.details : undefined);
   }
   return undefined;
@@ -75,16 +111,114 @@ function validateJson<TSchema extends z.ZodTypeAny>(value: unknown, schema: TSch
   return result.data;
 }
 
-export async function parseUnknownJson(req: Request): Promise<unknown> {
+export interface ParseJsonOptions {
+  maxBytes?: number;
+  requireContentType?: boolean;
+}
+
+function validateParseJsonOptions(options: ParseJsonOptions): void {
+  if (options.maxBytes !== undefined && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
+    throw new RangeError("parseJson maxBytes must be a non-negative safe integer");
+  }
+}
+
+function hasJsonContentType(req: Request): boolean {
+  const contentType = req.headers.get("content-type");
+  if (!contentType) {
+    return false;
+  }
+  const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase();
+  return mediaType === "application/json" || mediaType?.endsWith("+json") === true;
+}
+
+function declaredContentLength(req: Request, maxBytes: number | undefined): void {
+  const value = req.headers.get("content-length");
+  if (value === null) {
+    return;
+  }
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new InvalidRequestContentLengthError();
+  }
+  const length = BigInt(normalized);
+  if (maxBytes !== undefined && length > BigInt(maxBytes)) {
+    throw new RequestBodyTooLargeError();
+  }
+}
+
+async function cancelOversizedBody(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+  await reader.cancel("Request body is too large");
+}
+
+async function readLimitedRequestBody(req: Request, maxBytes: number): Promise<string> {
+  declaredContentLength(req, maxBytes);
+  if (!req.body) {
+    return "";
+  }
+
+  const reader = req.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let byteLength = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (!value) {
+      continue;
+    }
+    byteLength += value.byteLength;
+    if (byteLength > maxBytes) {
+      await cancelOversizedBody(reader);
+      throw new RequestBodyTooLargeError();
+    }
+    chunks.push(value);
+  }
+
+  const body = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
   try {
-    return await req.json();
+    return new TextDecoder("utf-8", { fatal: true }).decode(body);
   } catch {
     throw new InvalidJsonError();
   }
 }
 
-export async function parseJson<TSchema extends z.ZodTypeAny>(req: Request, schema: TSchema): Promise<z.infer<TSchema>> {
-  return validateJson(await parseUnknownJson(req), schema);
+async function readRequestBody(req: Request, maxBytes: number | undefined): Promise<string> {
+  if (maxBytes === undefined) {
+    declaredContentLength(req, undefined);
+    return await req.text();
+  }
+  return await readLimitedRequestBody(req, maxBytes);
+}
+
+function parseJsonText(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new InvalidJsonError();
+  }
+}
+
+export async function parseUnknownJson(req: Request, options: ParseJsonOptions = {}): Promise<unknown> {
+  validateParseJsonOptions(options);
+  if (options.requireContentType && !hasJsonContentType(req)) {
+    throw new InvalidRequestContentTypeError();
+  }
+  return parseJsonText(await readRequestBody(req, options.maxBytes));
+}
+
+export async function parseJson<TSchema extends z.ZodTypeAny>(
+  req: Request,
+  schema: TSchema,
+  options: ParseJsonOptions = {},
+): Promise<z.infer<TSchema>> {
+  return validateJson(await parseUnknownJson(req, options), schema);
 }
 
 export async function parseOptionalJson<TSchema extends z.ZodTypeAny>(req: Request, schema: TSchema): Promise<z.infer<TSchema> | undefined> {

package/src/server/server-types.ts

@@ -26,6 +26,7 @@ export type PublicRouteDefinition =
 export interface WebAppServerConfig<TEvent = unknown> {
   appName: string;
   envPrefix: string;
+  runtimeConfig?: RuntimeConfig;
   web?: WebAppDocumentConfig;
   version?: string;
   store?: WebAppStore;