XyPriss Core Developer Hooks

XyPriss provides a set of core hooks that allow developers to intercept and respond to critical server events. These hooks are integrated into the plugin system and can be implemented by any XyPriss plugin.

Overview

The following core hooks are available:

managePlugins

This is a specialized hook for administrative plugins. For detailed documentation, see the Plugin Management API.

onSecurityAttack

Triggered when the security middleware detects and blocks a malicious request.

Signature

onSecurityAttack(attackData: SecurityAttackData, req: XyPrisRequest, res: XyPrisResponse): void | Promise<void>

SecurityAttackData Properties

• type: The primary type of attack (e.g., "XSS", "SQL Injection", "Path Traversal", "Command Injection").
• threats: An array of detailed threat strings (e.g., "query.q:SQL Injection (CRITICAL)").
• ip: The IP address of the attacker.
• path: The request path where the attack was detected.

Example

{
    name: "security-logger",
    onSecurityAttack(attack, req) {
        console.log(`[SECURITY] ${attack.type} detected from ${attack.ip} on ${attack.path}`);
        attack.threats.forEach(threat => console.log(`  - ${threat}`));
    }
}

onResponseTime

Triggered after every request to provide performance metrics.

Signature

onResponseTime(responseTime: number, req: XyPrisRequest, res: XyPrisResponse): void | Promise<void>

Parameters

• responseTime: The time taken to process the request in milliseconds.
• req: The request object.
• res: The response object.

Example

{
    name: "perf-monitor",
    onResponseTime(ms, req) {
        if (ms > 500) {
            console.warn(`[PERF] Slow request: ${req.method} ${req.path} took ${ms}ms`);
        }
    }
}

onRouteError

Triggered when an unhandled error occurs during the execution of a route or middleware.

Signature

onRouteError(error: Error, req: XyPrisRequest, res: XyPrisResponse): void | Promise<void>

Parameters

• error: The error object that was thrown.
• req: The request object.
• res: The response object.

Example

{
    name: "error-reporter",
    onRouteError(err, req) {
        sendToSentry(err, { url: req.url });
    }
}

onRateLimit

Triggered when a request is blocked by the rate limiting middleware.

Signature

onRateLimit(limitData: RateLimitData, req: XyPrisRequest, res: XyPrisResponse): void | Promise<void>

RateLimitData Properties

• limit: The maximum number of requests allowed in the window.
• current: The current number of requests made by the client.
• remaining: The number of requests remaining in the window (usually 0 when triggered).
• resetTime: The time when the rate limit window resets.

Example

{
    name: "rate-limit-logger",
    onRateLimit(data, req) {
        console.log(`[RATE-LIMIT] Client ${req.ip} exceeded limit of ${data.limit} requests`);
    }
}

onConsoleIntercept

Triggered whenever a console method (log, info, warn, error, debug) is called anywhere in the application.

Signature

onConsoleIntercept(log: InterceptedConsoleCall): void | Promise<void>

InterceptedConsoleCall Properties

• method: The console method called ("log", "warn", "error", etc.).
• args: Array of arguments passed to the console call.
• timestamp: Date object when the log was generated.
• category: Classification of the log ("userApp", "system", "unknown").
• level: Severity level ("info", "warn", "error", "debug").
• source: (Optional) Source information if tracing is enabled.

Security & Permissions

This is a Privileged Hook. It is disabled by default for security reasons as console logs may contain sensitive information.

Requirement:

1. System Enablement: Console interception must be enabled in server options.
2. Plugin Permission: The plugin must be explicitly granted the PLG.LOGGING.CONSOLE_INTERCEPT hook permission.

Example

{
    name: "log-aggregator",
    version: "1.0.0",
    onConsoleIntercept(log) {
        // Send critical errors to external monitoring
        if (log.method === 'error') {
            externalService.report({
                message: log.args.join(' '),
                time: log.timestamp
            });
        }
    }
}

Integration

These hooks are automatically dispatched by the PluginManager. To use them, simply include the method in your plugin definition:

import { Plugin } from "xypriss";

Plugin.register({
    name: "my-plugin",
    onSecurityAttack(data) {
        // Handle attack
    },
    onResponseTime(ms) {
        // Handle performance
    },
});