[CX-5445] document http routing with pathPrefix (#24832)

Modifying our `http` demo to include an http action that fetches messages by author, determining the author id using the **request path suffix**, and a new route to it, to use as an example of using `pathPrefix` in routing.
Also adding some typedocs to include documentation of `RouteSpec` in docs.

GitOrigin-RevId: a4fb00fe2efa83bb5fdc82079015d47839ad7a39

Author: pashabitz

npm-packages/convex/src/server/index.ts

@@ -131,7 +131,12 @@ export type {
   IndexTiebreakerField,
 } from "./system_fields.js";
 export { httpRouter, HttpRouter, ROUTABLE_HTTP_METHODS } from "./router.js";
-export type { RoutableMethod } from "./router.js";
+export type {
+  RoutableMethod,
+  RouteSpec,
+  RouteSpecWithPath,
+  RouteSpecWithPathPrefix,
+} from "./router.js";
 export {
   anyApi,
   getFunctionName,

npm-packages/convex/src/server/router.ts

@@ -46,17 +46,59 @@ export function normalizeMethod(
  */
 export const httpRouter = () => new HttpRouter();
 
-type RouteSpec =
-  | {
-      path: string;
-      method: RoutableMethod;
-      handler: PublicHttpAction;
-    }
-  | {
-      pathPrefix: string;
-      method: RoutableMethod;
-      handler: PublicHttpAction;
-    };
+/**
+ * A type representing a route to an HTTP action using an exact request URL path match.
+ *
+ * Used by {@link HttpRouter} to route requests to HTTP actions.
+ *
+ * @public
+ */
+export type RouteSpecWithPath = {
+  /**
+   * Exact HTTP request path to route.
+   */
+  path: string;
+  /**
+   * HTTP method ("GET", "POST", ...) to route.
+   */
+  method: RoutableMethod;
+  /**
+   * The HTTP action to execute.
+   */
+  handler: PublicHttpAction;
+};
+
+/**
+ * A type representing a route to an HTTP action using a request URL path prefix match.
+ *
+ * Used by {@link HttpRouter} to route requests to HTTP actions.
+ *
+ * @public
+ */
+export type RouteSpecWithPathPrefix = {
+  /**
+   * An HTTP request path prefix to route. Requests with a path starting with this value
+   * will be routed to the HTTP action.
+   */
+  pathPrefix: string;
+  /**
+   * HTTP method ("GET", "POST", ...) to route.
+   */
+  method: RoutableMethod;
+  /**
+   * The HTTP action to execute.
+   */
+  handler: PublicHttpAction;
+};
+
+/**
+ * A type representing a route to an HTTP action.
+ *
+ * Used by {@link HttpRouter} to route requests to HTTP actions.
+ *
+ * @public
+ */
+export type RouteSpec = RouteSpecWithPath | RouteSpecWithPathPrefix;
 
 /**
  * HTTP router for specifying the paths and methods of {@link httpActionGeneric}s
@@ -152,7 +194,9 @@ export class HttpRouter {
       this.exactRoutes.set(spec.path, methods);
     } else if ("pathPrefix" in spec) {
       if (!spec.pathPrefix.startsWith("/")) {
-        throw new Error(`path '${spec.pathPrefix}' does not start with a /`);
+        throw new Error(
+          `pathPrefix '${spec.pathPrefix}' does not start with a /`,
+        );
       }
       if (!spec.pathPrefix.endsWith("/")) {
         throw new Error(`pathPrefix ${spec.pathPrefix} must end with a /`);