@omnitronix/rng-client-core 1.0.10 → 1.1.2

package/src/errors/rng-errors.ts

@@ -0,0 +1,96 @@
+import * as grpc from "@grpc/grpc-js";
+
+export class RngServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly originalError?: unknown
+  ) {
+    super(message);
+    this.name = "RngServiceError";
+  }
+}
+
+export class RngConnectionError extends RngServiceError {
+  constructor(
+    message: string = "Unable to connect to RNG service",
+    originalError?: unknown
+  ) {
+    super(message, "SERVICE_UNAVAILABLE", originalError);
+    this.name = "RngConnectionError";
+  }
+}
+
+export class HttpConnectionError extends Error {
+  constructor(
+    message: string = "Unable to connect to RNG service",
+    public readonly originalError?: unknown
+  ) {
+    super(message);
+    this.name = "HttpConnectionError";
+  }
+}
+
+export class HttpServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly originalError?: unknown
+  ) {
+    super(message);
+    this.name = "HttpServiceError";
+  }
+}
+
+export function handleGrpcError(
+  err: unknown,
+  operation: string,
+  grpcUrl?: string
+): never {
+  console.log(`RNG Client gRPC Error in ${operation}:`, err);
+
+  if (err && typeof err === "object" && "code" in err) {
+    const grpcError = err as grpc.ServiceError;
+
+    if (
+      grpcError.code === grpc.status.UNAVAILABLE ||
+      grpcError.code === grpc.status.DEADLINE_EXCEEDED ||
+      grpcError.code === grpc.status.UNKNOWN ||
+      grpcError.code === grpc.status.INTERNAL
+    ) {
+      throw new RngConnectionError(
+        grpcUrl
+          ? `Unable to connect to RNG service at ${grpcUrl}`
+          : "Unable to connect to RNG service",
+        err
+      );
+    }
+
+    throw new RngServiceError(
+      grpcError.details || grpcError.message || "Unknown gRPC error occurred",
+      grpcError.code?.toString() || "UNKNOWN",
+      err
+    );
+  }
+
+  if (err instanceof Error) {
+    if (
+      err.message.includes("ECONNREFUSED") ||
+      err.message.includes("ENOTFOUND") ||
+      err.message.includes("timeout")
+    ) {
+      throw new RngConnectionError(
+        grpcUrl
+          ? `Unable to connect to RNG service at ${grpcUrl}`
+          : "Unable to connect to RNG service",
+        err
+      );
+    }
+  }
+
+  throw new RngServiceError(
+    "An unexpected error occurred while communicating with the RNG service",
+    "UNKNOWN",
+    err
+  );
+}

package/src/grpc/grpc-rng-client.ts

@@ -0,0 +1,162 @@
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { RngClientInterface } from "../http/rng-client.interface";
+import {
+  RngBatchFloatRequest,
+  RngBatchRequest,
+  RngBatchResponse,
+  RngBatchResponseWithSeeds,
+  RngSingleFloatRequest,
+  RngSingleRequest,
+  RngSingleResponse,
+} from "../http/http-client.types";
+import { GrpcRngClientInterface } from "./grpc-rng-interface";
+import { handleGrpcError } from "../errors/rng-errors";
+
+const PROTO_PATH = __dirname + "/../rng.proto";
+
+export class GrpcRngClient implements RngClientInterface {
+  private readonly client: GrpcRngClientInterface;
+  private readonly grpcUrl: string;
+
+  constructor(grpcUrl: string) {
+    this.grpcUrl = grpcUrl;
+
+    const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+      keepCase: true,
+      longs: String,
+      enums: String,
+      defaults: true,
+      oneofs: true,
+    });
+
+    const rngProto = grpc.loadPackageDefinition(packageDefinition)
+      .rng as grpc.GrpcObject;
+    this.client = new (rngProto as any).RngService(
+      this.grpcUrl,
+      grpc.credentials.createInsecure()
+    );
+  }
+
+  async getSingleNumber(request: RngSingleRequest): Promise<RngSingleResponse> {
+    return new Promise((resolve, reject) => {
+      this.client.Single(
+        request,
+        (err: unknown, response: RngSingleResponse) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getSingleNumber", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+
+  async getBatchNumbers(request: RngBatchRequest): Promise<RngBatchResponse> {
+    return new Promise((resolve, reject) => {
+      this.client.SingleBatch(
+        request,
+        (err: unknown, response: RngBatchResponse) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getBatchNumbers", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+
+  async getSingleFloat(
+    request: RngSingleFloatRequest
+  ): Promise<RngSingleResponse> {
+    return new Promise((resolve, reject) => {
+      this.client.Float(
+        request,
+        (err: unknown, response: RngSingleResponse) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getSingleFloat", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+
+  async getBatchFloats(
+    request: RngBatchFloatRequest
+  ): Promise<RngBatchResponse> {
+    return new Promise((resolve, reject) => {
+      this.client.FloatBatch(
+        request,
+        (err: unknown, response: RngBatchResponse) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getBatchFloats", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+
+  async getBatchNumbersWithSeeds(
+    request: RngBatchRequest
+  ): Promise<RngBatchResponseWithSeeds> {
+    return new Promise((resolve, reject) => {
+      this.client.SingleBatchWithSeeds(
+        request,
+        (err: unknown, response: RngBatchResponseWithSeeds) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getBatchNumbersWithSeeds", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+
+  async getBatchFloatWithSeeds(
+    request: RngSingleFloatRequest
+  ): Promise<RngBatchResponseWithSeeds> {
+    return new Promise((resolve, reject) => {
+      this.client.FloatBatchWithSeeds(
+        request,
+        (err: unknown, response: RngBatchResponseWithSeeds) => {
+          if (err) {
+            try {
+              handleGrpcError(err, "getBatchFloatWithSeeds", this.grpcUrl);
+            } catch (error) {
+              reject(error);
+            }
+          } else {
+            resolve(response);
+          }
+        }
+      );
+    });
+  }
+}

package/src/grpc/grpc-rng-interface.ts

@@ -0,0 +1,36 @@
+import {
+  RngBatchFloatRequest,
+  RngBatchRequest,
+  RngBatchResponse,
+  RngBatchResponseWithSeeds,
+  RngSingleFloatRequest,
+  RngSingleRequest,
+  RngSingleResponse,
+} from "../http/http-client.types";
+
+export interface GrpcRngClientInterface {
+  Single(
+    request: RngSingleRequest,
+    callback: (err: unknown, response: RngSingleResponse) => void
+  ): Promise<RngSingleResponse>;
+  SingleBatch(
+    request: RngBatchRequest,
+    callback: (err: unknown, response: RngBatchResponse) => void
+  ): Promise<RngBatchResponse>;
+  Float(
+    request: RngSingleFloatRequest,
+    callback: (err: unknown, response: RngSingleResponse) => void
+  ): Promise<RngSingleResponse>;
+  FloatBatch(
+    request: RngBatchFloatRequest,
+    callback: (err: unknown, response: RngBatchResponse) => void
+  ): Promise<RngBatchResponse>;
+  SingleBatchWithSeeds(
+    request: RngBatchRequest,
+    callback: (err: unknown, response: RngBatchResponseWithSeeds) => void
+  ): Promise<RngBatchResponseWithSeeds>;
+  FloatBatchWithSeeds(
+    request: RngSingleFloatRequest,
+    callback: (err: unknown, response: RngBatchResponseWithSeeds) => void
+  ): Promise<RngBatchResponseWithSeeds>;
+}

package/src/http/http-client.types.ts

@@ -0,0 +1,48 @@
+export interface RngSingleRequest {
+  min: number;
+  max: number;
+  seed?: number;
+}
+
+export interface RngBatchRequest {
+  min: number;
+  max: number;
+  count: number;
+  seed?: number;
+}
+
+export interface RngSingleFloatRequest {
+  seed?: number;
+}
+
+export interface RngBatchFloatRequest {
+  count: number;
+  seed?: number;
+}
+
+export interface RngSingleResponse {
+  id: string;
+  seed: number;
+  result: number;
+  min: number;
+  max: number;
+  createdAt: string;
+}
+
+export interface RngBatchResponse {
+  id: string;
+  seed: number;
+  result: number[];
+  min: number;
+  max: number;
+  createdAt: string;
+}
+
+export interface RngBatchResponseWithSeeds {
+  id: string;
+  seed: number;
+  result: { value: number; seed: number }[];
+  min: number;
+  max: number;
+  createdAt: string;
+}

package/src/http/http-rng-client.ts

@@ -0,0 +1,140 @@
+import { RngClientInterface } from "./rng-client.interface";
+import {
+  RngBatchFloatRequest,
+  RngBatchRequest,
+  RngBatchResponse,
+  RngBatchResponseWithSeeds,
+  RngSingleFloatRequest,
+  RngSingleRequest,
+  RngSingleResponse,
+} from "./http-client.types";
+import { RestClient } from "./rest-client";
+import { HttpConnectionError, HttpServiceError } from "../errors/rng-errors";
+
+export class HttpRngClient extends RestClient implements RngClientInterface {
+  constructor(baseUrl: string) {
+    super(baseUrl);
+  }
+
+  async getSingleNumber(request: RngSingleRequest): Promise<RngSingleResponse> {
+    const response = await this.post<RngSingleResponse>(
+      "/api/rng/single",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+
+  async getBatchNumbers(request: RngBatchRequest): Promise<RngBatchResponse> {
+    const response = await this.post<RngBatchResponse>(
+      "/api/rng/batch",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+
+  async getSingleFloat(
+    request: RngSingleFloatRequest
+  ): Promise<RngSingleResponse> {
+    const response = await this.post<RngSingleResponse>(
+      "/api/rng/float",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+
+  async getBatchFloats(
+    request: RngBatchFloatRequest
+  ): Promise<RngBatchResponse> {
+    const response = await this.post<RngBatchResponse>(
+      "/api/rng/batch/float",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+
+  async getBatchNumbersWithSeeds(
+    request: RngBatchRequest
+  ): Promise<RngBatchResponseWithSeeds> {
+    const response = await this.post<RngBatchResponseWithSeeds>(
+      "/api/rng/batch/with-seeds",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+
+  async getBatchFloatWithSeeds(
+    request: RngSingleFloatRequest
+  ): Promise<RngBatchResponseWithSeeds> {
+    const response = await this.post<RngBatchResponseWithSeeds>(
+      "/api/rng/batch/float/with-seeds",
+      request
+    );
+
+    if (!response.success) {
+      if (response.error === "ConnectionError" || response.statusCode === 503) {
+        throw new HttpConnectionError(response.message);
+      }
+      throw new HttpServiceError(
+        response.message || `HTTP error! status: ${response.statusCode}`,
+        response.statusCode
+      );
+    }
+
+    return response.data;
+  }
+}

package/src/http/rest-client.ts

@@ -0,0 +1,151 @@
+import axios, { AxiosError, AxiosInstance } from "axios";
+
+export interface ApiErrorData {
+  internalCode?: number;
+  message?: string;
+}
+
+export interface ApiSuccessResponse<T> {
+  success: true;
+  data: T;
+}
+
+export interface ApiErrorResponse<E = null> {
+  success: false;
+  error: string;
+  message: string;
+  statusCode: number;
+  internalCode?: number;
+  data?: E;
+}
+
+export type ApiResponse<T, E = null> =
+  | ApiSuccessResponse<T>
+  | ApiErrorResponse<E>;
+
+export class RestClient {
+  private httpClient: AxiosInstance;
+
+  constructor(baseUrl: string) {
+    this.httpClient = axios.create({
+      baseURL: baseUrl,
+      timeout: 5000,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  private isApiErrorData(data: any): data is ApiErrorData {
+    return data && typeof data === "object" && "internalCode" in data;
+  }
+
+  private mapSuccessResponse<T>(data: T): ApiSuccessResponse<T> {
+    return { success: true, data };
+  }
+
+  private mapErrorResponse<E>(error: unknown): ApiErrorResponse<E> {
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError;
+      const status = axiosError.response?.status || 500;
+      const data = axiosError.response?.data ?? {};
+
+      if (
+        axiosError.code === "ECONNREFUSED" ||
+        axiosError.code === "ENOTFOUND" ||
+        axiosError.code === "ETIMEDOUT" ||
+        axiosError.message.includes("timeout") ||
+        axiosError.message.includes("ECONNREFUSED") ||
+        axiosError.message.includes("ENOTFOUND")
+      ) {
+        return {
+          success: false,
+          error: "ConnectionError",
+          message: "Unable to connect to RNG service",
+          statusCode: 503,
+        };
+      }
+
+      if (this.isApiErrorData(data)) {
+        return {
+          success: false,
+          error: "ApiError",
+          message: data.message ?? "An unexpected error occurred.",
+          statusCode: status,
+          internalCode: data.internalCode,
+          data: data as E,
+        };
+      }
+
+      return {
+        success: false,
+        error: "UnknownError",
+        message: "An unexpected error occurred.",
+        statusCode: status,
+      };
+    } else if (error instanceof Error) {
+      if (
+        error.message.includes("ECONNREFUSED") ||
+        error.message.includes("ENOTFOUND") ||
+        error.message.includes("timeout")
+      ) {
+        return {
+          success: false,
+          error: "ConnectionError",
+          message: "Unable to connect to RNG service",
+          statusCode: 503,
+        };
+      }
+
+      return {
+        success: false,
+        error: "UnexpectedError",
+        message: error.message || "An unknown error occurred.",
+        statusCode: 500,
+      };
+    }
+
+    return {
+      success: false,
+      error: "UnknownError",
+      message: "An unknown error occurred.",
+      statusCode: 500,
+    };
+  }
+
+  private async handleRequest<T, E = null>(
+    request: Promise<{ data: T }>
+  ): Promise<ApiResponse<T, E>> {
+    try {
+      const response = await request;
+      return this.mapSuccessResponse(response.data);
+    } catch (error) {
+      return this.mapErrorResponse<E>(error);
+    }
+  }
+
+  public async get<T, E = null>(
+    url: string,
+    params?: object
+  ): Promise<ApiResponse<T, E>> {
+    return this.handleRequest(this.httpClient.get<T>(url, { params }));
+  }
+
+  public async post<T, E = null>(
+    url: string,
+    data?: object
+  ): Promise<ApiResponse<T, E>> {
+    return this.handleRequest(this.httpClient.post<T>(url, data));
+  }
+
+  public async put<T, E = null>(
+    url: string,
+    data?: object
+  ): Promise<ApiResponse<T, E>> {
+    return this.handleRequest(this.httpClient.put<T>(url, data));
+  }
+
+  public async delete<T, E = null>(url: string): Promise<ApiResponse<T, E>> {
+    return this.handleRequest(this.httpClient.delete<T>(url));
+  }
+}

package/src/http/rng-client.interface.ts

@@ -0,0 +1,22 @@
+import {
+  RngBatchFloatRequest,
+  RngBatchRequest,
+  RngBatchResponse,
+  RngBatchResponseWithSeeds,
+  RngSingleFloatRequest,
+  RngSingleRequest,
+  RngSingleResponse,
+} from "./http-client.types";
+
+export interface RngClientInterface {
+  getSingleNumber(request: RngSingleRequest): Promise<RngSingleResponse>;
+  getBatchNumbers(request: RngBatchRequest): Promise<RngBatchResponse>;
+  getSingleFloat(request: RngSingleFloatRequest): Promise<RngSingleResponse>;
+  getBatchFloats(request: RngBatchFloatRequest): Promise<RngBatchResponse>;
+  getBatchNumbersWithSeeds(
+    request: RngBatchRequest
+  ): Promise<RngBatchResponseWithSeeds>;
+  getBatchFloatWithSeeds(
+    request: RngSingleFloatRequest
+  ): Promise<RngBatchResponseWithSeeds>;
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Main API
+export { RngClient } from './rng-client';
+
+// Clients
+export { HttpRngClient } from './http/http-rng-client';
+export { GrpcRngClient } from './grpc/grpc-rng-client';
+
+export {
+  RngServiceError,
+  RngConnectionError,
+  HttpConnectionError,
+  HttpServiceError,
+  handleGrpcError,
+} from './errors/rng-errors';
+
+// Configuration
+export type {
+  RngClientConfig,
+  ClientMethod,
+} from './interfaces/client-interfaces';
+export type { RngClientMetricsHandlers as MetricsHandlers } from './interfaces/metrics';

package/src/interfaces/client-interfaces.ts

@@ -0,0 +1,15 @@
+import { StorageType } from '../ring-buffer/ring-storage';
+import { RngClientMetricsHandlers } from './metrics';
+
+export type ClientMethod = 'rest' | 'grpc';
+
+export interface RngClientConfig {
+  readonly serverUrl: string;
+  readonly grpcUrl: string;
+  readonly clientMethod: ClientMethod;
+  readonly poolingSize?: number;
+  readonly storageType?: StorageType;
+  readonly metrics?: {
+    handlers?: Partial<RngClientMetricsHandlers>;
+  };
+}