@objectstack/core 0.8.2 → 0.9.1

package/dist/api-registry.js

@@ -0,0 +1,599 @@
+import { ApiRegistryEntrySchema } from '@objectstack/spec/api';
+/**
+ * API Registry Service
+ *
+ * Central registry for managing API endpoints across different protocols.
+ * Provides endpoint registration, discovery, and conflict resolution.
+ *
+ * **Features:**
+ * - Multi-protocol support (REST, GraphQL, OData, WebSocket, etc.)
+ * - Route conflict detection with configurable resolution strategies
+ * - RBAC permission integration
+ * - Dynamic schema linking with ObjectQL references
+ * - Plugin API registration
+ *
+ * **Architecture Alignment:**
+ * - Kubernetes: Service Discovery & API Server
+ * - AWS API Gateway: Unified API Management
+ * - Kong Gateway: Plugin-based API Management
+ *
+ * @example
+ * ```typescript
+ * const registry = new ApiRegistry(logger, 'priority');
+ *
+ * // Register an API
+ * registry.registerApi({
+ *   id: 'customer_api',
+ *   name: 'Customer API',
+ *   type: 'rest',
+ *   version: 'v1',
+ *   basePath: '/api/v1/customers',
+ *   endpoints: [...]
+ * });
+ *
+ * // Discover APIs
+ * const apis = registry.findApis({ type: 'rest', status: 'active' });
+ *
+ * // Get registry snapshot
+ * const snapshot = registry.getRegistry();
+ * ```
+ */
+export class ApiRegistry {
+    constructor(logger, conflictResolution = 'error', version = '1.0.0') {
+        this.apis = new Map();
+        this.endpoints = new Map();
+        this.routes = new Map();
+        // Performance optimization: Auxiliary indices for O(1) lookups
+        this.apisByType = new Map();
+        this.apisByTag = new Map();
+        this.apisByStatus = new Map();
+        this.logger = logger;
+        this.conflictResolution = conflictResolution;
+        this.version = version;
+        this.updatedAt = new Date().toISOString();
+    }
+    /**
+     * Register an API with its endpoints
+     *
+     * @param api - API registry entry
+     * @throws Error if API already registered or route conflicts detected
+     */
+    registerApi(api) {
+        // Check if API already exists
+        if (this.apis.has(api.id)) {
+            throw new Error(`[ApiRegistry] API '${api.id}' already registered`);
+        }
+        // Parse and validate the input using Zod schema
+        const fullApi = ApiRegistryEntrySchema.parse(api);
+        // Validate and register endpoints
+        for (const endpoint of fullApi.endpoints) {
+            this.validateEndpoint(endpoint, fullApi.id);
+        }
+        // Register the API
+        this.apis.set(fullApi.id, fullApi);
+        // Register endpoints
+        for (const endpoint of fullApi.endpoints) {
+            this.registerEndpoint(fullApi.id, endpoint);
+        }
+        // Update auxiliary indices for performance optimization
+        this.updateIndices(fullApi);
+        this.updatedAt = new Date().toISOString();
+        this.logger.info(`API registered: ${fullApi.id}`, {
+            api: fullApi.id,
+            type: fullApi.type,
+            endpointCount: fullApi.endpoints.length,
+        });
+    }
+    /**
+     * Unregister an API and all its endpoints
+     *
+     * @param apiId - API identifier
+     */
+    unregisterApi(apiId) {
+        const api = this.apis.get(apiId);
+        if (!api) {
+            throw new Error(`[ApiRegistry] API '${apiId}' not found`);
+        }
+        // Remove all endpoints
+        for (const endpoint of api.endpoints) {
+            this.unregisterEndpoint(apiId, endpoint.id);
+        }
+        // Remove from auxiliary indices
+        this.removeFromIndices(api);
+        // Remove the API
+        this.apis.delete(apiId);
+        this.updatedAt = new Date().toISOString();
+        this.logger.info(`API unregistered: ${apiId}`);
+    }
+    /**
+     * Register a single endpoint
+     *
+     * @param apiId - API identifier
+     * @param endpoint - Endpoint registration
+     * @throws Error if route conflict detected
+     */
+    registerEndpoint(apiId, endpoint) {
+        const endpointKey = `${apiId}:${endpoint.id}`;
+        // Check if endpoint already registered
+        if (this.endpoints.has(endpointKey)) {
+            throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' already registered for API '${apiId}'`);
+        }
+        // Register endpoint
+        this.endpoints.set(endpointKey, { api: apiId, endpoint });
+        // Register route if path is defined
+        if (endpoint.path) {
+            this.registerRoute(apiId, endpoint);
+        }
+    }
+    /**
+     * Unregister a single endpoint
+     *
+     * @param apiId - API identifier
+     * @param endpointId - Endpoint identifier
+     */
+    unregisterEndpoint(apiId, endpointId) {
+        const endpointKey = `${apiId}:${endpointId}`;
+        const entry = this.endpoints.get(endpointKey);
+        if (!entry) {
+            return; // Already unregistered
+        }
+        // Unregister route
+        if (entry.endpoint.path) {
+            const routeKey = this.getRouteKey(entry.endpoint);
+            this.routes.delete(routeKey);
+        }
+        // Unregister endpoint
+        this.endpoints.delete(endpointKey);
+    }
+    /**
+     * Register a route with conflict detection
+     *
+     * @param apiId - API identifier
+     * @param endpoint - Endpoint registration
+     * @throws Error if route conflict detected (based on strategy)
+     */
+    registerRoute(apiId, endpoint) {
+        const routeKey = this.getRouteKey(endpoint);
+        const priority = endpoint.priority ?? 100;
+        const existingRoute = this.routes.get(routeKey);
+        if (existingRoute) {
+            // Route conflict detected
+            this.handleRouteConflict(routeKey, apiId, endpoint, existingRoute, priority);
+            return;
+        }
+        // Register route
+        this.routes.set(routeKey, {
+            api: apiId,
+            endpointId: endpoint.id,
+            priority,
+        });
+    }
+    /**
+     * Handle route conflict based on resolution strategy
+     *
+     * @param routeKey - Route key
+     * @param apiId - New API identifier
+     * @param endpoint - New endpoint
+     * @param existingRoute - Existing route registration
+     * @param newPriority - New endpoint priority
+     * @throws Error if strategy is 'error'
+     */
+    handleRouteConflict(routeKey, apiId, endpoint, existingRoute, newPriority) {
+        const strategy = this.conflictResolution;
+        switch (strategy) {
+            case 'error':
+                throw new Error(`[ApiRegistry] Route conflict detected: '${routeKey}' is already registered by API '${existingRoute.api}' endpoint '${existingRoute.endpointId}'`);
+            case 'priority':
+                if (newPriority > existingRoute.priority) {
+                    // New endpoint has higher priority, replace
+                    this.logger.warn(`Route conflict: replacing '${routeKey}' (priority ${existingRoute.priority} -> ${newPriority})`, {
+                        oldApi: existingRoute.api,
+                        oldEndpoint: existingRoute.endpointId,
+                        newApi: apiId,
+                        newEndpoint: endpoint.id,
+                    });
+                    this.routes.set(routeKey, {
+                        api: apiId,
+                        endpointId: endpoint.id,
+                        priority: newPriority,
+                    });
+                }
+                else {
+                    // Existing endpoint has higher priority, keep it
+                    this.logger.warn(`Route conflict: keeping existing '${routeKey}' (priority ${existingRoute.priority} >= ${newPriority})`, {
+                        existingApi: existingRoute.api,
+                        existingEndpoint: existingRoute.endpointId,
+                        newApi: apiId,
+                        newEndpoint: endpoint.id,
+                    });
+                }
+                break;
+            case 'first-wins':
+                // Keep existing route
+                this.logger.warn(`Route conflict: keeping first registered '${routeKey}'`, {
+                    existingApi: existingRoute.api,
+                    newApi: apiId,
+                });
+                break;
+            case 'last-wins':
+                // Replace with new route
+                this.logger.warn(`Route conflict: replacing with last registered '${routeKey}'`, {
+                    oldApi: existingRoute.api,
+                    newApi: apiId,
+                });
+                this.routes.set(routeKey, {
+                    api: apiId,
+                    endpointId: endpoint.id,
+                    priority: newPriority,
+                });
+                break;
+            default:
+                throw new Error(`[ApiRegistry] Unknown conflict resolution strategy: ${strategy}`);
+        }
+    }
+    /**
+     * Generate a unique route key for conflict detection
+     *
+     * NOTE: This implementation uses exact string matching for route conflict detection.
+     * It works well for static paths but has limitations with parameterized routes.
+     * For example, `/api/users/:id` and `/api/users/:userId` will NOT be detected as conflicts
+     * even though they are semantically identical parameterized patterns. Similarly,
+     * `/api/:resource/list` and `/api/:entity/list` would also not be detected as conflicting.
+     *
+     * For more advanced conflict detection (e.g., path-to-regexp pattern matching),
+     * consider integrating with your routing library's conflict detection mechanism.
+     *
+     * @param endpoint - Endpoint registration
+     * @returns Route key (e.g., "GET:/api/v1/customers/:id")
+     */
+    getRouteKey(endpoint) {
+        const method = endpoint.method || 'ANY';
+        return `${method}:${endpoint.path}`;
+    }
+    /**
+     * Validate endpoint registration
+     *
+     * @param endpoint - Endpoint to validate
+     * @param apiId - API identifier (for error messages)
+     * @throws Error if endpoint is invalid
+     */
+    validateEndpoint(endpoint, apiId) {
+        if (!endpoint.id) {
+            throw new Error(`[ApiRegistry] Endpoint in API '${apiId}' missing 'id' field`);
+        }
+        if (!endpoint.path) {
+            throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' in API '${apiId}' missing 'path' field`);
+        }
+    }
+    /**
+     * Get an API by ID
+     *
+     * @param apiId - API identifier
+     * @returns API registry entry or undefined
+     */
+    getApi(apiId) {
+        return this.apis.get(apiId);
+    }
+    /**
+     * Get all registered APIs
+     *
+     * @returns Array of all APIs
+     */
+    getAllApis() {
+        return Array.from(this.apis.values());
+    }
+    /**
+     * Find APIs matching query criteria
+     *
+     * Performance optimized with auxiliary indices for O(1) lookups on type, tags, and status.
+     *
+     * @param query - Discovery query parameters
+     * @returns Matching APIs
+     */
+    findApis(query) {
+        let resultIds;
+        // Use indices for performance-optimized filtering
+        // Start with the most restrictive filter to minimize subsequent filtering
+        // Filter by type (using index for O(1) lookup)
+        if (query.type) {
+            const typeIds = this.apisByType.get(query.type);
+            if (!typeIds || typeIds.size === 0) {
+                return { apis: [], total: 0, filters: query };
+            }
+            resultIds = new Set(typeIds);
+        }
+        // Filter by status (using index for O(1) lookup)
+        if (query.status) {
+            const statusIds = this.apisByStatus.get(query.status);
+            if (!statusIds || statusIds.size === 0) {
+                return { apis: [], total: 0, filters: query };
+            }
+            if (resultIds) {
+                // Intersect with previous results
+                resultIds = new Set([...resultIds].filter(id => statusIds.has(id)));
+            }
+            else {
+                resultIds = new Set(statusIds);
+            }
+            if (resultIds.size === 0) {
+                return { apis: [], total: 0, filters: query };
+            }
+        }
+        // Filter by tags (using index for O(M) lookup where M is number of tags)
+        if (query.tags && query.tags.length > 0) {
+            const tagMatches = new Set();
+            for (const tag of query.tags) {
+                const tagIds = this.apisByTag.get(tag);
+                if (tagIds) {
+                    tagIds.forEach(id => tagMatches.add(id));
+                }
+            }
+            if (tagMatches.size === 0) {
+                return { apis: [], total: 0, filters: query };
+            }
+            if (resultIds) {
+                // Intersect with previous results
+                resultIds = new Set([...resultIds].filter(id => tagMatches.has(id)));
+            }
+            else {
+                resultIds = tagMatches;
+            }
+            if (resultIds.size === 0) {
+                return { apis: [], total: 0, filters: query };
+            }
+        }
+        // Get the actual API objects
+        let results;
+        if (resultIds) {
+            results = Array.from(resultIds)
+                .map(id => this.apis.get(id))
+                .filter((api) => api !== undefined);
+        }
+        else {
+            results = Array.from(this.apis.values());
+        }
+        // Apply remaining filters that don't have indices (less common filters)
+        // Filter by plugin source
+        if (query.pluginSource) {
+            results = results.filter((api) => api.metadata?.pluginSource === query.pluginSource);
+        }
+        // Filter by version
+        if (query.version) {
+            results = results.filter((api) => api.version === query.version);
+        }
+        // Search in name/description
+        if (query.search) {
+            const searchLower = query.search.toLowerCase();
+            results = results.filter((api) => api.name.toLowerCase().includes(searchLower) ||
+                (api.description && api.description.toLowerCase().includes(searchLower)));
+        }
+        return {
+            apis: results,
+            total: results.length,
+            filters: query,
+        };
+    }
+    /**
+     * Get endpoint by API ID and endpoint ID
+     *
+     * @param apiId - API identifier
+     * @param endpointId - Endpoint identifier
+     * @returns Endpoint registration or undefined
+     */
+    getEndpoint(apiId, endpointId) {
+        const key = `${apiId}:${endpointId}`;
+        return this.endpoints.get(key)?.endpoint;
+    }
+    /**
+     * Find endpoint by route (method + path)
+     *
+     * @param method - HTTP method
+     * @param path - URL path
+     * @returns Endpoint registration or undefined
+     */
+    findEndpointByRoute(method, path) {
+        const routeKey = `${method}:${path}`;
+        const route = this.routes.get(routeKey);
+        if (!route) {
+            return undefined;
+        }
+        const api = this.apis.get(route.api);
+        const endpoint = this.getEndpoint(route.api, route.endpointId);
+        if (!api || !endpoint) {
+            return undefined;
+        }
+        return { api, endpoint };
+    }
+    /**
+     * Get complete registry snapshot
+     *
+     * @returns Current registry state
+     */
+    getRegistry() {
+        const apis = Array.from(this.apis.values());
+        // Group by type
+        const byType = {};
+        for (const api of apis) {
+            if (!byType[api.type]) {
+                byType[api.type] = [];
+            }
+            byType[api.type].push(api);
+        }
+        // Group by status
+        const byStatus = {};
+        for (const api of apis) {
+            const status = api.metadata?.status || 'active';
+            if (!byStatus[status]) {
+                byStatus[status] = [];
+            }
+            byStatus[status].push(api);
+        }
+        // Count total endpoints
+        const totalEndpoints = apis.reduce((sum, api) => sum + api.endpoints.length, 0);
+        return {
+            version: this.version,
+            conflictResolution: this.conflictResolution,
+            apis,
+            totalApis: apis.length,
+            totalEndpoints,
+            byType,
+            byStatus,
+            updatedAt: this.updatedAt,
+        };
+    }
+    /**
+     * Clear all registered APIs
+     *
+     * **⚠️ SAFETY WARNING:**
+     * This method clears all registered APIs and should be used with caution.
+     *
+     * **Usage Restrictions:**
+     * - In production environments (NODE_ENV=production), a `force: true` parameter is required
+     * - Primarily intended for testing and development hot-reload scenarios
+     *
+     * @param options - Clear options
+     * @param options.force - Force clear in production environment (default: false)
+     * @throws Error if called in production without force flag
+     *
+     * @example Safe usage in tests
+     * ```typescript
+     * beforeEach(() => {
+     *   registry.clear(); // OK in test environment
+     * });
+     * ```
+     *
+     * @example Usage in production (requires explicit force)
+     * ```typescript
+     * // In production, explicit force is required
+     * registry.clear({ force: true });
+     * ```
+     */
+    clear(options = {}) {
+        const isProduction = this.isProductionEnvironment();
+        if (isProduction && !options.force) {
+            throw new Error('[ApiRegistry] Cannot clear registry in production environment without force flag. ' +
+                'Use clear({ force: true }) if you really want to clear the registry.');
+        }
+        this.apis.clear();
+        this.endpoints.clear();
+        this.routes.clear();
+        // Clear auxiliary indices
+        this.apisByType.clear();
+        this.apisByTag.clear();
+        this.apisByStatus.clear();
+        this.updatedAt = new Date().toISOString();
+        if (isProduction) {
+            this.logger.warn('API registry forcefully cleared in production', { force: options.force });
+        }
+        else {
+            this.logger.info('API registry cleared');
+        }
+    }
+    /**
+     * Get registry statistics
+     *
+     * @returns Registry statistics
+     */
+    getStats() {
+        const apis = Array.from(this.apis.values());
+        const apisByType = {};
+        for (const api of apis) {
+            apisByType[api.type] = (apisByType[api.type] || 0) + 1;
+        }
+        const endpointsByApi = {};
+        for (const api of apis) {
+            endpointsByApi[api.id] = api.endpoints.length;
+        }
+        return {
+            totalApis: this.apis.size,
+            totalEndpoints: this.endpoints.size,
+            totalRoutes: this.routes.size,
+            apisByType,
+            endpointsByApi,
+        };
+    }
+    /**
+     * Update auxiliary indices when an API is registered
+     *
+     * @param api - API entry to index
+     * @private
+     * @internal
+     */
+    updateIndices(api) {
+        // Index by type
+        this.ensureIndexSet(this.apisByType, api.type).add(api.id);
+        // Index by status
+        const status = api.metadata?.status || 'active';
+        this.ensureIndexSet(this.apisByStatus, status).add(api.id);
+        // Index by tags
+        const tags = api.metadata?.tags || [];
+        for (const tag of tags) {
+            this.ensureIndexSet(this.apisByTag, tag).add(api.id);
+        }
+    }
+    /**
+     * Remove API from auxiliary indices when unregistered
+     *
+     * @param api - API entry to remove from indices
+     * @private
+     * @internal
+     */
+    removeFromIndices(api) {
+        // Remove from type index
+        this.removeFromIndexSet(this.apisByType, api.type, api.id);
+        // Remove from status index
+        const status = api.metadata?.status || 'active';
+        this.removeFromIndexSet(this.apisByStatus, status, api.id);
+        // Remove from tag indices
+        const tags = api.metadata?.tags || [];
+        for (const tag of tags) {
+            this.removeFromIndexSet(this.apisByTag, tag, api.id);
+        }
+    }
+    /**
+     * Helper to ensure an index set exists and return it
+     *
+     * @param map - Index map
+     * @param key - Index key
+     * @returns The Set for this key (created if needed)
+     * @private
+     * @internal
+     */
+    ensureIndexSet(map, key) {
+        let set = map.get(key);
+        if (!set) {
+            set = new Set();
+            map.set(key, set);
+        }
+        return set;
+    }
+    /**
+     * Helper to remove an ID from an index set and clean up empty sets
+     *
+     * @param map - Index map
+     * @param key - Index key
+     * @param id - API ID to remove
+     * @private
+     * @internal
+     */
+    removeFromIndexSet(map, key, id) {
+        const set = map.get(key);
+        if (set) {
+            set.delete(id);
+            // Clean up empty sets to avoid memory leaks
+            if (set.size === 0) {
+                map.delete(key);
+            }
+        }
+    }
+    /**
+     * Check if running in production environment
+     *
+     * @returns true if NODE_ENV is 'production'
+     * @private
+     * @internal
+     */
+    isProductionEnvironment() {
+        return process.env.NODE_ENV === 'production';
+    }
+}

package/dist/api-registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-registry.test.d.ts.map

package/dist/api-registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-registry.test.d.ts","sourceRoot":"","sources":["../src/api-registry.test.ts"],"names":[],"mappings":""}