@rebasepro/server-core 0.0.1-canary.4d4fb3e

package/src/serve-spa.ts

@@ -0,0 +1,81 @@
+import { Hono } from "hono";
+import { serveStatic } from "@hono/node-server/serve-static";
+import * as path from "path";
+import * as fs from "fs";
+
+/**
+ * Configuration for serving a Single Page Application
+ */
+export interface ServeSPAConfig {
+    /**
+     * Absolute path to the frontend build directory
+     * @example path.join(__dirname, "../../frontend/dist")
+     */
+    frontendPath: string;
+
+    /**
+     * Base path for API routes (default: "/api")
+     * Requests to this path will be passed through to API handlers
+     */
+    apiBasePath?: string;
+
+    /**
+     * Additional paths to exclude from SPA handling
+     * These paths will be passed through to other handlers
+     * @example ["/health", "/ws", "/metrics"]
+     */
+    excludePaths?: string[];
+
+    /**
+     * Index file to serve for SPA routes (default: "index.html")
+     */
+    indexFile?: string;
+}
+
+/**
+ * Serve a Single Page Application from an Hono app.
+ */
+export function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: ServeSPAConfig): void {
+    const {
+        frontendPath,
+        apiBasePath = "/api",
+        excludePaths = [],
+        indexFile = "index.html"
+    } = config;
+
+    // Validate frontend path exists
+    if (!fs.existsSync(frontendPath)) {
+        console.warn(`⚠️ Frontend build path does not exist: ${frontendPath}`);
+        console.warn("   SPA serving is disabled. Build your frontend first.");
+        return;
+    }
+
+    // Serve static files from frontend build
+    app.use("/*", serveStatic({
+        root: path.relative(process.cwd(), frontendPath)
+    }));
+
+    // Build list of paths to exclude from SPA handling
+    const allExcludePaths = [apiBasePath, ...excludePaths];
+
+    // SPA fallback - serve index.html for all non-excluded routes
+    app.get("*", async (c, next) => {
+        // Skip excluded paths (API, health checks, etc.)
+        if (allExcludePaths.some(p => c.req.path.startsWith(p))) {
+            return next();
+        }
+
+        const indexPath = path.join(frontendPath, indexFile);
+
+        if (!fs.existsSync(indexPath)) {
+            console.warn(`⚠️ Index file not found: ${indexPath}`);
+            return next();
+        }
+
+        const html = fs.readFileSync(indexPath, "utf-8");
+        return c.html(html);
+    });
+
+    console.log(`✅ SPA serving enabled from: ${frontendPath}`);
+}
+

package/src/services/driver-registry.ts

@@ -0,0 +1,182 @@
+/**
+ * Driver Registry
+ *
+ * Manages multiple driver delegates for Rebase backend.
+ * Allows different databases for different collections.
+ *
+ * Usage:
+ * - Single DB: Pass a single DataDriver → maps to "(default)"
+ * - Multiple DBs: Pass a map of { dbId: DataDriver }
+ * - Collections use `databaseId` property to specify which driver to use
+ * - Collections without `databaseId` fallback to "(default)"
+ */
+
+import { DataDriver } from "@rebasepro/types";
+
+/**
+ * The default driver identifier used when:
+ * - A single driver is provided (not a map)
+ * - A collection doesn't specify a databaseId
+ */
+export const DEFAULT_DRIVER_ID = "(default)";
+
+/**
+ * Registry for managing multiple driver delegates
+ */
+export interface DriverRegistry {
+    /**
+     * Register a driver delegate with an ID
+     * @param id - Unique identifier for this driver (e.g., "analytics", "users")
+     * @param delegate - The DataDriver instance
+     */
+    register(id: string, delegate: DataDriver): void;
+
+    /**
+     * Get the default driver delegate (id = "(default)")
+     * @throws Error if no default driver is registered
+     */
+    getDefault(): DataDriver;
+
+    /**
+     * Get a driver delegate by ID
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver, or undefined if not found
+     */
+    get(id: string | undefined | null): DataDriver | undefined;
+
+    /**
+     * Get a driver delegate by ID, with fallback to default
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver (falls back to default if id not found)
+     * @throws Error if neither the specified nor default driver exists
+     */
+    getOrDefault(id: string | undefined | null): DataDriver;
+
+    /**
+     * Check if a driver with the given ID exists
+     */
+    has(id: string): boolean;
+
+    /**
+     * List all registered driver IDs
+     */
+    list(): string[];
+
+    /**
+     * Get the number of registered drivers
+     */
+    size(): number;
+}
+
+/**
+ * Default implementation of DriverRegistry
+ */
+export class DefaultDriverRegistry implements DriverRegistry {
+    private delegates = new Map<string, DataDriver>();
+
+    /**
+     * Create a DriverRegistry from either a single delegate or a map
+     * @param input - Single DataDriver (maps to "(default)") or Record<string, DataDriver>
+     */
+    static create(
+        input: DataDriver | Record<string, DataDriver>
+    ): DefaultDriverRegistry {
+        const registry = new DefaultDriverRegistry();
+
+        if (isDataDriverDelegate(input)) {
+            // Single delegate → register as "(default)"
+            registry.register(DEFAULT_DRIVER_ID, input);
+        } else {
+            // Map of delegates → register each
+            for (const [id, delegate] of Object.entries(input)) {
+                registry.register(id, delegate);
+            }
+            // Ensure there's a default if not explicitly provided
+            if (!registry.has(DEFAULT_DRIVER_ID) && registry.size() > 0) {
+                // If no explicit "(default)", use the first one as default
+                const firstId = Object.keys(input)[0];
+                console.warn(
+                    `[DriverRegistry] No "${DEFAULT_DRIVER_ID}" driver provided. ` +
+                    `Using "${firstId}" as the default.`
+                );
+                registry.register(DEFAULT_DRIVER_ID, input[firstId]);
+            }
+        }
+
+        return registry;
+    }
+
+    register(id: string, delegate: DataDriver): void {
+        if (this.delegates.has(id)) {
+            console.warn(`[DriverRegistry] Overwriting driver with id "${id}"`);
+        }
+        this.delegates.set(id, delegate);
+    }
+
+    getDefault(): DataDriver {
+        const delegate = this.delegates.get(DEFAULT_DRIVER_ID);
+        if (!delegate) {
+            throw new Error(
+                `[DriverRegistry] No default driver registered. ` +
+                `Register one with id "${DEFAULT_DRIVER_ID}" or pass a single DataDriver.`
+            );
+        }
+        return delegate;
+    }
+
+    get(id: string | undefined | null): DataDriver | undefined {
+        if (id === undefined || id === null) {
+            return this.delegates.get(DEFAULT_DRIVER_ID);
+        }
+        return this.delegates.get(id);
+    }
+
+    getOrDefault(id: string | undefined | null): DataDriver {
+        // If no ID specified, return default
+        if (id === undefined || id === null) {
+            return this.getDefault();
+        }
+
+        // Try to get by ID
+        const delegate = this.delegates.get(id);
+        if (delegate) {
+            return delegate;
+        }
+
+        // Fallback to default with warning
+        console.warn(
+            `[DriverRegistry] Driver "${id}" not found, falling back to "${DEFAULT_DRIVER_ID}"`
+        );
+        return this.getDefault();
+    }
+
+    has(id: string): boolean {
+        return this.delegates.has(id);
+    }
+
+    list(): string[] {
+        return Array.from(this.delegates.keys());
+    }
+
+    size(): number {
+        return this.delegates.size;
+    }
+}
+
+/**
+ * Type guard to check if an object is a DataDriver
+ */
+function isDataDriverDelegate(obj: unknown): obj is DataDriver {
+    if (typeof obj !== "object" || obj === null) {
+        return false;
+    }
+    const delegate = obj as DataDriver;
+    // Check for required DataDriver properties
+    return (
+        typeof delegate.key === "string" &&
+        typeof delegate.fetchCollection === "function" &&
+        typeof delegate.fetchEntity === "function" &&
+        typeof delegate.saveEntity === "function" &&
+        typeof delegate.deleteEntity === "function"
+    );
+}

package/src/storage/LocalStorageController.ts

@@ -0,0 +1,368 @@
+/**
+ * Local filesystem storage controller
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { promisify } from 'util';
+import {
+    StorageController,
+    LocalStorageConfig,
+    DEFAULT_MAX_FILE_SIZE
+} from './types';
+import {
+    UploadFileProps,
+    UploadFileResult,
+    DownloadConfig,
+    DownloadMetadata,
+    StorageListResult,
+    StorageReference
+} from '@rebasepro/types';
+
+const mkdir = promisify(fs.mkdir);
+const writeFile = promisify(fs.writeFile);
+const readFile = promisify(fs.readFile);
+const unlink = promisify(fs.unlink);
+const readdir = promisify(fs.readdir);
+const stat = promisify(fs.stat);
+const access = promisify(fs.access);
+
+/**
+ * Remove initial and trailing slashes from a path.
+ * Handles paths like "/images/", "images/", "/images" → "images"
+ */
+function normalizeStoragePath(s: string): string {
+    let result = s;
+    while (result.startsWith('/')) {
+        result = result.slice(1);
+    }
+    while (result.endsWith('/')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+
+/**
+ * Local filesystem storage implementation
+ * Stores files in a directory structure: {basePath}/{bucket}/{path}
+ */
+export class LocalStorageController implements StorageController {
+    private config: LocalStorageConfig;
+    private basePath: string;
+
+    constructor(config: LocalStorageConfig) {
+        this.config = config;
+        this.basePath = path.resolve(config.basePath);
+    }
+
+    getType(): 'local' {
+        return 'local';
+    }
+
+    /**
+     * Ensure directory exists, creating it if necessary
+     */
+    private async ensureDir(dirPath: string): Promise<void> {
+        try {
+            await mkdir(dirPath, { recursive: true });
+        } catch (error: unknown) {
+            if (error instanceof Error && (error as NodeJS.ErrnoException).code !== 'EEXIST') {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Get the full filesystem path for a storage path.
+     * Includes a path traversal guard to prevent escaping the base directory.
+     */
+    private getFullPath(storagePath: string, bucket?: string): string {
+        const parts = bucket ? [this.basePath, bucket, storagePath] : [this.basePath, storagePath];
+        const resolved = path.resolve(path.join(...parts));
+        if (!resolved.startsWith(this.basePath + path.sep) && resolved !== this.basePath) {
+            throw new Error("Path traversal detected: resolved storage path is outside the base directory.");
+        }
+        return resolved;
+    }
+
+    /**
+     * Validate file before upload
+     */
+    private validateFile(file: File): void {
+        const maxSize = this.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+        if (file.size > maxSize) {
+            throw new Error(`File size ${file.size} exceeds maximum allowed size ${maxSize}`);
+        }
+
+        if (this.config.allowedMimeTypes && this.config.allowedMimeTypes.length > 0) {
+            if (!this.config.allowedMimeTypes.includes(file.type)) {
+                throw new Error(`File type ${file.type} is not allowed. Allowed types: ${this.config.allowedMimeTypes.join(', ')}`);
+            }
+        }
+    }
+
+    async uploadFile({
+        file,
+        fileName,
+        path: storagePath,
+        metadata,
+        bucket
+    }: UploadFileProps): Promise<UploadFileResult> {
+        this.validateFile(file);
+
+        // Always use a bucket (default to 'default')
+        const usedBucket = bucket ?? 'default';
+        const usedFileName = fileName ?? file.name;
+        // Normalize storage path to remove leading/trailing slashes
+        const normalizedPath = storagePath ? normalizeStoragePath(storagePath) : '';
+        const fullStoragePath = normalizedPath ? `${normalizedPath}/${usedFileName}` : usedFileName;
+        const fullPath = this.getFullPath(fullStoragePath, usedBucket);
+
+        // Ensure parent directory exists
+        await this.ensureDir(path.dirname(fullPath));
+
+        // Convert File to Buffer and write
+        const arrayBuffer = await file.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        await writeFile(fullPath, buffer);
+
+        // Always save metadata file with at least contentType (required for preview)
+        const metadataPath = `${fullPath}.metadata.json`;
+        await writeFile(metadataPath, JSON.stringify({
+            ...(metadata || {}),
+            contentType: file.type,
+            size: file.size,
+            uploadedAt: new Date().toISOString()
+        }, null, 2));
+
+        return {
+            path: fullStoragePath,
+            bucket: usedBucket,
+            storageUrl: `local://${usedBucket}/${fullStoragePath}`
+        };
+    }
+
+    async getDownloadURL(storagePath: string, bucket?: string): Promise<DownloadConfig> {
+        // Handle local:// URLs
+        let resolvedPath = storagePath;
+        let resolvedBucket = bucket;
+
+        if (storagePath.startsWith('local://')) {
+            const withoutProtocol = storagePath.substring('local://'.length);
+            const firstSlash = withoutProtocol.indexOf('/');
+            if (firstSlash > 0) {
+                resolvedBucket = withoutProtocol.substring(0, firstSlash);
+                resolvedPath = withoutProtocol.substring(firstSlash + 1);
+            }
+        }
+
+        // Normalize path to handle leading/trailing slashes
+        resolvedPath = normalizeStoragePath(resolvedPath);
+        const fullPath = this.getFullPath(resolvedPath, resolvedBucket);
+
+        try {
+            await access(fullPath, fs.constants.R_OK);
+        } catch {
+            return {
+                url: null,
+                fileNotFound: true
+            };
+        }
+
+        // Read metadata if available
+        let metadata: DownloadMetadata | undefined;
+        const metadataPath = `${fullPath}.metadata.json`;
+        try {
+            const metadataContent = await readFile(metadataPath, 'utf-8');
+            const savedMetadata = JSON.parse(metadataContent);
+            const fileStat = await stat(fullPath);
+
+            metadata = {
+                bucket: resolvedBucket ?? 'default',
+                fullPath: resolvedPath,
+                name: path.basename(resolvedPath),
+                size: fileStat.size,
+                contentType: savedMetadata.contentType || 'application/octet-stream',
+                customMetadata: savedMetadata
+            };
+        } catch {
+            // No metadata file, create basic metadata from stat
+            try {
+                const fileStat = await stat(fullPath);
+                metadata = {
+                    bucket: resolvedBucket ?? 'default',
+                    fullPath: resolvedPath,
+                    name: path.basename(resolvedPath),
+                    size: fileStat.size,
+                    contentType: 'application/octet-stream',
+                    customMetadata: {}
+                };
+            } catch {
+                // Stat failed
+            }
+        }
+
+        // Return a relative URL that will be served by the storage routes
+        const bucketPath = resolvedBucket ? `${resolvedBucket}/` : '';
+        const url = `/api/storage/file/${bucketPath}${resolvedPath}`;
+
+        return {
+            url,
+            metadata
+        };
+    }
+
+    async getFile(storagePath: string, bucket?: string): Promise<File | null> {
+        // Handle local:// URLs
+        let resolvedPath = storagePath;
+        let resolvedBucket = bucket;
+
+        if (storagePath.startsWith('local://')) {
+            const withoutProtocol = storagePath.substring('local://'.length);
+            const firstSlash = withoutProtocol.indexOf('/');
+            if (firstSlash > 0) {
+                resolvedBucket = withoutProtocol.substring(0, firstSlash);
+                resolvedPath = withoutProtocol.substring(firstSlash + 1);
+            }
+        }
+
+        // Normalize path to handle leading/trailing slashes
+        resolvedPath = normalizeStoragePath(resolvedPath);
+        const fullPath = this.getFullPath(resolvedPath, resolvedBucket);
+
+        try {
+            await access(fullPath, fs.constants.R_OK);
+            const buffer = await readFile(fullPath);
+
+            // Try to get content type from metadata
+            let contentType = 'application/octet-stream';
+            try {
+                const metadataPath = `${fullPath}.metadata.json`;
+                const metadataContent = await readFile(metadataPath, 'utf-8');
+                const metadata = JSON.parse(metadataContent);
+                contentType = metadata.contentType || contentType;
+            } catch {
+                // No metadata, use default content type
+            }
+
+            const blob = new Blob([buffer], { type: contentType });
+            return new File([blob], path.basename(resolvedPath), { type: contentType });
+        } catch {
+            return null;
+        }
+    }
+
+    async deleteFile(storagePath: string, bucket?: string): Promise<void> {
+        // Handle local:// URLs
+        let resolvedPath = storagePath;
+        let resolvedBucket = bucket;
+
+        if (storagePath.startsWith('local://')) {
+            const withoutProtocol = storagePath.substring('local://'.length);
+            const firstSlash = withoutProtocol.indexOf('/');
+            if (firstSlash > 0) {
+                resolvedBucket = withoutProtocol.substring(0, firstSlash);
+                resolvedPath = withoutProtocol.substring(firstSlash + 1);
+            }
+        }
+
+        // Normalize path to handle leading/trailing slashes
+        resolvedPath = normalizeStoragePath(resolvedPath);
+        const fullPath = this.getFullPath(resolvedPath, resolvedBucket);
+
+        try {
+            await unlink(fullPath);
+            // Also delete metadata file if exists
+            try {
+                await unlink(`${fullPath}.metadata.json`);
+            } catch {
+                // Metadata file might not exist
+            }
+        } catch (error: unknown) {
+            if (error instanceof Error && (error as NodeJS.ErrnoException).code !== 'ENOENT') {
+                throw error;
+            }
+            // File doesn't exist, nothing to delete
+        }
+    }
+
+    async list(storagePath: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult> {
+        // Normalize path to handle leading/trailing slashes
+        const normalizedPath = normalizeStoragePath(storagePath);
+        const fullPath = this.getFullPath(normalizedPath, options?.bucket);
+        const items: StorageReference[] = [];
+        const prefixes: StorageReference[] = [];
+
+        try {
+            await access(fullPath, fs.constants.R_OK);
+            const entries = await readdir(fullPath, { withFileTypes: true });
+
+            let count = 0;
+            const maxResults = options?.maxResults ?? 1000;
+            const startIndex = options?.pageToken ? parseInt(options.pageToken, 10) : 0;
+
+            for (let i = startIndex; i < entries.length && count < maxResults; i++) {
+                const entry = entries[i];
+
+                // Skip metadata files
+                if (entry.name.endsWith('.metadata.json')) {
+                    continue;
+                }
+
+                const entryPath = storagePath ? `${storagePath}/${entry.name}` : entry.name;
+                const bucket = options?.bucket ?? 'default';
+
+                const ref: StorageReference = {
+                    bucket,
+                    fullPath: entryPath,
+                    name: entry.name,
+                    parent: null as never, // Simplified - not fully implementing parent chain
+                    root: null as never,
+                    toString: () => `local://${bucket}/${entryPath}`
+                };
+
+                if (entry.isDirectory()) {
+                    prefixes.push(ref);
+                } else {
+                    items.push(ref);
+                }
+                count++;
+            }
+
+            const nextPageToken = startIndex + count < entries.length
+                ? String(startIndex + count)
+                : undefined;
+
+            return {
+                items,
+                prefixes,
+                nextPageToken
+            };
+        } catch (error: unknown) {
+            const code = (error as NodeJS.ErrnoException)?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                return { items: [], prefixes: [] };
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Get the absolute filesystem path for serving files
+     * Used by the storage routes to serve files directly
+     */
+    getAbsolutePath(storagePath: string, bucket?: string): string {
+        return this.getFullPath(storagePath, bucket);
+    }
+
+    /**
+     * Get the base path for the storage
+     */
+    getBasePath(): string {
+        return this.basePath;
+    }
+}