@protobase/server 0.0.0-stage → 0.1.1

package/dist/openapi/document.js

@@ -0,0 +1,74 @@
+import { batchSchemas, errorResponses, parameters, problemSchema, searchBody } from "./components.js";
+import { resourcePaths } from "./resource-paths.js";
+import { resourceSchemas } from "./schemas.js";
+//#region src/openapi/document.ts
+/** The OpenAPI 3.1 document for one caller, generated from the resource models they may see and their zod record schemas. */
+const openApiDocument = (accesses, basePath, systemPath) => ({
+	openapi: "3.1.0",
+	info: {
+		title: "Protobase API",
+		version: "1.0.0",
+		description: "Admin API for an existing Postgres database. Follows Google's API design conventions ([AIP](https://google.aip.dev)) and reports errors as RFC 9457 `application/problem+json`."
+	},
+	servers: [{ url: basePath }],
+	security: [{ bearer: [] }],
+	tags: accesses.map(({ entry }) => ({ name: entry.name })),
+	paths: {
+		"/meta": {
+			servers: [{ url: systemPath || "/" }],
+			get: {
+				operationId: "get_meta",
+				summary: "Resource and view models",
+				description: "ETag from a content hash; send If-None-Match for a 304.",
+				responses: {
+					200: { description: "The models" },
+					304: { description: "Not modified" },
+					401: { $ref: "#/components/responses/Unauthorized" }
+				}
+			}
+		},
+		[`/${basePath.slice(basePath.lastIndexOf("/") + 1)}:batchWrite`]: {
+			servers: [{ url: basePath.slice(0, basePath.lastIndexOf("/")) || "/" }],
+			post: {
+				operationId: "batch_write",
+				summary: "Write many records in one transaction",
+				description: "Ordered create, update, delete and reorder operations, at most 500, across resources. Each runs through the normal write pipeline (validation, access with row filters and record rules, tenant, ETags, hooks); the first failure rolls everything back and the problem names it in `operation` (its index), `op` and `resource`. A stale ETag is a 412 for the whole batch. `reorder` moves only the records that change, first out of the way (above the highest value in the column, or below the lowest when a check constraint refuses that), so a unique index such as (invoice_id, position) is never violated half way. `{ \"$ref\": name }` points at a record created earlier by `ref`.",
+				requestBody: {
+					required: true,
+					content: { "application/json": { schema: { $ref: "#/components/schemas/BatchRequest" } } }
+				},
+				responses: {
+					200: {
+						description: "Every result, in order",
+						content: { "application/json": { schema: { $ref: "#/components/schemas/BatchResponse" } } }
+					},
+					400: { $ref: "#/components/responses/BadRequest" },
+					401: { $ref: "#/components/responses/Unauthorized" },
+					403: { $ref: "#/components/responses/Forbidden" },
+					404: { $ref: "#/components/responses/NotFound" },
+					409: { $ref: "#/components/responses/Conflict" },
+					412: { $ref: "#/components/responses/PreconditionFailed" },
+					428: { $ref: "#/components/responses/PreconditionRequired" }
+				}
+			}
+		},
+		...Object.assign({}, ...accesses.map(resourcePaths))
+	},
+	components: {
+		securitySchemes: { bearer: {
+			type: "http",
+			scheme: "bearer",
+			bearerFormat: "JWT"
+		} },
+		parameters,
+		responses: errorResponses,
+		schemas: {
+			Problem: problemSchema,
+			SearchBody: searchBody,
+			...batchSchemas,
+			...Object.assign({}, ...accesses.map(resourceSchemas))
+		}
+	}
+});
+//#endregion
+export { openApiDocument };

package/dist/openapi/naming.js

@@ -0,0 +1,4 @@
+//#region src/openapi/naming.ts
+const pascal = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+//#endregion
+export { pascal };

package/dist/openapi/resource-paths.js

@@ -0,0 +1,417 @@
+import { pascal } from "./naming.js";
+//#region src/openapi/resource-paths.ts
+const param = (name) => ({ $ref: `#/components/parameters/${name}` });
+const error = (name) => ({ $ref: `#/components/responses/${name}` });
+const json = (schema) => ({ "application/json": { schema } });
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const listParameters = (entry) => [
+	"filter",
+	"orderBy",
+	"pageSize",
+	"pageToken",
+	"fields",
+	"count",
+	...entry.model.softDelete ? ["showDeleted"] : []
+].map(param);
+const field = (description) => ({
+	name: "field",
+	in: "query",
+	required: true,
+	description,
+	schema: { type: "string" }
+});
+const query = (name, description, schema = { type: "string" }, required = false) => ({
+	name,
+	in: "query",
+	required,
+	description,
+	schema
+});
+const record = (name, entry) => ({
+	description: `The ${entry.name} record. The ETag header is its version.`,
+	headers: { ETag: { schema: { type: "string" } } },
+	content: json(ref(name))
+});
+const page = (name, seek = false) => json({
+	type: "object",
+	required: [
+		"items",
+		"next_page_token",
+		"total_size_estimate"
+	],
+	properties: {
+		items: {
+			type: "array",
+			items: ref(name)
+		},
+		next_page_token: {
+			type: "string",
+			description: "Empty on the last page"
+		},
+		...seek && { prev_page_token: {
+			type: "string",
+			description: "Empty on the first page"
+		} },
+		total_size_estimate: {
+			type: "integer",
+			description: "The planner's estimate"
+		},
+		total_size: {
+			type: "integer",
+			description: "Only with count=exact"
+		}
+	}
+});
+const needs = {
+	list: "list",
+	search: "list",
+	facets: "list",
+	series: "list",
+	histogram: "list",
+	seek: "list",
+	get: "read",
+	reveal: "read",
+	create: "create",
+	update: "update",
+	undelete: "update",
+	delete: "delete"
+};
+const withoutDenied = (paths, access) => Object.fromEntries(Object.entries(paths).flatMap(([path, methods]) => {
+	const allowed = Object.entries(methods).filter(([, operation]) => access.resolved.operations[needs[String(operation.operationId).split("_")[0]]]);
+	return allowed.length > 0 ? [[path, Object.fromEntries(allowed)]] : [];
+}));
+const auth = { 401: error("Unauthorized") };
+/** The paths of one resource: AIP-132 list, AIP-131 get, AIP-133 create, AIP-134 update, AIP-135 delete, and the `:` helpers (AIP-136). */
+const resourcePaths = (access) => {
+	const { entry } = access;
+	const name = pascal(entry.name);
+	const tag = [entry.name];
+	const tenantNote = entry.model.tenant ? " Rows of other tenants are never visible." : "";
+	const softNote = entry.model.softDelete ? " Soft-deleted rows are hidden." : "";
+	const keyErrors = {
+		400: error("BadRequest"),
+		...auth,
+		404: error("NotFound")
+	};
+	const sensitive = Object.values(access.readable.fields).filter((field) => field.sensitive).map((field) => field.name);
+	const paths = {
+		[`/${entry.name}`]: {
+			get: {
+				operationId: `list_${entry.name}`,
+				tags: tag,
+				summary: `List ${entry.name}`,
+				description: `Keyset paginated list.${tenantNote}${softNote}`,
+				parameters: listParameters(entry),
+				responses: {
+					200: {
+						description: "A page",
+						content: page(name)
+					},
+					400: error("BadRequest"),
+					...auth
+				}
+			},
+			post: {
+				operationId: `create_${entry.name}`,
+				tags: tag,
+				summary: `Create a ${entry.name} record`,
+				parameters: [param("prefer")],
+				requestBody: {
+					required: true,
+					content: json(ref(`${name}Create`))
+				},
+				responses: {
+					201: {
+						description: "Created; Location and ETag headers",
+						content: json(ref(name))
+					},
+					400: error("BadRequest"),
+					...auth,
+					403: error("Forbidden"),
+					409: error("Conflict")
+				}
+			}
+		},
+		[`/${entry.name}:search`]: { post: {
+			operationId: `search_${entry.name}`,
+			tags: tag,
+			summary: `List ${entry.name} with a JSON body`,
+			requestBody: {
+				required: true,
+				content: json({ $ref: "#/components/schemas/SearchBody" })
+			},
+			responses: {
+				200: {
+					description: "A page",
+					content: page(name)
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
+		[`/${entry.name}/{key}`]: {
+			get: {
+				operationId: `get_${entry.name}`,
+				tags: tag,
+				summary: `Get a ${entry.name} record`,
+				parameters: [
+					param("key"),
+					param("fields"),
+					...entry.model.softDelete ? [param("showDeleted")] : []
+				],
+				responses: {
+					200: record(name, entry),
+					...keyErrors
+				}
+			},
+			patch: {
+				operationId: `update_${entry.name}`,
+				tags: tag,
+				summary: `Update a ${entry.name} record`,
+				description: "Only the fields in the body change. Needs If-Match; a stale ETag is a 412.",
+				parameters: [
+					param("key"),
+					param("ifMatch"),
+					param("prefer")
+				],
+				requestBody: {
+					required: true,
+					content: json(ref(`${name}Update`))
+				},
+				responses: {
+					200: record(name, entry),
+					204: { description: "With Prefer: return=minimal" },
+					...keyErrors,
+					403: error("Forbidden"),
+					409: error("Conflict"),
+					412: error("PreconditionFailed"),
+					428: error("PreconditionRequired")
+				}
+			},
+			delete: {
+				operationId: `delete_${entry.name}`,
+				tags: tag,
+				summary: `Delete a ${entry.name} record`,
+				description: entry.model.softDelete ? "Soft delete: the record is hidden and can be restored." : "Removes the row.",
+				parameters: [
+					param("key"),
+					param("ifMatchOptional"),
+					param("prefer")
+				],
+				responses: {
+					204: { description: "Deleted" },
+					...keyErrors,
+					403: error("Forbidden"),
+					409: error("Conflict"),
+					412: error("PreconditionFailed")
+				}
+			}
+		},
+		...entry.model.softDelete && { [`/${entry.name}/{key}:undelete`]: { post: {
+			operationId: `undelete_${entry.name}`,
+			tags: tag,
+			summary: `Restore a deleted ${entry.name} record`,
+			description: "[AIP-164](https://google.aip.dev/164): restores a deleted record. A record that is not deleted is a 409.",
+			parameters: [
+				param("key"),
+				param("ifMatchOptional"),
+				param("prefer")
+			],
+			responses: {
+				200: record(name, entry),
+				204: { description: "With Prefer: return=minimal" },
+				...keyErrors,
+				403: error("Forbidden"),
+				409: error("Conflict"),
+				412: error("PreconditionFailed")
+			}
+		} } },
+		...sensitive.length > 0 && { [`/${entry.name}/{key}:reveal`]: { post: {
+			operationId: `reveal_${entry.name}`,
+			tags: tag,
+			summary: `Reveal a sensitive field of a ${entry.name} record`,
+			description: "A sensitive field never comes with the record. This returns its value for one record, with the same access as a get, and publishes an audit event first.",
+			parameters: [param("key")],
+			requestBody: {
+				required: true,
+				content: json({
+					type: "object",
+					required: ["field"],
+					properties: { field: {
+						type: "string",
+						enum: sensitive
+					} },
+					additionalProperties: false
+				})
+			},
+			responses: {
+				200: {
+					description: "The value; never cached",
+					content: json({
+						type: "object",
+						required: ["field", "value"],
+						properties: {
+							field: { type: "string" },
+							value: {}
+						}
+					})
+				},
+				...keyErrors
+			}
+		} } },
+		[`/${entry.name}:facets`]: { get: {
+			operationId: `facets_${entry.name}`,
+			tags: tag,
+			summary: `Value counts of a ${entry.name} field`,
+			description: "Applies the filter except its own terms on the field.",
+			parameters: [
+				field("A filterable field"),
+				param("filter"),
+				query("limit", "Most values to return", { type: "integer" })
+			],
+			responses: {
+				200: {
+					description: "Counts, most frequent first",
+					content: json({
+						type: "object",
+						properties: {
+							field: { type: "string" },
+							facets: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										value: {},
+										count: { type: "integer" }
+									}
+								}
+							}
+						}
+					})
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
+		[`/${entry.name}:series`]: { get: {
+			operationId: `series_${entry.name}`,
+			tags: tag,
+			summary: `Counts per time bucket of a ${entry.name} date field`,
+			parameters: [
+				field("A filterable date or timestamp field"),
+				param("filter"),
+				query("range", "Relative range ending now (default 30d); `all` starts at the earliest row", {
+					type: "string",
+					enum: [
+						"7d",
+						"30d",
+						"90d",
+						"1y",
+						"all"
+					]
+				}),
+				query("from", "Explicit start (ISO 8601); with `to`, replaces range"),
+				query("to", "Exclusive end (ISO 8601), default now"),
+				query("granularity", "Default day", {
+					type: "string",
+					enum: [
+						"hour",
+						"day",
+						"week",
+						"month"
+					]
+				}),
+				query("time_zone", "IANA time zone for the buckets, default UTC")
+			],
+			responses: {
+				200: {
+					description: "Buckets in local ISO time, empty ones included",
+					content: json({
+						type: "object",
+						properties: {
+							field: { type: "string" },
+							granularity: { type: "string" },
+							time_zone: { type: "string" },
+							points: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										bucket: { type: "string" },
+										count: { type: "integer" }
+									}
+								}
+							}
+						}
+					})
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
+		[`/${entry.name}:histogram`]: { get: {
+			operationId: `histogram_${entry.name}`,
+			tags: tag,
+			summary: `Equal-width buckets of a numeric ${entry.name} field`,
+			parameters: [
+				field("A filterable numeric field"),
+				param("filter"),
+				query("buckets", "Default 20, at most 200", { type: "integer" })
+			],
+			responses: {
+				200: {
+					description: "Buckets between the filtered minimum and maximum",
+					content: json({
+						type: "object",
+						properties: {
+							field: { type: "string" },
+							min: { type: ["number", "null"] },
+							max: { type: ["number", "null"] },
+							buckets: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										from: { type: "number" },
+										to: { type: "number" },
+										count: { type: "integer" }
+									}
+								}
+							}
+						}
+					})
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
+		[`/${entry.name}:seek`]: { get: {
+			operationId: `seek_${entry.name}`,
+			tags: tag,
+			summary: `A page of ${entry.name} at a row position`,
+			description: "For scrollbar jumps: resolves a 0-based row position, within the rows the caller can see and in the given order, to a page of rows, with no OFFSET. The estimate behind it is scaled to the caller's own rows; no column statistics or boundary values are returned, only the page and its tokens.",
+			parameters: [
+				query("position", "0-based row position to jump to", {
+					type: "integer",
+					minimum: 0
+				}, true),
+				param("orderBy"),
+				param("filter"),
+				param("pageSize"),
+				param("fields"),
+				param("count")
+			],
+			responses: {
+				200: {
+					description: "The page at that position; continue from either token",
+					content: page(name, true)
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} }
+	};
+	return withoutDenied(paths, access);
+};
+//#endregion
+export { resourcePaths };

package/dist/openapi/schemas.js

@@ -0,0 +1,93 @@
+import { writableFields } from "../request-access.js";
+import { pascal } from "./naming.js";
+import { z } from "zod";
+//#region src/openapi/schemas.ts
+const convert = (entry, io) => {
+	const schema = z.toJSONSchema(entry.source.recordSchema(), {
+		io,
+		unrepresentable: "any",
+		override: ({ jsonSchema }) => {
+			if (jsonSchema.format) delete jsonSchema.pattern;
+		}
+	});
+	delete schema.$schema;
+	return schema;
+};
+const hoist = (entry, schema) => {
+	const { $defs = {}, ...rest } = schema;
+	const rename = (key) => `${pascal(entry.name)}${key.replace(/^__/, "_")}`;
+	let text = JSON.stringify(rest);
+	for (const key of Object.keys($defs)) text = text.replaceAll(`"#/$defs/${key}"`, `"#/components/schemas/${rename(key)}"`);
+	const hoisted = Object.fromEntries(Object.entries($defs).map(([key, value]) => [rename(key), JSON.parse(JSON.stringify(value).replaceAll(`"#/$defs/${key}"`, `"#/components/schemas/${rename(key)}"`))]));
+	return {
+		schema: JSON.parse(text),
+		hoisted
+	};
+};
+const only = (schema, names) => ({
+	...schema,
+	properties: Object.fromEntries(names.filter((name) => schema.properties?.[name]).map((name) => [name, schema.properties[name]])),
+	...schema.required && { required: schema.required.filter((name) => names.includes(name)) }
+});
+/**
+* Component schemas of a resource for one caller: the record with the fields they may read, and the create and update
+* bodies with the fields they may write. Hidden fields appear nowhere.
+*/
+const resourceSchemas = (access) => {
+	const { entry, model, resolved } = access;
+	const name = pascal(entry.name);
+	const readable = Object.keys(model.fields);
+	const output = hoist(entry, convert(entry, "output"));
+	const input = hoist(entry, convert(entry, "input"));
+	const record = only(output.schema, readable);
+	for (const field of Object.values(model.fields)) if (field.readOnly && record.properties?.[field.name]) record.properties[field.name].readOnly = true;
+	record.properties.etag = {
+		type: "string",
+		readOnly: true,
+		description: "The record version, as in the ETag header; send it in If-Match when updating or deleting"
+	};
+	record.properties.permissions = {
+		type: "object",
+		readOnly: true,
+		description: "What the caller may do with this record: update and delete, and on a get also `fields`, the mode (`edit` or `read`) of each field",
+		properties: {
+			update: { type: "boolean" },
+			delete: { type: "boolean" },
+			fields: {
+				type: "object",
+				additionalProperties: {
+					type: "string",
+					enum: ["edit", "read"]
+				}
+			}
+		}
+	};
+	record.required = [...record.required ?? [], "etag"];
+	const writable = access.readable;
+	const body = (names) => {
+		const properties = only(input.schema, names).properties;
+		const optional = new Set(names.filter((field) => writable.fields[field]?.nullable || writable.fields[field]?.default && "db" in writable.fields[field].default));
+		for (const field of names) {
+			const fieldModel = writable.fields[field];
+			if (fieldModel?.default && "db" in fieldModel.default && properties[field]) properties[field].description = "Defaults to a value the database generates";
+		}
+		const required = input.schema.required?.filter((field) => names.includes(field) && !optional.has(field)) ?? [];
+		return {
+			type: "object",
+			properties,
+			...required.length > 0 && { required },
+			additionalProperties: false
+		};
+	};
+	const create = body(writableFields(access, "create"));
+	const update = { ...body(writableFields(access, "update")) };
+	delete update.required;
+	return {
+		[name]: record,
+		...resolved.operations.create && { [`${name}Create`]: create },
+		...resolved.operations.update && { [`${name}Update`]: update },
+		...output.hoisted
+	};
+};
+//#endregion
+export { resourceSchemas };

package/dist/params.js

@@ -0,0 +1,48 @@
+import { badRequest } from "./problem.js";
+import { z } from "zod";
+//#region src/params.ts
+/** Parses query or body parameters; a failure is a 400 problem listing each offending parameter. */
+const parseParams = (schema, input) => {
+	const parsed = schema.safeParse(input);
+	if (parsed.success) return parsed.data;
+	const errors = parsed.error.issues.map((issue) => ({
+		parameter: issue.path.join("."),
+		message: issue.message
+	}));
+	throw badRequest("invalid-parameter", `Invalid parameter ${errors[0].parameter}: ${errors[0].message}`, { errors });
+};
+const listParams = z.object({
+	filter: z.string().optional(),
+	order_by: z.string().optional(),
+	page_size: z.coerce.number().int().min(0).optional(),
+	page_token: z.string().optional(),
+	fields: z.union([z.string(), z.array(z.string())]).optional(),
+	count: z.literal("exact").optional(),
+	show_deleted: z.union([z.boolean(), z.enum(["true", "false"]).transform((value) => value === "true")]).optional()
+});
+/** The list parameters plus the row position to jump to (`:seek`). */
+const seekParams = listParams.extend({ position: z.coerce.number().int().min(0) });
+/** AIP-158: 0 or absent means the default, anything above the maximum is coerced down. */
+const pageSizeOf = (requested) => Math.min(requested || 50, 500);
+/** AIP-157 style column selection: comma separated field names, or an array in a body. */
+const selectedFields = (model, fields) => {
+	if (fields === void 0) return void 0;
+	const names = (Array.isArray(fields) ? fields : fields.split(",")).map((name) => name.trim()).filter(Boolean);
+	const unknown = names.filter((name) => !Object.hasOwn(model.fields, name));
+	if (unknown.length > 0) throw badRequest("invalid-parameter", `Unknown fields: ${unknown.join(", ")}`, { errors: unknown.map((name) => ({
+		parameter: "fields",
+		message: `Unknown field "${name}"`
+	})) });
+	return names.length > 0 ? names : void 0;
+};
+/** AIP-164 `show_deleted`: only soft-delete resources have deleted rows to show. */
+const deletedRows = (model, showDeleted) => {
+	if (!showDeleted) return "hide";
+	if (!model.softDelete) throw badRequest("invalid-parameter", `Resource "${model.name}" does not soft delete, so show_deleted does not apply`, { errors: [{
+		parameter: "show_deleted",
+		message: "Not supported"
+	}] });
+	return "show";
+};
+//#endregion
+export { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields };

package/dist/problem.d.ts

@@ -0,0 +1,17 @@
+//#region src/problem.d.ts
+export type ProblemExtras = Record<string, unknown>;
+/** An RFC 9457 problem. Throw it anywhere below a route; the central error handler renders it. */
+export declare class HttpProblem extends Error {
+  readonly status: number;
+  readonly slug: string;
+  readonly title: string;
+  readonly extras: ProblemExtras;
+  readonly headers: Record<string, string>;
+  constructor(status: number, slug: string, title: string, detail: string, extras?: ProblemExtras, headers?: Record<string, string>);
+  get detail(): string;
+}
+export declare const badRequest: (slug: string, detail: string, extras?: ProblemExtras) => HttpProblem;
+export declare const unauthorized: (detail: string) => HttpProblem;
+export declare const forbidden: (slug: string, detail: string) => HttpProblem;
+export declare const notFound: (detail: string) => HttpProblem;
+//#endregion