@alxia/core 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,3 +1,78 @@
+// src/errors/errors.ts
+class HttpError extends Error {
+  name = "HttpError";
+  status;
+  body;
+  constructor(status, body, message) {
+    super(message ?? `HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class ContentTooLargeError extends HttpError {
+  name = "ContentTooLargeError";
+  limit;
+  constructor(limit) {
+    super(413, { error: "content_too_large", limit }, `The request body is larger than the route's limit of ${limit} bytes`);
+    this.limit = limit;
+  }
+}
+
+class ResponseValidationError extends Error {
+  name = "ResponseValidationError";
+  status;
+  issues;
+  constructor(method, path, status, issues, message) {
+    super(message ?? `${method} ${path}: the ${status} reply does not match its schema: ${issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
+    this.status = status;
+    this.issues = issues;
+  }
+  static undeclared(method, path, status) {
+    return new ResponseValidationError(method, path, status, [
+      {
+        target: "body",
+        path: [],
+        code: "undeclared_status",
+        message: `the route declares no ${status} reply`
+      }
+    ], `${method} ${path} declares no ${status} reply`);
+  }
+}
+
+// src/request/limit.ts
+function limitBody(request, limit) {
+  const source = request.body;
+  if (source === null || request.bodyUsed || source.locked)
+    return request;
+  const declared = Number(request.headers.get("content-length") ?? Number.NaN);
+  let body;
+  if (declared > limit) {
+    source.cancel().catch(() => {});
+    body = new ReadableStream({
+      start: (controller) => controller.error(new ContentTooLargeError(limit))
+    });
+  } else {
+    let count = 0;
+    body = source.pipeThrough(new TransformStream({
+      transform(chunk, controller) {
+        count += chunk.byteLength;
+        if (count > limit) {
+          controller.error(new ContentTooLargeError(limit));
+        } else
+          controller.enqueue(chunk);
+      }
+    }));
+  }
+  return new Request(request, { body, duplex: "half" });
+}
+function checkLimit(limit, where) {
+  if (!Number.isSafeInteger(limit) || limit < 0) {
+    throw new TypeError(`${where}: bodyLimit must be a whole number of bytes, 0 or more; got ${limit}`);
+  }
+  return limit;
+}
+
 // src/router/compile.ts
 var LITERAL = 0;
 var PARAMETER = 1;
@@ -233,6 +308,11 @@ class Router {
 // src/static/serve.ts
 import { extname as extname2, resolve, sep } from "node:path";
 
+// src/sse/async-iterable.ts
+function isAsyncIterable(value) {
+  return value !== null && typeof value === "object" && Symbol.asyncIterator in value && !(value instanceof ReadableStream);
+}
+
 // src/schema/standard-schema.ts
 async function check(schema, value, target) {
   let result = schema["~standard"].validate(value);
@@ -254,8 +334,143 @@ async function check(schema, value, target) {
   };
 }
 
+// src/sse/frame.ts
+class Frame {
+  event;
+  data;
+  id;
+  retry;
+  constructor(event, data, id, retry) {
+    this.event = event;
+    this.data = data;
+    this.id = id;
+    this.retry = retry;
+  }
+}
+function frameText(value) {
+  const lines = [];
+  let data = value;
+  if (value instanceof Frame) {
+    lines.push(`event: ${value.event}`);
+    if (value.id !== undefined)
+      lines.push(`id: ${value.id}`);
+    if (value.retry !== undefined)
+      lines.push(`retry: ${value.retry}`);
+    data = value.data;
+  }
+  const json = JSON.stringify(data) ?? "null";
+  for (const line of json.split(/\r\n|\r|\n/))
+    lines.push(`data: ${line}`);
+  return `${lines.join(`
+`)}
+
+`;
+}
+function mismatch(issues, name) {
+  return new TypeError(`An event does not match its schema: ${issues.map((issue) => {
+    const path = name === undefined ? issue.path : [name, ...issue.path];
+    return `${path.join(".") || "(root)"}: ${issue.message}`;
+  }).join("; ")}`);
+}
+var BREAK = /[\r\n\0]/;
+function refuseName(name) {
+  if (name === "")
+    return "An event name must not be empty";
+  if (BREAK.test(name)) {
+    return `An event name must not hold a line break or a NUL: ${JSON.stringify(name)}`;
+  }
+  return;
+}
+function refuseId(id) {
+  if (id === undefined)
+    return;
+  if (typeof id !== "string")
+    return "An event id must be a string";
+  if (BREAK.test(id)) {
+    return `An event id must not hold a line break or a NUL: ${JSON.stringify(id)}`;
+  }
+  return;
+}
+function refuseRetry(retry) {
+  if (retry === undefined)
+    return;
+  if (typeof retry !== "number" || !Number.isSafeInteger(retry) || retry < 0) {
+    return `An event retry must be a whole number of milliseconds, 0 or more: ${String(retry)}`;
+  }
+  return;
+}
+
+// src/sse/named-events.ts
+function namedEventStream(events) {
+  const names = Object.keys(events);
+  if (names.length === 0) {
+    throw new TypeError("A named event stream declares at least one event");
+  }
+  for (const name of names) {
+    const refused = refuseName(name);
+    if (refused !== undefined)
+      throw new TypeError(refused);
+    const schema = events[name];
+    if (schema === null || typeof schema !== "object" || !("~standard" in schema)) {
+      throw new TypeError(`The event ${JSON.stringify(name)} is not a Standard Schema`);
+    }
+  }
+  return {
+    "~events": events,
+    event: (event, data, fields) => ({
+      ...fields,
+      event,
+      data
+    }),
+    "~standard": {
+      version: 1,
+      vendor: "alxia",
+      validate: (value) => {
+        if (!isAsyncIterable(value)) {
+          return {
+            issues: [
+              { message: "An event stream replies with an async iterable" }
+            ]
+          };
+        }
+        return { value: toFrames(events, value, true) };
+      }
+    }
+  };
+}
+function isNamedEventStreamSchema(schema) {
+  return "~events" in schema;
+}
+async function* toFrames(events, values, validate) {
+  for await (const value of values) {
+    if (value === null || typeof value !== "object" || !("event" in value)) {
+      throw new TypeError("An event of a named stream is an object { event, data }");
+    }
+    const { event, data, id, retry } = value;
+    const schema = typeof event === "string" && Object.hasOwn(events, event) ? events[event] : undefined;
+    if (schema === undefined) {
+      throw new TypeError(`The event ${JSON.stringify(event)} is not declared: ${Object.keys(events).join(", ")}`);
+    }
+    const refused = refuseId(id) ?? refuseRetry(retry);
+    if (refused !== undefined)
+      throw new TypeError(refused);
+    let output = data;
+    if (validate) {
+      const checked = await check(schema, data, "body");
+      if (!checked.ok) {
+        throw mismatch(checked.issues, event);
+      }
+      output = checked.value;
+    }
+    yield new Frame(event, output, id, retry);
+  }
+}
+
 // src/sse/event-stream.ts
-function eventStream(item) {
+function eventStream(schema) {
+  if (!isStandardSchema(schema))
+    return namedEventStream(schema);
+  const item = schema;
   return {
     "~eventStream": item,
     "~standard": {
@@ -277,14 +492,14 @@ function eventStream(item) {
 async function* checkEach(item, values) {
   for await (const value of values) {
     const checked = await check(item, value, "body");
-    if (!checked.ok) {
-      throw new TypeError(`An event does not match its schema: ${checked.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
-    }
+    if (!checked.ok)
+      throw mismatch(checked.issues);
     yield checked.value;
   }
 }
-function isAsyncIterable(value) {
-  return value !== null && typeof value === "object" && Symbol.asyncIterator in value && !(value instanceof ReadableStream);
+function isStandardSchema(value) {
+  const standard = value["~standard"];
+  return standard?.version === 1 && typeof standard.vendor === "string";
 }
 function isEventStreamSchema(schema) {
   return "~eventStream" in schema;
@@ -327,12 +542,7 @@ function toEventStream(values, signal) {
           controller.close();
           return;
         }
-        const data = JSON.stringify(next.value) ?? "null";
-        controller.enqueue(encoder.encode(`${data.split(`
-`).map((line) => `data: ${line}`).join(`
-`)}
-
-`));
+        controller.enqueue(encoder.encode(frameText(next.value)));
       } catch (error) {
         stop();
         console.error(error);
@@ -661,39 +871,6 @@ function isBunFile(blob) {
   return typeof blob.exists === "function";
 }
 
-// src/errors/errors.ts
-class HttpError extends Error {
-  name = "HttpError";
-  status;
-  body;
-  constructor(status, body, message) {
-    super(message ?? `HTTP ${status}`);
-    this.status = status;
-    this.body = body;
-  }
-}
-
-class ResponseValidationError extends Error {
-  name = "ResponseValidationError";
-  status;
-  issues;
-  constructor(method, path, status, issues, message) {
-    super(message ?? `${method} ${path}: the ${status} reply does not match its schema: ${issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
-    this.status = status;
-    this.issues = issues;
-  }
-  static undeclared(method, path, status) {
-    return new ResponseValidationError(method, path, status, [
-      {
-        target: "body",
-        path: [],
-        code: "undeclared_status",
-        message: `the route declares no ${status} reply`
-      }
-    ], `${method} ${path} declares no ${status} reply`);
-  }
-}
-
 // src/request/read.ts
 function readQuery(url) {
   const query = {};
@@ -730,6 +907,8 @@ async function readBody(request, parsers = []) {
     try {
       return { ok: true, value: await custom.parse(request) };
     } catch (error) {
+      if (error instanceof ContentTooLargeError)
+        throw error;
       return {
         ok: false,
         issue: {
@@ -780,6 +959,33 @@ async function readBody(request, parsers = []) {
   return { ok: true, value: await request.arrayBuffer() };
 }
 
+// src/app/context.ts
+var redirect = (location, status) => new Reply(status ?? 302, undefined, {
+  headers: { location: String(location) }
+});
+function routeContext(definition, request, pathParams) {
+  let cookies;
+  const set = {
+    headers: new Headers,
+    get cookies() {
+      cookies ??= new Bun.CookieMap;
+      return cookies;
+    },
+    touched: () => cookies !== undefined
+  };
+  const limit = "bodyLimit" in definition ? definition.bodyLimit : undefined;
+  const ctx = {
+    ...request,
+    ...limit === undefined ? {} : { request: limitBody(request.request, limit) },
+    route: definition.path,
+    pathParams,
+    set,
+    reply: createReply,
+    redirect
+  };
+  return { ctx, set };
+}
+
 // src/app/send.ts
 var internal = { error: "internal" };
 function internalError() {
@@ -810,17 +1016,23 @@ async function sendDeclared(route, reply, set, signal, validateResponses) {
   if (responses === undefined || isRedirect(reply)) {
     return send2(reply, set, signal);
   }
+  const checked = await checkReply(route.method, route.path, responses, reply, validateResponses);
+  return send2(checked, set, signal);
+}
+async function checkReply(method, path, responses, reply, validateResponses) {
   const schema = responses[reply.status];
   if (schema === undefined) {
-    throw ResponseValidationError.undeclared(route.method, route.path, reply.status);
+    throw ResponseValidationError.undeclared(method, path, reply.status);
   }
   if (!validateResponses)
-    return send2(reply, set, signal);
+    return framed(schema, reply);
   const checked = await check(schema, reply.body, "body");
   if (!checked.ok) {
-    throw new ResponseValidationError(route.method, route.path, reply.status, checked.issues);
+    throw new ResponseValidationError(method, path, reply.status, checked.issues);
   }
-  return send2(new Reply(reply.status, checked.value, { headers: reply.headers ?? {} }), set, signal);
+  return new Reply(reply.status, checked.value, {
+    headers: reply.headers ?? {}
+  });
 }
 function routingError(status, error, allowed) {
   const headers = new Headers;
@@ -829,42 +1041,73 @@ function routingError(status, error, allowed) {
   const body = { error };
   return toResponse(status, body, headers);
 }
+function framed(schema, reply) {
+  if (!isNamedEventStreamSchema(schema) || !isAsyncIterable(reply.body)) {
+    return reply;
+  }
+  return new Reply(reply.status, toFrames(schema["~events"], reply.body, false), { headers: reply.headers ?? {} });
+}
 function isRedirect(reply) {
   return reply.status >= 300 && reply.status < 400 && reply.body === undefined;
 }
 
-// src/app/chain.ts
-var redirect = (location, status) => new Reply(status ?? 302, undefined, {
-  headers: { location: String(location) }
-});
-function routeContext(definition, request, pathParams) {
-  let cookies;
-  const set = {
-    headers: new Headers,
-    get cookies() {
-      cookies ??= new Bun.CookieMap;
-      return cookies;
-    },
-    touched: () => cookies !== undefined
-  };
-  const ctx = {
-    ...request,
-    route: definition.path,
-    pathParams,
-    set,
-    reply: createReply,
-    redirect
-  };
-  return { ctx, set };
+// src/app/refusal.ts
+async function refuse(definition, refusal, set, ctx, validateResponses) {
+  const handler = definition.refusal;
+  if (handler !== undefined) {
+    let reply = handler.hook(refusal, ctx);
+    if (reply instanceof Promise)
+      reply = await reply;
+    const method = "method" in definition ? definition.method : "WS";
+    if (reply instanceof Reply) {
+      if (handler.response !== undefined) {
+        reply = await checkReply(method, definition.path, handler.response, reply, validateResponses);
+      }
+      return send2(withContentType2(reply, handler.contentType), set);
+    }
+    if (reply !== undefined) {
+      throw new TypeError(`${method} ${definition.path}: the onRefusal hook returned neither a reply nor nothing.`);
+    }
+  }
+  return send2(byDefault(refusal), set);
+}
+function byDefault(refusal) {
+  switch (refusal.kind) {
+    case "validation": {
+      const body = {
+        error: "validation",
+        issues: refusal.issues
+      };
+      return new Reply(400, body);
+    }
+    case "body_limit": {
+      const body = {
+        error: "content_too_large",
+        limit: refusal.limit
+      };
+      return new Reply(413, body);
+    }
+  }
+}
+function withContentType2(reply, type) {
+  if (type === undefined)
+    return reply;
+  const headers = new Headers(reply.headers);
+  if (headers.has("content-type"))
+    return reply;
+  headers.set("content-type", type);
+  return new Reply(reply.status, reply.body, { headers });
 }
-async function chain(definition, request, rawParams, set, ctx, parsers, last) {
+
+// src/app/chain.ts
+async function chain(definition, request, rawParams, set, ctx, parsers, validateResponses, last) {
   const hooks = definition.derive;
   const socket = !("method" in definition);
   const signal = request.request.signal;
   const step = async (index) => {
     const hook = hooks[index];
     if (hook === undefined) {
-      const refused = await validate(definition, request, rawParams, set, ctx, parsers);
+      const refused = await validate(definition, request, rawParams, set, ctx, parsers, validateResponses);
       return refused ?? last();
     }
     if (hook.kind === "wrap") {
@@ -887,9 +1130,10 @@ async function chain(definition, request, rawParams, set, ctx, parsers, last) {
   };
   return step(0);
 }
-async function validate(definition, request, rawParams, set, ctx, parsers) {
+async function validate(definition, request, rawParams, set, ctx, parsers, validateResponses) {
   const { schema } = definition;
   const issues = [];
+  let part;
   const parts = [
     ["params", schema.params, () => rawParams],
     ["query", schema.query, () => readQuery(request.url)],
@@ -905,33 +1149,36 @@ async function validate(definition, request, rawParams, set, ctx, parsers) {
     const checked = await check(partSchema, raw, target);
     if (checked.ok)
       ctx[target] = checked.value;
-    else
+    else {
+      part ??= target;
       issues.push(...checked.issues);
+    }
   }
   ctx["body"] = undefined;
   const bodySchema = "body" in schema ? schema.body : undefined;
   if (bodySchema !== undefined) {
-    const body = await readBody(request.request, parsers);
-    if (!body.ok)
+    const body = await readBody(ctx.request, parsers);
+    if (!body.ok) {
+      part ??= "body";
       issues.push(body.issue);
-    else {
+    } else {
       const checked = await check(bodySchema, body.value, "body");
       if (checked.ok)
         ctx["body"] = checked.value;
-      else
+      else {
+        part ??= "body";
         issues.push(...checked.issues);
+      }
     }
   }
-  if (issues.length > 0) {
-    const body = { error: "validation", issues };
-    return send2(new Reply(400, body), set);
-  }
-  return;
+  if (part === undefined)
+    return;
+  return refuse(definition, { kind: "validation", part, issues }, set, ctx, validateResponses);
 }
 async function handle(route, request, rawParams, parsers, validateResponses) {
   const { ctx, set } = routeContext(route, request, rawParams);
   try {
-    return await chain(route, request, rawParams, set, ctx, parsers, async () => {
+    return await chain(route, request, rawParams, set, ctx, parsers, validateResponses, async () => {
       let reply = route.handler(ctx);
       if (reply instanceof Promise)
         reply = await reply;
@@ -942,10 +1189,18 @@ async function handle(route, request, rawParams, parsers, validateResponses) {
     });
   } catch (error) {
     request.error = error;
-    return fail(route, error, ctx);
+    return fail(route, error, ctx, validateResponses);
   }
 }
-async function fail(definition, error, ctx) {
+async function fail(definition, error, ctx, validateResponses = true) {
+  if (error instanceof ContentTooLargeError) {
+    try {
+      return await refuse(definition, { kind: "body_limit", limit: error.limit }, ctx.set, ctx, validateResponses);
+    } catch (thrown) {
+      console.error(thrown);
+      return internalError();
+    }
+  }
   for (const hook of definition.onError) {
     let handled = hook(error, ctx);
     if (handled instanceof Promise)
@@ -962,11 +1217,11 @@ async function fail(definition, error, ctx) {
 
 // src/app/socket.ts
 var UPGRADED = Symbol("upgraded");
-async function upgradeSocket(definition, request, rawParams, parsers) {
+async function upgradeSocket(definition, request, rawParams, parsers, validateResponses) {
   const { ctx, set } = routeContext(definition, request, rawParams);
   const server = request.server;
   try {
-    return await chain(definition, request, rawParams, set, ctx, parsers, async () => {
+    return await chain(definition, request, rawParams, set, ctx, parsers, validateResponses, async () => {
       if (server === undefined) {
         return routingError(426, "upgrade_required");
       }
@@ -1158,7 +1413,7 @@ async function route(runtime, ctx, path) {
     const socket = find("WS");
     if (socket !== undefined && "value" in socket && socket.value.kind === "ws") {
       ctx.route = socket.value.path;
-      return upgradeSocket(socket.value, ctx, socket.params, globals.parsers);
+      return upgradeSocket(socket.value, ctx, socket.params, globals.parsers, runtime.validateResponses);
     }
   }
   let match = find(request.method);
@@ -1197,6 +1452,8 @@ class Alxia {
   #sockets = [];
   #derive = [];
   #onError = [];
+  #refusal;
+  #bodyLimit;
   #server;
   #websocket;
   constructor(options = {}) {
@@ -1253,7 +1510,8 @@ class Alxia {
       schema,
       handlers,
       derive: [...this.#derive],
-      onError: [...this.#onError]
+      onError: [...this.#onError],
+      refusal: this.#refusal
     };
     this.#mount(definition);
     return this;
@@ -1270,10 +1528,29 @@ class Alxia {
     this.#derive.push({ kind: "wrap", run: hook });
     return this;
   }
+  bodyLimit(bytes) {
+    this.#bodyLimit = checkLimit(bytes, "bodyLimit()");
+    return this;
+  }
   onError(hook) {
     this.#onError.push(hook);
     return this;
   }
+  onRefusal(schemaOrHook, maybeHook) {
+    if (typeof schemaOrHook === "function") {
+      this.#refusal = { hook: schemaOrHook };
+      return this;
+    }
+    if (typeof maybeHook !== "function") {
+      throw new TypeError("onRefusal(): the hook is missing");
+    }
+    this.#refusal = {
+      hook: maybeHook,
+      response: schemaOrHook.response,
+      ...schemaOrHook.contentType === undefined ? {} : { contentType: schemaOrHook.contentType }
+    };
+    return this;
+  }
   onRequest(hook) {
     this.#runtime.globals.onRequest.push(hook);
     return this;
@@ -1308,6 +1585,8 @@ class Alxia {
     });
     child.#derive = [...this.#derive];
     child.#onError = [...this.#onError];
+    child.#refusal = this.#refusal;
+    child.#bodyLimit = this.#bodyLimit;
     child.#runtime = { ...child.#runtime, globals: this.#runtime.globals };
     const before = new Set(this.#runtime.globals.pages.keys());
     const built = build(child);
@@ -1330,7 +1609,8 @@ class Alxia {
         ...route,
         path: joinPath(this.#prefix, route.path),
         derive: [...this.#derive, ...route.derive],
-        onError: [...route.onError, ...this.#onError]
+        onError: [...route.onError, ...this.#onError],
+        refusal: route.refusal ?? this.#refusal
       });
     }
     for (const socket of plugin.sockets) {
@@ -1338,11 +1618,14 @@ class Alxia {
         ...socket,
         path: joinPath(this.#prefix, socket.path),
         derive: [...this.#derive, ...socket.derive],
-        onError: [...socket.onError, ...this.#onError]
+        onError: [...socket.onError, ...this.#onError],
+        refusal: socket.refusal ?? this.#refusal
       });
     }
     this.#derive = [...this.#derive, ...plugin.#derive];
     this.#onError = [...plugin.#onError, ...this.#onError];
+    this.#refusal = plugin.#refusal ?? this.#refusal;
+    this.#bodyLimit = plugin.#bodyLimit ?? this.#bodyLimit;
     if (plugin.#runtime.globals !== this.#runtime.globals) {
       const globals = plugin.#runtime.globals;
       this.#runtime.globals.around.push(...globals.around);
@@ -1410,13 +1693,17 @@ class Alxia {
       if (typeof handler !== "function") {
         throw new TypeError(`${method} ${path}: the handler is missing`);
       }
+      const full = joinPath(this.#prefix, path);
+      const bodyLimit = schema.bodyLimit === undefined ? this.#bodyLimit : checkLimit(schema.bodyLimit, `${method} ${full}`);
       this.#register({
         method,
-        path: joinPath(this.#prefix, path),
+        path: full,
         schema,
+        ...bodyLimit === undefined ? {} : { bodyLimit },
         handler,
         derive: [...this.#derive],
-        onError: [...this.#onError]
+        onError: [...this.#onError],
+        refusal: this.#refusal
       });
       return this;
     };
@@ -1455,8 +1742,17 @@ function alxia(options = {}) {
 function definePlugin() {
   return (build) => build(alxia());
 }
+// src/reply/problem.ts
+function problem(body, init) {
+  const headers = new Headers(init?.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/problem+json");
+  }
+  return new Reply(body.status, body, { ...init, headers });
+}
 export {
   Alxia,
+  ContentTooLargeError,
   HttpError,
   Reply,
   ResponseValidationError,
@@ -1466,12 +1762,14 @@ export {
   definePlugin,
   eventStream,
   isEventStreamSchema,
+  isNamedEventStreamSchema,
   joinPath,
   parseRange,
+  problem,
   shapeOf,
   vary,
   withHeaders
 };
 
-//# debugId=F86708E1572B31A764756E2164756E21
+//# debugId=62C2FCF982C60F6964756E2164756E21
 //# sourceMappingURL=index.js.map