@geode/opengeodeweb-front 10.35.0 → 10.36.0-rc.2

package/server/api/microservice/app/schemas/get_is_app_ready.json

@@ -4,5 +4,18 @@
   "type": "object",
   "properties": {},
   "required": [],
-  "additionalProperties": false
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      },
+      "isReady": {
+        "type": "boolean"
+      }
+    },
+    "required": ["statusCode", "isReady"],
+    "additionalProperties": false
+  }
 }

package/server/api/microservice/app/schemas/set_app_base_url.json

@@ -3,8 +3,23 @@
   "methods": ["POST"],
   "type": "object",
   "properties": {
-    "baseUrl": { "type": "string" }
+    "baseUrl": {
+      "type": "string"
+    }
   },
   "required": ["baseUrl"],
-  "additionalProperties": false
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      },
+      "baseUrl": {
+        "type": "string"
+      }
+    },
+    "required": ["statusCode", "baseUrl"],
+    "additionalProperties": false
+  }
 }

package/server/api/microservice/app/schemas/set_back_base_url.json

@@ -3,8 +3,23 @@
   "methods": ["POST"],
   "type": "object",
   "properties": {
-    "baseUrl": { "type": "string" }
+    "baseUrl": {
+      "type": "string"
+    }
   },
   "required": ["baseUrl"],
-  "additionalProperties": false
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      },
+      "baseUrl": {
+        "type": "string"
+      }
+    },
+    "required": ["statusCode", "baseUrl"],
+    "additionalProperties": false
+  }
 }

package/server/api/microservice/app/schemas/set_is_app_ready.json

@@ -3,8 +3,23 @@
   "methods": ["POST"],
   "type": "object",
   "properties": {
-    "isReady": { "type": "boolean" }
+    "isReady": {
+      "type": "boolean"
+    }
   },
   "required": ["isReady"],
-  "additionalProperties": false
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      },
+      "isReady": {
+        "type": "boolean"
+      }
+    },
+    "required": ["statusCode", "isReady"],
+    "additionalProperties": false
+  }
 }

package/server/api/microservice/app/schemas/set_viewer_base_url.json

@@ -3,8 +3,23 @@
   "methods": ["POST"],
   "type": "object",
   "properties": {
-    "baseUrl": { "type": "string" }
+    "baseUrl": {
+      "type": "string"
+    }
   },
   "required": ["baseUrl"],
-  "additionalProperties": false
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      },
+      "baseUrl": {
+        "type": "string"
+      }
+    },
+    "required": ["statusCode", "baseUrl"],
+    "additionalProperties": false
+  }
 }

package/server/api/microservice/app/set_app_base_url.post.ts

@@ -1,30 +1,21 @@
 // Third party imports
-import { type H3Event, createError, defineEventHandler, readBody } from "h3";
 import { consola } from "consola";
+import { createError } from "h3";
 
 // Local imports
 import { setAppBaseUrl } from "@geode/opengeodeweb-front/server/utils/server_config.ts";
 
-interface SetAppBaseUrlBody {
-  baseUrl: string;
-}
+import { defineTypedEventHandler } from "@geode/opengeodeweb-front/server/utils/typed_handler.ts";
+import schemas from "@geode/opengeodeweb-front/opengeodeweb_front_typed_schemas.js";
 
-export default defineEventHandler(async (event: H3Event) => {
-  try {
-    const { baseUrl } = await readBody<SetAppBaseUrlBody>(event);
+export default defineTypedEventHandler(
+  schemas.api.microservice.app.set_app_base_url,
+  ({ baseUrl }) => {
     if (!baseUrl) {
       throw createError({ statusCode: 400, statusMessage: "baseUrl is required" });
     }
-
     setAppBaseUrl(baseUrl);
     consola.info(`Updated APP_BASE_URL to ${baseUrl}`);
-
     return { statusCode: 200, baseUrl };
-  } catch (error) {
-    consola.error(error);
-    throw createError({
-      statusCode: 500,
-      statusMessage: error instanceof Error ? error.message : String(error),
-    });
-  }
-});
+  },
+);

package/server/api/microservice/app/set_back_base_url.post.ts

@@ -1,27 +1,19 @@
 // Third party imports
-import { type H3Event, createError, defineEventHandler, readBody } from "h3";
-import { consola } from "consola";
+import { createError } from "h3";
 
 // Local imports
 import { setBackBaseUrl } from "@geode/opengeodeweb-front/server/utils/server_config.ts";
 
-interface SetBackBaseUrlBody {
-  baseUrl: string;
-}
+import { defineTypedEventHandler } from "@geode/opengeodeweb-front/server/utils/typed_handler.ts";
+import schemas from "@geode/opengeodeweb-front/opengeodeweb_front_typed_schemas.js";
 
-export default defineEventHandler(async (event: H3Event) => {
-  try {
-    const { baseUrl } = await readBody<SetBackBaseUrlBody>(event);
+export default defineTypedEventHandler(
+  schemas.api.microservice.app.set_back_base_url,
+  ({ baseUrl }) => {
     if (!baseUrl) {
       throw createError({ statusCode: 400, statusMessage: "baseUrl is required" });
     }
     setBackBaseUrl(baseUrl);
     return { statusCode: 200, baseUrl };
-  } catch (error) {
-    consola.error(error);
-    throw createError({
-      statusCode: 500,
-      statusMessage: error instanceof Error ? error.message : String(error),
-    });
-  }
-});
+  },
+);

package/server/api/microservice/app/set_is_app_ready.post.ts

@@ -1,30 +1,21 @@
 // Third party imports
-import { type H3Event, createError, defineEventHandler, readBody } from "h3";
 import { consola } from "consola";
+import { createError } from "h3";
 
 // Local imports
 import { setIsAppReady } from "@geode/opengeodeweb-front/server/utils/server_config.ts";
 
-interface SetIsAppReadyBody {
-  isReady: boolean;
-}
+import { defineTypedEventHandler } from "@geode/opengeodeweb-front/server/utils/typed_handler.ts";
+import schemas from "@geode/opengeodeweb-front/opengeodeweb_front_typed_schemas.js";
 
-export default defineEventHandler(async (event: H3Event) => {
-  try {
-    const { isReady } = await readBody<SetIsAppReadyBody>(event);
+export default defineTypedEventHandler(
+  schemas.api.microservice.app.set_is_app_ready,
+  ({ isReady }) => {
     if (!isReady) {
       throw createError({ statusCode: 400, statusMessage: "isReady is required" });
     }
-
     setIsAppReady(isReady);
     consola.info(`Updated IS_APP_READY to ${isReady}`);
-
     return { statusCode: 200, isReady };
-  } catch (error) {
-    consola.error(error);
-    throw createError({
-      statusCode: 500,
-      statusMessage: error instanceof Error ? error.message : String(error),
-    });
-  }
-});
+  },
+);

package/server/api/microservice/app/set_viewer_base_url.post.ts

@@ -1,27 +1,19 @@
 // Third party imports
-import { type H3Event, createError, defineEventHandler, readBody } from "h3";
-import { consola } from "consola";
+import { createError } from "h3";
 
 // Local imports
 import { setViewerBaseUrl } from "@geode/opengeodeweb-front/server/utils/server_config.ts";
 
-interface SetViewerBaseUrlBody {
-  baseUrl: string;
-}
+import { defineTypedEventHandler } from "@geode/opengeodeweb-front/server/utils/typed_handler.ts";
+import schemas from "@geode/opengeodeweb-front/opengeodeweb_front_typed_schemas.js";
 
-export default defineEventHandler(async (event: H3Event) => {
-  try {
-    const { baseUrl } = await readBody<SetViewerBaseUrlBody>(event);
+export default defineTypedEventHandler(
+  schemas.api.microservice.app.set_viewer_base_url,
+  ({ baseUrl }) => {
     if (!baseUrl) {
       throw createError({ statusCode: 400, statusMessage: "baseUrl is required" });
     }
     setViewerBaseUrl(baseUrl);
     return { statusCode: 200, baseUrl };
-  } catch (error) {
-    consola.error(error);
-    throw createError({
-      statusCode: 500,
-      statusMessage: error instanceof Error ? error.message : String(error),
-    });
-  }
-});
+  },
+);

package/server/api/microservice/extensions/download.post.ts

@@ -2,7 +2,6 @@
 import { promises as fs } from "node:fs";
 
 // Third party imports
-import { type H3Event, createError, defineEventHandler, readBody } from "h3";
 import { consola } from "consola";
 
 // Local imports
@@ -11,30 +10,18 @@ import {
   targetExtensionFilePath,
 } from "@geode/opengeodeweb-front/server/utils/app_config.ts";
 
-interface DownloadExtensionBody {
-  projectName: string;
-  url: string;
-  extensionFileName: string;
-}
+import { defineTypedEventHandler } from "@geode/opengeodeweb-front/server/utils/typed_handler.ts";
+import schemas from "@geode/opengeodeweb-front/opengeodeweb_front_typed_schemas.js";
 
-export default defineEventHandler(async (event: H3Event) => {
-  try {
-    const body = await readBody<DownloadExtensionBody>(event);
-    const { projectName, url, extensionFileName } = body;
+export default defineTypedEventHandler(
+  schemas.api.microservice.extensions.download,
+  async ({ projectName, url, extensionFileName }) => {
     consola.debug({ projectName, url, extensionFileName });
     const response: Response = await fetch(url);
     const fileBuffer = await response.arrayBuffer();
     const filePath = targetExtensionFilePath(projectName, extensionFileName);
     await fs.writeFile(filePath, Buffer.from(fileBuffer));
     await registerExtensionFile(projectName, filePath);
-    return {
-      statusCode: 200,
-    };
-  } catch (error) {
-    consola.error("Error downloading extension:", error);
-    throw createError({
-      statusCode: 500,
-      statusMessage: error instanceof Error ? error.message : String(error),
-    });
-  }
-});
+    return { statusCode: 200 };
+  },
+);

package/server/api/microservice/extensions/schemas/download.json

@@ -3,9 +3,26 @@
   "methods": ["POST"],
   "type": "object",
   "properties": {
-    "extension": { "type": "string" },
-    "platform": { "type": "string" }
+    "projectName": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "extensionFileName": {
+      "type": "string"
+    }
   },
-  "required": ["extension", "platform"],
-  "additionalProperties": false
+  "required": ["projectName", "url", "extensionFileName"],
+  "additionalProperties": false,
+  "response": {
+    "type": "object",
+    "properties": {
+      "statusCode": {
+        "type": "integer"
+      }
+    },
+    "required": ["statusCode"],
+    "additionalProperties": false
+  }
 }

package/server/utils/typed_handler.ts

@@ -0,0 +1,114 @@
+// Third party imports
+import {
+  type EventHandler,
+  type H3Event,
+  createError,
+  defineEventHandler,
+  getQuery,
+  isError,
+  readBody,
+  setResponseStatus,
+} from "h3";
+import Ajv from "ajv";
+import { consola } from "consola";
+
+// Local imports
+import type {
+  JsonRpcSchema,
+  ParamsOf,
+  ResponseOf,
+} from "@geode/opengeodeweb-front/shared/utils/types.ts";
+import type { ErrorResponse } from "@geode/opengeodeweb-back/opengeodeweb_back_typed_schemas.js";
+import { validateSchema } from "@geode/opengeodeweb-front/shared/utils/validate_schema.ts";
+
+const BAD_REQUEST = 400;
+const INTERNAL_SERVER_ERROR = 500;
+
+type RouteSchema = JsonRpcSchema & { readonly response?: object };
+
+// Same body as the Flask microservices' errors, so the client reads every error the same way
+function toErrorResponse(error: unknown): ErrorResponse {
+  if (isError(error)) {
+    return {
+      code: error.statusCode,
+      name: error.statusMessage ?? "Error",
+      description: error.message,
+    };
+  }
+  return {
+    code: INTERNAL_SERVER_ERROR,
+    name: "Internal Server Error",
+    description: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function sendError(event: H3Event, schema: RouteSchema, error: unknown): ErrorResponse {
+  consola.error(`[${schema.$id}]`, error);
+  const errorResponse = toErrorResponse(error);
+  setResponseStatus(event, errorResponse.code, errorResponse.name);
+  return errorResponse;
+}
+
+async function readParams(event: H3Event): Promise<unknown> {
+  if (event.method === "GET" || event.method === "HEAD") {
+    return getQuery(event);
+  }
+  const body: unknown = await readBody(event);
+  return body ?? {};
+}
+
+function checkResponse(schema: RouteSchema, payload: unknown): void {
+  if (process.env.NODE_ENV === "production" || schema.response === undefined) {
+    return;
+  }
+  const ajv = new Ajv();
+  if (!ajv.validate(schema.response, payload)) {
+    throw new Error(`${schema.$id} response does not match its schema: ${ajv.errorsText()}`);
+  }
+}
+
+// Register a JSON route whose handler takes its typed params and returns its typed success response. Errors must be thrown (createError or any exception), they are sent as an ErrorResponse.
+function defineTypedEventHandler<Schema extends RouteSchema>(
+  schema: Schema,
+  handler: (
+    params: ParamsOf<Schema>,
+    event: H3Event,
+  ) => ResponseOf<Schema> | Promise<ResponseOf<Schema>>,
+): EventHandler<Record<string, never>, Promise<ResponseOf<Schema> | ErrorResponse>> {
+  return defineEventHandler(async (event) => {
+    try {
+      const params = await readParams(event);
+      const { valid, error } = validateSchema(schema, params);
+      if (!valid) {
+        throw createError({
+          statusCode: BAD_REQUEST,
+          statusMessage: "Bad Request",
+          message: error,
+        });
+      }
+      // Validated against the schema the params type was generated from
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      const response = await handler(params as ParamsOf<Schema>, event);
+      checkResponse(schema, response);
+      return response;
+    } catch (error) {
+      return sendError(event, schema, error);
+    }
+  });
+}
+
+// Register a route that cannot go through defineTypedEventHandler: non JSON request body (file upload) or non JSON response (stream). Errors are still sent as an ErrorResponse.
+function defineRawEventHandler<Response>(
+  schema: RouteSchema,
+  handler: (event: H3Event) => Response | Promise<Response>,
+): EventHandler<Record<string, never>, Promise<Response | ErrorResponse>> {
+  return defineEventHandler(async (event) => {
+    try {
+      return await handler(event);
+    } catch (error) {
+      return sendError(event, schema, error);
+    }
+  });
+}
+
+export { defineRawEventHandler, defineTypedEventHandler };

package/shared/utils/types.ts

@@ -13,10 +13,18 @@ interface ValidationError {
   error: string | null | undefined;
 }
 
-interface RequestHandlers {
+// Generated `*_schemas.d.ts` files tag each schema with phantom `__params`/`__response` types; untagged schemas fall back to untyped.
+type ResponseOf<Schema> = Schema extends { readonly __response?: infer Response }
+  ? Response
+  : unknown;
+type ParamsOf<Schema> = Schema extends { readonly __params?: infer Params }
+  ? Params
+  : Record<string, unknown>;
+
+interface RequestHandlers<Response = unknown> {
   readonly request_error_function?: (error: unknown) => void | Promise<void>;
   // Return value is intentionally untyped: callers commonly return the Promise of a downstream call (e.g. a Dexie `.put()`, which resolves to a primary key) that this code chains/awaits but never inspects the resolved value of.
-  readonly response_function?: (response: unknown) => unknown;
+  readonly response_function?: (response: Response) => unknown;
   readonly response_error_function?: (response: unknown) => void | Promise<void>;
 }
 
@@ -24,4 +32,11 @@ interface RequestHandlersWithValidation extends RequestHandlers {
   readonly validation_error_function?: (error: ValidationError) => void;
 }
 
-export type { JsonRpcSchema, RequestHandlers, RequestHandlersWithValidation, ValidationError };
+export type {
+  JsonRpcSchema,
+  ParamsOf,
+  RequestHandlers,
+  RequestHandlersWithValidation,
+  ResponseOf,
+  ValidationError,
+};

package/shared/utils/validate_schema.ts

@@ -4,7 +4,7 @@ import type { JsonRpcSchema } from "./types.js";
 
 function validateSchema(schema: JsonRpcSchema, body: unknown): { valid: boolean; error: string } {
   const ajv = new Ajv();
-  const list_keywords = ["methods", "route", "max_retry", "rpc"];
+  const list_keywords = ["methods", "route", "max_retry", "rpc", "response"];
   for (const keyword of list_keywords) {
     ajv.addKeyword(keyword);
   }