@pablozaiden/webapp 0.1.0 → 0.2.1

package/src/server/index.ts

@@ -1,5 +1,6 @@
 export * from "./runtime-config";
 export * from "./routes";
+export * from "./route-catalog";
 export * from "./responses";
 export * from "./create-web-app-server";
 export * from "./auth/store";

package/src/server/realtime/bus.ts

@@ -2,6 +2,7 @@ import type { ServerWebSocket } from "bun";
 
 export interface WebSocketData {
   filters?: Record<string, string>;
+  userId?: string;
 }
 
 export type RealtimeAction = "created" | "updated" | "changed" | "deleted";
@@ -19,6 +20,7 @@ export type RealtimeTarget = {
   resource?: string;
   id?: string;
   scope?: string;
+  userId?: string;
 } & Record<string, string | undefined>;
 
 export interface RealtimePublishOptions {
@@ -31,8 +33,12 @@ export type RealtimeMessage<TEvent> =
   | { type: "ping" }
   | { type: "pong" };
 
-function targetMatches(filters: Record<string, string> | undefined, target: RealtimeTarget | undefined): boolean {
+function targetMatches(socket: ServerWebSocket<WebSocketData>, target: RealtimeTarget | undefined): boolean {
   if (!target) return true;
+  if (target.userId !== undefined && socket.data.userId !== target.userId) {
+    return false;
+  }
+  const filters = socket.data.filters;
   if (!filters) return true;
   for (const [key, value] of Object.entries(filters)) {
     if (value !== undefined && target[key] !== value) {
@@ -57,7 +63,7 @@ export class RealtimeBus<TEvent = unknown> {
     const publishOptions = typeof options === "function" ? { filter: options } : options;
     const payload = JSON.stringify({ type: "event", event } satisfies RealtimeMessage<TEvent>);
     for (const socket of this.sockets) {
-      if (targetMatches(socket.data.filters, publishOptions?.target) && (!publishOptions?.filter || publishOptions.filter(socket))) {
+      if (targetMatches(socket, publishOptions?.target) && (!publishOptions?.filter || publishOptions.filter(socket))) {
         socket.send(payload);
       }
     }

package/src/server/route-catalog.ts

@@ -0,0 +1,147 @@
+import type { HttpMethod, RouteAuth, RouteDefinition, RouteTable, SameOriginMode } from "./routes";
+
+const HTTP_METHODS: HttpMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+export interface RouteCatalogEntry {
+  path: string;
+  cliPath: string;
+  methods: HttpMethod[];
+  auth: RouteAuth;
+  sameOrigin: SameOriginMode;
+  scopes: string[];
+  description?: string;
+  tags: string[];
+  requestSchema?: unknown;
+  querySchema?: unknown;
+  responseSchema?: unknown;
+}
+
+export interface RouteCatalogMatch {
+  entry: RouteCatalogEntry;
+  path: string;
+  params: Record<string, string>;
+}
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+
+function defaultCliPath(path: string): string {
+  return trimSlashes(path.startsWith("/api/") ? path.slice("/api/".length) : path);
+}
+
+function methodsFor(route: RouteDefinition): HttpMethod[] {
+  return HTTP_METHODS.filter((method) => typeof route[method] === "function");
+}
+
+export function createRouteCatalog<TEvent = unknown>(routes: RouteTable<TEvent>): RouteCatalogEntry[] {
+  return Object.entries(routes)
+    .filter(([, route]) => route.catalog !== false)
+    .map(([path, route]) => ({
+      path,
+      cliPath: route.cliPath ?? defaultCliPath(path),
+      methods: methodsFor(route),
+      auth: route.auth ?? "required",
+      sameOrigin: route.sameOrigin ?? "mutations",
+      scopes: route.scopes ?? [],
+      description: route.description,
+      tags: route.tags ?? [],
+      requestSchema: route.requestSchema,
+      querySchema: route.querySchema,
+      responseSchema: route.responseSchema,
+    }))
+    .filter((entry) => entry.methods.length > 0)
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function normalizeApiPath(input: string): string {
+  const [path = ""] = input.trim().split(/[?#]/);
+  if (!path) {
+    throw new Error("API endpoint is required");
+  }
+  if (path.startsWith("/api/") || path === "/api") {
+    return path;
+  }
+  if (path.startsWith("api/")) {
+    return `/${path}`;
+  }
+  if (path.startsWith("/")) {
+    return path;
+  }
+  return `/api/${path}`;
+}
+
+function normalizeCliPath(input: string): string {
+  const [path = ""] = input.trim().split(/[?#]/);
+  return trimSlashes(path.startsWith("/api/") ? path.slice("/api/".length) : path);
+}
+
+function decodePathPart(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function matchPattern(pattern: string, value: string): Record<string, string> | undefined {
+  const patternParts = trimSlashes(pattern).split("/").filter(Boolean);
+  const valueParts = trimSlashes(value).split("/").filter(Boolean);
+  if (patternParts.length !== valueParts.length) {
+    return undefined;
+  }
+  const params: Record<string, string> = {};
+  for (let index = 0; index < patternParts.length; index += 1) {
+    const patternPart = patternParts[index]!;
+    const valuePart = valueParts[index]!;
+    if (patternPart.startsWith(":")) {
+      const decoded = decodePathPart(valuePart);
+      if (decoded === undefined) {
+        return undefined;
+      }
+      params[patternPart.slice(1)] = decoded;
+      continue;
+    }
+    if (patternPart !== valuePart) {
+      return undefined;
+    }
+  }
+  return params;
+}
+
+function concretePath(pattern: string, params: Record<string, string>): string {
+  return trimSlashes(pattern)
+    .split("/")
+    .map((part) => part.startsWith(":") ? encodeURIComponent(params[part.slice(1)] ?? "") : part)
+    .join("/")
+    .replace(/^/, "/");
+}
+
+function specificity(entry: RouteCatalogEntry): number {
+  return entry.path.split("/").reduce((score, part) => score + (part && !part.startsWith(":") ? 2 : 1), 0);
+}
+
+export function findRouteCatalogEntry(catalog: readonly RouteCatalogEntry[], input: string): RouteCatalogMatch | undefined {
+  const apiPath = normalizeApiPath(input);
+  const cliPath = normalizeCliPath(input);
+  const sorted = [...catalog].sort((left, right) => specificity(right) - specificity(left));
+  for (const entry of sorted) {
+    if (entry.path === apiPath) {
+      return { entry, path: apiPath, params: {} };
+    }
+    if (entry.cliPath === cliPath) {
+      return { entry, path: entry.path, params: {} };
+    }
+  }
+  for (const entry of sorted) {
+    const apiParams = matchPattern(entry.path, apiPath);
+    if (apiParams) {
+      return { entry, path: apiPath, params: apiParams };
+    }
+    const cliParams = matchPattern(entry.cliPath, cliPath);
+    if (cliParams) {
+      return { entry, path: concretePath(entry.path, cliParams), params: cliParams };
+    }
+  }
+  return undefined;
+}

package/src/server/routes.ts

@@ -1,28 +1,59 @@
 import type { Server } from "bun";
+import type { CurrentUser } from "../contracts";
 import type { AuthenticatedRequestState } from "./auth/types";
-import type { RealtimeBus } from "./realtime/bus";
+import type { RealtimeBus, ResourceRealtimeEvent, RealtimeTarget } from "./realtime/bus";
 
-export type RouteAuth = "required" | "public" | "optional";
+export type RouteAuth = "required" | "user" | "admin" | "owner" | "public" | "optional";
 export type SameOriginMode = "mutations" | "always" | "never";
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type UserOwnedResource = { userId: string };
+export type UserIdSelector<TResource> = (resource: TResource) => string | undefined;
+
+export interface UserScopedRealtimePublisher<TEvent = unknown> {
+  publishChanged<TPayload = unknown>(resource: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action"> & { target?: RealtimeTarget }): void;
+  publishEntityChanged<TPayload = unknown>(resource: string, id: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action" | "id"> & { target?: RealtimeTarget }): void;
+  publishDeleted<TPayload = unknown>(resource: string, id: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action" | "id"> & { target?: RealtimeTarget }): void;
+  publishSettingsChanged<TPayload = unknown>(options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action"> & { target?: RealtimeTarget }): void;
+}
 
 export interface RouteContext<TParams extends Record<string, string> = Record<string, string>, TEvent = unknown> {
   params: TParams;
   auth: AuthenticatedRequestState;
+  user?: CurrentUser;
+  requireUser(): CurrentUser;
+  requireAdmin(): CurrentUser;
+  requireOwner(): CurrentUser;
+  assertUser(userId: string): CurrentUser;
+  filterOwned<TResource extends UserOwnedResource>(resources: readonly TResource[]): TResource[];
+  filterOwned<TResource>(resources: readonly TResource[], getUserId: UserIdSelector<TResource>): TResource[];
+  requireOwned<TResource extends UserOwnedResource>(resource: TResource | null | undefined): TResource;
+  requireOwned<TResource>(resource: TResource | null | undefined, getUserId: UserIdSelector<TResource>): TResource;
   realtime: RealtimeBus<TEvent>;
+  userRealtime: UserScopedRealtimePublisher<TEvent>;
   server?: Server<unknown>;
 }
 
 export type WebAppRouteHandler<TParams extends Record<string, string> = Record<string, string>, TEvent = unknown> = (
   req: Request,
   ctx: RouteContext<TParams, TEvent>,
-) => Response | Promise<Response>;
+) => Response | undefined | Promise<Response | undefined>;
+
+export interface RouteMetadata {
+  description?: string;
+  cliPath?: string;
+  tags?: string[];
+  requestSchema?: unknown;
+  querySchema?: unknown;
+  responseSchema?: unknown;
+  catalog?: boolean;
+}
 
 export type RouteDefinition<TEvent = unknown> = {
   auth?: RouteAuth;
   sameOrigin?: SameOriginMode;
   scopes?: string[];
-} & Partial<Record<HttpMethod, WebAppRouteHandler<Record<string, string>, TEvent>>>;
+  userParam?: string;
+} & RouteMetadata & Partial<Record<HttpMethod, WebAppRouteHandler<Record<string, string>, TEvent>>>;
 
 export type RouteTable<TEvent = unknown> = Record<string, RouteDefinition<TEvent>>;
 

package/src/server/runtime-config.ts

@@ -70,7 +70,7 @@ export function readRuntimeConfig(input: {
   return {
     appName: input.appName,
     envPrefix,
-    host: readEnv(envPrefix, "HOST") || "127.0.0.1",
+    host: readEnv(envPrefix, "HOST") || "localhost",
     port: parsePort(readEnv(envPrefix, "PORT"), envName(envPrefix, "PORT")),
     dataDir: readEnv(envPrefix, "DATA_DIR") || "./data",
     logLevel,