@fluixi/api 0.0.0-stage → 0.1.0-alpha.3

package/dist/route.cjs

@@ -0,0 +1,192 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/route.ts
+var route_exports = {};
+__export(route_exports, {
+  CONTRACT: () => CONTRACT,
+  REVALIDATE_HEADER: () => REVALIDATE_HEADER,
+  contractOf: () => contractOf,
+  route: () => route,
+  setErrorReporter: () => setErrorReporter
+});
+module.exports = __toCommonJS(route_exports);
+
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var unauthorized = (message = "Sign in to continue.") => new ApiError(401, "unauthorized", message);
+var forbidden = (message = "Not allowed.") => new ApiError(403, "forbidden", message);
+function toApiError(error) {
+  if (error instanceof ApiError) return { error, internal: false };
+  const { status, code, message } = error ?? {};
+  if (status === 401 || status === 403) {
+    if (typeof code === "string" && typeof message === "string") return { error: new ApiError(status, code, message), internal: false };
+    return { error: status === 401 ? unauthorized() : forbidden(), internal: false };
+  }
+  return { error: new ApiError(500, "internal", "Something went wrong on our side."), internal: true };
+}
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+function readQuery(url) {
+  const out = {};
+  for (const [key, value] of url.searchParams) {
+    const seen = out[key];
+    if (seen === void 0) out[key] = value;
+    else out[key] = Array.isArray(seen) ? [...seen, value] : [seen, value];
+  }
+  return out;
+}
+async function readJson(request, limit = DEFAULT_BODY_LIMIT) {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) throw tooLarge(limit);
+  if (!request.body) return void 0;
+  const type = request.headers.get("content-type") ?? "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      throw tooLarge(limit);
+    }
+    chunks.push(value);
+  }
+  if (size === 0) return void 0;
+  if (!isJson(type)) {
+    throw new ApiError(415, "unsupported_media_type", "Send the body as application/json.");
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new ApiError(400, "invalid_json", "The body is not valid JSON.");
+  }
+}
+function isJson(type) {
+  const mime = type.split(";")[0].trim().toLowerCase();
+  return mime === "application/json" || mime.endsWith("+json");
+}
+function tooLarge(limit) {
+  return new ApiError(413, "payload_too_large", `The body is larger than ${limit} bytes.`);
+}
+
+// src/route.ts
+var CONTRACT = /* @__PURE__ */ Symbol.for("fluixi.api.contract");
+var report = (error, request) => {
+  console.error(`[fluixi/api] ${request.method} ${new URL(request.url).pathname}`, error);
+};
+function setErrorReporter(reporter) {
+  report = reporter;
+}
+function route(contract) {
+  const handle = async (request, context = {}) => {
+    try {
+      const auth = contract.guard ? await contract.guard.check(request) : void 0;
+      const issues = [];
+      const params = await check(contract.params, context.params ?? {}, "params", issues);
+      const query = await check(contract.query, readQuery(new URL(request.url)), "query", issues);
+      const body = contract.body ? await check(contract.body, await readJson(request, contract.bodyLimit), "body", issues) : void 0;
+      if (issues.length) throw new ApiError(400, "validation_failed", "The request is not valid.", issues);
+      const input = { params, query, body, auth, request };
+      const out = await contract.handler(input);
+      const stale = !contract.revalidates ? [] : typeof contract.revalidates === "function" ? contract.revalidates(out, input) : contract.revalidates;
+      if (out instanceof Response) return withRevalidate(out, stale);
+      if (out === void 0 && !contract.response) return withRevalidate(new Response(null, { status: contract.status ?? 204 }), stale);
+      let value = out;
+      if (contract.response && contract.validateResponse !== false) {
+        const result = await contract.response["~standard"].validate(out);
+        if (result.issues) {
+          throw Object.assign(new Error("Response does not match the route contract."), {
+            issues: result.issues.map((issue) => toIssue(issue, "response"))
+          });
+        }
+        value = result.value;
+      }
+      return withRevalidate(
+        new Response(JSON.stringify(value ?? null), {
+          status: contract.status ?? 200,
+          headers: { "content-type": "application/json; charset=utf-8" }
+        }),
+        stale
+      );
+    } catch (thrown) {
+      const { error, internal } = toApiError(thrown);
+      if (internal) report(thrown, request);
+      return errorResponse(error);
+    }
+  };
+  Object.defineProperty(handle, CONTRACT, { value: contract });
+  return handle;
+}
+var REVALIDATE_HEADER = "x-fx-revalidate";
+function withRevalidate(response, names) {
+  if (!names.length || !response.ok) return response;
+  const value = names.join(", ");
+  try {
+    response.headers.append(REVALIDATE_HEADER, value);
+    return response;
+  } catch {
+    const headers = new Headers(response.headers);
+    headers.append(REVALIDATE_HEADER, value);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+  }
+}
+function contractOf(handler) {
+  return typeof handler === "function" ? handler[CONTRACT] : void 0;
+}
+async function check(schema, value, where, issues) {
+  if (!schema) return value;
+  const result = await schema["~standard"].validate(value);
+  if (result.issues) {
+    for (const issue of result.issues) issues.push(toIssue(issue, where));
+    return void 0;
+  }
+  return result.value;
+}
+function toIssue(issue, where) {
+  const path = (issue.path ?? []).map(
+    (segment) => String(typeof segment === "object" && segment !== null ? segment.key : segment)
+  );
+  return { path: [where, ...path].join("."), message: issue.message };
+}

package/dist/route.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A route with a contract: what it accepts and what it returns, as Standard Schema.
+ *
+ * `route()` returns an ordinary `@fluixi/start` API handler, `(request, { params })` to a
+ * `Response`, so a file under `src/api` exports it and start routes to it unchanged. Before
+ * the handler runs, params, query and body are validated and every problem is reported at
+ * once; the handler receives the validated values, typed. What it returns goes through the
+ * response schema too, so unknown fields are dropped before anything leaves the server.
+ */
+import type { StandardSchemaV1 as Schema } from './standard-schema.js';
+type AnySchema = Schema | undefined;
+type AnyGuard = Guard<any> | undefined;
+type GuardOutput<G extends AnyGuard> = G extends Guard<infer A> ? A : undefined;
+/**
+ * Decides who may call a route. It runs before anything is read from the request, so a caller
+ * who may not call it learns nothing about what it accepts. What `check` returns reaches the
+ * handler as `auth`; a refusal is thrown, with a 401 or 403 `status`.
+ *
+ * Auth packages provide them (`signedIn()`, `member()` in `@fluixi/auth/server`), matched by
+ * shape, so this package depends on none of them.
+ */
+export interface Guard<A = unknown> {
+    check(request: Request): A | Promise<A>;
+    /** For the API description: the security scheme a caller satisfies, under a stable name. */
+    security?: {
+        name: string;
+        scheme: Record<string, unknown>;
+        scopes?: string[];
+    };
+    /**
+     * The refusals it answers with, for the API description. `[401]` when not given. 503 for a
+     * guard that asks another service (a token's issuer, say) and refuses while it cannot.
+     */
+    refuses?: readonly (401 | 403 | 503)[];
+}
+type Output<S extends AnySchema, Fallback> = S extends Schema ? Schema.InferOutput<S> : Fallback;
+type Input<S extends AnySchema, Fallback> = S extends Schema ? Schema.InferInput<S> : Fallback;
+/** What a handler receives: the validated input, and the request for anything else. */
+export interface RouteInput<P extends AnySchema, Q extends AnySchema, B extends AnySchema, G extends AnyGuard = undefined> {
+    params: Output<P, Record<string, string>>;
+    query: Output<Q, Record<string, string | string[]>>;
+    body: Output<B, undefined>;
+    /** What the guard resolved: the user, their membership. `undefined` without a guard. */
+    auth: GuardOutput<G>;
+    request: Request;
+}
+export interface RouteContract<P extends AnySchema = undefined, Q extends AnySchema = undefined, B extends AnySchema = undefined, R extends AnySchema = undefined, G extends AnyGuard = undefined> {
+    /** Who may call it. Without one, anyone. */
+    guard?: G;
+    /** Path parameters, from the file name: `[id].ts` gives `{ id }`. */
+    params?: P;
+    /** The query string, with repeated keys as arrays. */
+    query?: Q;
+    /** The JSON body. Without a schema the body is not read, and the handler may read it itself. */
+    body?: B;
+    /** What the handler returns. Applied on the way out: unknown fields are dropped, transforms run. */
+    response?: R;
+    /** Status of a successful response. 200, or 204 when the handler returns nothing. */
+    status?: number;
+    /** Largest body accepted, in bytes. 1 MiB by default. */
+    bodyLimit?: number;
+    /** Apply `response` to what the handler returns. On by default; off only for a measured reason. */
+    validateResponse?: boolean;
+    /** For the API description: a one-line summary, a longer description, grouping tags. */
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** A stable name for the operation in the API description. Derived from method and path otherwise. */
+    operationId?: string;
+    /** Marked deprecated in the API description. */
+    deprecated?: boolean;
+    /**
+     * Cached data a success changes, by name (`['orgs']`), or a function of the result and the
+     * input. Sent as `x-fx-revalidate`; `@fluixi/api/client` passes the names to the router, which
+     * drops those entries and reloads the routes on screen.
+     */
+    revalidates?: string[] | ((result: unknown, input: RouteInput<P, Q, B, G>) => string[]);
+    handler(input: RouteInput<P, Q, B, G>): Input<R, unknown> | Response | Promise<Input<R, unknown> | Response>;
+}
+/** Where a route's contract is kept on its handler, for the API description and the client. */
+export declare const CONTRACT: unique symbol;
+/** A contracted route, as `@fluixi/start` calls it. */
+export interface RouteHandler<P extends AnySchema = AnySchema, Q extends AnySchema = AnySchema, B extends AnySchema = AnySchema, R extends AnySchema = AnySchema, G extends AnyGuard = AnyGuard> {
+    (request: Request, context?: {
+        params?: Record<string, string>;
+    }): Promise<Response>;
+    readonly [CONTRACT]: RouteContract<P, Q, B, R, G>;
+}
+/** Send unexpected route errors somewhere else, a logger or an error tracker. */
+export declare function setErrorReporter(reporter: (error: unknown, request: Request) => void): void;
+export declare function route<P extends AnySchema = undefined, Q extends AnySchema = undefined, B extends AnySchema = undefined, R extends AnySchema = undefined, G extends AnyGuard = undefined>(contract: RouteContract<P, Q, B, R, G>): RouteHandler<P, Q, B, R, G>;
+/** The header that names cached data a response made stale. */
+export declare const REVALIDATE_HEADER = "x-fx-revalidate";
+/** The contract a route was declared with, or undefined for a plain handler. */
+export declare function contractOf(handler: unknown): RouteContract<AnySchema, AnySchema, AnySchema, AnySchema, AnyGuard> | undefined;
+export {};
+//# sourceMappingURL=route.d.ts.map

package/dist/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"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"}

package/dist/route.js

@@ -0,0 +1,98 @@
+import { ApiError, errorResponse, toApiError } from './errors.js';
+import { readJson, readQuery } from './input.js';
+/** Where a route's contract is kept on its handler, for the API description and the client. */
+export const CONTRACT = Symbol.for('fluixi.api.contract');
+/** Where a failure no one meant to report goes: logged, never sent. `console.error` by default. */
+let report = (error, request) => {
+    console.error(`[fluixi/api] ${request.method} ${new URL(request.url).pathname}`, error);
+};
+/** Send unexpected route errors somewhere else, a logger or an error tracker. */
+export function setErrorReporter(reporter) {
+    report = reporter;
+}
+export function route(contract) {
+    const handle = async (request, context = {}) => {
+        try {
+            const auth = contract.guard ? await contract.guard.check(request) : undefined;
+            const issues = [];
+            const params = await check(contract.params, context.params ?? {}, 'params', issues);
+            const query = await check(contract.query, readQuery(new URL(request.url)), 'query', issues);
+            const body = contract.body
+                ? await check(contract.body, await readJson(request, contract.bodyLimit), 'body', issues)
+                : undefined;
+            if (issues.length)
+                throw new ApiError(400, 'validation_failed', 'The request is not valid.', issues);
+            const input = { params, query, body, auth, request };
+            const out = await contract.handler(input);
+            const stale = !contract.revalidates
+                ? []
+                : typeof contract.revalidates === 'function'
+                    ? contract.revalidates(out, input)
+                    : contract.revalidates;
+            if (out instanceof Response)
+                return withRevalidate(out, stale);
+            if (out === undefined && !contract.response)
+                return withRevalidate(new Response(null, { status: contract.status ?? 204 }), stale);
+            let value = out;
+            if (contract.response && contract.validateResponse !== false) {
+                const result = await contract.response['~standard'].validate(out);
+                if (result.issues) {
+                    // The handler broke its own contract: a server fault, never the caller's to see.
+                    throw Object.assign(new Error('Response does not match the route contract.'), {
+                        issues: result.issues.map((issue) => toIssue(issue, 'response')),
+                    });
+                }
+                value = result.value;
+            }
+            return withRevalidate(new Response(JSON.stringify(value ?? null), {
+                status: contract.status ?? 200,
+                headers: { 'content-type': 'application/json; charset=utf-8' },
+            }), stale);
+        }
+        catch (thrown) {
+            const { error, internal } = toApiError(thrown);
+            if (internal)
+                report(thrown, request);
+            return errorResponse(error);
+        }
+    };
+    Object.defineProperty(handle, CONTRACT, { value: contract });
+    return handle;
+}
+/** The header that names cached data a response made stale. */
+export const REVALIDATE_HEADER = 'x-fx-revalidate';
+/** Names the stale data on a successful response; a refused one changed nothing. */
+function withRevalidate(response, names) {
+    if (!names.length || !response.ok)
+        return response;
+    const value = names.join(', ');
+    try {
+        response.headers.append(REVALIDATE_HEADER, value);
+        return response;
+    }
+    catch {
+        // Immutable headers (a fetched or redirect Response): copy it.
+        const headers = new Headers(response.headers);
+        headers.append(REVALIDATE_HEADER, value);
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+    }
+}
+/** The contract a route was declared with, or undefined for a plain handler. */
+export function contractOf(handler) {
+    return typeof handler === 'function' ? handler[CONTRACT] : undefined;
+}
+async function check(schema, value, where, issues) {
+    if (!schema)
+        return value;
+    const result = await schema['~standard'].validate(value);
+    if (result.issues) {
+        for (const issue of result.issues)
+            issues.push(toIssue(issue, where));
+        return undefined;
+    }
+    return result.value;
+}
+function toIssue(issue, where) {
+    const path = (issue.path ?? []).map((segment) => String(typeof segment === 'object' && segment !== null ? segment.key : segment));
+    return { path: [where, ...path].join('.'), message: issue.message };
+}

package/dist/route.mjs

@@ -0,0 +1,169 @@
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var unauthorized = (message = "Sign in to continue.") => new ApiError(401, "unauthorized", message);
+var forbidden = (message = "Not allowed.") => new ApiError(403, "forbidden", message);
+function toApiError(error) {
+  if (error instanceof ApiError) return { error, internal: false };
+  const { status, code, message } = error ?? {};
+  if (status === 401 || status === 403) {
+    if (typeof code === "string" && typeof message === "string") return { error: new ApiError(status, code, message), internal: false };
+    return { error: status === 401 ? unauthorized() : forbidden(), internal: false };
+  }
+  return { error: new ApiError(500, "internal", "Something went wrong on our side."), internal: true };
+}
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+function readQuery(url) {
+  const out = {};
+  for (const [key, value] of url.searchParams) {
+    const seen = out[key];
+    if (seen === void 0) out[key] = value;
+    else out[key] = Array.isArray(seen) ? [...seen, value] : [seen, value];
+  }
+  return out;
+}
+async function readJson(request, limit = DEFAULT_BODY_LIMIT) {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) throw tooLarge(limit);
+  if (!request.body) return void 0;
+  const type = request.headers.get("content-type") ?? "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      throw tooLarge(limit);
+    }
+    chunks.push(value);
+  }
+  if (size === 0) return void 0;
+  if (!isJson(type)) {
+    throw new ApiError(415, "unsupported_media_type", "Send the body as application/json.");
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new ApiError(400, "invalid_json", "The body is not valid JSON.");
+  }
+}
+function isJson(type) {
+  const mime = type.split(";")[0].trim().toLowerCase();
+  return mime === "application/json" || mime.endsWith("+json");
+}
+function tooLarge(limit) {
+  return new ApiError(413, "payload_too_large", `The body is larger than ${limit} bytes.`);
+}
+
+// src/route.ts
+var CONTRACT = /* @__PURE__ */ Symbol.for("fluixi.api.contract");
+var report = (error, request) => {
+  console.error(`[fluixi/api] ${request.method} ${new URL(request.url).pathname}`, error);
+};
+function setErrorReporter(reporter) {
+  report = reporter;
+}
+function route(contract) {
+  const handle = async (request, context = {}) => {
+    try {
+      const auth = contract.guard ? await contract.guard.check(request) : void 0;
+      const issues = [];
+      const params = await check(contract.params, context.params ?? {}, "params", issues);
+      const query = await check(contract.query, readQuery(new URL(request.url)), "query", issues);
+      const body = contract.body ? await check(contract.body, await readJson(request, contract.bodyLimit), "body", issues) : void 0;
+      if (issues.length) throw new ApiError(400, "validation_failed", "The request is not valid.", issues);
+      const input = { params, query, body, auth, request };
+      const out = await contract.handler(input);
+      const stale = !contract.revalidates ? [] : typeof contract.revalidates === "function" ? contract.revalidates(out, input) : contract.revalidates;
+      if (out instanceof Response) return withRevalidate(out, stale);
+      if (out === void 0 && !contract.response) return withRevalidate(new Response(null, { status: contract.status ?? 204 }), stale);
+      let value = out;
+      if (contract.response && contract.validateResponse !== false) {
+        const result = await contract.response["~standard"].validate(out);
+        if (result.issues) {
+          throw Object.assign(new Error("Response does not match the route contract."), {
+            issues: result.issues.map((issue) => toIssue(issue, "response"))
+          });
+        }
+        value = result.value;
+      }
+      return withRevalidate(
+        new Response(JSON.stringify(value ?? null), {
+          status: contract.status ?? 200,
+          headers: { "content-type": "application/json; charset=utf-8" }
+        }),
+        stale
+      );
+    } catch (thrown) {
+      const { error, internal } = toApiError(thrown);
+      if (internal) report(thrown, request);
+      return errorResponse(error);
+    }
+  };
+  Object.defineProperty(handle, CONTRACT, { value: contract });
+  return handle;
+}
+var REVALIDATE_HEADER = "x-fx-revalidate";
+function withRevalidate(response, names) {
+  if (!names.length || !response.ok) return response;
+  const value = names.join(", ");
+  try {
+    response.headers.append(REVALIDATE_HEADER, value);
+    return response;
+  } catch {
+    const headers = new Headers(response.headers);
+    headers.append(REVALIDATE_HEADER, value);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+  }
+}
+function contractOf(handler) {
+  return typeof handler === "function" ? handler[CONTRACT] : void 0;
+}
+async function check(schema, value, where, issues) {
+  if (!schema) return value;
+  const result = await schema["~standard"].validate(value);
+  if (result.issues) {
+    for (const issue of result.issues) issues.push(toIssue(issue, where));
+    return void 0;
+  }
+  return result.value;
+}
+function toIssue(issue, where) {
+  const path = (issue.path ?? []).map(
+    (segment) => String(typeof segment === "object" && segment !== null ? segment.key : segment)
+  );
+  return { path: [where, ...path].join("."), message: issue.message };
+}
+export {
+  CONTRACT,
+  REVALIDATE_HEADER,
+  contractOf,
+  route,
+  setErrorReporter
+};