RNG Client Core

Multi-protocol client library for random number generation with the Omnitronix RNG service.

Features

• HTTP & gRPC Support: Choose between HTTP or gRPC communication
• Single & Batch Operations: Generate single numbers or batches
• Float Support: Dedicated endpoints for float generation
• TypeScript Support: Full type safety and IntelliSense
• Error Handling: Robust error handling with detailed messages
• Easy Integration: Simple configuration with server URL and optional gRPC URL

Installation

npm install @omnitronix/rng-client-core

Quick Start

Basic Usage

import { RngClient } from "@omnitronix/rng-client-core";

// Create RNG client instance
const rngClient = new RngClient({
  serverUrl: "http://localhost:3001",
});

// Get single random integer
const singleResult = await rngClient.getSingleNumber(1, 100);
console.log("Random number:", singleResult.result); // e.g., 42
console.log("Seed used:", singleResult.seed);
console.log("Generated at:", singleResult.createdAt);

// Get single random float
const floatResult = await rngClient.getSingleFloat();
console.log("Random float:", floatResult.result); // e.g., 0.75

// Get batch of integers
const batchResult = await rngClient.getBatchNumbers(1, 100, 10);
console.log("Batch numbers:", batchResult.result); // [42, 15, 78, ...]

// Get batch of floats
const batchFloats = await rngClient.getBatchFloats(5);
console.log("Batch floats:", batchFloats.result); // [0.75, 0.23, 0.91, ...]

// Alternative method names
const randomNumber = await rngClient.getRandomNumber(1, 100);
const randomFloat = await rngClient.getRandomFloat();

Configuration

import { RngClient, RngClientConfig } from "@omnitronix/rng-client-core";

const config: RngClientConfig = {
  serverUrl: "https://rng.example.com:3001", // RNG service URL
  grpcUrl: "rng.example.com:50051", // gRPC service URL
  clientMethod: "rest", // 'rest' or 'grpc'
  // Optional parameters for future use:
  // bufferSize: 10000,
  // refillThreshold: 0.2,
  // connectionTimeout: 5000,
  // retryAttempts: 3,
  // retryDelay: 1000
};

const rngClient = new RngClient(config);

Protocol Selection

The client uses the clientMethod parameter to determine the communication protocol:

• REST/HTTP: Set clientMethod: "rest" (default)

  const rngClient = new RngClient({
    serverUrl: "http://localhost:3001",
    clientMethod: "rest",
  });

• gRPC: Set clientMethod: "grpc" and provide grpcUrl

  const rngClient = new RngClient({
    serverUrl: "http://localhost:3001", // Required but not used
    grpcUrl: "localhost:50051",
    clientMethod: "grpc",
  });

• Both parameters required: Both serverUrl and grpcUrl must be provided

  const rngClient = new RngClient({
    serverUrl: "http://localhost:3001",
    grpcUrl: "localhost:50051",
    clientMethod: "rest", // or "grpc"
  });

Error Handling

try {
  const result = await rngClient.generateSingle(1, 100);
  console.log("Success:", result.result);
} catch (error) {
  if (error.message.includes("HTTP error! status: 500")) {
    console.error("RNG service is down");
  } else if (error.message.includes("HTTP error! status: 400")) {
    console.error("Invalid request parameters");
  } else {
    console.error("Unexpected error:", error.message);
  }
}

API Reference

RngClient

Main class for client-side random number generation.

Constructor

constructor(config: RngClientConfig)

• config.serverUrl: RNG service URL (required)
• config.grpcUrl: gRPC service URL (required)
• config.clientMethod: Communication method - 'rest' or 'grpc' (required)
• config.bufferSize: Optional buffer size for future use
• config.refillThreshold: Optional refill threshold for future use
• config.connectionTimeout: Optional connection timeout
• config.retryAttempts: Optional retry attempts
• config.retryDelay: Optional retry delay

Methods

getSingleNumber(min: number, max: number, seed?: number): Promise<RngSingleResponse>

Get a single random number.

• min: Minimum value (inclusive)
• max: Maximum value (inclusive)
• seed: Optional seed for deterministic generation
• Returns: Promise with RngSingleResponse

getBatchNumbers(min: number, max: number, count: number, seed?: number): Promise<RngBatchResponse>

Get a batch of random numbers.

• min: Minimum value (inclusive)
• max: Maximum value (inclusive)
• count: Number of values to generate
• seed: Optional seed for deterministic generation
• Returns: Promise with RngBatchResponse

getSingleFloat(seed?: number): Promise<RngSingleResponse>

Get a single random float.

• seed: Optional seed for deterministic generation
• Returns: Promise with RngSingleResponse

getBatchFloats(count: number, seed?: number): Promise<RngBatchResponse>

Get a batch of random floats.

• count: Number of values to generate
• seed: Optional seed for deterministic generation
• Returns: Promise with RngBatchResponse

getRandomNumber(min: number, max: number, seed?: number): Promise<RngSingleResponse>

Get a random number.

• min: Minimum value (inclusive)
• max: Maximum value (inclusive)
• seed: Optional seed for deterministic generation
• Returns: Promise with RngSingleResponse

getRandomFloat(seed?: number): Promise<RngSingleResponse>

Get a random float.

• seed: Optional seed for deterministic generation
• Returns: Promise with RngSingleResponse

Response Types

RngSingleResponse

interface RngSingleResponse {
  readonly id: string; // Unique identifier
  readonly seed: number; // Seed used for generation
  readonly result: number; // Generated value
  readonly min: number; // Minimum value
  readonly max: number; // Maximum value
  readonly createdAt: string; // Generation timestamp (ISO string)
  readonly sessionId?: string; // Optional session ID
}

RngBatchResponse

interface RngBatchResponse {
  readonly id: string; // Unique identifier
  readonly seed: number; // Seed used for generation
  readonly result: number[]; // Generated values array
  readonly min: number; // Minimum value
  readonly max: number; // Maximum value
  readonly createdAt: string; // Generation timestamp (ISO string)
  readonly sessionId?: string; // Optional session ID
}

Integration Examples

Express.js Application

import express from "express";
import { RngClient } from "@omnitronix/rng-client-core";

const app = express();
const rngClient = new RngClient({
  serverUrl: process.env.RNG_SERVER_URL || "http://localhost:3001",
});

app.get("/api/random", async (req, res) => {
  try {
    const result = await rngClient.getSingleNumber(1, 100);
    res.json({ randomNumber: result.result });
  } catch (error) {
    res.status(500).json({ error: "Failed to generate random number" });
  }
});

app.listen(3000);

NestJS Service

import { Injectable } from "@nestjs/common";
import { RngClient } from "@omnitronix/rng-client-core";

@Injectable()
export class GameService {
  private readonly rngClient: RngClient;

  constructor() {
    this.rngClient = new RngClient({
      serverUrl: process.env.RNG_SERVER_URL,
    });
  }

  async rollDice(): Promise<number> {
    const result = await this.rngClient.getSingleNumber(1, 6);
    return result.result;
  }

  async generateLootTable(): Promise<number[]> {
    const result = await this.rngClient.getBatchNumbers(1, 100, 10);
    return result.result;
  }
}

React Hook

import { useState, useCallback } from "react";
import { RngClient } from "@omnitronix/rng-client-core";

export const useRng = (serverUrl: string) => {
  const [rngClient] = useState(() => new RngClient({ serverUrl }));
  const [loading, setLoading] = useState(false);

  const generateRandom = useCallback(
    async (min: number, max: number) => {
      setLoading(true);
      try {
        const result = await rngClient.getSingleNumber(min, max);
        return result.result;
      } finally {
        setLoading(false);
      }
    },
    [rngClient]
  );

  return { generateRandom, loading };
};

Environment Configuration

Development

RNG_SERVER_URL=http://localhost:3001

Production

RNG_SERVER_URL=https://rng.production.com:3001

Docker

version: "3.8"
services:
  app:
    build: .
    environment:
      - RNG_SERVER_URL=http://rng-service:3001
    depends_on:
      - rng-service

Error Handling

The client handles various error scenarios:

• Connection Errors: Network issues, service unavailable
• HTTP Errors: 4xx/5xx status codes with detailed messages
• Validation Errors: Invalid parameters (400 Bad Request)
• Server Errors: Internal server errors (500 Internal Server Error)

License

Proprietary - Omnitronix Internal Use Only