@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/services/parallel/native-worker.entry.js

@@ -0,0 +1,10 @@
+import { parentPort } from 'node:worker_threads';
+import { processMessage } from './worker';
+const port = parentPort;
+if (!port) {
+    throw new Error('native-worker.entry.ts must be executed inside a Worker thread');
+}
+port.on('message', (message) => {
+    const response = processMessage(message);
+    port.postMessage(response);
+});

package/dist/runtime/server/services/parallel/worker-pool.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Worker Pool
+ *
+ * Native worker thread pool for CPU-bound computations.
+ * Tasks are executed in `node:worker_threads` and communicated through
+ * structured-cloned messages.
+ */
+import { WorkerInfo, WorkerMessage, WorkerPoolConfig } from '../../types/parallel.types';
+type EventCallback = (...args: unknown[]) => void;
+/**
+ * Simple event emitter (FiveM compatible)
+ */
+declare class SimpleEventEmitter {
+    private events;
+    on(event: string, callback: EventCallback): void;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, ...args: unknown[]): void;
+}
+export declare class WorkerPool extends SimpleEventEmitter {
+    private workers;
+    private taskQueue;
+    private config;
+    private workerIdCounter;
+    private cleanupInterval;
+    private isShuttingDown;
+    private workerScriptPath;
+    constructor(config?: Partial<WorkerPoolConfig>);
+    /**
+     * Check if using native workers
+     */
+    get isNative(): boolean;
+    /**
+     * Execute a task
+     */
+    execute(message: WorkerMessage): Promise<unknown>;
+    /**
+     * Get current pool statistics
+     */
+    getStats(): {
+        totalWorkers: number;
+        idleWorkers: number;
+        busyWorkers: number;
+        queuedTasks: number;
+        isNative: boolean;
+    };
+    /**
+     * Get all worker info
+     */
+    getWorkerInfo(): WorkerInfo[];
+    /**
+     * Shutdown the pool gracefully
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Spawn a new native worker
+     */
+    private spawnWorker;
+    /**
+     * Find an idle worker
+     */
+    private findIdleWorker;
+    /**
+     * Assign a task to a worker
+     */
+    private assignTask;
+    /**
+     * Handle task timeout
+     */
+    private handleTaskTimeout;
+    /**
+     * Process queued tasks
+     */
+    private processQueue;
+    /**
+     * Cleanup idle workers
+     */
+    private cleanupIdleWorkers;
+}
+export {};

package/dist/runtime/server/services/parallel/worker-pool.js

@@ -0,0 +1,428 @@
+/**
+ * Worker Pool
+ *
+ * Native worker thread pool for CPU-bound computations.
+ * Tasks are executed in `node:worker_threads` and communicated through
+ * structured-cloned messages.
+ */
+import * as path from 'node:path';
+import { Worker } from 'node:worker_threads';
+const DEFAULT_CONFIG = {
+    minWorkers: 0,
+    maxWorkers: 4,
+    idleTimeout: 30000,
+    taskTimeout: 60000,
+};
+/**
+ * Simple event emitter (FiveM compatible)
+ */
+class SimpleEventEmitter {
+    events = new Map();
+    on(event, callback) {
+        const callbacks = this.events.get(event) || [];
+        callbacks.push(callback);
+        this.events.set(event, callbacks);
+    }
+    off(event, callback) {
+        const callbacks = this.events.get(event) || [];
+        const index = callbacks.indexOf(callback);
+        if (index !== -1) {
+            callbacks.splice(index, 1);
+        }
+    }
+    emit(event, ...args) {
+        const callbacks = this.events.get(event) || [];
+        for (const callback of callbacks) {
+            try {
+                callback(...args);
+            }
+            catch {
+                // Ignore callback errors
+            }
+        }
+    }
+}
+/**
+ * Native worker backed by `node:worker_threads`.
+ *
+ * Executes one task at a time and returns `WorkerResponse` coming from the
+ * worker entrypoint.
+ */
+class NativeWorker {
+    id;
+    _status = 'idle';
+    tasksCompleted = 0;
+    lastActiveAt = Date.now();
+    currentTask = null;
+    worker;
+    pendingResponses = new Map();
+    constructor(id, workerScriptPath, callbacks) {
+        this.id = id;
+        this.worker = new Worker(workerScriptPath);
+        this.worker.on('message', (response) => {
+            const handlers = this.pendingResponses.get(response.id);
+            if (handlers) {
+                this.pendingResponses.delete(response.id);
+                handlers.resolve(response);
+            }
+        });
+        this.worker.on('error', (error) => {
+            this.failAllPending(error instanceof Error ? error : new Error(String(error)));
+            this._status = 'terminated';
+            this.currentTask = null;
+            callbacks.onError(this.id, error instanceof Error ? error : new Error(String(error)));
+        });
+        this.worker.on('exit', (code) => {
+            if (this._status !== 'terminated') {
+                this.failAllPending(new Error(`Worker exited with code ${code}`));
+            }
+            this._status = 'terminated';
+            this.currentTask = null;
+            callbacks.onExit(this.id, code);
+        });
+    }
+    get status() {
+        return this._status;
+    }
+    get info() {
+        return {
+            id: this.id,
+            status: this._status,
+            currentTaskId: this.currentTask?.id ?? null,
+            tasksCompleted: this.tasksCompleted,
+            lastActiveAt: this.lastActiveAt,
+        };
+    }
+    async execute(task) {
+        if (this._status === 'terminated') {
+            throw new Error('Worker is terminated');
+        }
+        this._status = 'busy';
+        this.currentTask = task;
+        return new Promise((resolve, reject) => {
+            this.pendingResponses.set(task.id, {
+                resolve: (response) => {
+                    this.tasksCompleted++;
+                    this.lastActiveAt = Date.now();
+                    this._status = 'idle';
+                    this.currentTask = null;
+                    resolve(response);
+                },
+                reject: (error) => {
+                    this._status = 'idle';
+                    this.currentTask = null;
+                    reject(error);
+                },
+            });
+            this.worker.postMessage(task.message);
+        });
+    }
+    terminate() {
+        this._status = 'terminated';
+        this.currentTask = null;
+        void this.worker.terminate();
+    }
+    cancelTask(taskId, reason) {
+        const handlers = this.pendingResponses.get(taskId);
+        if (handlers) {
+            this.pendingResponses.delete(taskId);
+            handlers.reject(reason);
+        }
+    }
+    failAllPending(error) {
+        const handlers = Array.from(this.pendingResponses.values());
+        this.pendingResponses.clear();
+        for (const h of handlers) {
+            try {
+                h.reject(error);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+export class WorkerPool extends SimpleEventEmitter {
+    workers = new Map();
+    taskQueue = [];
+    config;
+    workerIdCounter = 0;
+    cleanupInterval = null;
+    isShuttingDown = false;
+    workerScriptPath;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.workerScriptPath = path.join(__dirname, 'native-worker.entry.js');
+        // Start cleanup interval
+        this.cleanupInterval = setInterval(() => this.cleanupIdleWorkers(), 10000);
+        // Spawn minimum workers
+        for (let i = 0; i < this.config.minWorkers; i++) {
+            this.spawnWorker();
+        }
+    }
+    /**
+     * Check if using native workers
+     */
+    get isNative() {
+        return true;
+    }
+    /**
+     * Execute a task
+     */
+    async execute(message) {
+        if (this.isShuttingDown) {
+            throw new Error('Worker pool is shutting down');
+        }
+        return new Promise((resolve, reject) => {
+            const task = {
+                id: message.id,
+                message,
+                resolve,
+                reject,
+                startTime: Date.now(),
+                timeoutId: null,
+                settled: false,
+            };
+            // Set timeout
+            task.timeoutId = setTimeout(() => {
+                this.handleTaskTimeout(task);
+            }, this.config.taskTimeout);
+            // Find an idle worker
+            const idleWorker = this.findIdleWorker();
+            if (idleWorker) {
+                this.assignTask(idleWorker, task);
+            }
+            else if (this.workers.size < this.config.maxWorkers) {
+                const newWorker = this.spawnWorker();
+                if (newWorker) {
+                    this.assignTask(newWorker, task);
+                }
+                else {
+                    this.taskQueue.push(task);
+                }
+            }
+            else {
+                this.taskQueue.push(task);
+            }
+        });
+    }
+    /**
+     * Get current pool statistics
+     */
+    getStats() {
+        let idle = 0;
+        let busy = 0;
+        for (const worker of this.workers.values()) {
+            if (worker.status === 'idle')
+                idle++;
+            else if (worker.status === 'busy')
+                busy++;
+        }
+        return {
+            totalWorkers: this.workers.size,
+            idleWorkers: idle,
+            busyWorkers: busy,
+            queuedTasks: this.taskQueue.length,
+            isNative: true,
+        };
+    }
+    /**
+     * Get all worker info
+     */
+    getWorkerInfo() {
+        return Array.from(this.workers.values()).map((w) => w.info);
+    }
+    /**
+     * Shutdown the pool gracefully
+     */
+    async shutdown() {
+        this.isShuttingDown = true;
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Reject all queued tasks
+        for (const task of this.taskQueue) {
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            task.reject(new Error('Worker pool shutdown'));
+        }
+        this.taskQueue = [];
+        // Terminate all workers
+        for (const worker of this.workers.values()) {
+            worker.terminate();
+        }
+        this.workers.clear();
+    }
+    /**
+     * Spawn a new native worker
+     */
+    spawnWorker() {
+        try {
+            const id = this.workerIdCounter++;
+            const worker = new NativeWorker(id, this.workerScriptPath, {
+                onExit: (workerId, code) => {
+                    const existing = this.workers.get(workerId);
+                    if (!existing)
+                        return;
+                    this.workers.delete(workerId);
+                    this.emit('workerExit', { workerId, code: code ?? 0 });
+                    if (!this.isShuttingDown && this.workers.size < this.config.minWorkers) {
+                        this.spawnWorker();
+                    }
+                },
+                onError: (workerId, error) => {
+                    const existing = this.workers.get(workerId);
+                    if (!existing)
+                        return;
+                    this.workers.delete(workerId);
+                    this.emit('workerExit', { workerId, code: 1, error: error.message });
+                    if (!this.isShuttingDown && this.workers.size < this.config.minWorkers) {
+                        this.spawnWorker();
+                    }
+                },
+            });
+            this.workers.set(id, worker);
+            this.emit('workerSpawned', id);
+            return worker;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Find an idle worker
+     */
+    findIdleWorker() {
+        for (const worker of this.workers.values()) {
+            if (worker.status === 'idle') {
+                return worker;
+            }
+        }
+        return null;
+    }
+    /**
+     * Assign a task to a worker
+     */
+    async assignTask(worker, task) {
+        try {
+            const response = await worker.execute(task);
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            if (task.settled) {
+                // Task was already rejected (e.g. timeout). Ignore late responses.
+                this.processQueue();
+                return;
+            }
+            if (response.success) {
+                task.settled = true;
+                task.resolve(response.result);
+            }
+            else {
+                task.settled = true;
+                task.reject(new Error(response.error || 'Unknown worker error'));
+            }
+            this.emit('taskCompleted', {
+                taskId: response.id,
+                workerId: worker.id,
+                executionTime: response.executionTime,
+            });
+            // Process next queued task
+            this.processQueue();
+        }
+        catch (error) {
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            if (!task.settled) {
+                task.settled = true;
+                task.reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+    /**
+     * Handle task timeout
+     */
+    handleTaskTimeout(task) {
+        const timeoutError = new Error('Task timeout');
+        if (task.timeoutId) {
+            clearTimeout(task.timeoutId);
+            task.timeoutId = null;
+        }
+        if (!task.settled) {
+            task.settled = true;
+            task.reject(timeoutError);
+        }
+        // Try to terminate the worker that was executing this task.
+        for (const [id, worker] of this.workers) {
+            if (worker.info.currentTaskId === task.id) {
+                worker.cancelTask(task.id, timeoutError);
+                worker.terminate();
+                this.workers.delete(id);
+                this.emit('workerExit', { workerId: id, code: 1 });
+                if (!this.isShuttingDown && this.workers.size < this.config.minWorkers) {
+                    this.spawnWorker();
+                }
+                break;
+            }
+        }
+        // Remove from queue if present
+        const queueIndex = this.taskQueue.findIndex((t) => t.id === task.id);
+        if (queueIndex !== -1) {
+            this.taskQueue.splice(queueIndex, 1);
+        }
+    }
+    /**
+     * Process queued tasks
+     */
+    processQueue() {
+        while (this.taskQueue.length > 0) {
+            const idleWorker = this.findIdleWorker();
+            if (idleWorker) {
+                const task = this.taskQueue.shift();
+                if (!task)
+                    break;
+                this.assignTask(idleWorker, task);
+            }
+            else if (this.workers.size < this.config.maxWorkers) {
+                const newWorker = this.spawnWorker();
+                if (newWorker) {
+                    const task = this.taskQueue.shift();
+                    if (!task)
+                        break;
+                    this.assignTask(newWorker, task);
+                }
+                else {
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+    }
+    /**
+     * Cleanup idle workers
+     */
+    cleanupIdleWorkers() {
+        if (this.isShuttingDown)
+            return;
+        const now = Date.now();
+        const workersToRemove = [];
+        for (const [id, worker] of this.workers) {
+            if (worker.status === 'idle' &&
+                now - worker.info.lastActiveAt > this.config.idleTimeout &&
+                this.workers.size > this.config.minWorkers) {
+                workersToRemove.push(id);
+            }
+        }
+        for (const id of workersToRemove) {
+            const worker = this.workers.get(id);
+            if (worker) {
+                worker.terminate();
+                this.workers.delete(id);
+                this.emit('workerExit', { workerId: id, code: 0 });
+            }
+        }
+    }
+}

package/dist/runtime/server/services/parallel/worker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Worker Script
+ *
+ * Utilities used by the native worker thread entrypoint.
+ *
+ * The worker pool executes user-provided compute functions by serializing the
+ * function body (`Function#toString()`) and evaluating it with `new Function`.
+ *
+ * Requirements/limitations:
+ * - The compute function must be pure (no closures / no external references).
+ * - Inputs/outputs must be structured-cloneable.
+ * - Do not pass untrusted code as compute functions.
+ */
+import { WorkerMessage, WorkerResponse } from '../../types/parallel.types';
+/**
+ * Execute a compute function from its string body
+ */
+export declare function executeCompute(functionBody: string, input: unknown): unknown;
+/**
+ * Process a worker message and return a response
+ */
+export declare function processMessage(message: WorkerMessage): WorkerResponse;

package/dist/runtime/server/services/parallel/worker.js

@@ -0,0 +1,48 @@
+/**
+ * Worker Script
+ *
+ * Utilities used by the native worker thread entrypoint.
+ *
+ * The worker pool executes user-provided compute functions by serializing the
+ * function body (`Function#toString()`) and evaluating it with `new Function`.
+ *
+ * Requirements/limitations:
+ * - The compute function must be pure (no closures / no external references).
+ * - Inputs/outputs must be structured-cloneable.
+ * - Do not pass untrusted code as compute functions.
+ */
+/**
+ * Execute a compute function from its string body
+ */
+export function executeCompute(functionBody, input) {
+    const fn = new Function('input', `return (${functionBody})(input)`);
+    return fn(input);
+}
+/**
+ * Process a worker message and return a response
+ */
+export function processMessage(message) {
+    const startTime = performance.now();
+    try {
+        const result = executeCompute(message.functionBody, message.input);
+        const executionTime = performance.now() - startTime;
+        return {
+            id: message.id,
+            success: true,
+            result,
+            executionTime,
+        };
+    }
+    catch (error) {
+        const executionTime = performance.now() - startTime;
+        return {
+            id: message.id,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            executionTime,
+        };
+    }
+}
+// Note: Native worker thread initialization would go here
+// when the runtime supports it. For now, this module exports
+// utilities that can be used by the virtual worker implementation.

package/dist/runtime/server/services/persistence.service.d.ts

@@ -0,0 +1,59 @@
+import { Player } from '../entities/player';
+/**
+ * Internal service that orchestrates player data persistence.
+ *
+ * This service manages the lifecycle of persistence hooks and auto-save intervals.
+ * It is used internally by the framework and should not be instantiated directly.
+ */
+export declare class PlayerPersistenceService {
+    private provider;
+    private autoSaveIntervals;
+    private initialized;
+    /**
+     * Initializes the persistence service by resolving the provider from DI.
+     * Called during bootstrap if a provider is registered.
+     */
+    initialize(): void;
+    /**
+     * Whether persistence is enabled (provider is configured).
+     */
+    get isEnabled(): boolean;
+    /**
+     * Handles player session load - called when a player joins.
+     *
+     * @param player - The player who just joined
+     */
+    handleSessionLoad(player: Player): Promise<void>;
+    /**
+     * Handles player session save - called when a player disconnects.
+     *
+     * @param player - The player who is disconnecting
+     */
+    handleSessionSave(player: Player): Promise<void>;
+    /**
+     * Manually triggers a save for a specific player.
+     *
+     * @param player - The player whose data should be saved
+     */
+    savePlayer(player: Player): Promise<void>;
+    /**
+     * Saves all connected players' data.
+     * Useful for server shutdown or periodic global saves.
+     *
+     * @param players - Array of all connected players
+     */
+    saveAllPlayers(players: Player[]): Promise<void>;
+    /**
+     * Starts the auto-save interval for a player.
+     */
+    private startAutoSave;
+    /**
+     * Stops the auto-save interval for a player.
+     */
+    private stopAutoSave;
+    /**
+     * Stops all auto-save intervals.
+     * Called during server shutdown.
+     */
+    stopAllAutoSaves(): void;
+}