@luckystack/sync 0.1.0

package/dist/index.js

@@ -0,0 +1,1203 @@
+// src/handleSyncRequest.ts
+import { getSession } from "@luckystack/login";
+import { getProjectConfig as getProjectConfig2 } from "@luckystack/core";
+import { getRuntimeSyncMaps } from "@luckystack/core";
+import {
+  validateRequest,
+  extractTokenFromSocket,
+  getIoInstance as getIoInstance2,
+  tryCatch,
+  parseTransportRouteName,
+  checkRateLimit,
+  buildSyncProgressEventName,
+  buildSyncResponseEventName,
+  socketEventNames as socketEventNames2,
+  dispatchHook as dispatchHook2,
+  validateInputByType,
+  getLogger as getLogger2
+} from "@luckystack/core";
+import { extractLanguageFromHeader, normalizeErrorResponse, applyErrorFormatter } from "@luckystack/core";
+
+// src/_shared/streamEmitters.ts
+import {
+  dispatchHook,
+  getIoInstance,
+  getLogger,
+  getProjectConfig,
+  socketEventNames
+} from "@luckystack/core";
+var chunkCounters = /* @__PURE__ */ new Map();
+var counterKey = (routeName, recipient) => `${routeName}|${recipient}`;
+var bumpChunkIndex = (routeName, recipient) => {
+  const key = counterKey(routeName, recipient);
+  const next = (chunkCounters.get(key) ?? 0) + 1;
+  chunkCounters.set(key, next);
+  return next;
+};
+var dispatchStreamHooks = (routeName, recipient, chunk) => {
+  void dispatchHook("preSyncStream", { routeName, chunk, recipient });
+  const chunkIndex = bumpChunkIndex(routeName, recipient);
+  void dispatchHook("postSyncStream", { routeName, chunk, recipient, chunkIndex });
+};
+var shouldLogStream = () => getProjectConfig().logging.stream;
+var DEFAULT_THRESHOLD_BYTES = 1048576;
+var AVG_PACKET_BYTES = 1024;
+var POLL_INTERVAL_MS = 10;
+var MAX_SOCKETS_FOR_PRESSURE_SAMPLE = 32;
+var isEngineConnLike = (value) => typeof value === "object" && value !== null;
+var readSocketPressure = (socket) => {
+  const maybeConn = socket.conn;
+  if (!isEngineConnLike(maybeConn)) return { packets: 0, writable: true };
+  const packets = maybeConn.writeBuffer?.length ?? 0;
+  const writable = maybeConn.transport?.writable ?? true;
+  return { packets, writable };
+};
+var waitUntilSocketDrained = async (socket, packetThreshold, isAborted) => {
+  let { packets, writable } = readSocketPressure(socket);
+  while (writable && packets >= packetThreshold && !isAborted()) {
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    ({ packets, writable } = readSocketPressure(socket));
+  }
+};
+var collectRoomSocketsForPressure = (receiver) => {
+  const io = getIoInstance();
+  if (!io) return [];
+  if (!receiver) return [];
+  if (receiver === "all") {
+    const out2 = [];
+    let i2 = 0;
+    for (const [, sock] of io.sockets.sockets) {
+      if (i2 >= MAX_SOCKETS_FOR_PRESSURE_SAMPLE) break;
+      out2.push(sock);
+      i2++;
+    }
+    return out2;
+  }
+  const ids = io.sockets.adapter.rooms.get(receiver);
+  if (!ids || ids.size === 0) return [];
+  const out = [];
+  let i = 0;
+  for (const id of ids) {
+    if (i >= MAX_SOCKETS_FOR_PRESSURE_SAMPLE) break;
+    const sock = io.sockets.sockets.get(id);
+    if (sock) out.push(sock);
+    i++;
+  }
+  return out;
+};
+var buildSyncStreamEmitters = ({
+  cb,
+  receiver,
+  resolvedName,
+  emitOriginatorChunk,
+  logLabel,
+  signal,
+  originatorSocket
+}) => {
+  const buildBroadcastFrame = (payload) => ({
+    ...payload,
+    cb,
+    fullName: resolvedName,
+    status: "stream"
+  });
+  const isAborted = () => signal?.aborted === true;
+  const logAbortedDrop = (kind) => {
+    if (shouldLogStream()) {
+      getLogger().debug(`${logLabel}: ${resolvedName} ${kind} skipped \u2014 request aborted`);
+    }
+  };
+  const emitServerSyncStream = (payload = {}) => {
+    if (isAborted()) {
+      logAbortedDrop("server stream");
+      return;
+    }
+    if (shouldLogStream()) {
+      getLogger().debug(`${logLabel}: ${resolvedName} server stream`, { payload });
+    }
+    dispatchStreamHooks(resolvedName, "originator", payload);
+    emitOriginatorChunk(payload);
+  };
+  const emitBroadcastSyncStream = (payload = {}) => {
+    if (isAborted()) {
+      logAbortedDrop("broadcastStream");
+      return;
+    }
+    if (shouldLogStream()) {
+      getLogger().debug(`${logLabel}: ${resolvedName} broadcastStream`, { payload });
+    }
+    if (!receiver) return;
+    const io = getIoInstance();
+    if (!io) return;
+    dispatchStreamHooks(resolvedName, receiver, payload);
+    io.to(receiver).emit(socketEventNames.sync, buildBroadcastFrame(payload));
+  };
+  const emitStreamToTokens = (tokens, payload = {}) => {
+    if (isAborted()) {
+      logAbortedDrop("streamTo");
+      return;
+    }
+    const list = Array.isArray(tokens) ? tokens : [tokens];
+    const filtered = list.filter((t) => typeof t === "string" && t.length > 0);
+    if (filtered.length === 0) return;
+    if (shouldLogStream()) {
+      getLogger().debug(`${logLabel}: ${resolvedName} streamTo`, { tokens: filtered, payload });
+    }
+    const io = getIoInstance();
+    if (!io) return;
+    for (const recipient of filtered) {
+      dispatchStreamHooks(resolvedName, recipient, payload);
+    }
+    const frame = buildBroadcastFrame(payload);
+    io.to(filtered).emit(socketEventNames.sync, frame);
+  };
+  const flushPressure = async ({ thresholdBytes } = {}) => {
+    if (isAborted()) return;
+    const effectiveThresholdBytes = typeof thresholdBytes === "number" && thresholdBytes > 0 ? thresholdBytes : DEFAULT_THRESHOLD_BYTES;
+    const packetThreshold = Math.max(1, Math.ceil(effectiveThresholdBytes / AVG_PACKET_BYTES));
+    const targets = [];
+    if (originatorSocket) targets.push(originatorSocket);
+    for (const sock of collectRoomSocketsForPressure(receiver)) {
+      if (sock !== originatorSocket) targets.push(sock);
+    }
+    if (targets.length === 0) return;
+    await Promise.all(targets.map((sock) => waitUntilSocketDrained(sock, packetThreshold, isAborted)));
+  };
+  return {
+    emitServerSyncStream,
+    emitBroadcastSyncStream,
+    emitStreamToTokens,
+    buildBroadcastFrame,
+    flushPressure
+  };
+};
+
+// src/handleSyncRequest.ts
+import {
+  registerSyncAbortController,
+  unregisterSyncAbortController
+} from "@luckystack/core";
+var shouldLogDev = () => getProjectConfig2().logging.devLogs;
+var shouldLogStream2 = () => getProjectConfig2().logging.stream;
+var applySyncRateLimits = async ({
+  resolvedName,
+  token,
+  socket,
+  user,
+  responseIndex,
+  buildSyncError,
+  preferredLocale
+}) => {
+  const config = getProjectConfig2();
+  const defaultApiLimit = config.rateLimiting.defaultApiLimit;
+  if (defaultApiLimit !== false && defaultApiLimit > 0) {
+    const requesterIdentity = token ?? socket.handshake.address ?? "unknown";
+    const keyPrefix = token ? "token" : "ip";
+    const rateLimitKey = `${keyPrefix}:${requesterIdentity}:sync:${resolvedName}`;
+    const { allowed, resetIn } = await checkRateLimit({
+      key: rateLimitKey,
+      limit: defaultApiLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook2("rateLimitExceeded", {
+        scope: token ? "user" : "route",
+        key: rateLimitKey,
+        limit: defaultApiLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: defaultApiLimit + 1,
+        route: resolvedName,
+        userId: user?.id
+      });
+      if (typeof responseIndex === "number") {
+        socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+          response: {
+            status: "error",
+            errorCode: "sync.rateLimitExceeded",
+            errorParams: [{ key: "seconds", value: resetIn }],
+            httpStatus: 429
+          },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        }));
+      }
+      return false;
+    }
+  }
+  const defaultIpLimit = config.rateLimiting.defaultIpLimit;
+  if (defaultIpLimit !== false && defaultIpLimit > 0) {
+    const requesterIp = socket.handshake.address ?? "unknown";
+    const ipKey = `ip:${requesterIp}:sync:all`;
+    const { allowed, resetIn } = await checkRateLimit({
+      key: ipKey,
+      limit: defaultIpLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook2("rateLimitExceeded", {
+        scope: "ip",
+        key: ipKey,
+        limit: defaultIpLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: defaultIpLimit + 1,
+        ip: requesterIp
+      });
+      if (typeof responseIndex === "number") {
+        socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+          response: {
+            status: "error",
+            errorCode: "sync.rateLimitExceeded",
+            errorParams: [{ key: "seconds", value: resetIn }],
+            httpStatus: 429
+          },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        }));
+      }
+      return false;
+    }
+  }
+  return true;
+};
+async function handleSyncRequest({ msg, socket, token }) {
+  const ioInstance = getIoInstance2();
+  if (!ioInstance) {
+    return;
+  }
+  if (typeof msg != "object") {
+    if (shouldLogDev()) {
+      getLogger2().warn("sync: socket message was not a json object");
+    }
+    const normalized = normalizeErrorResponse({
+      response: { status: "error", errorCode: "sync.invalidRequest" },
+      preferredLocale: extractLanguageFromHeader(socket.handshake.headers["x-language"]) || extractLanguageFromHeader(socket.handshake.headers["accept-language"])
+    });
+    return socket.emit(socketEventNames2.sync, {
+      status: normalized.status,
+      message: normalized.message,
+      errorCode: normalized.errorCode,
+      errorParams: normalized.errorParams,
+      httpStatus: normalized.httpStatus
+    });
+  }
+  const { name, data, cb, receiver: rawReceiver, responseIndex, ignoreSelf } = msg;
+  const receiver = typeof rawReceiver === "string" ? rawReceiver.trim() : "";
+  const preferredLocale = extractLanguageFromHeader(socket.handshake.headers["x-language"]) || extractLanguageFromHeader(socket.handshake.headers["accept-language"]);
+  let currentRouteName;
+  let currentPerRouteFormatter;
+  let currentUserId;
+  const buildSyncError = ({
+    response,
+    preferred,
+    userLanguage
+  }) => {
+    const normalized = normalizeErrorResponse({
+      response,
+      preferredLocale: preferred,
+      userLanguage
+    });
+    const baseEnvelope = {
+      status: normalized.status,
+      message: normalized.message,
+      errorCode: normalized.errorCode,
+      errorParams: normalized.errorParams,
+      httpStatus: normalized.httpStatus
+    };
+    return applyErrorFormatter({
+      response: baseEnvelope,
+      routeName: currentRouteName ?? "sync/unknown",
+      transport: "socket",
+      userId: currentUserId,
+      perRouteFormatter: currentPerRouteFormatter
+    });
+  };
+  const ensureSyncErrorShape = (response) => {
+    if (typeof response.errorCode === "string" && response.errorCode.trim().length > 0) {
+      return response;
+    }
+    return {
+      ...response,
+      errorCode: "sync.clientRejected"
+    };
+  };
+  if (!name || !data || typeof name != "string" || typeof data != "object") {
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: { status: "error", errorCode: "sync.invalidRequest" },
+      preferred: preferredLocale
+    }));
+  }
+  const normalizedData = data;
+  const parsedRoute = parseTransportRouteName({ value: name, prefix: "sync" });
+  if (parsedRoute.status === "error") {
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: {
+        status: "error",
+        errorCode: "routing.invalidServiceRouteName",
+        errorParams: [{ key: "name", value: name }]
+      },
+      preferred: preferredLocale
+    }));
+  }
+  const resolvedName = parsedRoute.normalizedFullName;
+  currentRouteName = resolvedName;
+  if (!cb || typeof cb != "string") {
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: { status: "error", errorCode: "sync.invalidCallback" },
+      preferred: preferredLocale
+    }));
+  }
+  if (!receiver) {
+    if (shouldLogDev()) {
+      getLogger2().warn("sync: missing receiver / roomCode", { receiver });
+    }
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: { status: "error", errorCode: "sync.missingReceiver" },
+      preferred: preferredLocale
+    }));
+  }
+  if (shouldLogDev()) {
+    getLogger2().debug(`sync: ${resolvedName} called`, { sync: resolvedName });
+  }
+  const user = await getSession(token);
+  currentUserId = user?.id;
+  const { syncObject, functionsObject } = await getRuntimeSyncMaps();
+  const abortController = new AbortController();
+  const abortKey = registerSyncAbortController(socket.id, cb, abortController);
+  const onSocketDisconnect = () => {
+    abortController.abort();
+  };
+  socket.once(socketEventNames2.disconnect, onSocketDisconnect);
+  let cleanupDone = false;
+  const cleanupRequest = () => {
+    if (cleanupDone) return;
+    cleanupDone = true;
+    socket.off(socketEventNames2.disconnect, onSocketDisconnect);
+    unregisterSyncAbortController(abortKey);
+  };
+  if (!syncObject[`${resolvedName}_client`] && !syncObject[`${resolvedName}_server`]) {
+    if (shouldLogDev()) {
+      getLogger2().warn(`sync: ${name} has no _client or _server file`, { sync: name });
+    }
+    cleanupRequest();
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: { status: "error", errorCode: "sync.notFound" },
+      preferred: preferredLocale,
+      userLanguage: user?.language
+    }));
+  }
+  const { emitServerSyncStream, emitBroadcastSyncStream, emitStreamToTokens, flushPressure } = buildSyncStreamEmitters({
+    cb,
+    receiver,
+    resolvedName,
+    logLabel: "sync",
+    signal: abortController.signal,
+    originatorSocket: socket,
+    emitOriginatorChunk: (payload) => {
+      if (typeof responseIndex !== "number") return;
+      socket.emit(buildSyncProgressEventName(responseIndex), payload);
+    }
+  });
+  const serverSyncEntry = syncObject[`${resolvedName}_server`];
+  currentPerRouteFormatter = serverSyncEntry?.errorFormatter;
+  if (serverSyncEntry) {
+    const { auth } = serverSyncEntry;
+    if (auth.login && !user?.id) {
+      if (shouldLogDev()) {
+        getLogger2().warn(`sync: ${resolvedName} requires login`, { sync: resolvedName });
+      }
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+        response: { status: "error", errorCode: "auth.required" },
+        preferred: preferredLocale
+      }));
+    }
+    const validationResult = validateRequest({ auth, user });
+    if (validationResult.status === "error") {
+      if (shouldLogDev()) {
+        getLogger2().warn(`sync: auth failed for ${resolvedName}`, { sync: resolvedName, errorCode: validationResult.errorCode });
+      }
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+        response: {
+          status: "error",
+          errorCode: validationResult.errorCode || "auth.forbidden",
+          errorParams: validationResult.errorParams,
+          httpStatus: validationResult.httpStatus
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      }));
+    }
+  }
+  const preAuthorizeResult = await dispatchHook2("preSyncAuthorize", {
+    routeName: resolvedName,
+    data: normalizedData,
+    user,
+    receiver,
+    transport: "socket"
+  });
+  if (preAuthorizeResult.stopped) {
+    if (shouldLogDev()) {
+      getLogger2().warn(`sync: preSyncAuthorize stopped ${resolvedName}`, { sync: resolvedName, errorCode: preAuthorizeResult.signal.errorCode });
+    }
+    cleanupRequest();
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: {
+        status: "error",
+        errorCode: preAuthorizeResult.signal.errorCode,
+        httpStatus: preAuthorizeResult.signal.httpStatus
+      },
+      preferred: preferredLocale,
+      userLanguage: user?.language
+    }));
+  }
+  void dispatchHook2("postSyncAuthorize", {
+    routeName: resolvedName,
+    data: normalizedData,
+    user,
+    receiver,
+    transport: "socket"
+  });
+  const rateLimitOk = await applySyncRateLimits({
+    resolvedName,
+    token,
+    socket,
+    user,
+    responseIndex,
+    buildSyncError,
+    preferredLocale
+  });
+  if (!rateLimitOk) {
+    cleanupRequest();
+    return;
+  }
+  let serverOutput = {};
+  if (serverSyncEntry) {
+    const { main: serverMain, inputType, inputTypeFilePath } = serverSyncEntry;
+    const inputValidation = await validateInputByType({
+      typeText: inputType,
+      value: normalizedData,
+      rootKey: "clientInput",
+      filePath: inputTypeFilePath
+    });
+    if (inputValidation.status === "error") {
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+        response: {
+          status: "error",
+          errorCode: "sync.invalidInputType",
+          errorParams: [{ key: "message", value: inputValidation.message }]
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      }));
+    }
+    const [serverSyncError, serverSyncResult] = await tryCatch(
+      async () => await serverMain({
+        clientInput: normalizedData,
+        user,
+        functions: functionsObject,
+        roomCode: receiver,
+        stream: emitServerSyncStream,
+        broadcastStream: emitBroadcastSyncStream,
+        streamTo: emitStreamToTokens,
+        abortSignal: abortController.signal,
+        flushPressure
+      }),
+      void 0,
+      {
+        handler: "handleSyncRequest",
+        sync: resolvedName,
+        stage: "server",
+        userId: user?.id,
+        receiver,
+        transport: "socket"
+      }
+    );
+    if (serverSyncError) {
+      if (shouldLogDev()) {
+        getLogger2().error(`sync: server execution failed for ${resolvedName}`, serverSyncError, { sync: resolvedName });
+      }
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+        response: { status: "error", errorCode: "sync.serverExecutionFailed" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      }));
+    } else if (serverSyncResult?.status == "error") {
+      const normalizedServerError = buildSyncError({
+        response: serverSyncResult,
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+      if (shouldLogDev()) {
+        getLogger2().warn(`sync: server returned error for ${resolvedName}`, { sync: resolvedName, message: normalizedServerError.message });
+      }
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), normalizedServerError);
+    } else if (serverSyncResult?.status !== "success") {
+      if (shouldLogDev()) {
+        getLogger2().warn(`sync: ${resolvedName}_server returned invalid response`, { sync: resolvedName });
+      }
+      cleanupRequest();
+      return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+        response: { status: "error", errorCode: "sync.invalidServerResponse" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      }));
+    } else if (serverSyncResult?.status == "success") {
+      serverOutput = serverSyncResult;
+    }
+  }
+  const sockets = receiver === "all" ? await ioInstance.fetchSockets() : await ioInstance.in(receiver).fetchSockets();
+  if (sockets.length === 0) {
+    if (shouldLogDev()) {
+      getLogger2().warn("sync: no sockets found for receiver", { receiver, sync: resolvedName });
+    }
+    cleanupRequest();
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: { status: "error", errorCode: "sync.noReceiversFound" },
+      preferred: preferredLocale,
+      userLanguage: user?.language
+    }));
+  }
+  const fanoutPayload = {
+    routeName: resolvedName,
+    data: normalizedData,
+    user,
+    receiver,
+    serverOutput,
+    transport: "socket",
+    recipientCount: 0
+  };
+  const preFanoutResult = await dispatchHook2("preSyncFanout", fanoutPayload);
+  if (preFanoutResult.stopped) {
+    cleanupRequest();
+    return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), buildSyncError({
+      response: {
+        status: "error",
+        errorCode: preFanoutResult.signal.errorCode,
+        httpStatus: preFanoutResult.signal.httpStatus
+      },
+      preferred: preferredLocale,
+      userLanguage: user?.language
+    }));
+  }
+  const { fanoutYieldEvery, fanoutYieldMs } = getProjectConfig2().sync;
+  let recipientCount = 0;
+  let tempCount = 1;
+  for (const tempSocket of sockets) {
+    tempCount++;
+    if (tempCount % fanoutYieldEvery === 0) {
+      await new Promise((resolve) => setTimeout(resolve, fanoutYieldMs));
+    }
+    const tempToken = extractTokenFromSocket(tempSocket);
+    if (ignoreSelf && typeof ignoreSelf == "boolean" && token == tempToken) {
+      continue;
+    }
+    recipientCount++;
+    if (syncObject[`${resolvedName}_client`]) {
+      const clientSyncHandler = syncObject[`${resolvedName}_client`];
+      const emitClientSyncStream = (payload = {}) => {
+        if (shouldLogStream2()) {
+          getLogger2().debug(`sync: ${resolvedName} client stream`, { payload });
+        }
+        tempSocket.emit(socketEventNames2.sync, {
+          ...payload,
+          cb,
+          fullName: resolvedName,
+          status: "stream"
+        });
+      };
+      const [clientSyncError, clientSyncResult] = await tryCatch(
+        async () => await clientSyncHandler({ clientInput: normalizedData, token: tempToken, functions: functionsObject, serverOutput, roomCode: receiver, stream: emitClientSyncStream }),
+        void 0,
+        {
+          handler: "handleSyncRequest",
+          sync: resolvedName,
+          stage: "client",
+          sourceUserId: user?.id,
+          targetToken: tempToken,
+          receiver,
+          transport: "socket"
+        }
+      );
+      if (clientSyncError) {
+        tempSocket.emit(socketEventNames2.sync, {
+          cb,
+          fullName: resolvedName,
+          ...buildSyncError({
+            response: { status: "error", errorCode: "sync.clientExecutionFailed" },
+            preferred: extractLanguageFromHeader(tempSocket.handshake.headers["x-language"]) || extractLanguageFromHeader(tempSocket.handshake.headers["accept-language"])
+          })
+        });
+        continue;
+      }
+      if (clientSyncResult?.status == "error") {
+        tempSocket.emit(socketEventNames2.sync, {
+          cb,
+          fullName: resolvedName,
+          ...buildSyncError({
+            response: ensureSyncErrorShape(clientSyncResult),
+            preferred: extractLanguageFromHeader(tempSocket.handshake.headers["x-language"]) || extractLanguageFromHeader(tempSocket.handshake.headers["accept-language"])
+          })
+        });
+        continue;
+      }
+      if (clientSyncResult?.status !== "success") {
+        tempSocket.emit(socketEventNames2.sync, {
+          cb,
+          fullName: resolvedName,
+          ...buildSyncError({
+            response: { status: "error", errorCode: "sync.invalidClientResponse" },
+            preferred: extractLanguageFromHeader(tempSocket.handshake.headers["x-language"]) || extractLanguageFromHeader(tempSocket.handshake.headers["accept-language"])
+          })
+        });
+        continue;
+      } else if (clientSyncResult?.status == "success") {
+        const result = {
+          cb,
+          fullName: resolvedName,
+          serverOutput,
+          clientOutput: clientSyncResult,
+          // Return from _client file (success only)
+          message: clientSyncResult.message || `${resolvedName} sync success`,
+          status: "success"
+        };
+        if (shouldLogDev()) {
+          getLogger2().debug(`sync: ${resolvedName} client success`, { result });
+        }
+        tempSocket.emit(socketEventNames2.sync, result);
+      }
+    } else {
+      const result = {
+        cb,
+        fullName: resolvedName,
+        serverOutput,
+        clientOutput: {},
+        // No client file, so empty output
+        message: `${resolvedName} sync success`,
+        status: "success"
+      };
+      if (shouldLogDev()) {
+        getLogger2().debug(`sync: ${resolvedName} server-only success`, { result });
+      }
+      tempSocket.emit(socketEventNames2.sync, result);
+    }
+  }
+  fanoutPayload.recipientCount = recipientCount;
+  await dispatchHook2("postSyncFanout", fanoutPayload);
+  cleanupRequest();
+  return typeof responseIndex == "number" && socket.emit(buildSyncResponseEventName(responseIndex), {
+    status: "success",
+    message: `sync ${resolvedName} success`,
+    result: serverOutput
+  });
+}
+
+// src/handleHttpSyncRequest.ts
+import { getSession as getSession2 } from "@luckystack/login";
+import { getProjectConfig as getProjectConfig3 } from "@luckystack/core";
+import { getRuntimeSyncMaps as getRuntimeSyncMapsFromSource } from "@luckystack/core";
+import {
+  validateRequest as validateRequest2,
+  extractTokenFromSocket as extractTokenFromSocket2,
+  getIoInstance as getIoInstance3,
+  tryCatch as tryCatch2,
+  parseTransportRouteName as parseTransportRouteName2,
+  checkRateLimit as checkRateLimit2,
+  socketEventNames as socketEventNames3,
+  validateInputByType as validateInputByType2,
+  dispatchHook as dispatchHook3,
+  getLogger as getLogger3
+} from "@luckystack/core";
+import { extractLanguageFromHeader as extractLanguageFromHeader2, normalizeErrorResponse as normalizeErrorResponse2, applyErrorFormatter as applyErrorFormatter2 } from "@luckystack/core";
+var shouldLogDev2 = () => getProjectConfig3().logging.devLogs;
+var shouldLogStream3 = () => getProjectConfig3().logging.stream;
+var applyHttpSyncRateLimits = async ({
+  resolvedName,
+  token,
+  requesterIp,
+  user,
+  buildSyncError,
+  preferredLocale
+}) => {
+  const config = getProjectConfig3();
+  const effectiveSyncLimit = config.rateLimiting.defaultApiLimit;
+  if (effectiveSyncLimit !== false && effectiveSyncLimit > 0) {
+    const requesterIdentity = token ?? requesterIp ?? "anonymous";
+    const keyPrefix = token ? "token" : "ip";
+    const rateLimitKey = `${keyPrefix}:${requesterIdentity}:sync:${resolvedName}`;
+    const { allowed, resetIn } = await checkRateLimit2({
+      key: rateLimitKey,
+      limit: effectiveSyncLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook3("rateLimitExceeded", {
+        scope: token ? "user" : "route",
+        key: rateLimitKey,
+        limit: effectiveSyncLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: effectiveSyncLimit + 1,
+        route: resolvedName,
+        userId: user?.id
+      });
+      return buildSyncError({
+        response: {
+          status: "error",
+          errorCode: "sync.rateLimitExceeded",
+          errorParams: [{ key: "seconds", value: resetIn }],
+          httpStatus: 429
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+  }
+  const defaultIpLimit = config.rateLimiting.defaultIpLimit;
+  const requesterIsLoopback = process.env.NODE_ENV !== "production" && (requesterIp === "127.0.0.1" || requesterIp === "::1" || requesterIp === "::ffff:127.0.0.1" || typeof requesterIp === "string" && requesterIp.startsWith("127."));
+  if (!requesterIsLoopback && defaultIpLimit !== false && defaultIpLimit > 0) {
+    const ipBucket = requesterIp ?? "unknown";
+    const ipKey = `ip:${ipBucket}:sync:all`;
+    const { allowed, resetIn } = await checkRateLimit2({
+      key: ipKey,
+      limit: defaultIpLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook3("rateLimitExceeded", {
+        scope: "ip",
+        key: ipKey,
+        limit: defaultIpLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: defaultIpLimit + 1,
+        ip: ipBucket
+      });
+      return buildSyncError({
+        response: {
+          status: "error",
+          errorCode: "sync.rateLimitExceeded",
+          errorParams: [{ key: "seconds", value: resetIn }],
+          httpStatus: 429
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+  }
+  return null;
+};
+async function handleHttpSyncRequest({
+  name,
+  cb,
+  data,
+  receiver,
+  ignoreSelf,
+  token,
+  requesterIp,
+  xLanguageHeader,
+  acceptLanguageHeader,
+  stream,
+  abortSignal
+}) {
+  if (shouldLogDev2()) {
+    getLogger3().debug(`http sync: ${name} called`);
+  }
+  const effectiveAbortSignal = abortSignal ?? new AbortController().signal;
+  const normalizedReceiver = typeof receiver === "string" ? receiver.trim() : "";
+  const preferredLocale = extractLanguageFromHeader2(xLanguageHeader) || extractLanguageFromHeader2(acceptLanguageHeader);
+  const user = await getSession2(token);
+  let currentRouteName;
+  let currentPerRouteFormatter;
+  const buildSyncError = ({
+    response,
+    preferred,
+    userLanguage
+  }) => {
+    const normalized = normalizeErrorResponse2({
+      response,
+      preferredLocale: preferred,
+      userLanguage
+    });
+    const baseEnvelope = {
+      status: normalized.status,
+      message: normalized.message,
+      errorCode: normalized.errorCode,
+      errorParams: normalized.errorParams,
+      httpStatus: normalized.httpStatus
+    };
+    return applyErrorFormatter2({
+      response: baseEnvelope,
+      routeName: currentRouteName ?? "sync/unknown",
+      transport: "http",
+      userId: user?.id,
+      perRouteFormatter: currentPerRouteFormatter
+    });
+  };
+  const ensureSyncErrorShape = (response) => {
+    if (typeof response.errorCode === "string" && response.errorCode.trim().length > 0) {
+      return response;
+    }
+    return {
+      ...response,
+      errorCode: "sync.clientRejected"
+    };
+  };
+  const ioInstance = getIoInstance3();
+  const [bodyError, bodyResult] = await tryCatch2(async () => {
+    if (!ioInstance) {
+      return buildSyncError({
+        response: { status: "error", errorCode: "sync.ioUnavailable" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    if (!name || typeof name !== "string") {
+      return buildSyncError({
+        response: { status: "error", errorCode: "sync.invalidRequest" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    const parsedRoute = parseTransportRouteName2({ value: name, prefix: "sync" });
+    if (parsedRoute.status === "error") {
+      return buildSyncError({
+        response: {
+          status: "error",
+          errorCode: "routing.invalidServiceRouteName",
+          errorParams: [{ key: "name", value: name }]
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    const resolvedName = parsedRoute.normalizedFullName;
+    currentRouteName = resolvedName;
+    const callbackName = typeof cb === "string" && cb.trim().length > 0 ? cb.trim() : `${parsedRoute.serviceRoute.normalizedRouteName}/${parsedRoute.version}`;
+    if (!normalizedReceiver) {
+      return buildSyncError({
+        response: { status: "error", errorCode: "sync.missingReceiver" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    const { syncObject, functionsObject } = await getRuntimeSyncMapsFromSource();
+    if (!syncObject[`${resolvedName}_client`] && !syncObject[`${resolvedName}_server`]) {
+      return buildSyncError({
+        response: { status: "error", errorCode: "sync.notFound" },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    const serverSyncEntry = syncObject[`${resolvedName}_server`];
+    currentPerRouteFormatter = serverSyncEntry?.errorFormatter;
+    if (serverSyncEntry) {
+      const { auth } = serverSyncEntry;
+      if (auth.login && !user?.id) {
+        return buildSyncError({
+          response: { status: "error", errorCode: "auth.required" },
+          preferred: preferredLocale
+        });
+      }
+      const validationResult = validateRequest2({ auth, user });
+      if (validationResult.status === "error") {
+        return buildSyncError({
+          response: {
+            status: "error",
+            errorCode: validationResult.errorCode || "auth.forbidden",
+            errorParams: validationResult.errorParams,
+            httpStatus: validationResult.httpStatus
+          },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        });
+      }
+    }
+    const preAuthorizeResult = await dispatchHook3("preSyncAuthorize", {
+      routeName: resolvedName,
+      data,
+      user,
+      receiver: normalizedReceiver,
+      transport: "http"
+    });
+    if (preAuthorizeResult.stopped) {
+      return buildSyncError({
+        response: {
+          status: "error",
+          errorCode: preAuthorizeResult.signal.errorCode,
+          httpStatus: preAuthorizeResult.signal.httpStatus
+        },
+        preferred: preferredLocale,
+        userLanguage: user?.language
+      });
+    }
+    const rateLimitResult = await applyHttpSyncRateLimits({
+      resolvedName,
+      token,
+      requesterIp,
+      user,
+      buildSyncError,
+      preferredLocale
+    });
+    if (rateLimitResult) return rateLimitResult;
+    let serverOutput = {};
+    if (serverSyncEntry) {
+      const { main: serverMain, inputType, inputTypeFilePath } = serverSyncEntry;
+      const { emitServerSyncStream, emitBroadcastSyncStream, emitStreamToTokens, flushPressure } = buildSyncStreamEmitters({
+        cb,
+        receiver: normalizedReceiver,
+        resolvedName,
+        logLabel: "http sync",
+        signal: effectiveAbortSignal,
+        //? No originatorSocket for HTTP/SSE — `flushPressure` falls back
+        //? to room-socket measurement only. SSE backpressure is the
+        //? caller's responsibility (Node's `res.write` returns a bool).
+        //? Originator chunks travel back via SSE; broadcast / targeted
+        //? chunks still flow over Socket.io to recipients in the receiver room.
+        emitOriginatorChunk: (payload) => {
+          stream?.(payload);
+        }
+      });
+      const inputValidation = await validateInputByType2({
+        typeText: inputType,
+        value: data,
+        rootKey: "clientInput",
+        filePath: inputTypeFilePath
+      });
+      if (inputValidation.status === "error") {
+        return buildSyncError({
+          response: {
+            status: "error",
+            errorCode: "sync.invalidInputType",
+            errorParams: [{ key: "message", value: inputValidation.message }]
+          },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        });
+      }
+      const [serverSyncError, serverSyncResult] = await tryCatch2(
+        async () => await serverMain({
+          clientInput: data,
+          user,
+          functions: functionsObject,
+          roomCode: normalizedReceiver,
+          stream: emitServerSyncStream,
+          broadcastStream: emitBroadcastSyncStream,
+          streamTo: emitStreamToTokens,
+          abortSignal: effectiveAbortSignal,
+          flushPressure
+        }),
+        void 0,
+        {
+          handler: "handleHttpSyncRequest",
+          sync: resolvedName,
+          stage: "server",
+          userId: user?.id,
+          receiver,
+          transport: "http"
+        }
+      );
+      if (serverSyncError) {
+        return buildSyncError({
+          response: { status: "error", errorCode: "sync.serverExecutionFailed" },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        });
+      }
+      if (serverSyncResult?.status == "error") {
+        return buildSyncError({
+          response: serverSyncResult,
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        });
+      }
+      if (serverSyncResult?.status !== "success") {
+        return buildSyncError({
+          response: { status: "error", errorCode: "sync.invalidServerResponse" },
+          preferred: preferredLocale,
+          userLanguage: user?.language
+        });
+      }
+      serverOutput = serverSyncResult;
+    }
+    const fanoutPayload = {
+      routeName: resolvedName,
+      data,
+      user,
+      receiver: normalizedReceiver,
+      serverOutput,
+      transport: "http",
+      recipientCount: 0
+    };
+    await dispatchHook3("preSyncFanout", fanoutPayload);
+    const sockets = receiver === "all" ? await ioInstance.fetchSockets() : await ioInstance.in(normalizedReceiver).fetchSockets();
+    let recipientCount = 0;
+    for (const tempSocket of sockets) {
+      const tempToken = extractTokenFromSocket2(tempSocket);
+      if (ignoreSelf && token && token === tempToken) {
+        continue;
+      }
+      if (syncObject[`${resolvedName}_client`]) {
+        const clientSyncHandler = syncObject[`${resolvedName}_client`];
+        const emitClientSyncStream = (payload = {}) => {
+          if (shouldLogStream3()) {
+            getLogger3().debug(`http sync: ${resolvedName} client stream`, { payload });
+          }
+          tempSocket.emit(socketEventNames3.sync, {
+            ...payload,
+            cb: callbackName,
+            fullName: resolvedName,
+            status: "stream"
+          });
+        };
+        const [clientSyncError, clientSyncResult] = await tryCatch2(
+          async () => await clientSyncHandler({ clientInput: data, token: tempToken, functions: functionsObject, serverOutput, roomCode: normalizedReceiver, stream: emitClientSyncStream }),
+          void 0,
+          {
+            handler: "handleHttpSyncRequest",
+            sync: resolvedName,
+            stage: "client",
+            sourceUserId: user?.id,
+            targetToken: tempToken,
+            receiver,
+            transport: "http"
+          }
+        );
+        if (clientSyncError) {
+          tempSocket.emit(socketEventNames3.sync, {
+            cb: callbackName,
+            fullName: resolvedName,
+            ...buildSyncError({
+              response: { status: "error", errorCode: "sync.clientExecutionFailed" },
+              preferred: extractLanguageFromHeader2(tempSocket.handshake.headers["accept-language"] || tempSocket.handshake.headers["x-language"])
+            })
+          });
+          continue;
+        }
+        if (clientSyncResult?.status === "error") {
+          tempSocket.emit(socketEventNames3.sync, {
+            cb: callbackName,
+            fullName: resolvedName,
+            ...buildSyncError({
+              response: ensureSyncErrorShape(clientSyncResult),
+              preferred: extractLanguageFromHeader2(tempSocket.handshake.headers["accept-language"] || tempSocket.handshake.headers["x-language"])
+            })
+          });
+          continue;
+        }
+        if (clientSyncResult?.status !== "success") {
+          tempSocket.emit(socketEventNames3.sync, {
+            cb: callbackName,
+            fullName: resolvedName,
+            ...buildSyncError({
+              response: { status: "error", errorCode: "sync.invalidClientResponse" },
+              preferred: extractLanguageFromHeader2(tempSocket.handshake.headers["accept-language"] || tempSocket.handshake.headers["x-language"])
+            })
+          });
+          continue;
+        }
+        tempSocket.emit(socketEventNames3.sync, {
+          cb: callbackName,
+          fullName: resolvedName,
+          serverOutput,
+          clientOutput: clientSyncResult,
+          message: clientSyncResult.message || `${resolvedName} sync success`,
+          status: "success"
+        });
+        recipientCount++;
+        continue;
+      }
+      tempSocket.emit(socketEventNames3.sync, {
+        cb: callbackName,
+        fullName: resolvedName,
+        serverOutput,
+        clientOutput: {},
+        message: `${resolvedName} sync success`,
+        status: "success"
+      });
+      recipientCount++;
+    }
+    fanoutPayload.recipientCount = recipientCount;
+    await dispatchHook3("postSyncFanout", fanoutPayload);
+    if (shouldLogDev2()) {
+      getLogger3().debug(`http sync: ${resolvedName} completed`);
+    }
+    const serverMessage = serverOutput.message;
+    return {
+      ...serverOutput,
+      status: "success",
+      message: typeof serverMessage === "string" ? serverMessage : `${resolvedName} sync success`
+    };
+  });
+  if (bodyError) {
+    getLogger3().error(`http sync: ${name} threw`, bodyError, { sync: name });
+    return buildSyncError({
+      response: { status: "error", errorCode: "sync.serverExecutionFailed" },
+      preferred: preferredLocale,
+      userLanguage: user?.language
+    });
+  }
+  return bodyResult ?? buildSyncError({
+    response: { status: "error", errorCode: "sync.serverExecutionFailed" },
+    preferred: preferredLocale,
+    userLanguage: user?.language
+  });
+}
+
+// src/streamThrottle.ts
+import { getProjectConfig as getProjectConfig4 } from "@luckystack/core";
+var createStreamThrottle = (options = {}) => {
+  const defaults = getProjectConfig4().sync.streamThrottle;
+  const flushAtChars = options.flushAtChars ?? defaults.flushAtChars;
+  const flushEveryMs = options.flushEveryMs ?? defaults.flushEveryMs;
+  const field = options.field ?? defaults.field;
+  let buffer = "";
+  let timer = null;
+  const clearTimer = () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  const flushNow = (emit) => {
+    if (buffer.length === 0) {
+      clearTimer();
+      return;
+    }
+    const payload = { [field]: buffer };
+    buffer = "";
+    clearTimer();
+    emit(payload);
+  };
+  return {
+    push: (text, emit) => {
+      if (!text) return;
+      buffer += text;
+      if (buffer.length >= flushAtChars) {
+        flushNow(emit);
+        return;
+      }
+      if (flushEveryMs !== false && timer === null) {
+        timer = setTimeout(() => {
+          flushNow(emit);
+        }, flushEveryMs);
+        if (typeof timer === "object" && "unref" in timer) {
+          timer.unref();
+        }
+      }
+    },
+    flush: (emit) => {
+      flushNow(emit);
+    },
+    reset: () => {
+      buffer = "";
+      clearTimer();
+    }
+  };
+};
+export {
+  createStreamThrottle,
+  handleHttpSyncRequest,
+  handleSyncRequest
+};
+//# sourceMappingURL=index.js.map