codeweaver 3.1.3 → 4.0.1

package/src/core/message-broker/rabitmq/producer.ts

@@ -0,0 +1,100 @@
+import { ChannelManager } from "./channel";
+import { ProducerConfig } from "./basic-types";
+import { backoff } from "../utilities";
+
+/**
+ * RabbitMQ producer.
+ * @template T - The type of the message body.
+ */
+export class RabbitProducer<T = any> {
+  private cm = new ChannelManager({ url: "" });
+  private config: ProducerConfig;
+
+  /**
+   * Creates a new RabbitMQ producer with the given configuration options.
+   * @param opts - Configuration options for the producer.
+   */
+  public constructor(opts: ProducerConfig) {
+    this.config = opts;
+    this.cm = new ChannelManager({ url: opts.url });
+  }
+
+  /**
+   * Connects to the RabbitMQ cluster and sets up the producer.
+   * Ensures the exchange exists.
+   * @returns A promise resolved when the producer is connected.
+   */
+  public async connect(): Promise<void> {
+    await this.cm.connect();
+    const ex = this.config.exchange ?? "";
+    if (ex) {
+      const type = this.config.exchangeType ?? "direct";
+      await this.cm.assertExchange(ex, type, true);
+    }
+  }
+
+  /**
+   * Publishes a message to a RabbitMQ exchange.
+   * If a serializer is provided in the producer config, it will be used to serialize the message body.
+   * Otherwise, the message body will be serialized as JSON.
+   * @param message - The message to publish with optional routing key and headers.
+   * @returns A promise resolved when the message has been published.
+   */
+  public async publish(message: {
+    body: T;
+    routingKey?: string;
+    headers?: any;
+  }): Promise<void> {
+    if (!message) throw new Error("Message required");
+    if (!this.cm) throw new Error("ChannelManager not initialized");
+
+    const bodyBuf = this.config.serializer?.serialize
+      ? this.config.serializer.serialize(message.body)
+      : Buffer.from(JSON.stringify(message.body));
+
+    const routingKey = message.routingKey ?? this.config.routingKey ?? "";
+    const exchange = this.config.exchange ?? "";
+
+    // Ensure connection and exchange
+    if (!this.cm) await this.connect();
+
+    const payload = {
+      exchange,
+      routingKey,
+      persistent: true,
+      contentType: "application/json",
+      payload: bodyBuf,
+      headers: message.headers,
+    } as any;
+
+    // kaf way: use channel.publish
+    let attempt = 0;
+    while (true) {
+      try {
+        await this.cm.ch.publish(exchange, routingKey, bodyBuf, {
+          headers: message.headers,
+          persistent: true,
+        });
+        return;
+      } catch (e) {
+        attempt++;
+        const max = this.config.retry?.retries ?? 5;
+        if (attempt > max) throw e;
+        const wait = backoff(
+          attempt,
+          this.config.retry?.baseMs ?? 100,
+          this.config.retry?.maxMs ?? 2000
+        );
+        await new Promise((r) => setTimeout(r, wait));
+      }
+    }
+  }
+
+  /**
+   * Closes the underlying ChannelManager and its associated objects.
+   * @returns A promise resolved when all objects have been closed.
+   */
+  public async close(): Promise<void> {
+    await this.cm.close();
+  }
+}

package/src/core/message-broker/utilities.ts

@@ -0,0 +1,50 @@
+/**
+ * Compute the next delay in milliseconds according to an exponential backoff
+ * algorithm with jitter.
+ *
+ * @param attempt The attempt number, starting from 1.
+ * @param baseMs The base delay in milliseconds, defaults to 100.
+ * @param maxMs The maximum delay in milliseconds, defaults to 3000.
+ * @returns The computed delay in milliseconds.
+ */
+export function backoff(attempt: number, baseMs = 100, maxMs = 3000): number {
+  const cap = Math.min(maxMs, baseMs * Math.pow(2, attempt));
+  // jitter
+  return cap / 2 + Math.floor(Math.random() * (cap / 2));
+}
+
+/**
+ * Validates a topic name.
+ * @param name The topic name to validate.
+ * @throws {Error} If the topic name is invalid (null, undefined, not a string) or too long (> 249 characters).
+ */
+export function validateTopic(name: string): void {
+  if (!name || typeof name !== "string") throw new Error("Invalid topic name");
+  // simple rule demo; adapt to your needs
+  if (name.length > 249) throw new Error("Topic name too long");
+}
+
+/**
+ * Interface for serializing and deserializing data for a message broker.
+ * @template T The type of data to serialize and deserialize.
+ */
+export interface BrokerSerializer<T = any> {
+  version?: number;
+  serialize?: (data: T) => Buffer;
+  deserialize?: (buffer: Buffer) => T;
+}
+
+/**
+ * Returns a default broker serializer for JSON-serialized data.
+ * The serializer will store the given version number in the serialized data.
+ * The deserializer will parse the JSON data and return the deserialized object.
+ * @param version The version number to store in the serialized data.
+ * @returns A default broker serializer for JSON-serialized data.
+ */
+export function getDefaultJsonSchema<T>(version?: number): BrokerSerializer<T> {
+  return {
+    version,
+    serialize: (data: T): Buffer => Buffer.from(JSON.stringify(data)),
+    deserialize: (buffer: Buffer): T => JSON.parse(buffer.toString()) as T,
+  };
+}

package/src/core/middlewares/basic-types.ts

@@ -0,0 +1,39 @@
+import { Request, Response, NextFunction } from "express";
+
+/**
+ * Extend Express Request to optionally include a user payload.
+ * This allows downstream middleware and handlers to access authenticated user data.
+ */
+export interface UserRequest<UserIdType = string | number> extends Request {
+  /** Authenticated user payload parsed from the JWT. */
+  user?: UserPayload<UserIdType>;
+}
+
+export type RouterFn<UserIdType = string | number> = (
+  req: UserRequest<UserIdType>,
+  res: Response,
+  next: NextFunction
+) => void;
+
+/**
+ * User payload attached to the request after successful authentication.
+ * Extends JwtPayload with a flexible key-value store.
+ */
+export type UserPayload<UserIdType = string | number> = {
+  id?: UserIdType;
+} & Record<string, any>;
+
+/**
+ * Options for the authenticateToken middleware.
+ * - audience: Optional JWT audience claim to validate against.
+ * - issuer: Optional JWT issuer claim to validate against.
+ * - maxAge: Optional maximum age for the token (e.g., "1h", "15m").
+ */
+export type JwtOptions = {
+  /** Valid audience for the JWT. */
+  audience?: string;
+  /** Valid issuer for the JWT. */
+  issuer?: string;
+  /** Maximum allowed age for the JWT (e.g., "1h"). */
+  maxAge?: string;
+};

package/src/core/middlewares/decorators.ts

@@ -0,0 +1,244 @@
+import { logger } from "@/core/logger";
+import { ResponseError } from "@/core/error";
+import jwt from "jsonwebtoken";
+import { config } from "@/config";
+import { JwtOptions, UserPayload, UserRequest } from "./basic-types";
+import { createMethodDecorator } from "@/core/helpers/decorators";
+import { AsyncFn } from "@/core/helpers";
+import { authenticate, hashRequest, inFlightMap } from "./middlewares";
+import { AuthenticateCallback, AuthenticateOptions, Strategy } from "passport";
+
+/**
+ * Decorator: Log a request when the controller method is invoked.
+ */
+export const LogRequest = createMethodDecorator<[], [UserRequest]>(
+  async ([], [req]) => {
+    const { method, url } = req;
+    logger.info(
+      `Request Method=${method}, Url=${url}, User Id=${req.user?.id}, IP=${req.ip}, Agent=${req.headers["user-agent"]}`,
+      "Request",
+      {
+        user: req.user,
+        body: req.body,
+        query: req.query,
+        params: req.params,
+        headers: req.headers,
+        cookies: req.cookies,
+      }
+    );
+    return null;
+  }
+);
+
+/**
+ * Decorator: Log a method invocation with arguments and result.
+ */
+export const LogMethod = createMethodDecorator<[], [UserRequest]>(
+  async ([], [], method, args, classInstance) => {
+    const startTime = process.hrtime.bigint();
+    const result = await method.apply(classInstance, args);
+    const endTime = process.hrtime.bigint();
+    const duration = Number(endTime - startTime) / 1000000;
+    logger.info("Method arguments and result", "Method", {
+      args,
+      result,
+      duration,
+      reqPerSec: 1000 / duration,
+    });
+    return result;
+  }
+);
+
+/**
+ * Decorator: Authenticate token and attach user to req.
+ * Internally uses the existing authenticateToken middleware logic without changing route signatures.
+ */
+export const AuthenticateToken = createMethodDecorator<
+  [JwtOptions | undefined],
+  [UserRequest]
+>(async ([options], [req]) => {
+  const tokenHeader = req.header("Authorization");
+  const token = tokenHeader?.split(" ")[1];
+  if (token == null) {
+    throw new ResponseError("Authentication failed: Token not found.", 401);
+  }
+
+  try {
+    const decoded = jwt.verify(token, config.jwtSecretKey, options);
+    req.user = decoded as UserPayload;
+    return null;
+  } catch (error: unknown) {
+    let message = "";
+    if (error instanceof Error) message = error.message;
+    throw new ResponseError(
+      "Authentication failed: Token is invalid.",
+      401,
+      message
+    );
+  }
+});
+
+/**
+ * Decorator: Apply authentication using passport.authenticate
+ * Internally uses the existing authenticatePassport middleware logic without changing route signatures.
+ */
+export const Authenticate = createMethodDecorator<
+  [
+    string | string[] | Strategy,
+    AuthenticateOptions | undefined,
+    AuthenticateCallback | ((...args: any[]) => Promise<any>) | undefined,
+    (
+      | ((
+          req: UserRequest,
+          strategy: string | string[] | Strategy,
+          options: AuthenticateOptions,
+          callback?: AuthenticateCallback | ((...args: any[]) => Promise<any>)
+        ) => any)
+      | undefined
+    )
+  ],
+  [UserRequest]
+>(async ([strategy, options, callback, authenticationFn], [req]) => {
+  await (authenticationFn ?? authenticate)(
+    req,
+    strategy,
+    options ?? {},
+    callback
+  );
+
+  if (req.user?.id === null) {
+    throw new ResponseError("Authentication failed.", 401);
+  }
+
+  return null;
+});
+
+/**
+ * Decorator: Apply a timeout to the controller method.
+ * Mirrors the timeout middleware but applied at method level.
+ */
+export function Timeout(
+  milliseconds: number,
+  timeoutHandler?: () => Promise<any>
+) {
+  return createMethodDecorator<[number, (() => Promise<any>) | undefined], []>(
+    async ([milliseconds, timeoutHandler], [], method, args, classInstance) => {
+      const controller = new AbortController();
+
+      // Create a promise that rejects after the timeout
+      let timeoutHandle: NodeJS.Timeout;
+      const timeoutPromise = new Promise<any>(async (resolve, reject) => {
+        timeoutHandle = setTimeout(() => {
+          if (timeoutHandler != null) {
+            resolve(timeoutHandler());
+          } else {
+            controller.abort();
+            reject(new ResponseError("Request timed out", 503));
+          }
+        }, milliseconds);
+      });
+
+      // Add the signal to the method arguments
+      args.push(controller.signal);
+
+      // Run the original method
+      try {
+        return await Promise.race([
+          timeoutPromise,
+          method.apply(classInstance, args),
+        ]);
+      } finally {
+        clearTimeout(timeoutHandle!);
+      }
+    }
+  )(milliseconds, timeoutHandler);
+}
+
+/**
+ * Decorator: Per-user debounce for a controller method.
+ * Mirrors perUserDebounce with optional cleanup after response.
+ */
+export const Debounce = createMethodDecorator<
+  [
+    number | undefined,
+    Map<string, number> | undefined,
+    ((req: UserRequest) => string) | undefined
+  ],
+  [req: UserRequest]
+>(async ([debounceTimeSpan, inFlight, hashFunction], [req]) => {
+  // Import the in-flight mechanism from your existing module
+  // If inFlight and hashRequest are exported, import them here
+  const userId = req.user?.id ?? "anonymous";
+  const key =
+    `${userId}:` +
+    (hashFunction != null ? hashFunction(req) : hashRequest(req));
+
+  const now = Date.now();
+  const last = (inFlight ?? inFlightMap).get(key) ?? 0;
+
+  if (now - last < (debounceTimeSpan ?? config.debounceTimeSpan)) {
+    throw new ResponseError("Please wait before repeating this action.", 429);
+  }
+
+  (inFlight ?? inFlightMap).set(key, now);
+  return null;
+});
+
+/**
+ * Before decorator: run a function before the controller method.
+ * You can supply a small hook to run any pre-processing (e.g., logging, metric increment).
+ */
+export const Before = createMethodDecorator<
+  [(method: AsyncFn, ...methodArgs: any[]) => Promise<boolean>],
+  any[]
+>(async ([callback], _args, method, rawMethodArgs) => {
+  return await callback(method, rawMethodArgs);
+});
+
+/**
+ * After decorator: run a function after the controller method completes.
+ * If the controller method returns a Promise, the afterFn runs after it resolves.
+ */
+export const After = createMethodDecorator<
+  [(result: any, method: AsyncFn, ...methodArgs: any[]) => Promise<void>],
+  []
+>(undefined, async (result, [callback], _args, method, rawMethodArgs) => {
+  return await callback(result, method, rawMethodArgs);
+});
+
+/**
+ * Error handler decorator with a callback
+ * The callback receives the error and a context object describing the invocation.
+ *
+ * @param callback - callback invoked when an error occurs.
+ * @returns decorator
+ */
+export const ErrorHandler = createMethodDecorator<
+  [(error: Error) => Promise<void>],
+  []
+>(async ([callback], [], method, rawMethodArgs, classInstance) => {
+  try {
+    return await method.apply(classInstance, rawMethodArgs);
+  } catch (error: unknown) {
+    return await callback(
+      error instanceof Error ? (error as Error) : new Error("Unexpected error!")
+    );
+  }
+});
+
+/**
+ * Guard decorator: restrict access to a controller method.
+ *
+ * @param callback - callback invoked to check if the request is allowed: (req) => Promise<boolean>
+ * @returns decorator
+ */
+export const Guard = createMethodDecorator<
+  [(req: UserRequest) => Promise<boolean>],
+  [UserRequest]
+>(async ([callback], [req]) => {
+  const isAllowed = await callback(req);
+  if (!isAllowed) {
+    throw new ResponseError("Forbidden", 403);
+  }
+  return null;
+});

package/src/core/middlewares/index.ts

@@ -0,0 +1,3 @@
+export * from "./basic-types";
+export * from "./middlewares";
+export * from "./decorators";

package/src/core/middlewares/middlewares.ts

@@ -0,0 +1,246 @@
+import { config } from "@/config";
+import { Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+import { ResponseError } from "@/core/error";
+import { logger } from "@/core/logger";
+import { JwtOptions, RouterFn, UserPayload, UserRequest } from "./basic-types";
+import passport, {
+  AuthenticateCallback,
+  AuthenticateOptions,
+  Strategy,
+} from "passport";
+
+/**
+ * Simple request logger middleware.
+ * Logs the HTTP method and URL of each incoming request at the "Request" context.
+ *
+ * @param req - Express HTTP request object
+ * @param res - Express HTTP response object
+ * @param next - Next middleware function
+ */
+export function requestLogger<
+  UserIdType = string | number
+>(): RouterFn<UserIdType> {
+  return async (req, _res, next) => {
+    const { method, url } = req;
+    logger.info(
+      `Method=${method}, Url=${url}, User Id=${req.user?.id}, IP=${req.ip}, Agent=${req.headers["user-agent"]}`,
+      "Request",
+      {
+        user: req.user,
+        body: req.body,
+        query: req.query,
+        params: req.params,
+        headers: req.headers,
+        cookies: req.cookies,
+      }
+    );
+    next();
+  };
+}
+
+/**
+ * Factory to create a middleware that authenticates a JWT from the Authorization header.
+ * Validates the token using the configured secret key and optional JWT claims.
+ *
+ * Behavior:
+ * - Extracts the token from the Authorization header (Bearer <token>).
+ * - Verifies the token with jwt.verify using config.jwtSecretKey and optional options.
+ * - Attaches the decoded payload as req.user.
+ * - Calls await next() on success.
+ * - Throws a 401 ResponseError if token is missing or invalid.
+ *
+ * @param options Optional JWT validation constraints.
+ * @returns Express middleware function.
+ */
+export function authenticateToken<UserIdType = string | number>(
+  options: JwtOptions
+): RouterFn<UserIdType> {
+  return async (req, _res, next) => {
+    let authHeader = req.header("Authorization");
+    const token = authHeader?.split(" ")[1];
+
+    if (token == null) {
+      throw new ResponseError("Authentication failed: Token not found.", 401);
+    }
+
+    try {
+      const decoded = jwt.verify(token, config.jwtSecretKey, options);
+      req.user = decoded as UserPayload<UserIdType>;
+      next();
+    } catch {
+      throw new ResponseError("Authentication failed: Token is invalid.", 401);
+    }
+  };
+}
+
+/**
+ * Utility function to authenticate a user using passport.authenticate.
+ * Throws a 401 ResponseError if authentication fails.
+ *
+ * @param req - Express HTTP request object
+ * @param strategy - Passport strategy to use for authentication
+ * @param options - Optional authentication options
+ * @param callback - Optional callback function
+ * @returns Express middleware function
+ */
+export function authenticate<UserIdType = string | number>(
+  req: UserRequest<UserIdType>,
+  strategy: string | string[] | Strategy,
+  options: AuthenticateOptions,
+  callback?: AuthenticateCallback | ((...args: any[]) => any)
+) {
+  passport.authenticate(
+    strategy,
+    options,
+    async (
+      error: any,
+      user?: Express.User | false | null,
+      info?: object | string | Array<string | undefined>,
+      status?: number | Array<number | undefined>
+    ) => {
+      if (error) throw new ResponseError("Authentication failed.", 401, error);
+      if (!user) throw new ResponseError("Authentication failed.", 401);
+      await callback?.(error, user, info, status);
+      req.user = user;
+    }
+  );
+}
+
+/**
+ * Middleware to authenticate a user using passport.authenticate.
+ * Throws a 401 ResponseError if authentication fails.
+ *
+ * @param strategy - Passport strategy to use for authentication
+ * @param options - Optional authentication options
+ * @param callback - Optional callback function
+ * @returns Express middleware function
+ */
+export function authenticatePassport<UserIdType = string | number>(
+  strategy: string | string[] | Strategy,
+  options?: AuthenticateOptions,
+  callback?: AuthenticateCallback | ((...args: any[]) => any),
+  authenticationFn?: (
+    req: UserRequest<UserIdType>,
+    strategy: string | string[] | Strategy,
+    options: AuthenticateOptions,
+    callback?: AuthenticateCallback | ((...args: any[]) => any)
+  ) => any
+): RouterFn<UserIdType> {
+  return async (req: UserRequest<UserIdType>, _res, next) => {
+    await (authenticationFn ?? authenticate)(
+      req,
+      strategy,
+      options ?? {},
+      callback
+    );
+    next();
+  };
+}
+
+/**
+ * Timeout middleware to enforce request time limits.
+ * Starts a timer for the given duration and, if the response has not finished
+ * by then, responds with HTTP 503 (Request timed out).
+ * When the response finishes, invokes onFinish with the timer reference and clears it.
+ *
+ * @param milliseconds Duration before timing out the request (in ms)
+ * @param onFinish Callback invoked when the response finishes, receiving the timer
+ * @returns Express middleware function
+ */
+export function timeout(
+  milliseconds: number,
+  onFinish: (timer: NodeJS.Timeout) => void
+): RouterFn {
+  return async (_req, res, next) => {
+    const timer = setTimeout(() => {
+      if (!res.headersSent) {
+        res.status(503).json({ message: "Request timed out" });
+      }
+    }, milliseconds);
+
+    res.once("finish", () => {
+      onFinish(timer);
+      clearTimeout(timer);
+    });
+    res.once("close", () => clearTimeout(timer));
+    next();
+  };
+}
+
+// Map of in-flight requests per user
+export const inFlightMap: Map<string, number> = new Map();
+
+/**
+ * Utility function to generate a hash for a request.
+ * The hash is based on the method, URL and body of the request.
+ *
+ * @param req - Express HTTP request object
+ * @returns A string representation of the hash
+ */
+export function hashRequest<UserIdType = string | number>(
+  req: UserRequest<UserIdType>
+): string {
+  const { method, url, body } = req;
+  const payload = JSON.stringify(body ?? {});
+  const str = `${method}:${url}:${payload}`;
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = (h << 5) - h + str.charCodeAt(i);
+    h |= 0;
+  }
+  return String(h);
+}
+
+/**
+ * Per-user in-flight request debounce.
+ * Prevents identical in-flight requests from being processed concurrently within a
+ * short time span by the same user.
+ *
+ * - Uses a lightweight hash of the request (method, url, body) together with a per-user key.
+ * - If a similar request was processed within config.debounceTimeSpan, responds with 429
+ *   and a Retry-After header indicating the wait time.
+ * - Stores the timestamp of the last in-flight occurrence in a map.
+ * - Optionally cleans up the in-flight key after the response finishes if
+ *   cleanUpAfterResponse is true.
+ *
+ * @param cleanUpAfterResponse If true, cleans up the in-flight key after the response finishes.
+ * @returns Express middleware function
+ */
+export function debounce<UserIdType = string | number>(
+  cleanUpAfterResponse: boolean = false,
+  inFlight: Map<string, number> = inFlightMap,
+  hashFunction: (req: UserRequest<UserIdType>) => string = hashRequest
+) {
+  return async (
+    req: UserRequest<UserIdType>,
+    res: Response,
+    next: NextFunction
+  ) => {
+    const userId = req.user?.id ?? "anonymous";
+    const key = `${userId}:${hashFunction(req)}`;
+
+    const now = Date.now();
+    const last = inFlight.get(key) ?? 0;
+
+    if (now - last < config.debounceTimeSpan) {
+      res.header(
+        "Retry-After",
+        String(Math.ceil((config.debounceTimeSpan - (now - last)) / 1000))
+      );
+      return res
+        .status(429)
+        .json({ error: "Please wait before repeating this action." });
+    }
+
+    inFlight.set(key, now);
+
+    if (cleanUpAfterResponse) {
+      res.on("finish", () => {
+        inFlight.delete(key);
+      });
+    }
+
+    next();
+  };
+}

package/src/core/parallel/index.ts

@@ -0,0 +1,3 @@
+export * from "./chanel";
+export * from "./worker-pool";
+export * from "./parallel";