@africode/core 5.0.0

package/core/server/rate-limit.js

@@ -0,0 +1,238 @@
+/**
+ * AfriCode Rate Limiting Middleware
+ *
+ * In-memory sliding window rate limiter for API endpoints.
+ * Framework-level middleware — protect by default.
+ *
+ * Algorithm: Fixed window with sliding expiry
+ * - Each client (identified by IP) gets a counter per window
+ * - When the window expires, the counter resets
+ * - If the counter exceeds the limit, requests are rejected with 429
+ *
+ * Limitations:
+ * - In-memory only (resets on server restart)
+ * - Single-process only (not shared across workers/instances)
+ * - For production multi-instance environments, use Redis-backed rate limiting
+ *
+ * Future: This interface is designed so a Redis/KV adapter can be
+ * swapped in without changing the middleware API.
+ *
+ * @module core/server/rate-limit
+ */
+
+import { RateLimitError } from '../errors.js';
+import { emitRateLimit } from '../config.js';
+
+/**
+ * @typedef {Object} RateLimitConfig
+ * @property {number} [windowMs=60000] - Time window in milliseconds (default: 1 minute)
+ * @property {number} [maxRequests=60] - Maximum requests per window (default: 60)
+ * @property {string} [message='Too many requests'] - Error message
+ * @property {Function} [keyGenerator] - Custom key generator: (request) => string
+ * @property {string[]} [excludePaths=[]] - Paths that skip rate limiting
+ * @property {Function} [onLimitReached] - Callback when limit is reached: (key, request) => void
+ * @property {Object} [headers=true] - Include rate limit headers in response
+ */
+
+/**
+ * In-memory rate limit store.
+ * Maps client keys to their request tracking data.
+ *
+ * @type {Map<string, { count: number, resetAt: number }>}
+ */
+const store = new Map();
+
+/**
+ * Cleanup interval reference.
+ * Periodically removes expired entries to prevent memory leaks.
+ */
+let cleanupInterval = null;
+
+/**
+ * Get the client identifier from a request.
+ * Default: uses IP address from various headers.
+ *
+ * @param {Request} request
+ * @returns {string} Client identifier
+ */
+function defaultKeyGenerator(request) {
+  // Check standard headers in priority order
+  const forwarded = request.headers.get('X-Forwarded-For');
+  if (forwarded) {
+    // X-Forwarded-For can contain multiple IPs, take the first (client)
+    return forwarded.split(',')[0].trim();
+  }
+
+  const realIp = request.headers.get('X-Real-IP');
+  if (realIp) {return realIp;}
+
+  // Fallback: use the request URL host (not ideal, but safe fallback)
+  try {
+    const url = new URL(request.url);
+    return url.hostname;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Create a rate limiting middleware.
+ *
+ * @param {RateLimitConfig} [config] - Configuration
+ * @returns {Function} Middleware function: (request) => { response: Response|null, headers: Record<string, string> }
+ *
+ * @example
+ * // Basic usage — 60 requests per minute
+ * const limiter = createRateLimiter();
+ *
+ * // In your request handler:
+ * const { response, headers } = limiter(request);
+ * if (response) return response; // 429 Too Many Requests
+ * // Add headers to your success response for transparency
+ *
+ * @example
+ * // Custom limits for auth endpoints
+ * const authLimiter = createRateLimiter({
+ *   windowMs: 15 * 60 * 1000,  // 15 minutes
+ *   maxRequests: 5,             // 5 attempts
+ *   message: 'Too many login attempts. Please try again later.',
+ *   onLimitReached: (key) => console.warn(`Rate limit reached for ${key}`)
+ * });
+ *
+ * @example
+ * // Skip rate limiting for certain paths
+ * const limiter = createRateLimiter({
+ *   excludePaths: ['/api/health', '/api/status']
+ * });
+ */
+export function createRateLimiter(config = {}) {
+  const {
+    windowMs = 60 * 1000,       // 1 minute
+    maxRequests = 60,            // 60 requests per window
+    message = 'Too many requests. Please try again later.',
+    keyGenerator = defaultKeyGenerator,
+    excludePaths = [],
+    onLimitReached = null
+  } = config;
+
+  // Start cleanup interval if not already running
+  if (!cleanupInterval) {
+    cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, data] of store.entries()) {
+        if (now >= data.resetAt) {
+          store.delete(key);
+        }
+      }
+    }, windowMs);
+
+    // Don't keep the process alive just for cleanup
+    if (cleanupInterval.unref) {
+      cleanupInterval.unref();
+    }
+  }
+
+  /**
+   * @param {Request} request
+   * @returns {{ response: Response|null, headers: Record<string, string> }}
+   */
+  return function rateLimitMiddleware(request) {
+    // Check excluded paths
+    try {
+      const url = new URL(request.url);
+      if (excludePaths.some(path => url.pathname.startsWith(path))) {
+        return { response: null, headers: {} };
+      }
+    } catch {
+      // Invalid URL, continue with rate limiting
+    }
+
+    const key = keyGenerator(request);
+    const now = Date.now();
+
+    // Get or create entry
+    let entry = store.get(key);
+
+    if (!entry || now >= entry.resetAt) {
+      // Window expired or new client — reset
+      entry = { count: 0, resetAt: now + windowMs };
+      store.set(key, entry);
+    }
+
+    // Increment count
+    entry.count++;
+
+    // Build rate limit headers (always returned for transparency)
+    const remaining = Math.max(0, maxRequests - entry.count);
+    const resetAtSeconds = Math.ceil(entry.resetAt / 1000);
+    const headers = {
+      'X-RateLimit-Limit': String(maxRequests),
+      'X-RateLimit-Remaining': String(remaining),
+      'X-RateLimit-Reset': String(resetAtSeconds)
+    };
+
+    // Check if over limit
+    if (entry.count > maxRequests) {
+      const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+
+      // Emit hook
+      emitRateLimit(key, request);
+
+      // Call user callback if provided
+      if (onLimitReached) {
+        onLimitReached(key, request);
+      }
+
+      const error = new RateLimitError(retryAfter, message);
+
+      return {
+        response: new Response(
+          JSON.stringify(error.toJSON()),
+          {
+            status: 429,
+            headers: {
+              'Content-Type': 'application/json',
+              'Retry-After': String(retryAfter),
+              ...headers
+            }
+          }
+        ),
+        headers
+      };
+    }
+
+    // Under limit — pass through
+    return { response: null, headers };
+  };
+}
+
+/**
+ * Reset the rate limit store.
+ * Useful for testing or administrative purposes.
+ */
+export function resetRateLimitStore() {
+  store.clear();
+}
+
+/**
+ * Get the current store size (number of tracked clients).
+ * Useful for monitoring.
+ *
+ * @returns {number}
+ */
+export function getRateLimitStoreSize() {
+  return store.size;
+}
+
+/**
+ * Stop the cleanup interval.
+ * Call this during server shutdown.
+ */
+export function stopRateLimitCleanup() {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+}
+
+export default { createRateLimiter, resetRateLimitStore, getRateLimitStoreSize, stopRateLimitCleanup };

package/core/server/render.js

@@ -0,0 +1,69 @@
+/**
+ * AfriCode SSR Engine
+ * Implements Declarative Shadow DOM (DSD) for instant loading.
+ * 
+ * "The primary requirement... is the optimization of the rendering pipeline." - Blueprint
+ */
+
+import { file } from "bun";
+
+// Registry of component definitions for SSR
+// In a real framework, this would parse the component class
+// For v1, we map tags to their Shadow DOM HTML
+const componentRegistry = {
+    'af-navbar': (attrs) => `
+        <template shadowrootmode="open">
+            <style>
+                :host { display: block; font-family: 'Inter', system-ui; }
+                nav { background: #1EB53A; padding: 16px; color: white; display: flex; justify-content: space-between; }
+                .logo { font-weight: 800; font-size: 1.2rem; }
+            </style>
+            <nav>
+                <div class="logo">${attrs.logo || 'AfriCode'}</div>
+                <div class="links"><slot></slot></div>
+            </nav>
+        </template>
+    `,
+    'af-card': (attrs) => `
+        <template shadowrootmode="open">
+            <style>
+            :host { display: block; background: #1e293b; border: 1px solid #334155; border-radius: 12px; padding: 24px; color: white; }
+            </style>
+            <slot></slot>
+        </template>
+    `
+};
+
+// Bun-specific imports moved inside functions to allow browser-side evaluation without crashes
+export async function renderPage(filePath) {
+    const { file } = await import("bun");
+    const fileRef = file(filePath);
+    let html = await fileRef.text();
+
+    // 1. SSR: Inject Declarative Shadow DOM
+    // Matches <af-tag ...></af-tag>
+    // Regex is simple for v1, real parser needed for production
+    for (const [tag, renderFn] of Object.entries(componentRegistry)) {
+        const regex = new RegExp(`<${tag}([^>]*)>`, 'g');
+
+        html = html.replace(regex, (match, attrString) => {
+            // Parse attributes
+            const attrs = {};
+            attrString.replace(/(\w+)="([^"]*)"/g, (m, key, value) => {
+                attrs[key] = value;
+            });
+
+            // Return tag + DSD Template
+            return `<${tag}${attrString}>${renderFn(attrs)}`;
+        });
+    }
+
+    // 2. SEO: Inject Meta Tags if missing
+    if (!html.includes('<meta name="generator"')) {
+        html = html.replace('</head>', '<meta name="generator" content="AfriCode v1.0 SSR"></head>');
+    }
+
+    return new Response(html, {
+        headers: { 'Content-Type': 'text/html' }
+    });
+}

package/core/server/router.js

@@ -0,0 +1,120 @@
+/**
+ * AfriCode Server-Side Router
+ * 
+ * Handles dynamic API routing by mapping URLs to the file system.
+ * Edge-Ready: Uses strictly standard Request/Response objects.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Cache routes in memory for performance
+const routeCache = new Map();
+
+/**
+ * Discovers API routes in the /pages/api directory
+ * Note: In a pure Edge environment (Cloudflare), this would be replaced
+ * by a build-time manifest injection.
+ */
+async function loadRoutes() {
+    const apiDir = path.join(process.cwd(), 'pages', 'api');
+
+    if (!fs.existsSync(apiDir)) {return;}
+
+    const files = fs.readdirSync(apiDir);
+
+    for (const file of files) {
+        if (file.endsWith('.js')) {
+            const routeName = '/api/' + file.replace('.js', '');
+            const modulePath = path.join(apiDir, file);
+            routeCache.set(routeName, modulePath);
+            console.log(`✓ Registered Route: ${routeName}`);
+        }
+    }
+}
+
+/**
+ * HTTP Method Handler
+ * @param {object} module - The imported API module
+ * @param {Request} req - The incoming request
+ * @returns {Promise<Response>}
+ */
+async function executeHandler(module, req) {
+    const method = req.method.toUpperCase();
+
+    if (module[method]) {
+        return await module[method](req);
+    } else if (module.default) {
+        return await module.default(req);
+    }
+
+    return new Response('Method Not Allowed', { status: 405 });
+}
+
+/**
+ * Router Handler
+ * @param {Request} req
+ * @returns {Promise<Response|null>}
+ */
+export async function handleApiRequest(req) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    // 0. Handle built-in auth endpoints
+    if (pathname.startsWith('/api/auth/')) {
+        try {
+            const { handleAuthRequest } = await import('./auth-endpoints.js');
+            const authResponse = await handleAuthRequest(req, pathname);
+            if (authResponse) {
+                return authResponse;
+            }
+        } catch (err) {
+            console.error(`Auth endpoint error at ${pathname}:`, err);
+            return new Response(JSON.stringify({ error: err.message }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' }
+            });
+        }
+    }
+
+    // Load routes lazily
+    if (routeCache.size === 0) {
+        await loadRoutes();
+    }
+
+    // 1. Exact Match
+    let modulePath = routeCache.get(pathname);
+
+    // 2. Dynamic Match (Basic implementation)
+    // If no exact match, look for dynamic routes [id].js? 
+    if (!modulePath) {
+        for (const [route, path] of routeCache.entries()) {
+            if (route.includes('[') && matchDynamicRoute(route, pathname)) {
+                modulePath = path;
+                // We would inject params into request here
+                break;
+            }
+        }
+    }
+
+    if (modulePath) {
+        try {
+            // Import the module
+            const module = await import(modulePath);
+            return await executeHandler(module, req);
+        } catch (err) {
+            console.error(`Status 500 at ${pathname}:`, err);
+            return new Response(JSON.stringify({ error: err.message }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' }
+            });
+        }
+    }
+
+    return null; // Not captured -> 404 handled by server.js
+}
+
+function matchDynamicRoute(routePattern, actualPath) {
+    // Placeholder logic for future expansion
+    return false;
+}

package/core/shim.js

@@ -0,0 +1,28 @@
+/**
+ * AfriCode SSR DOM Shim
+ * Allows Web Components to be imported in Node/Bun environment.
+ */
+
+if (typeof globalThis.HTMLElement === 'undefined') {
+    globalThis.HTMLElement = class HTMLElement { };
+    globalThis.customElements = { define: () => { }, get: () => { } };
+    globalThis.document = {
+        createElement: () => ({
+            classList: { add: () => { } },
+            setAttribute: () => { },
+            style: {}
+        }),
+        head: { appendChild: () => { } },
+        body: { appendChild: () => { } }
+    };
+    globalThis.window = globalThis;
+    globalThis.CSSStyleSheet = class CSSStyleSheet { replaceSync() { } };
+}
+
+// Global scope support for certain libraries
+if (typeof global !== 'undefined') {
+    global.HTMLElement = globalThis.HTMLElement;
+    global.customElements = globalThis.customElements;
+    global.document = globalThis.document;
+    global.window = globalThis;
+}

package/core/state.d.ts

@@ -0,0 +1,86 @@
+/**
+ * AfriCode State Management - TypeScript Definitions
+ * Reactive state, signals, and effects
+ */
+
+/**
+ * Creates a reactive state object with Proxy-based reactivity
+ * @template T - The shape of the state object
+ * @param initialState - Initial state values
+ * @returns Reactive proxy of the state
+ */
+export function createReactiveState<T extends Record<string, any>>(
+  initialState: T
+): T & {
+  [K in keyof T]: T[K];
+};
+
+/**
+ * Subscriber callback type
+ */
+export type Subscriber<T extends Record<string, any>> = (
+  newValue: T,
+  oldValue?: T
+) => void;
+
+/**
+ * Subscribe to state changes
+ * @param state - Reactive state object to subscribe to
+ * @param callback - Called when state changes
+ * @returns Unsubscribe function
+ */
+export function subscribe<T extends Record<string, any>>(
+  state: T,
+  callback: Subscriber<T>
+): () => void;
+
+/**
+ * Signal getter function
+ */
+export type SignalGetter<T> = () => T;
+
+/**
+ * Signal setter function - accepts value or updater function
+ */
+export type SignalSetter<T> = (value: T | ((prev: T) => T)) => void;
+
+/**
+ * Signal tuple return type
+ */
+export type Signal<T> = [getter: SignalGetter<T>, setter: SignalSetter<T>];
+
+/**
+ * Create a reactive signal with getter and setter
+ * @template T - Signal value type
+ * @param initialValue - Initial signal value
+ * @returns Tuple of [getter, setter]
+ */
+export function createSignal<T>(initialValue: T): Signal<T>;
+
+/**
+ * Effect callback - can optionally return cleanup function
+ */
+export type EffectCallback = () => void | (() => void);
+
+/**
+ * Effect cleanup function
+ */
+export type EffectCleanup = () => void;
+
+/**
+ * Create an effect that runs side effects
+ * Effects track dependencies from signals and state
+ * @param effect - Effect function to run
+ * @returns Cleanup function
+ */
+export function createEffect(effect: EffectCallback): EffectCleanup;
+
+/**
+ * Internal subscriber map (for advanced use)
+ */
+export const subscribers: WeakMap<object, Set<Subscriber<any>>>;
+
+/**
+ * Internal signal registry (for advanced use)
+ */
+export const signals: WeakMap<object, any>;