@jmruthers/pace-core 0.5.186 → 0.5.188

package/src/rbac/components/PagePermissionGuard.tsx

@@ -73,6 +73,7 @@ import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { UUID, Permission, Scope } from '../types';
 import { createScopeFromEvent } from '../utils/eventContext';
 import { getRBACLogger } from '../config';
+import { scopeEqual } from '../utils/deep-equal';
 
 export interface PagePermissionGuardProps {
   /** Name of the page being protected */
@@ -333,17 +334,24 @@ const PagePermissionGuardComponent = ({
 
   // Create a stable scope that only includes valid values
   // OrganisationId is required - use undefined if not available, useCan will handle loading state
+  // Use ref to track previous scope for deep equality comparison
+  const prevScopeRef = useRef<Scope | null>(null);
   const stableScope = useMemo(() => {
-    if (resolvedScope && resolvedScope.organisationId) {
-      return {
-        organisationId: resolvedScope.organisationId,
-        appId: resolvedScope.appId || undefined,
-        eventId: resolvedScope.eventId || undefined
-      };
+    const newScope: Scope = resolvedScope && resolvedScope.organisationId
+      ? {
+          organisationId: resolvedScope.organisationId,
+          appId: resolvedScope.appId || undefined,
+          eventId: resolvedScope.eventId || undefined
+        }
+      : { organisationId: undefined, appId: undefined, eventId: undefined };
+    
+    // Only return new object if scope actually changed (deep equality check)
+    if (scopeEqual(prevScopeRef.current, newScope)) {
+      return prevScopeRef.current!;
     }
-    // Return scope without organisationId - useCan will keep loading state until resolved
-    // Scope.organisationId is optional, so undefined is valid
-    return { organisationId: undefined, appId: undefined, eventId: undefined };
+    
+    prevScopeRef.current = newScope;
+    return newScope;
   }, [resolvedScope]);
 
   // Check if user has permission - only call useCan when we have a resolved scope with valid organisationId
@@ -487,5 +495,6 @@ function DefaultLoading() {
   );
 };
 
-export const PagePermissionGuard = PagePermissionGuardComponent;
+// Memoize component to prevent unnecessary re-renders when props haven't changed
+export const PagePermissionGuard = React.memo(PagePermissionGuardComponent);
 export default PagePermissionGuard;

package/src/rbac/components/__tests__/PagePermissionGuard.performance.test.tsx

@@ -0,0 +1,248 @@
+/**
+ * Performance tests for PagePermissionGuard
+ * @package @jmruthers/pace-core
+ * @module RBAC/Components/PagePermissionGuard/Performance
+ * @since 2.0.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import React from 'react';
+import { PagePermissionGuard } from '../PagePermissionGuard';
+import { useCan } from '../../hooks';
+import { useUnifiedAuth } from '../../../providers/services/UnifiedAuthProvider';
+import { clearInFlightRequests, getInFlightRequestCount } from '../../request-deduplication';
+import { rbacCache } from '../../cache';
+
+// Mock dependencies - use same path as component
+vi.mock('../../hooks', () => ({
+  useCan: vi.fn()
+}));
+
+// Mock the auth provider
+const mockUseUnifiedAuthFn = vi.fn();
+vi.mock('../../../providers/services/UnifiedAuthProvider', () => ({
+  useUnifiedAuth: () => mockUseUnifiedAuthFn(),
+  UnifiedAuthProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
+
+// Mock the event context utility
+vi.mock('../../utils/eventContext', () => ({
+  createScopeFromEvent: vi.fn()
+}));
+
+// Mock the app name resolver
+vi.mock('../../../utils/app/appNameResolver', () => ({
+  getCurrentAppName: vi.fn(() => 'test-app')
+}));
+
+import { createScopeFromEvent } from '../../utils/eventContext';
+import { getCurrentAppName } from '../../../utils/app/appNameResolver';
+
+const mockUseCan = vi.mocked(useCan);
+const mockCreateScopeFromEvent = vi.mocked(createScopeFromEvent);
+const mockGetCurrentAppName = vi.mocked(getCurrentAppName);
+
+describe('PagePermissionGuard Performance', () => {
+  const mockUser = {
+    id: 'user-123',
+    email: 'test@example.com',
+  };
+
+  const mockOrganisation = {
+    id: 'org-123',
+    name: 'Test Org',
+  };
+
+  const mockEvent = {
+    event_id: 'event-123',
+    name: 'Test Event',
+  };
+
+  const mockScope = {
+    organisationId: 'org-123',
+    eventId: 'event-123',
+    appId: 'app-123',
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    clearInFlightRequests();
+    rbacCache.clear();
+    
+    // Set up mocks to match working test exactly
+    mockUseUnifiedAuthFn.mockReturnValue({
+      user: mockUser,
+      selectedOrganisation: { id: 'org-123' },
+      selectedEvent: { event_id: 'event-123' },
+      appId: 'app-123', // Required for scope resolution
+      supabase: {
+        from: vi.fn().mockReturnValue({
+          select: vi.fn().mockReturnValue({
+            eq: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                single: vi.fn().mockResolvedValue({
+                  data: { id: 'app-123', name: 'test-app', is_active: true },
+                  error: null
+                })
+              })
+            })
+          })
+        })
+      } as any
+    });
+    
+    mockGetCurrentAppName.mockReturnValue('test-app');
+    
+    // Mock useCan to return permission granted
+    // Use mockImplementation to handle all calls, including initial calls with undefined scope
+    mockUseCan.mockImplementation(() => ({
+      can: true,
+      isLoading: false,
+      error: null,
+      refetch: vi.fn(),
+    }));
+  });
+
+  describe('Request Deduplication', () => {
+    it('should deduplicate requests when multiple instances check the same permission', async () => {
+      // Ensure useCan returns permission granted
+      mockUseCan.mockImplementation(() => ({
+        can: true,
+        isLoading: false,
+        error: null,
+        refetch: vi.fn(),
+      }));
+
+      render(
+        <>
+          <PagePermissionGuard pageName="dashboard" operation="read">
+            <div data-testid="content-1">Content 1</div>
+          </PagePermissionGuard>
+          <PagePermissionGuard pageName="dashboard" operation="read">
+            <div data-testid="content-2">Content 2</div>
+          </PagePermissionGuard>
+          <PagePermissionGuard pageName="dashboard" operation="read">
+            <div data-testid="content-3">Content 3</div>
+          </PagePermissionGuard>
+        </>
+      );
+
+      // Wait for scope resolution and permission check to complete
+      // The component resolves scope asynchronously, so we need to wait
+      await waitFor(() => {
+        expect(screen.getByTestId('content-1')).toBeInTheDocument();
+        expect(screen.getByTestId('content-2')).toBeInTheDocument();
+        expect(screen.getByTestId('content-3')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Verify useCan was called (deduplication happens at API level, not hook level)
+      expect(mockUseCan).toHaveBeenCalled();
+    });
+
+    it('should track in-flight requests correctly', () => {
+      expect(getInFlightRequestCount()).toBe(0);
+    });
+  });
+
+  describe('Cache Performance', () => {
+    it('should use cached results on subsequent renders', async () => {
+      let checkCount = 0;
+      
+      mockUseCan.mockImplementation(() => {
+        checkCount++;
+        return {
+          can: true,
+          isLoading: false,
+          error: null,
+          refetch: vi.fn(),
+        };
+      });
+
+      const { rerender } = render(
+        <PagePermissionGuard pageName="dashboard" operation="read">
+          <div data-testid="content">Content</div>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('content')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      const initialCheckCount = checkCount;
+
+      // Rerender with same props
+      rerender(
+        <PagePermissionGuard pageName="dashboard" operation="read">
+          <div data-testid="content">Content</div>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('content')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Should not increase check count significantly due to memoization
+      // Allow some margin for React's rendering behavior
+      expect(checkCount).toBeLessThanOrEqual(initialCheckCount + 2);
+    });
+  });
+
+  describe('Render Performance', () => {
+    it('should not cause excessive re-renders', () => {
+      let renderCount = 0;
+      
+      const TestComponent = () => {
+        renderCount++;
+        return (
+          <PagePermissionGuard pageName="dashboard" operation="read">
+            <div data-testid="content">Content</div>
+          </PagePermissionGuard>
+        );
+      };
+
+      render(<TestComponent />);
+
+      // Should not have excessive re-renders
+      expect(renderCount).toBeLessThan(10);
+    });
+
+    it('should memoize scope objects to prevent unnecessary re-renders', async () => {
+      // Ensure useCan returns permission granted
+      mockUseCan.mockImplementation(() => ({
+        can: true,
+        isLoading: false,
+        error: null,
+        refetch: vi.fn(),
+      }));
+
+      const { rerender } = render(
+        <PagePermissionGuard pageName="dashboard" operation="read">
+          <div data-testid="content">Content</div>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('content')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      const initialCallCount = mockUseCan.mock.calls.length;
+
+      // Rerender with same props
+      rerender(
+        <PagePermissionGuard pageName="dashboard" operation="read">
+          <div data-testid="content">Content</div>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('content')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // useCan should be called, but scope memoization prevents excessive calls
+      // Allow some margin for React's rendering behavior
+      expect(mockUseCan.mock.calls.length).toBeLessThanOrEqual(initialCallCount + 2);
+    });
+  });
+});
+

package/src/rbac/config.ts

@@ -22,12 +22,21 @@ export interface RBACConfig {
   cache?: {
     ttl?: number;
     enabled?: boolean;
+    sessionTtl?: number; // Session cache TTL in milliseconds (default: 5 minutes)
   };
   audit?: {
     enabled?: boolean;
     logLevel?: LogLevel;
+    batched?: boolean; // Enable batched audit logging (default: true)
+    batchWindow?: number; // Time window in milliseconds (default: 100ms)
+    batchSize?: number; // Maximum batch size (default: 10)
   };
   security?: Partial<RBACSecurityConfig>;
+  performance?: {
+    enableRequestDeduplication?: boolean; // Enable request deduplication (default: true)
+    enableBatchedAuditLogging?: boolean; // Enable batched audit logging (default: true)
+    enablePerformanceTracking?: boolean; // Enable performance tracking (default: false in production)
+  };
 }
 
 export interface RBACLogger {

package/src/rbac/engine.ts

@@ -156,27 +156,8 @@ export class RBACEngine {
         cacheHit = true;
         cacheSource = 'memory';
         
-        const duration = Date.now() - startTime;
-        
-        // Audit cache hit (if organisation context exists)
-        if (scope.organisationId) {
-          const resolvedPageId = await this.resolvePageId(pageId, scope.appId);
-          await emitAuditEvent({
-            type: 'permission_check',
-            userId,
-            organisationId: scope.organisationId,
-            eventId: scope.eventId,
-            appId: scope.appId,
-            pageId: resolvedPageId,
-            permission,
-            decision: cached,
-            source: 'api',
-            duration_ms: duration,
-            cache_hit: true,
-            cache_source: 'memory',
-          });
-        }
-        
+        // Skip audit logging for cached checks (only log on cache miss)
+        // This significantly reduces network requests
         return cached;
       }
 

package/src/rbac/hooks/usePermissions.ts

@@ -22,6 +22,7 @@ import {
   isPermittedCached 
 } from '../api';
 import { getRBACLogger } from '../config';
+import { scopeEqual } from '../utils/deep-equal';
 
 /**
  * Hook to get user's permissions in a scope
@@ -337,20 +338,35 @@ export function useCan(
   const lastPageIdRef = useRef<UUID | undefined | null>(null);
   const lastUseCacheRef = useRef<boolean | null>(null);
 
+  // Create a stable scope object for comparison
+  const stableScope = useMemo(() => {
+    if (!isValidScope) {
+      return null;
+    }
+    return {
+      organisationId,
+      eventId,
+      appId,
+    };
+  }, [isValidScope, organisationId, eventId, appId]);
+
+  // Track previous scope for deep equality comparison
+  const prevScopeRef = useRef<Scope | null>(null);
+
   useEffect(() => {
-    // Create a scope key to track changes - use safe property access
-    const scopeKey = isValidScope ? `${organisationId}-${eventId}-${appId}` : 'invalid-scope';
+    // Use deep equality check for scope to prevent unnecessary re-runs
+    const scopeChanged = !scopeEqual(prevScopeRef.current, stableScope);
     
     // Only run if something has actually changed
     if (
       lastUserIdRef.current !== userId ||
-      lastScopeRef.current !== scopeKey ||
+      scopeChanged ||
       lastPermissionRef.current !== permission ||
       lastPageIdRef.current !== pageId ||
       lastUseCacheRef.current !== useCache
     ) {
       lastUserIdRef.current = userId;
-      lastScopeRef.current = scopeKey;
+      prevScopeRef.current = stableScope;
       lastPermissionRef.current = permission;
       lastPageIdRef.current = pageId;
       lastUseCacheRef.current = useCache;
@@ -410,7 +426,7 @@ export function useCan(
       
       checkPermission();
     }
-  }, [userId, isValidScope, organisationId, eventId, appId, permission, pageId, useCache]);
+  }, [userId, stableScope, permission, pageId, useCache]);
 
   const refetch = useCallback(async () => {
     if (!userId) {

package/src/rbac/index.ts

@@ -59,6 +59,25 @@ export {
   CACHE_PATTERNS,
 } from './cache';
 
+// Performance monitoring
+export {
+  enablePerformanceMonitoring,
+  disablePerformanceMonitoring,
+  isPerformanceMonitoringEnabled,
+  recordPermissionCheck,
+  recordAuditEvent,
+  getPerformanceMetrics,
+  resetPerformanceMetrics,
+  getPerformanceSummary,
+  type RBACPerformanceMetrics,
+} from './performance';
+
+// Request deduplication
+export {
+  clearInFlightRequests,
+  getInFlightRequestCount,
+} from './request-deduplication';
+
 // Audit
 export {
   RBACAuditManager,

package/src/rbac/performance.ts

@@ -0,0 +1,210 @@
+/**
+ * Performance Monitoring for RBAC
+ * @package @jmruthers/pace-core
+ * @module RBAC/Performance
+ * @since 2.0.0
+ * 
+ * This module provides performance monitoring and metrics tracking for RBAC operations.
+ */
+
+export interface RBACPerformanceMetrics {
+  /** Total number of permission checks */
+  totalChecks: number;
+  /** Number of cache hits */
+  cacheHits: number;
+  /** Number of cache misses */
+  cacheMisses: number;
+  /** Cache hit rate (0-1) */
+  cacheHitRate: number;
+  /** Number of deduplicated requests */
+  deduplicatedRequests: number;
+  /** Total number of network requests made */
+  networkRequests: number;
+  /** Average response time in milliseconds */
+  averageResponseTime: number;
+  /** Total response time in milliseconds */
+  totalResponseTime: number;
+  /** Number of batched audit events */
+  batchedAuditEvents: number;
+  /** Number of individual audit events */
+  individualAuditEvents: number;
+}
+
+class RBACPerformanceMonitor {
+  private metrics: RBACPerformanceMetrics = {
+    totalChecks: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+    cacheHitRate: 0,
+    deduplicatedRequests: 0,
+    networkRequests: 0,
+    averageResponseTime: 0,
+    totalResponseTime: 0,
+    batchedAuditEvents: 0,
+    individualAuditEvents: 0,
+  };
+
+  private enabled: boolean = false;
+
+  /**
+   * Enable or disable performance monitoring
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check if performance monitoring is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Record a permission check
+   */
+  recordCheck(cacheHit: boolean, responseTime: number, wasDeduplicated: boolean = false): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    this.metrics.totalChecks++;
+    
+    if (cacheHit) {
+      this.metrics.cacheHits++;
+    } else {
+      this.metrics.cacheMisses++;
+      this.metrics.networkRequests++;
+    }
+
+    if (wasDeduplicated) {
+      this.metrics.deduplicatedRequests++;
+    }
+
+    this.metrics.totalResponseTime += responseTime;
+    this.metrics.averageResponseTime = this.metrics.totalResponseTime / this.metrics.totalChecks;
+    this.metrics.cacheHitRate = this.metrics.cacheHits / this.metrics.totalChecks;
+  }
+
+  /**
+   * Record an audit event
+   */
+  recordAuditEvent(batched: boolean): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    if (batched) {
+      this.metrics.batchedAuditEvents++;
+    } else {
+      this.metrics.individualAuditEvents++;
+    }
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): RBACPerformanceMetrics {
+    return { ...this.metrics };
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.metrics = {
+      totalChecks: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      cacheHitRate: 0,
+      deduplicatedRequests: 0,
+      networkRequests: 0,
+      averageResponseTime: 0,
+      totalResponseTime: 0,
+      batchedAuditEvents: 0,
+      individualAuditEvents: 0,
+    };
+  }
+
+  /**
+   * Get metrics summary as a formatted string
+   */
+  getSummary(): string {
+    const m = this.metrics;
+    return `
+RBAC Performance Metrics:
+  Total Checks: ${m.totalChecks}
+  Cache Hits: ${m.cacheHits} (${(m.cacheHitRate * 100).toFixed(1)}%)
+  Cache Misses: ${m.cacheMisses}
+  Deduplicated Requests: ${m.deduplicatedRequests}
+  Network Requests: ${m.networkRequests}
+  Average Response Time: ${m.averageResponseTime.toFixed(2)}ms
+  Batched Audit Events: ${m.batchedAuditEvents}
+  Individual Audit Events: ${m.individualAuditEvents}
+`;
+  }
+}
+
+// Global performance monitor instance
+const performanceMonitor = new RBACPerformanceMonitor();
+
+/**
+ * Enable performance monitoring
+ */
+export function enablePerformanceMonitoring(): void {
+  performanceMonitor.setEnabled(true);
+}
+
+/**
+ * Disable performance monitoring
+ */
+export function disablePerformanceMonitoring(): void {
+  performanceMonitor.setEnabled(false);
+}
+
+/**
+ * Check if performance monitoring is enabled
+ */
+export function isPerformanceMonitoringEnabled(): boolean {
+  return performanceMonitor.isEnabled();
+}
+
+/**
+ * Record a permission check
+ */
+export function recordPermissionCheck(
+  cacheHit: boolean,
+  responseTime: number,
+  wasDeduplicated: boolean = false
+): void {
+  performanceMonitor.recordCheck(cacheHit, responseTime, wasDeduplicated);
+}
+
+/**
+ * Record an audit event
+ */
+export function recordAuditEvent(batched: boolean): void {
+  performanceMonitor.recordAuditEvent(batched);
+}
+
+/**
+ * Get current performance metrics
+ */
+export function getPerformanceMetrics(): RBACPerformanceMetrics {
+  return performanceMonitor.getMetrics();
+}
+
+/**
+ * Reset performance metrics
+ */
+export function resetPerformanceMetrics(): void {
+  performanceMonitor.reset();
+}
+
+/**
+ * Get performance metrics summary
+ */
+export function getPerformanceSummary(): string {
+  return performanceMonitor.getSummary();
+}
+