bunsane 0.1.4 → 0.2.0

package/core/metadata/definitions/Component.ts

@@ -13,4 +13,13 @@ export interface ComponentPropertyMetadata {
     isEnum: boolean;
     enumValues?: string[];
     enumKeys?: string[];
+    isOptional: boolean;
+    arrayOf?: any;
+}
+
+export interface IndexedFieldMetadata {
+    componentId: string;
+    propertyKey: string;
+    indexType: 'gin' | 'btree' | 'hash' | 'numeric';
+    isDateField: boolean;
 }

package/core/metadata/definitions/gqlObject.ts

@@ -2,7 +2,7 @@ import {
     GraphQLScalar,
     type GraphQLObject,
     type GraphQLField
-} from "gql/types"
+} from "../../../gql/types"
 
 export interface GQLObjectMetaData {
     name: string;

package/core/metadata/index.ts

@@ -1,5 +1,46 @@
 import "reflect-metadata";
-export {getMetadataStorage} from "./getMetadataStorage";
+import { getMetadataStorage } from "./getMetadataStorage";
+
+export { getMetadataStorage } from "./getMetadataStorage";
+
+function toFieldLabel(fieldName: string): string {
+    let label = fieldName.replace(/_/g, ' ');
+    label = label.split(' ').map(word => word === 'id' ? 'ID' : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(' ');
+    return label;
+}
+
+export function getSerializedMetadataStorage(): {
+    archeTypes: Record<
+        string,
+        {
+            fieldName: string;
+            componentName: string;
+            fieldLabel: string;
+            nullable?: boolean;
+        }[]
+    >;
+} {
+    const storage = getMetadataStorage();
+    const archeTypes: Record<string, any> = {};
+
+    storage.archetypes_field_map.forEach((v, k) => {
+        archeTypes[k] = v.map((value) => {
+            return {
+                fieldName: value.fieldName,
+                componentName: value.component.name,
+                fieldLabel: toFieldLabel(value.fieldName),
+                nullable: value.options?.nullable,
+            };
+        });
+    });
+
+    // console.log(archeTypes, 'archeTypes');
+
+    return {
+        archeTypes,
+    };
+}
+
 export function Enum() {
     return (target: any) => {
         Reflect.defineMetadata("isEnum", true, target);

package/core/metadata/metadata-storage.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'crypto';
 import type { 
     ComponentMetadata,
-    ComponentPropertyMetadata
+    ComponentPropertyMetadata,
+    IndexedFieldMetadata
  } from "./definitions/Component";
 import type { ArcheTypeMetadata, ArcheTypeFieldOptions } from './definitions/ArcheType';
 import type { RelationOptions } from '../ArcheType';
@@ -18,6 +19,7 @@ export class MetadataStorage {
     components: ComponentMetadata[] = [];
     components_map: Map<string, ComponentMetadata> = new Map();
     componentProperties: Map<string, ComponentPropertyMetadata[]> = new Map();
+    indexedFields: Map<string, IndexedFieldMetadata[]> = new Map();
     archetypes: ArcheTypeMetadata[] = [];
     archetypes_field_map: Map<string, ArcheTypeFieldMap[]> = new Map();
     archetypes_relations_map: Map<string, ArcheTypeRelationMap[]> = new Map();
@@ -48,6 +50,17 @@ export class MetadataStorage {
         this.componentProperties.get(metadata.component_id)!.push(metadata);
     }
 
+    collectIndexedFieldMetadata(metadata: IndexedFieldMetadata) {
+        if(!this.indexedFields.has(metadata.componentId)) {
+            this.indexedFields.set(metadata.componentId, []);
+        }
+        this.indexedFields.get(metadata.componentId)!.push(metadata);
+    }
+
+    getIndexedFields(componentId: string): IndexedFieldMetadata[] {
+        return this.indexedFields.get(componentId) || [];
+    }
+
 
     getComponentProperties(component_id: string): ComponentPropertyMetadata[] {
         return this.componentProperties.get(component_id) || [];
@@ -75,7 +88,20 @@ export class MetadataStorage {
     }
 
     collectArcheTypeMetadata(metadata: ArcheTypeMetadata) {
-        this.archetypes.push(metadata);
+        // Check if archetype already exists and update it
+        const existingIndex = this.archetypes.findIndex(
+            a => a.typeId === metadata.typeId
+        );
+        if (existingIndex !== -1) {
+            // Update existing metadata
+            const existing = this.archetypes[existingIndex];
+            if (existing && metadata.functions) {
+                existing.functions = metadata.functions;
+            }
+        } else {
+            // Add new metadata
+            this.archetypes.push(metadata);
+        }
     }
 }
 

package/core/middleware/AccessLog.ts

@@ -0,0 +1,59 @@
+import type { Middleware } from '../Middleware';
+import { logger as MainLogger } from '../Logger';
+import { getRequestId } from './RequestId';
+
+const logger = MainLogger.child({ scope: 'HTTP' });
+
+export type AccessLogOptions = {
+    /** Paths to skip logging for (e.g., '/health'). Default: [] */
+    skip?: string[];
+};
+
+export function accessLog(options: AccessLogOptions = {}): Middleware {
+    const skipSet = new Set(options.skip || []);
+
+    return async (req, next) => {
+        const url = new URL(req.url);
+        if (skipSet.has(url.pathname)) {
+            return next();
+        }
+
+        const start = performance.now();
+        let response: Response;
+
+        try {
+            response = await next();
+        } catch (error) {
+            const duration = Math.round(performance.now() - start);
+            logger.error({
+                requestId: getRequestId(),
+                method: req.method,
+                path: url.pathname,
+                status: 500,
+                duration,
+                msg: `${req.method} ${url.pathname} 500 ${duration}ms`,
+            });
+            throw error;
+        }
+
+        const duration = Math.round(performance.now() - start);
+        const logData = {
+            requestId: getRequestId(),
+            method: req.method,
+            path: url.pathname,
+            status: response.status,
+            duration,
+            msg: `${req.method} ${url.pathname} ${response.status} ${duration}ms`,
+        };
+
+        if (response.status >= 500) {
+            logger.error(logData);
+        } else if (response.status >= 400) {
+            logger.warn(logData);
+        } else {
+            logger.info(logData);
+        }
+
+        return response;
+    };
+}

package/core/middleware/RequestId.ts

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Middleware } from '../Middleware';
+
+/**
+ * AsyncLocalStorage to propagate requestId to any code running within a request.
+ * Import this from your modules to access the current request's ID and logger.
+ */
+const requestStore = new AsyncLocalStorage<{ requestId: string }>();
+
+export function getRequestId(): string | undefined {
+    return requestStore.getStore()?.requestId;
+}
+
+export { requestStore };
+
+/**
+ * Middleware that generates a unique request ID per request and stores it
+ * in AsyncLocalStorage so it's accessible anywhere in the call stack.
+ * Respects incoming X-Request-Id header (from load balancers/proxies).
+ */
+export function requestId(): Middleware {
+    return async (req, next) => {
+        const id = req.headers.get('X-Request-Id') || crypto.randomUUID();
+
+        return requestStore.run({ requestId: id }, async () => {
+            const response = await next();
+
+            const newHeaders = new Headers(response.headers);
+            newHeaders.set('X-Request-Id', id);
+
+            return new Response(response.body, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: newHeaders,
+            });
+        });
+    };
+}

package/core/middleware/SecurityHeaders.ts

@@ -0,0 +1,62 @@
+import type { Middleware } from '../Middleware';
+
+export type SecurityHeadersOptions = {
+    /** Enable HSTS header. Default: true in production */
+    hsts?: boolean;
+    /** HSTS max-age in seconds. Default: 31536000 (1 year) */
+    hstsMaxAge?: number;
+    /** X-Frame-Options value. Default: 'DENY' */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /** X-Content-Type-Options. Default: true (sets 'nosniff') */
+    noSniff?: boolean;
+    /** Referrer-Policy value. Default: 'strict-origin-when-cross-origin' */
+    referrerPolicy?: string | false;
+    /** X-XSS-Protection. Default: false (deprecated header, modern browsers don't need it) */
+    xssProtection?: boolean;
+};
+
+export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
+    const isProduction = process.env.NODE_ENV === 'production';
+    const {
+        hsts = isProduction,
+        hstsMaxAge = 31536000,
+        frameOptions = 'DENY',
+        noSniff = true,
+        referrerPolicy = 'strict-origin-when-cross-origin',
+        xssProtection = false,
+    } = options;
+
+    // Pre-compute headers once at registration time
+    const headersToSet: [string, string][] = [];
+
+    if (hsts) {
+        headersToSet.push(['Strict-Transport-Security', `max-age=${hstsMaxAge}; includeSubDomains`]);
+    }
+    if (frameOptions) {
+        headersToSet.push(['X-Frame-Options', frameOptions]);
+    }
+    if (noSniff) {
+        headersToSet.push(['X-Content-Type-Options', 'nosniff']);
+    }
+    if (referrerPolicy) {
+        headersToSet.push(['Referrer-Policy', referrerPolicy]);
+    }
+    if (xssProtection) {
+        headersToSet.push(['X-XSS-Protection', '1; mode=block']);
+    }
+
+    return async (req, next) => {
+        const response = await next();
+
+        const newHeaders = new Headers(response.headers);
+        for (const [key, value] of headersToSet) {
+            newHeaders.set(key, value);
+        }
+
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: newHeaders,
+        });
+    };
+}

package/core/middleware/index.ts

@@ -0,0 +1,3 @@
+export { securityHeaders, type SecurityHeadersOptions } from './SecurityHeaders';
+export { requestId, getRequestId, requestStore } from './RequestId';
+export { accessLog, type AccessLogOptions } from './AccessLog';

package/core/scheduler/DistributedLock.ts

@@ -0,0 +1,266 @@
+/**
+ * Distributed Lock using PostgreSQL Advisory Locks
+ *
+ * PostgreSQL advisory locks are application-level locks that can be used
+ * to coordinate between multiple application instances. They are:
+ * - Session-based: automatically released when connection closes
+ * - Non-blocking with pg_try_advisory_lock
+ * - Perfect for distributed task scheduling
+ *
+ * @see https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS
+ */
+
+import db from "../../database";
+import { logger } from "../Logger";
+
+const loggerInstance = logger.child({ scope: "DistributedLock" });
+
+/**
+ * Result of a lock acquisition attempt
+ */
+export interface LockResult {
+    acquired: boolean;
+    lockKey: bigint;
+    taskId: string;
+}
+
+/**
+ * Configuration for the distributed lock system
+ */
+export interface DistributedLockConfig {
+    /** Whether distributed locking is enabled */
+    enabled: boolean;
+    /** Prefix for lock keys to avoid collisions with other applications */
+    lockKeyPrefix: number;
+    /** Whether to log lock acquisition/release events */
+    enableLogging: boolean;
+    /** Timeout for lock acquisition attempts in milliseconds (0 = no retry) */
+    lockTimeout: number;
+    /** Retry interval when lockTimeout > 0 */
+    retryInterval: number;
+}
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_LOCK_CONFIG: DistributedLockConfig = {
+    enabled: true,
+    lockKeyPrefix: 0x42554E53, // "BUNS" in hex as a namespace prefix
+    enableLogging: false,
+    lockTimeout: 0, // No retry by default - skip if can't acquire
+    retryInterval: 100,
+};
+
+/**
+ * Distributed Lock Manager using PostgreSQL Advisory Locks
+ *
+ * Provides distributed coordination for scheduled tasks across multiple
+ * application instances. Uses PostgreSQL's advisory lock system which
+ * guarantees that only one instance can hold a lock at a time.
+ *
+ * Advisory locks are automatically released when:
+ * - Explicitly unlocked via pg_advisory_unlock
+ * - The database session ends
+ * - The connection is closed
+ */
+export class DistributedLock {
+    private config: DistributedLockConfig;
+    private heldLocks: Set<string> = new Set();
+
+    constructor(config: Partial<DistributedLockConfig> = {}) {
+        this.config = { ...DEFAULT_LOCK_CONFIG, ...config };
+    }
+
+    /**
+     * Generate a consistent 64-bit lock key from a task ID
+     * Uses a simple hash function to convert string task IDs to bigints
+     *
+     * The lock key is composed of:
+     * - Upper 32 bits: lockKeyPrefix (namespace)
+     * - Lower 32 bits: hash of taskId
+     */
+    private generateLockKey(taskId: string): bigint {
+        // Simple hash function for the task ID
+        let hash = 0;
+        for (let i = 0; i < taskId.length; i++) {
+            const char = taskId.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        // Make it positive
+        hash = Math.abs(hash);
+
+        // Combine prefix (upper 32 bits) with hash (lower 32 bits)
+        const prefix = BigInt(this.config.lockKeyPrefix);
+        const hashBigInt = BigInt(hash >>> 0); // Ensure unsigned
+        return (prefix << 32n) | hashBigInt;
+    }
+
+    /**
+     * Try to acquire a distributed lock for a task
+     *
+     * Uses pg_try_advisory_lock which is non-blocking:
+     * - Returns true immediately if lock is available
+     * - Returns false immediately if lock is held by another session
+     *
+     * @param taskId The unique identifier for the task
+     * @returns LockResult indicating whether the lock was acquired
+     */
+    async tryAcquire(taskId: string): Promise<LockResult> {
+        if (!this.config.enabled) {
+            return { acquired: true, lockKey: 0n, taskId };
+        }
+
+        const lockKey = this.generateLockKey(taskId);
+        const startTime = Date.now();
+
+        try {
+            // Try to acquire the lock
+            let acquired = await this.attemptLock(lockKey);
+
+            // If lockTimeout > 0, retry until timeout
+            if (!acquired && this.config.lockTimeout > 0) {
+                while (!acquired && (Date.now() - startTime) < this.config.lockTimeout) {
+                    await this.sleep(this.config.retryInterval);
+                    acquired = await this.attemptLock(lockKey);
+                }
+            }
+
+            if (acquired) {
+                this.heldLocks.add(taskId);
+                if (this.config.enableLogging) {
+                    loggerInstance.debug(`Acquired lock for task ${taskId} (key: ${lockKey})`);
+                }
+            } else {
+                if (this.config.enableLogging) {
+                    loggerInstance.debug(`Failed to acquire lock for task ${taskId} (key: ${lockKey}) - another instance is executing`);
+                }
+            }
+
+            return { acquired, lockKey, taskId };
+        } catch (error) {
+            loggerInstance.error(`Error acquiring lock for task ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+            // On error, return false to be safe (don't execute without lock)
+            return { acquired: false, lockKey, taskId };
+        }
+    }
+
+    /**
+     * Attempt to acquire the PostgreSQL advisory lock
+     */
+    private async attemptLock(lockKey: bigint): Promise<boolean> {
+        const result = await db`
+            SELECT pg_try_advisory_lock(${lockKey}::bigint) as pg_try_advisory_lock
+        `;
+        return result[0]?.pg_try_advisory_lock ?? false;
+    }
+
+    /**
+     * Release a distributed lock for a task
+     *
+     * Uses pg_advisory_unlock to explicitly release the lock.
+     * The lock is also automatically released if the connection closes.
+     *
+     * @param taskId The unique identifier for the task
+     * @returns true if the lock was released, false if it wasn't held
+     */
+    async release(taskId: string): Promise<boolean> {
+        if (!this.config.enabled) {
+            return true;
+        }
+
+        const lockKey = this.generateLockKey(taskId);
+
+        try {
+            const result = await db`
+                SELECT pg_advisory_unlock(${lockKey}::bigint) as pg_advisory_unlock
+            `;
+
+            const released = result[0]?.pg_advisory_unlock ?? false;
+
+            if (released) {
+                this.heldLocks.delete(taskId);
+                if (this.config.enableLogging) {
+                    loggerInstance.debug(`Released lock for task ${taskId} (key: ${lockKey})`);
+                }
+            } else {
+                if (this.config.enableLogging) {
+                    loggerInstance.warn(`Lock for task ${taskId} was not held or already released`);
+                }
+            }
+
+            return released;
+        } catch (error) {
+            loggerInstance.error(`Error releasing lock for task ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+            this.heldLocks.delete(taskId); // Remove from tracking even on error
+            return false;
+        }
+    }
+
+    /**
+     * Release all locks held by this instance
+     * Useful during shutdown
+     */
+    async releaseAll(): Promise<void> {
+        const tasks = Array.from(this.heldLocks);
+        for (const taskId of tasks) {
+            await this.release(taskId);
+        }
+    }
+
+    /**
+     * Check if a lock is currently held (locally tracked)
+     */
+    isHeld(taskId: string): boolean {
+        return this.heldLocks.has(taskId);
+    }
+
+    /**
+     * Get the count of locks held by this instance
+     */
+    getHeldLockCount(): number {
+        return this.heldLocks.size;
+    }
+
+    /**
+     * Update the configuration
+     */
+    updateConfig(config: Partial<DistributedLockConfig>): void {
+        this.config = { ...this.config, ...config };
+    }
+
+    /**
+     * Get current configuration
+     */
+    getConfig(): DistributedLockConfig {
+        return { ...this.config };
+    }
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+
+/**
+ * Singleton instance for global access
+ */
+let distributedLockInstance: DistributedLock | null = null;
+
+export function getDistributedLock(config?: Partial<DistributedLockConfig>): DistributedLock {
+    if (!distributedLockInstance) {
+        distributedLockInstance = new DistributedLock(config);
+    } else if (config) {
+        distributedLockInstance.updateConfig(config);
+    }
+    return distributedLockInstance;
+}
+
+/**
+ * Reset the singleton instance (useful for testing)
+ */
+export function resetDistributedLock(): void {
+    if (distributedLockInstance) {
+        distributedLockInstance.releaseAll().catch(() => {});
+        distributedLockInstance = null;
+    }
+}

package/core/scheduler/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Scheduler Module
+ *
+ * Provides distributed task scheduling capabilities for multi-instance deployments.
+ * Uses PostgreSQL advisory locks to ensure only one instance executes a task at a time.
+ */
+
+export {
+    DistributedLock,
+    getDistributedLock,
+    resetDistributedLock,
+    DEFAULT_LOCK_CONFIG,
+    type DistributedLockConfig,
+    type LockResult,
+} from './DistributedLock';

package/core/validateEnv.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+const envSchema = z
+    .object({
+        // DB connection: either URL or individual fields
+        DB_CONNECTION_URL: z.string().url().optional(),
+        POSTGRES_HOST: z.string().optional(),
+        POSTGRES_USER: z.string().optional(),
+        POSTGRES_PASSWORD: z.string().optional(),
+        POSTGRES_DB: z.string().optional(),
+        POSTGRES_PORT: z
+            .string()
+            .regex(/^\d+$/, "POSTGRES_PORT must be numeric")
+            .optional(),
+        POSTGRES_MAX_CONNECTIONS: z
+            .string()
+            .regex(/^\d+$/, "POSTGRES_MAX_CONNECTIONS must be numeric")
+            .optional(),
+
+        // App config
+        APP_PORT: z
+            .string()
+            .regex(/^\d+$/, "APP_PORT must be numeric")
+            .optional(),
+        NODE_ENV: z.enum(["development", "production", "test"]).optional(),
+
+        // GraphQL
+        GRAPHQL_MAX_DEPTH: z
+            .string()
+            .regex(/^\d+$/, "GRAPHQL_MAX_DEPTH must be numeric")
+            .optional(),
+
+        // S3 Storage (opt-in)
+        S3_BUCKET: z.string().optional(),
+        S3_REGION: z.string().optional(),
+        S3_ENDPOINT: z.string().optional(),
+        S3_ACCESS_KEY_ID: z.string().optional(),
+        S3_SECRET_ACCESS_KEY: z.string().optional(),
+
+        // HTTP
+        MAX_REQUEST_BODY_SIZE: z
+            .string()
+            .regex(/^\d+$/, "MAX_REQUEST_BODY_SIZE must be numeric")
+            .optional(),
+
+        // Operational
+        SHUTDOWN_GRACE_PERIOD_MS: z
+            .string()
+            .regex(/^\d+$/, "SHUTDOWN_GRACE_PERIOD_MS must be numeric")
+            .optional(),
+        DB_STATEMENT_TIMEOUT: z
+            .string()
+            .regex(/^\d+$/, "DB_STATEMENT_TIMEOUT must be numeric")
+            .optional(),
+    })
+    .refine(
+        (env) => {
+            const hasUrl = !!env.DB_CONNECTION_URL;
+            const hasFields =
+                !!env.POSTGRES_HOST && !!env.POSTGRES_USER && !!env.POSTGRES_DB;
+            return hasUrl || hasFields;
+        },
+        {
+            message:
+                "Database connection required: provide DB_CONNECTION_URL or POSTGRES_HOST + POSTGRES_USER + POSTGRES_DB",
+        },
+    )
+    .refine(
+        (env) => {
+            if (env.S3_BUCKET) {
+                return !!env.S3_ACCESS_KEY_ID && !!env.S3_SECRET_ACCESS_KEY;
+            }
+            return true;
+        },
+        {
+            message:
+                "S3_BUCKET requires S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY (or use IAM roles and omit S3_BUCKET from env)",
+        },
+    );
+
+export function validateEnv(): void {
+    const result = envSchema.safeParse(process.env);
+    if (!result.success) {
+        const messages = result.error.issues.map(
+            (issue) =>
+                `  - ${issue.path.length ? issue.path.join(".") + ": " : ""}${issue.message}`,
+        );
+        throw new Error(
+            `Environment validation failed:\n${messages.join("\n")}`,
+        );
+    }
+}