@enderworld/onlyapi 1.5.1

package/src/presentation/handlers/sse.handler.ts

@@ -0,0 +1,165 @@
+/**
+ * Server-Sent Events (SSE) handler — streaming endpoint for real-time updates.
+ *
+ * Clients connect to GET /api/v1/events/stream with optional query params:
+ * - token: JWT for authentication (required)
+ * - events: comma-separated event types to subscribe to (default: all)
+ *
+ * Protocol: standard SSE (text/event-stream), each event is:
+ *   event: <type>
+ *   id: <eventId>
+ *   data: <JSON payload>
+ *
+ * Heartbeat "ping" comments sent every 30s to keep the connection alive.
+ */
+
+import type { DomainEvent, EventBus } from "../../core/ports/event-bus.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenService } from "../../core/ports/token-service.js";
+import type { RequestContext } from "../context.js";
+
+interface SseHandlerDeps {
+  readonly tokenService: TokenService;
+  readonly eventBus: EventBus;
+  readonly logger: Logger;
+}
+
+interface SseConnection {
+  readonly id: string;
+  readonly controller: ReadableStreamDefaultController;
+  readonly unsubscribe: () => void;
+  readonly heartbeat: ReturnType<typeof setInterval>;
+}
+
+export interface SseHandler {
+  /** Handle SSE connection request */
+  stream(req: Request, ctx: RequestContext): Promise<Response>;
+  /** Number of active SSE connections */
+  readonly connectionCount: number;
+}
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+const encoder = new TextEncoder();
+
+const formatSseMessage = (event: DomainEvent): string => {
+  const data = JSON.stringify({
+    id: event.id,
+    type: event.type,
+    timestamp: event.timestamp,
+    payload: event.payload,
+  });
+  return `event: ${event.type}\nid: ${event.id}\ndata: ${data}\n\n`;
+};
+
+export const createSseHandler = (deps: SseHandlerDeps): SseHandler => {
+  const { tokenService, eventBus, logger } = deps;
+
+  const connections = new Map<string, SseConnection>();
+
+  return {
+    async stream(req: Request, ctx: RequestContext): Promise<Response> {
+      // Authenticate via query param or Authorization header
+      const url = new URL(req.url);
+      const token =
+        url.searchParams.get("token") ?? req.headers.get("authorization")?.replace("Bearer ", "");
+
+      if (!token) {
+        return new Response(
+          JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Missing token" } }),
+          { status: 401, headers: { "Content-Type": "application/json" } },
+        );
+      }
+
+      const authResult = await tokenService.verify(token);
+      if (!authResult.ok) {
+        return new Response(
+          JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Invalid token" } }),
+          { status: 401, headers: { "Content-Type": "application/json" } },
+        );
+      }
+
+      // Parse event filter
+      const eventFilter = url.searchParams.get("events");
+      const subscribedEvents = eventFilter
+        ? new Set(eventFilter.split(",").map((e) => e.trim()))
+        : null;
+
+      const connectionId = ctx.requestId as string;
+
+      const stream = new ReadableStream({
+        start(controller) {
+          // Send initial connection message
+          controller.enqueue(
+            encoder.encode(
+              `: connected\nevent: connected\ndata: ${JSON.stringify({ connectionId })}\n\n`,
+            ),
+          );
+
+          // Subscribe to events
+          const handler = (event: DomainEvent): void => {
+            if (subscribedEvents && !subscribedEvents.has(event.type)) return;
+            try {
+              controller.enqueue(encoder.encode(formatSseMessage(event)));
+            } catch {
+              // Stream may have closed
+            }
+          };
+
+          // Subscribe to all events (filtering done in handler)
+          const unsubscribe = eventBus.subscribeAll(handler);
+
+          // Heartbeat to keep connection alive
+          const heartbeat = setInterval(() => {
+            try {
+              controller.enqueue(encoder.encode(": heartbeat\n\n"));
+            } catch {
+              // Stream closed
+            }
+          }, HEARTBEAT_INTERVAL_MS);
+
+          connections.set(connectionId, {
+            id: connectionId,
+            controller,
+            unsubscribe,
+            heartbeat,
+          });
+
+          logger.debug("SSE client connected", {
+            connectionId,
+            userId: authResult.value.sub,
+            events: subscribedEvents ? [...subscribedEvents] : "*",
+            totalConnections: connections.size,
+          });
+        },
+
+        cancel() {
+          const conn = connections.get(connectionId);
+          if (conn) {
+            conn.unsubscribe();
+            clearInterval(conn.heartbeat);
+            connections.delete(connectionId);
+          }
+          logger.debug("SSE client disconnected", {
+            connectionId,
+            totalConnections: connections.size,
+          });
+        },
+      });
+
+      return new Response(stream, {
+        status: 200,
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+          "X-Accel-Buffering": "no", // Disable Nginx buffering
+        },
+      });
+    },
+
+    get connectionCount(): number {
+      return connections.size;
+    },
+  };
+};

package/src/presentation/handlers/user.handler.ts

@@ -0,0 +1,81 @@
+import { updateUserDto } from "../../application/dtos/auth.dto.js";
+import type { UserService } from "../../application/services/user.service.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenService } from "../../core/ports/token-service.js";
+import type { RequestContext } from "../context.js";
+import { authenticate } from "../middleware/auth.js";
+import { validateBody } from "../middleware/validate.js";
+import { errorResponse, jsonResponse, noContentResponse } from "./response.js";
+
+export const userHandlers = (
+  userService: UserService,
+  tokenService: TokenService,
+  logger: Logger,
+) => ({
+  getMe: async (req: Request, ctx: RequestContext): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) {
+      logger.warn("Auth failed on getMe", {
+        requestId: ctx.requestId,
+        code: authResult.error.code,
+      });
+      return errorResponse(authResult.error, ctx.requestId);
+    }
+
+    const result = await userService.getById(authResult.value.sub);
+    if (!result.ok) {
+      logger.warn("getMe failed", { requestId: ctx.requestId, code: result.error.code });
+      return errorResponse(result.error, ctx.requestId);
+    }
+
+    return jsonResponse(result.value);
+  },
+
+  updateMe: async (req: Request, ctx: RequestContext): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) {
+      logger.warn("Auth failed on updateMe", {
+        requestId: ctx.requestId,
+        code: authResult.error.code,
+      });
+      return errorResponse(authResult.error, ctx.requestId);
+    }
+
+    const body = await req.json().catch(() => null);
+    const validated = validateBody(updateUserDto, body);
+    if (!validated.ok) {
+      logger.warn("Update validation failed", {
+        requestId: ctx.requestId,
+        code: validated.error.code,
+      });
+      return errorResponse(validated.error, ctx.requestId);
+    }
+
+    const result = await userService.update(authResult.value.sub, validated.value);
+    if (!result.ok) {
+      logger.warn("updateMe failed", { requestId: ctx.requestId, code: result.error.code });
+      return errorResponse(result.error, ctx.requestId);
+    }
+
+    return jsonResponse(result.value);
+  },
+
+  deleteMe: async (req: Request, ctx: RequestContext): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) {
+      logger.warn("Auth failed on deleteMe", {
+        requestId: ctx.requestId,
+        code: authResult.error.code,
+      });
+      return errorResponse(authResult.error, ctx.requestId);
+    }
+
+    const result = await userService.remove(authResult.value.sub);
+    if (!result.ok) {
+      logger.warn("deleteMe failed", { requestId: ctx.requestId, code: result.error.code });
+      return errorResponse(result.error, ctx.requestId);
+    }
+
+    return noContentResponse();
+  },
+});

package/src/presentation/handlers/webhook.handler.ts

@@ -0,0 +1,92 @@
+/**
+ * Webhook management API handlers.
+ *
+ * POST   /api/v1/webhooks       — Create a webhook subscription
+ * GET    /api/v1/webhooks       — List webhook subscriptions
+ * DELETE /api/v1/webhooks/:id   — Remove a webhook subscription
+ */
+
+import { UserRole } from "../../core/entities/user.entity.js";
+import type { DomainEventType } from "../../core/ports/event-bus.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenService } from "../../core/ports/token-service.js";
+import type { WebhookRegistry } from "../../core/ports/webhook.js";
+import type { RequestContext } from "../context.js";
+import { authenticate, authorise } from "../middleware/auth.js";
+import { errorResponse, jsonResponse } from "./response.js";
+
+export const webhookHandlers = (
+  registry: WebhookRegistry,
+  tokenService: TokenService,
+  logger: Logger,
+) => {
+  const requireAdmin = async (req: Request, _ctx: RequestContext) => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) return authResult;
+    return authorise(authResult.value, [UserRole.ADMIN]);
+  };
+
+  return {
+    async create(req: Request, ctx: RequestContext): Promise<Response> {
+      const authResult = await requireAdmin(req, ctx);
+      if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+      const body = (await req.json().catch(() => null)) as {
+        url?: string;
+        events?: string[];
+        secret?: string;
+      } | null;
+
+      if (!body || !body.url || typeof body.url !== "string") {
+        return errorResponse(
+          { code: "VALIDATION" as const, message: "url is required" },
+          ctx.requestId,
+        );
+      }
+      if (!body.secret || typeof body.secret !== "string") {
+        return errorResponse(
+          { code: "VALIDATION" as const, message: "secret is required" },
+          ctx.requestId,
+        );
+      }
+
+      const events = body.events ?? [];
+      const result = registry.create({
+        url: body.url,
+        events: events as ReadonlyArray<DomainEventType>,
+        secret: body.secret,
+      });
+
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      logger.info("Webhook subscription created", {
+        webhookId: result.value.id,
+        url: result.value.url,
+        events,
+      });
+
+      return Response.json({ data: result.value }, { status: 201 });
+    },
+
+    async list(req: Request, ctx: RequestContext): Promise<Response> {
+      const authResult = await requireAdmin(req, ctx);
+      if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+      const result = registry.list();
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return jsonResponse({ webhooks: result.value });
+    },
+
+    async remove(req: Request, ctx: RequestContext, webhookId: string): Promise<Response> {
+      const authResult = await requireAdmin(req, ctx);
+      if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+      const result = registry.remove(webhookId);
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      logger.info("Webhook subscription removed", { webhookId });
+      return jsonResponse({ deleted: true });
+    },
+  };
+};

package/src/presentation/handlers/websocket.handler.ts

@@ -0,0 +1,226 @@
+/**
+ * WebSocket manager — handles Bun-native WebSocket connections.
+ *
+ * Supports:
+ * - Connection lifecycle (open, close, message)
+ * - Per-connection authentication (JWT in query string or first message)
+ * - Topic-based pub/sub (subscribe to event types)
+ * - Broadcasting domain events to subscribed clients
+ */
+
+import type { ServerWebSocket } from "bun";
+import type { DomainEvent, EventBus } from "../../core/ports/event-bus.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenPayload, TokenService } from "../../core/ports/token-service.js";
+
+export interface WsConnectionData {
+  readonly id: string;
+  auth: TokenPayload | null;
+  readonly connectedAt: number;
+  readonly ip: string;
+  subscriptions: Set<string>;
+}
+
+export interface WebSocketManager {
+  /** Handle WebSocket upgrade request. Returns upgrade data or null if rejected. */
+  handleUpgrade(req: Request, ip: string): WsConnectionData | null;
+
+  /** Called when a WebSocket connection opens */
+  onOpen(ws: ServerWebSocket<WsConnectionData>): void;
+
+  /** Called when a message is received */
+  onMessage(ws: ServerWebSocket<WsConnectionData>, message: string | Buffer): void;
+
+  /** Called when a WebSocket connection closes */
+  onClose(ws: ServerWebSocket<WsConnectionData>, code: number, reason: string): void;
+
+  /** Broadcast a domain event to all subscribed WebSocket clients */
+  broadcast(event: DomainEvent): void;
+
+  /** Number of active connections */
+  readonly connectionCount: number;
+}
+
+interface WsManagerDeps {
+  readonly tokenService: TokenService;
+  readonly eventBus: EventBus;
+  readonly logger: Logger;
+}
+
+/**
+ * Client-to-server message protocol:
+ *
+ * { "type": "auth", "token": "<JWT>" }
+ * { "type": "subscribe", "events": ["user.registered", "login.failed"] }
+ * { "type": "unsubscribe", "events": ["user.registered"] }
+ * { "type": "ping" }
+ *
+ * Server-to-client message protocol:
+ *
+ * { "type": "auth", "ok": true, "userId": "..." }
+ * { "type": "auth", "ok": false, "error": "Invalid token" }
+ * { "type": "subscribed", "events": ["user.registered"] }
+ * { "type": "event", "event": { ... } }
+ * { "type": "pong" }
+ * { "type": "error", "message": "..." }
+ */
+
+interface ClientMessage {
+  readonly type: string;
+  readonly token?: string | undefined;
+  readonly events?: ReadonlyArray<string> | undefined;
+}
+
+export const createWebSocketManager = (deps: WsManagerDeps): WebSocketManager => {
+  const { tokenService, logger } = deps;
+
+  const connections = new Set<ServerWebSocket<WsConnectionData>>();
+
+  const sendJson = (ws: ServerWebSocket<WsConnectionData>, data: Record<string, unknown>): void => {
+    try {
+      ws.send(JSON.stringify(data));
+    } catch {
+      // Connection may have closed
+    }
+  };
+
+  const authenticateToken = async (token: string): Promise<TokenPayload | null> => {
+    const result = await tokenService.verify(token);
+    return result.ok ? result.value : null;
+  };
+
+  return {
+    handleUpgrade(req: Request, ip: string): WsConnectionData | null {
+      // Extract token from query string for initial auth (optional)
+      const url = new URL(req.url);
+      const token = url.searchParams.get("token");
+
+      const data: WsConnectionData = {
+        id: crypto.randomUUID(),
+        auth: null,
+        connectedAt: Date.now(),
+        ip,
+        subscriptions: new Set(),
+      };
+
+      // If token provided in URL, validate later in onOpen
+      if (token) {
+        // Store token temporarily — will authenticate in onOpen
+        (data as { auth: TokenPayload | null }).auth = null;
+      }
+
+      return data;
+    },
+
+    onOpen(ws: ServerWebSocket<WsConnectionData>): void {
+      connections.add(ws);
+      logger.debug("WebSocket connected", {
+        connectionId: ws.data.id,
+        ip: ws.data.ip,
+        totalConnections: connections.size,
+      });
+
+      sendJson(ws, {
+        type: "connected",
+        connectionId: ws.data.id,
+        message: 'Authenticate with { "type": "auth", "token": "<JWT>" }',
+      });
+    },
+
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: WebSocket message handling has many branches
+    onMessage(ws: ServerWebSocket<WsConnectionData>, message: string | Buffer): void {
+      const raw = typeof message === "string" ? message : message.toString();
+
+      let msg: ClientMessage;
+      try {
+        msg = JSON.parse(raw) as ClientMessage;
+      } catch {
+        sendJson(ws, { type: "error", message: "Invalid JSON" });
+        return;
+      }
+
+      switch (msg.type) {
+        case "ping":
+          sendJson(ws, { type: "pong" });
+          break;
+
+        case "auth": {
+          if (!msg.token) {
+            sendJson(ws, { type: "auth", ok: false, error: "Missing token" });
+            return;
+          }
+          authenticateToken(msg.token).then((payload) => {
+            if (payload) {
+              ws.data.auth = payload;
+              sendJson(ws, { type: "auth", ok: true, userId: payload.sub });
+              logger.debug("WebSocket authenticated", {
+                connectionId: ws.data.id,
+                userId: payload.sub,
+              });
+            } else {
+              sendJson(ws, { type: "auth", ok: false, error: "Invalid token" });
+            }
+          });
+          break;
+        }
+
+        case "subscribe": {
+          if (!ws.data.auth) {
+            sendJson(ws, { type: "error", message: "Not authenticated" });
+            return;
+          }
+          const events = msg.events ?? [];
+          for (const event of events) {
+            ws.data.subscriptions.add(event);
+          }
+          sendJson(ws, { type: "subscribed", events: [...ws.data.subscriptions] });
+          break;
+        }
+
+        case "unsubscribe": {
+          const events = msg.events ?? [];
+          for (const event of events) {
+            ws.data.subscriptions.delete(event);
+          }
+          sendJson(ws, { type: "subscribed", events: [...ws.data.subscriptions] });
+          break;
+        }
+
+        default:
+          sendJson(ws, { type: "error", message: `Unknown message type: ${msg.type}` });
+      }
+    },
+
+    onClose(ws: ServerWebSocket<WsConnectionData>, code: number, reason: string): void {
+      connections.delete(ws);
+      logger.debug("WebSocket disconnected", {
+        connectionId: ws.data.id,
+        code,
+        reason,
+        totalConnections: connections.size,
+      });
+    },
+
+    broadcast(event: DomainEvent): void {
+      const payload = JSON.stringify({ type: "event", event });
+
+      for (const ws of connections) {
+        // Only send to authenticated clients subscribed to this event type
+        if (
+          ws.data.auth &&
+          (ws.data.subscriptions.has(event.type) || ws.data.subscriptions.has("*"))
+        ) {
+          try {
+            ws.send(payload);
+          } catch {
+            // Connection may have closed
+          }
+        }
+      }
+    },
+
+    get connectionCount(): number {
+      return connections.size;
+    },
+  };
+};