@adaas/a-server 0.0.22 → 0.0.23

package/src/lib/A-Request/A-Request.env.ts

@@ -0,0 +1,50 @@
+
+
+export const A_RequestEnvVariables = {
+
+    /**
+     * Default request timeout in milliseconds
+     */
+    A_SERVER_REQUEST_TIMEOUT: 5000,
+
+    /**
+     * Maximum request body size in bytes
+     */
+    A_SERVER_REQUEST_MAX_BODY_SIZE: 10 * 1024 * 1024, // 10MB
+
+    /**
+     * Default request encoding
+     */
+    A_SERVER_REQUEST_DEFAULT_ENCODING: 'utf8',
+
+    /**
+     * Enable automatic cookie parsing
+     */
+    A_SERVER_REQUEST_PARSE_COOKIES: true,
+
+    /**
+     * Enable automatic query parameter parsing
+     */
+    A_SERVER_REQUEST_PARSE_QUERY: true,
+
+    /**
+     * Enable automatic body parsing
+     */
+    A_SERVER_REQUEST_PARSE_BODY: true,
+
+    /**
+     * Enable file upload handling
+     */
+    A_SERVER_REQUEST_ENABLE_FILE_UPLOADS: false,
+
+} as const;
+
+
+export const A_RequestEnvVariablesArray = Object.keys(A_RequestEnvVariables) as Array<keyof typeof A_RequestEnvVariables>;
+
+
+
+/**
+ * Array of all possible fields in A_RequestEnvVariables
+ */
+export type A_RequestEnvVariablesType = Array<keyof typeof A_RequestEnvVariables>;

package/src/lib/A-Request/A-Request.error.ts

@@ -0,0 +1,11 @@
+import { A_Error } from "@adaas/a-concept";
+
+export class A_RequestError extends A_Error {
+
+    static readonly RequestBodyParsingError = 'Unable to parse request body';
+    static readonly FileUploadError = 'File upload error';
+    static readonly RequestTimeoutError = 'Request timed out';
+    static readonly InvalidRequestError = 'Invalid request';
+    static readonly MissingParametersError = 'Missing required parameters';
+
+}

package/src/lib/A-Request/A-Request.helper.ts

@@ -0,0 +1,276 @@
+import { A_HttpServerRequestContext } from "./A-HttpServerRequest.context";
+import { A_RequestError } from "./A-Request.error";
+import { A_Request_BodyType, A_Request_FileUpload } from "./A-Request.types";
+
+/**
+ * A_RequestHelper - Stateless utility class for HTTP request processing
+ * 
+ * This helper class provides static methods for parsing and processing HTTP request data:
+ * - URL parameter extraction from route patterns
+ * - Query string parsing
+ * - Request body parsing (JSON, form-data, multipart, raw)
+ * - URL-encoded form data parsing
+ * - Multipart form data parsing (including file uploads)
+ * 
+ * All methods are stateless and only depend on input parameters.
+ * 
+ * @example
+ * ```typescript
+ * // Extract URL parameters
+ * const params = A_RequestHelper.extractParams('/users/123', '/users/:id');
+ * // { id: '123' }
+ * 
+ * // Parse query string
+ * const query = A_RequestHelper.extractQuery('/api/users?page=1&limit=10');
+ * // { page: '1', limit: '10' }
+ * 
+ * // Parse request body
+ * const result = await A_RequestHelper.parseRequestBody(req, { maxBodySize: 1024 * 1024 });
+ * // { data: {...}, type: 'json' }
+ * ```
+ */
+export class A_RequestHelper {
+
+    /**
+     * Extract URL parameters from a URL using a route pattern
+     * @param url - The actual URL to extract parameters from
+     * @param routePattern - The route pattern with parameters (e.g., "/users/:id/posts/:postId")
+     * @returns Object containing extracted parameters
+     */
+    static extractParams(url: string, routePattern: string): Record<string, string> {
+        // Remove query string (anything after ?)
+        const cleanUrl = url.split('?')[0];
+        const cleanPattern = routePattern.split('?')[0];
+
+        const urlSegments = cleanUrl.split('/').filter(Boolean);
+        const patternSegments = cleanPattern.split('/').filter(Boolean);
+
+        const params: Record<string, string> = {};
+
+        for (let i = 0; i < patternSegments.length; i++) {
+            const patternSegment = patternSegments[i];
+            const urlSegment = urlSegments[i];
+
+            if (patternSegment.startsWith(':')) {
+                const paramName = patternSegment.slice(1); // Remove ':' from pattern
+                if (urlSegment) {
+                    params[paramName] = decodeURIComponent(urlSegment);
+                }
+            } else if (patternSegment !== urlSegment) {
+                // If static segments don't match → fail
+                return {};
+            }
+        }
+
+        return params;
+    }
+
+
+
+    /**
+     * Extract query parameters from URL
+     * @param url - The URL to extract query parameters from
+     * @returns Object containing query parameters
+     */
+    static extractQuery<T = Record<string, string>>(url: string): T {
+        const query: Record<string, string> = {};
+
+        // Take only the part after "?"
+        const queryString = url.split('?')[1];
+        if (!queryString) return query as T;
+
+        // Remove fragment (#...) if present
+        const cleanQuery = queryString.split('#')[0];
+
+        // Split into key=value pairs
+        for (const pair of cleanQuery.split('&')) {
+            if (!pair) continue;
+            const [key, value = ''] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(value);
+        }
+
+        return query as T;
+    }
+
+
+    /**
+     * Parse cookies from Cookie header
+     */
+    static parseCookies(
+        cookieHeader?: string
+    ): Record<string, string> {
+        const cookies: Record<string, string> = {};
+
+        if (!cookieHeader) return {};
+
+        cookieHeader.split(';').forEach(cookie => {
+            const [name, ...rest] = cookie.trim().split('=');
+            const value = rest.join('=');
+            if (name && value) {
+                cookies[name] = decodeURIComponent(value);
+            }
+        });
+
+        return cookies;
+    }
+
+    /**
+     * Parse request body based on Content-Type
+     * 
+     * 
+     * @param context - The HTTP server request context
+     * @returns Parsed body data and detected body type
+     */
+    static parseRequestBody<T extends any = any>(
+        context: A_HttpServerRequestContext
+    ): {
+        data: T;
+        type: A_Request_BodyType;
+    } {
+        let parsedBody: any;
+        let bodyType: A_Request_BodyType;
+
+        switch (true) {
+            case !!context.contentType && context.contentType.includes('application/json'):
+                parsedBody = JSON.parse(context.data);
+                bodyType = 'json';
+                break;
+            case !!context.contentType && context.contentType.includes('application/x-www-form-urlencoded'):
+                parsedBody = A_RequestHelper.parseFormUrlEncoded(context.data) as T;
+                bodyType = 'form';
+                break;
+            case !!context.contentType && context.contentType.includes('multipart/form-data'):
+                const multipartResult = A_RequestHelper.parseMultipartData(Buffer.concat(context.buffers), context.contentType);
+                // Return the entire multipart result (fields + files) as T
+                parsedBody = {
+                    ...multipartResult.fields,
+                    _files: multipartResult.files
+                } as T;
+                bodyType = 'multipart';
+                break;
+            case !!context.contentType && context.contentType.includes('text/'):
+                parsedBody = context.data as T;
+                bodyType = 'text';
+                break;
+            default:
+                parsedBody = Buffer.concat(context.buffers) as T;
+                bodyType = 'raw';
+                break;
+        }
+
+
+        return {
+            data: parsedBody,
+            type: bodyType
+        };
+    }
+
+    /**
+     * Parse URL-encoded form data (application/x-www-form-urlencoded)
+     * @param body - The URL-encoded body string
+     * @returns Object containing form data
+     */
+    static parseFormUrlEncoded(
+        /**
+         * The URL-encoded body string
+         */
+        body: string
+    ): Record<string, string | string[]> {
+        const result: Record<string, string | string[]> = {};
+
+        if (!body) return result;
+
+        const pairs = body.split('&');
+
+        for (const pair of pairs) {
+            if (!pair) continue;
+
+            const [key, value = ''] = pair.split('=');
+            const decodedKey = decodeURIComponent(key.replace(/\+/g, ' '));
+            const decodedValue = decodeURIComponent(value.replace(/\+/g, ' '));
+
+            // Handle multiple values for the same key (arrays)
+            if (decodedKey in result) {
+                const existing = result[decodedKey];
+                if (Array.isArray(existing)) {
+                    existing.push(decodedValue);
+                } else {
+                    result[decodedKey] = [existing, decodedValue];
+                }
+            } else {
+                result[decodedKey] = decodedValue;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Parse multipart form data (for file uploads and form data)
+     * @param buffer - The raw buffer containing multipart data
+     * @param contentType - The content type header
+     * @returns Object containing fields and files
+     */
+    static parseMultipartData(
+        /**
+         * The raw buffer containing multipart data
+         */
+        buffer: Buffer,
+        /**
+         * The content type header
+         */
+        contentType: string
+    ): {
+        fields: Record<string, string>;
+        files: A_Request_FileUpload[];
+    } {
+        // Extract boundary
+        const boundaryMatch = contentType.match(/boundary=(.+)/);
+        if (!boundaryMatch) {
+            throw new A_RequestError(
+                A_RequestError.RequestBodyParsingError,
+                'Missing boundary in multipart/form-data content type'
+            )
+        }
+
+        const boundary = '--' + boundaryMatch[1];
+        const textData = buffer.toString();
+        const parts = textData.split(boundary).filter(part => part.trim() && !part.includes('--'));
+
+        const fields: Record<string, string> = {};
+        const files: A_Request_FileUpload[] = [];
+
+        parts.forEach(part => {
+            const [headers, content] = part.split('\r\n\r\n');
+            if (!headers || content === undefined) return;
+
+            const nameMatch = headers.match(/name="([^"]+)"/);
+            const filenameMatch = headers.match(/filename="([^"]+)"/);
+            const contentTypeMatch = headers.match(/Content-Type: ([^\r\n]+)/);
+
+            if (nameMatch) {
+                const fieldName = nameMatch[1];
+                const cleanContent = content.replace(/\r\n$/, '');
+
+                if (filenameMatch) {
+                    // It's a file upload
+                    const file: A_Request_FileUpload = {
+                        fieldName,
+                        filename: filenameMatch[1],
+                        encoding: 'binary',
+                        mimetype: contentTypeMatch?.[1] || 'application/octet-stream',
+                        size: Buffer.byteLength(cleanContent),
+                        buffer: Buffer.from(cleanContent, 'binary')
+                    };
+                    files.push(file);
+                } else {
+                    // It's a regular field
+                    fields[fieldName] = cleanContent;
+                }
+            }
+        });
+
+        return { fields, files };
+    }
+
+}

package/src/lib/A-Request/A-Request.types.ts

@@ -0,0 +1,284 @@
+import type { IncomingMessage } from "http";
+import { A_Request } from "./A-Request.entity";
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+import { A_HttpServerRequestMethod } from "@adaas/a-server/server/A-HttpServer.types";
+import { A_RequestFeatures } from "./A-Request.constants";
+
+
+// =============================================
+// Core Request Types
+// =============================================
+/**
+ * Constructor parameters for A_Request entity
+ */
+export type A_Request_Init = {
+    /**
+     * Unique identifier for the request (should correspond to Response id)
+     */
+    id: string;
+
+    /**
+     * ASEID Shard for the request.  
+     * it's some sort of request fingerprint
+     */
+    shard: string
+    /**
+     * Node.js IncomingMessage object
+     */
+    request: IncomingMessage;
+    /**
+     * Request scope for context resolution
+     */
+    scope: string;
+};
+
+/**
+ * Serialized representation of A_Request entity
+ */
+export type A_Request_Serialized<
+    _ReqBodyType = any,
+    _ParamsType extends Record<string, string> = any,
+    _QueryType = any,
+> = A_TYPES__Entity_Serialized & {
+    method: A_HttpServerRequestMethod;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    params?: _ParamsType;
+    query?: _QueryType;
+    cookies: Record<string, string>;
+    body?: _ReqBodyType;
+    userAgent?: string;
+    isValid: boolean;
+    bodyType?: A_Request_BodyType;
+    filesCount?: number;
+    fileFieldNames?: string[];
+    totalFileSize?: number;
+}
+
+/**
+ * Supported HTTP request methods
+ */
+export type A_Request_Methods =
+    | 'GET'
+    | 'POST'
+    | 'PUT'
+    | 'DELETE'
+    | 'PATCH'
+    | 'OPTIONS'
+    | 'HEAD'
+    | 'CONNECT'
+    | 'TRACE'
+    | 'DEFAULT'; // Default is used for routes that do not have a method specified
+
+/**
+ * Request lifecycle events
+ */
+export enum A_Request_Event {
+    Error = 'error',
+    Finish = 'finish',
+    Data = 'data',
+    End = 'end',
+    Close = 'close',
+}
+
+
+export type A_RequestFeatureNames = typeof A_RequestFeatures[keyof typeof A_RequestFeatures];
+
+/**
+ * Request event callback function type
+ */
+export type A_Request_EventCallback = (request: A_Request) => void;
+
+
+// =============================================
+// Body Parsing Types
+// =============================================
+
+/**
+ * Supported body content types for parsing
+ */
+export type A_Request_BodyType = 'json' | 'form' | 'multipart' | 'raw' | 'text';
+
+/**
+ * Result of body parsing operation
+ */
+export type A_Request_ParsedBody = {
+    /**
+     * Type of parsed content
+     */
+    type: A_Request_BodyType;
+    /**
+     * Parsed data
+     */
+    data: any;
+    /**
+     * Size of the body in bytes
+     */
+    size: number;
+    /**
+     * Character encoding used
+     */
+    encoding?: string;
+    /**
+     * Multipart boundary (for multipart content)
+     */
+    boundary?: string;
+};
+
+
+
+// =============================================
+// Session Management Types
+// =============================================
+
+/**
+ * Session data structure for user session management
+ */
+export type A_Request_SessionData = {
+    /**
+     * Unique session identifier
+     */
+    id?: string;
+    /**
+     * Associated user ID
+     */
+    userId?: string;
+    /**
+     * Session creation timestamp
+     */
+    createdAt?: Date;
+    /**
+     * Last access timestamp
+     */
+    lastAccess?: Date;
+    /**
+     * Session data storage
+     */
+    data?: Record<string, any>;
+    /**
+     * Whether session is expired
+     */
+    isExpired?: boolean;
+    /**
+     * Maximum session age in milliseconds
+     */
+    maxAge?: number;
+};
+
+
+// =============================================
+// File Upload Types
+// =============================================
+
+/**
+ * File upload information for multipart requests
+ */
+export type A_Request_FileUpload = {
+    /**
+     * Form field name
+     */
+    fieldName: string;
+    /**
+     * Original filename
+     */
+    filename: string;
+    /**
+     * File encoding
+     */
+    encoding: string;
+    /**
+     * MIME type
+     */
+    mimetype: string;
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * File buffer data
+     */
+    buffer: Buffer;
+    /**
+     * Path if saved to disk
+     */
+    path?: string;
+    /**
+     * File hash for integrity verification
+     */
+    hash?: string;
+};
+
+
+// =============================================
+// Validation Types
+// =============================================
+
+/**
+ * Request validation result with detailed feedback
+ */
+export type A_Request_ValidationResult = {
+    /**
+     * Whether validation passed
+     */
+    isValid: boolean;
+    /**
+     * Validation error messages
+     */
+    errors: string[];
+    /**
+     * Warning messages
+     */
+    warnings: string[];
+    /**
+     * Sanitized data after validation
+     */
+    sanitized?: any;
+};
+
+
+// =============================================
+// Configuration Types
+// =============================================
+
+/**
+ * Request processing configuration options
+ */
+export type A_Request_Options = {
+    /**
+     * Maximum request body size in bytes (default: 10MB)
+     */
+    maxBodySize?: number;
+    /**
+     * Request timeout in milliseconds (default: 30s)
+     */
+    timeout?: number;
+    /**
+     * Default character encoding (default: 'utf8')
+     */
+    encoding?: string;
+    /**
+     * Automatically parse cookies (default: true)
+     */
+    parseCookies?: boolean;
+    /**
+     * Automatically parse query parameters (default: true)
+     */
+    parseQuery?: boolean;
+    /**
+     * Automatically parse request body (default: true)
+     */
+    parseBody?: boolean;
+    /**
+     * Enable file upload handling (default: false)
+     */
+    enableFileUploads?: boolean;
+    /**
+     * Enable strict validation mode (default: false)
+     */
+    strictValidation?: boolean;
+};
+
+/**
+ * Request Event Listener Function
+ */
+export type A_Request_Listener = (req?: A_Request) => void;