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

package/dist/runtime/server/controllers/chat.controller.js

@@ -0,0 +1,67 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject } from 'tsyringe';
+import { Controller } from '../decorators/controller';
+import { Export } from '../decorators/export';
+import { Chat } from '../apis/chat.api';
+import { Players } from '../ports/players.api-port';
+let ChatController = class ChatController {
+    chat;
+    players;
+    constructor(chat, players) {
+        this.chat = chat;
+        this.players = players;
+    }
+    coreBroadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+        this.chat.broadcast(message, author, color);
+    }
+    coreSendPrivate(targetId, message, author = 'Private') {
+        const player = this.players.getByClient(targetId);
+        if (!player) {
+            throw new Error(`Player with client ID ${targetId} not found`);
+        }
+        this.chat.sendPrivate(player, message, author);
+    }
+    coreSendToGroupOfPlayers(targets, message, author = 'Private', color) {
+        const players = this.players.getMany(targets);
+        for (let i = 0; i < players.length; i++) {
+            this.chat.sendPrivate(players[i], message, author, color);
+        }
+    }
+};
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "coreBroadcast", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String, String]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "coreSendPrivate", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array, String, String, Object]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "coreSendToGroupOfPlayers", null);
+ChatController = __decorate([
+    Controller(),
+    __param(0, inject(Chat)),
+    __param(1, inject(Players)),
+    __metadata("design:paramtypes", [Chat,
+        Players])
+], ChatController);
+export { ChatController };

package/dist/runtime/server/controllers/command-export.controller.d.ts

@@ -0,0 +1,83 @@
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
+import { Player } from '../entities';
+import { CommandExecutionPort, type CommandInfo } from '../ports/internal/command-execution.port';
+import { Players } from '../ports/players.api-port';
+import { Authorization } from '../ports/authorization.api-port';
+import { RateLimiterService } from '../services/rate-limiter.service';
+import { CommandRegistrationDto, InternalCommandsExports } from '../types/core-exports.types';
+/**
+ * Export controller for command system (CORE mode only).
+ *
+ * @remarks
+ * Exposes command registration and execution to RESOURCE mode instances.
+ * Maintains a registry of both local and remote commands, delegating
+ * remote command execution back to the owning resource via net events.
+ */
+export declare class CommandExportController implements InternalCommandsExports {
+    private commandService;
+    private playerDirectory;
+    private principalPort;
+    private rateLimiter;
+    private readonly commandErrorObserver;
+    private engineEvents;
+    private remoteCommands;
+    constructor(commandService: CommandExecutionPort, playerDirectory: Players, principalPort: Authorization, rateLimiter: RateLimiterService, commandErrorObserver: CommandErrorObserverContract, engineEvents: IEngineEvents);
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break the command pipeline.
+     */
+    private safeObserve;
+    /**
+     * Receives command execution requests from clients.
+     *
+     * @remarks
+     * This is the entry point for all command execution in CORE mode.
+     * Handles both local commands (registered in CORE) and remote commands
+     * (registered by RESOURCE mode instances).
+     */
+    onCommandReceived(player: Player, command: string, args: string[]): Promise<void>;
+    /**
+     * Registers a command from a RESOURCE with CORE.
+     *
+     * @remarks
+     * The command handler remains in the resource. CORE stores metadata
+     * and delegates execution back to the resource when invoked.
+     *
+     * Exported as: `exports[coreResourceName].registerCommand`
+     */
+    registerCommand(metadata: CommandRegistrationDto): void;
+    /**
+     * Executes a command (local or remote).
+     *
+     * @remarks
+     * If the command is registered locally in CORE, executes it directly.
+     * If it's a remote command, delegates to the owning resource via net event.
+     *
+     * Exported as: `exports[coreResourceName].executeCommand`
+     */
+    executeCommand(clientID: number, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns all registered commands (local + remote).
+     *
+     * Exported as: `exports[coreResourceName].getAllCommands`
+     */
+    getAllCommands(): CommandInfo[];
+    /**
+     * Validates security decorators before delegating to RESOURCE.
+     *
+     * @remarks
+     * Validation order: @Guard → @Throttle → @RequiresState
+     * Throws on first failure to prevent execution.
+     *
+     * @param player - Player executing the command
+     * @param commandName - Command name (for rate limit key)
+     * @param security - Security metadata from command decorators
+     *
+     * @throws AppError - If @Guard or @RequiresState validation fails
+     * @throws SecurityError - If @Throttle rate limit is exceeded
+     */
+    private validateSecurity;
+}

package/dist/runtime/server/controllers/command-export.controller.js

@@ -0,0 +1,331 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject } from 'tsyringe';
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { AppError, SecurityError } from '../../../kernel/error';
+import { loggers } from '../../../kernel/logger';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
+import { Controller, Export, Public } from '../decorators';
+import { OnNet } from '../decorators/onNet';
+import { Player } from '../entities';
+import { normalizeToAppError } from '../helpers/normalize-app-error';
+import { getRuntimeContext } from '../runtime';
+import { CommandExecutionPort } from '../ports/internal/command-execution.port';
+import { Players } from '../ports/players.api-port';
+import { Authorization } from '../ports/authorization.api-port';
+import { RateLimiterService } from '../services/rate-limiter.service';
+/**
+ * Export controller for command system (CORE mode only).
+ *
+ * @remarks
+ * Exposes command registration and execution to RESOURCE mode instances.
+ * Maintains a registry of both local and remote commands, delegating
+ * remote command execution back to the owning resource via net events.
+ */
+let CommandExportController = class CommandExportController {
+    commandService;
+    playerDirectory;
+    principalPort;
+    rateLimiter;
+    commandErrorObserver;
+    engineEvents;
+    remoteCommands = new Map();
+    constructor(commandService, playerDirectory, principalPort, rateLimiter, commandErrorObserver, engineEvents) {
+        this.commandService = commandService;
+        this.playerDirectory = playerDirectory;
+        this.principalPort = principalPort;
+        this.rateLimiter = rateLimiter;
+        this.commandErrorObserver = commandErrorObserver;
+        this.engineEvents = engineEvents;
+    }
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break the command pipeline.
+     */
+    async safeObserve(ctx) {
+        try {
+            await this.commandErrorObserver.onError(ctx);
+        }
+        catch (e) {
+            loggers.command.fatal(`Command error observer failed`, ctx, e);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Network Event Handler (receives commands from clients)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Receives command execution requests from clients.
+     *
+     * @remarks
+     * This is the entry point for all command execution in CORE mode.
+     * Handles both local commands (registered in CORE) and remote commands
+     * (registered by RESOURCE mode instances).
+     */
+    async onCommandReceived(player, command, args) {
+        try {
+            if (command.startsWith('/'))
+                command = command.slice(1);
+            // Basic input validation
+            if (args.length > 10 || !/^[a-zA-Z0-9:_-]+$/.test(command)) {
+                loggers.command.warn(`Rejected suspicious command: ${command}`, {
+                    playerId: player.clientID,
+                    playerName: player.name,
+                    accountID: player.accountID,
+                    args: args,
+                });
+                return;
+            }
+            loggers.command.trace(`Received: /${command}`, {
+                playerId: player.clientID,
+                playerName: player.name,
+            });
+            // Use unified execution that handles both local and remote commands
+            await this.executeCommand(player.clientID, command, args);
+        }
+        catch (error) {
+            const runtime = getRuntimeContext();
+            const remoteEntry = this.remoteCommands.get(command.toLowerCase());
+            const localMeta = this.commandService.getCommandMeta(command);
+            const appError = normalizeToAppError(error, 'server');
+            // If we have an error and it's not a remote command, try to find local meta
+            // to populate the error context properly for the observer.
+            const commandInfo = localMeta
+                ? {
+                    command: localMeta.command,
+                    description: localMeta.description,
+                    usage: localMeta.usage,
+                    isPublic: localMeta.isPublic,
+                    methodName: localMeta.methodName,
+                    expectsPlayer: localMeta.expectsPlayer,
+                    paramNames: localMeta.paramNames,
+                }
+                : remoteEntry
+                    ? {
+                        command: remoteEntry.metadata.command,
+                        description: remoteEntry.metadata.description,
+                        usage: remoteEntry.metadata.usage,
+                        isPublic: remoteEntry.metadata.isPublic,
+                    }
+                    : undefined;
+            const stage = error instanceof SecurityError
+                ? 'security'
+                : appError.code === 'AUTH:UNAUTHORIZED'
+                    ? 'auth'
+                    : appError.code === 'GAME:BAD_REQUEST' || appError.code.startsWith('SCHEMA:')
+                        ? 'validation'
+                        : appError.code === 'COMMAND:NOT_FOUND'
+                            ? 'dispatch'
+                            : 'unknown';
+            await this.safeObserve({
+                mode: runtime.mode,
+                scope: runtime.mode === 'CORE'
+                    ? 'core'
+                    : runtime.mode === 'RESOURCE'
+                        ? 'resource'
+                        : 'standalone',
+                stage,
+                error: appError,
+                commandName: command,
+                args,
+                player: {
+                    clientId: player.clientID,
+                    accountId: player.accountID || player.clientID.toString(),
+                    name: player.name,
+                },
+                playerRef: player,
+                ownerResourceName: remoteEntry?.resourceName,
+                command: commandInfo,
+                commandMeta: localMeta,
+            });
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Command Registration (for RESOURCE mode)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Registers a command from a RESOURCE with CORE.
+     *
+     * @remarks
+     * The command handler remains in the resource. CORE stores metadata
+     * and delegates execution back to the resource when invoked.
+     *
+     * Exported as: `exports[coreResourceName].registerCommand`
+     */
+    registerCommand(metadata) {
+        const commandKey = metadata.command.toLowerCase();
+        const existing = this.remoteCommands.get(commandKey);
+        if (existing) {
+            // Allow re-registration from the same resource (hot-reload scenario)
+            if (existing.resourceName === metadata.resourceName) {
+                loggers.command.debug(`Re-registering command '${metadata.command}' from same resource (hot-reload)`, { command: metadata.command, resource: metadata.resourceName });
+                // Update the entry with new metadata
+                this.remoteCommands.set(commandKey, {
+                    metadata,
+                    resourceName: metadata.resourceName,
+                });
+                return;
+            }
+            loggers.command.warn(`Remote command '${metadata.command}' already registered`, {
+                command: metadata.command,
+                existingResource: existing.resourceName,
+                newResource: metadata.resourceName,
+            });
+            return;
+        }
+        this.remoteCommands.set(commandKey, {
+            metadata,
+            resourceName: metadata.resourceName,
+        });
+        const publicFlag = metadata.isPublic ? ' [Public]' : '';
+        loggers.command.debug(`Registered remote command: /${metadata.command}${publicFlag} (owner: ${metadata.resourceName})`);
+    }
+    /**
+     * Executes a command (local or remote).
+     *
+     * @remarks
+     * If the command is registered locally in CORE, executes it directly.
+     * If it's a remote command, delegates to the owning resource via net event.
+     *
+     * Exported as: `exports[coreResourceName].executeCommand`
+     */
+    async executeCommand(clientID, commandName, args) {
+        const player = this.playerDirectory.getByClient(clientID);
+        if (!player) {
+            throw new AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${clientID}`, 'core');
+        }
+        const commandKey = commandName.toLowerCase();
+        const remoteEntry = this.remoteCommands.get(commandKey);
+        if (remoteEntry) {
+            // Validate security BEFORE delegating to resource
+            await this.validateSecurity(player, commandName, remoteEntry.metadata.security);
+            // Delegate to resource via local event (server-to-server, not network)
+            const eventName = `opencore:command:execute:${remoteEntry.resourceName}`;
+            this.engineEvents.emit(eventName, clientID, commandName, args);
+            loggers.command.debug(`Delegated remote command execution to ${remoteEntry.resourceName}`, {
+                command: commandName,
+                clientID,
+                resource: remoteEntry.resourceName,
+            });
+            return;
+        }
+        // Execute local command
+        return await this.commandService.execute(player, commandName, args);
+    }
+    /**
+     * Returns all registered commands (local + remote).
+     *
+     * Exported as: `exports[coreResourceName].getAllCommands`
+     */
+    getAllCommands() {
+        const localCommands = this.commandService.getAllCommands();
+        const remoteCommandsInfo = Array.from(this.remoteCommands.values()).map((entry) => ({
+            command: entry.metadata.command,
+            description: entry.metadata.description,
+            usage: entry.metadata.usage,
+            isPublic: entry.metadata.isPublic,
+        }));
+        return [...localCommands, ...remoteCommandsInfo];
+    }
+    /**
+     * Validates security decorators before delegating to RESOURCE.
+     *
+     * @remarks
+     * Validation order: @Guard → @Throttle → @RequiresState
+     * Throws on first failure to prevent execution.
+     *
+     * @param player - Player executing the command
+     * @param commandName - Command name (for rate limit key)
+     * @param security - Security metadata from command decorators
+     *
+     * @throws AppError - If @Guard or @RequiresState validation fails
+     * @throws SecurityError - If @Throttle rate limit is exceeded
+     */
+    async validateSecurity(player, commandName, security) {
+        if (!security)
+            return;
+        // 1. Validate @Guard (rank/permission)
+        if (security.guard) {
+            await this.principalPort.enforce(player, security.guard);
+        }
+        // 2. Validate @Throttle (rate limiting)
+        if (security.throttle) {
+            const { limit, windowMs, onExceed, message } = security.throttle;
+            const rateLimitKey = `${player.clientID}:remote:${commandName}`;
+            const allowed = this.rateLimiter.checkLimit(rateLimitKey, limit, windowMs);
+            if (!allowed) {
+                const errorMessage = message || `Rate limit exceeded for command: ${commandName}`;
+                if (onExceed === 'KICK') {
+                    DropPlayer(player.clientID.toString(), errorMessage);
+                }
+                throw new SecurityError(onExceed || 'LOG', errorMessage, { clientID: player.clientID });
+            }
+        }
+        // 3. Validate @RequiresState (player state)
+        if (security.requiresState) {
+            const { has, missing, errorMessage } = security.requiresState;
+            if (has) {
+                for (const state of has) {
+                    if (!player.hasState(state)) {
+                        throw new AppError('GAME:INVALID_STATE', errorMessage || `Command requires state: ${state}`, 'core');
+                    }
+                }
+            }
+            if (missing) {
+                for (const state of missing) {
+                    if (player.hasState(state)) {
+                        throw new AppError('GAME:INVALID_STATE', errorMessage || `Command cannot be used in state: ${state}`, 'core');
+                    }
+                }
+            }
+        }
+    }
+};
+__decorate([
+    Public(),
+    OnNet('core:execute-command'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Player, String, Array]),
+    __metadata("design:returntype", Promise)
+], CommandExportController.prototype, "onCommandReceived", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], CommandExportController.prototype, "registerCommand", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String, Array]),
+    __metadata("design:returntype", Promise)
+], CommandExportController.prototype, "executeCommand", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Array)
+], CommandExportController.prototype, "getAllCommands", null);
+CommandExportController = __decorate([
+    Controller(),
+    __param(4, inject(CommandErrorObserverContract)),
+    __param(5, inject(IEngineEvents)),
+    __metadata("design:paramtypes", [CommandExecutionPort,
+        Players,
+        Authorization,
+        RateLimiterService,
+        CommandErrorObserverContract,
+        IEngineEvents])
+], CommandExportController);
+export { CommandExportController };

package/dist/runtime/server/controllers/player-export.controller.d.ts

@@ -0,0 +1,30 @@
+import { Players } from '../ports/players.api-port';
+import { InternalPlayerExports, SerializedPlayerData } from '../types/core-exports.types';
+import { LinkedID } from '../services';
+/**
+ * Exports player directory functionality for RESOURCE mode access.
+ *
+ * @remarks
+ * This controller provides a complete API for remote resources to:
+ * - Query player data (by client ID, account ID, or all players)
+ * - Check online status and player count
+ * - Read/write session metadata
+ * - Manage player state flags
+ */
+export declare class PlayerExportController implements InternalPlayerExports {
+    private playerService;
+    constructor(playerService: Players);
+    getPlayerId(clientID: number): LinkedID | undefined;
+    getPlayerData(clientID: number): SerializedPlayerData | null;
+    getManyData(clientIds: number[]): SerializedPlayerData[];
+    getAllPlayersData(): SerializedPlayerData[];
+    getPlayerByAccountId(accountId: string): SerializedPlayerData | null;
+    getPlayerCount(): number;
+    isPlayerOnline(accountId: string): boolean;
+    getPlayerMeta(clientID: number, key: string): Promise<any>;
+    setPlayerMeta(clientID: number, key: string, value: any): void;
+    getPlayerStates(clientID: number): string[];
+    hasPlayerState(clientID: number, state: string): boolean;
+    addPlayerState(clientID: number, state: string): void;
+    removePlayerState(clientID: number, state: string): void;
+}