@rebasepro/server-core 0.0.1-canary.09e5ec5

package/src/storage/routes.ts

@@ -0,0 +1,264 @@
+/**
+ * Storage REST API routes using Hono
+ */
+
+import { Hono } from "hono";
+import * as fs from "fs";
+import { StorageController } from "./types";
+import { LocalStorageController } from "./LocalStorageController";
+import { requireAuth as jwtRequireAuth, optionalAuth } from "../auth/middleware";
+import { ApiError, errorHandler } from "../api/errors";
+import { HonoEnv } from "../api/types";
+
+export interface StorageRoutesConfig {
+    controller: StorageController;
+    /** Base path for storage routes (default: '/api/storage') */
+    basePath?: string;
+    /** Require authentication for write operations (default: true) */
+    requireAuth?: boolean;
+    /** Allow unauthenticated read access to stored files (default: false).
+     *  When false and requireAuth is true, reads also require authentication. */
+    publicRead?: boolean;
+}
+
+/**
+ * Extract the wildcard portion of a route path from the full request path.
+ *
+ * Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
+ * via `app.route(prefix, subRouter)`. Instead we derive the wildcard value
+ * from the fully-resolved `c.req.path` and `c.req.routePath`.
+ *
+ * For a route `/metadata/*` mounted at `/api/storage`, a request to
+ * `/api/storage/metadata/default/file.jpg` yields routePath
+ * `/api/storage/metadata/*`.  We strip the prefix (everything before `/*`)
+ * plus one character for the trailing `/` to obtain `default/file.jpg`.
+ */
+export function extractWildcardPath(c: { req: { path: string; routePath: string } }): string {
+    const routePath = c.req.routePath; // e.g. "/api/storage/metadata/*"
+    const prefix = routePath.replace("/*", ""); // e.g. "/api/storage/metadata"
+    const fullPath = c.req.path; // e.g. "/api/storage/metadata/default/file.jpg"
+    const idx = fullPath.indexOf(prefix);
+    if (idx < 0) return "";
+    // +1 to skip the '/' after the prefix
+    return fullPath.substring(idx + prefix.length + 1);
+}
+
+/**
+ * Create storage REST API routes
+ */
+export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv> {
+    const router = new Hono<HonoEnv>();
+    router.onError(errorHandler);
+    const { controller, requireAuth = true, publicRead = false } = config;
+
+    // Use actual JWT auth middleware from auth module
+    const writeAuthMiddleware = requireAuth ? jwtRequireAuth : optionalAuth;
+
+    // For read operations: respect publicRead config.
+    const readAuthMiddleware = (publicRead || !requireAuth) ? optionalAuth : jwtRequireAuth;
+
+    /**
+     * Parse bucket and path from a combined file path.
+     */
+    const parseBucketAndPath = (filePath: string): { bucket: string; resolvedPath: string } => {
+        const parts = filePath.split("/");
+
+        // Only recognize 'default' as an explicit bucket prefix
+        if (parts.length > 1 && parts[0].toLowerCase() === "default") {
+            return {
+                bucket: "default",
+                resolvedPath: parts.slice(1).join("/")
+            };
+        }
+
+        // All other paths use 'default' bucket with the full path
+        return {
+            bucket: "default",
+            resolvedPath: filePath
+        };
+    };
+
+    /**
+     * POST /upload - Upload a file
+     * Body: multipart/form-data with 'file' field
+     * Request body can also contain metadata keys 'metadata_*'
+     */
+    router.post("/upload", writeAuthMiddleware, async (c) => {
+        const body = await c.req.parseBody();
+        const uploadedFile = body["file"];
+
+        if (!uploadedFile || typeof uploadedFile === "string") {
+            throw ApiError.badRequest("No file provided");
+        }
+
+        const key = typeof body["key"] === "string" ? body["key"] : "";
+        const bucket = typeof body["bucket"] === "string" ? body["bucket"] : undefined;
+
+        // Backward compatibility support for older clients sending path and fileName
+        const legacyPath = typeof body["path"] === "string" ? body["path"] : "";
+        const legacyFileName = typeof body["fileName"] === "string" ? body["fileName"] : undefined;
+
+        let finalKey = key;
+        if (!finalKey) {
+            if (legacyPath || legacyFileName) {
+                const parts = [];
+                if (legacyPath) parts.push(legacyPath);
+                if (legacyFileName) {
+                    parts.push(legacyFileName);
+                } else {
+                    parts.push(uploadedFile.name || "unnamed");
+                }
+                finalKey = parts.join("/");
+            } else {
+                finalKey = uploadedFile.name || "unnamed";
+            }
+        }
+
+        // Extract custom metadata from request body
+        const metadata: Record<string, unknown> = {};
+        for (const [k, value] of Object.entries(body)) {
+            if (k.startsWith("metadata_")) {
+                metadata[k.replace("metadata_", "")] = value;
+            }
+        }
+
+        const result = await controller.putObject({
+            file: uploadedFile,
+            key: finalKey,
+            metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+            bucket
+        });
+
+        return c.json({
+            success: true,
+            data: result
+        }, 201);
+    });
+
+    /**
+     * GET /file/* - Download/serve a file
+     * Path: /file/{bucket}/{path} or /file/{path}
+     */
+    router.get("/file/*", readAuthMiddleware, async (c) => {
+        const rawPath = extractWildcardPath(c);
+        if (!rawPath) {
+            throw ApiError.notFound("File not found");
+        }
+
+        const filePath = decodeURIComponent(rawPath);
+
+        // For local storage, serve the file directly from disk
+        if (controller.getType() === "local") {
+            const localController = controller as LocalStorageController;
+            const { bucket, resolvedPath } = parseBucketAndPath(filePath);
+
+            const absolutePath = localController.getAbsolutePath(resolvedPath, bucket);
+
+            // Check if file exists
+            if (!fs.existsSync(absolutePath)) {
+                throw ApiError.notFound("File not found");
+            }
+
+            // Get content type from metadata or infer from extension
+            let contentType = "application/octet-stream";
+            const metadataPath = `${absolutePath}.metadata.json`;
+            if (fs.existsSync(metadataPath)) {
+                try {
+                    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+                    contentType = metadata.contentType || contentType;
+                } catch {
+                    // Ignore metadata errors
+                }
+            }
+
+            c.header("Content-Type", contentType);
+            // In a better scenario, we should pipe the stream instead of reading whole file
+            const fileContent = fs.readFileSync(absolutePath);
+            return c.body(new Uint8Array(fileContent));
+        }
+
+        // For remote storage (S3, GCS, etc.), redirect to a signed URL
+        const downloadConfig = await controller.getSignedUrl(filePath);
+        if (downloadConfig.fileNotFound || !downloadConfig.url) {
+            throw ApiError.notFound("File not found");
+        }
+
+        return c.redirect(downloadConfig.url);
+    });
+
+    /**
+     * GET /metadata/* - Get file metadata
+     */
+    router.get("/metadata/*", readAuthMiddleware, async (c) => {
+        const rawPath = extractWildcardPath(c);
+        if (!rawPath) {
+            return c.json({
+                success: true,
+                data: null,
+                fileNotFound: true
+            }, 404);
+        }
+
+        const filePath = decodeURIComponent(rawPath);
+        const { bucket, resolvedPath } = parseBucketAndPath(filePath);
+
+        const downloadConfig = await controller.getSignedUrl(resolvedPath, bucket);
+
+        if (downloadConfig.fileNotFound) {
+            throw ApiError.notFound("File not found");
+        }
+
+        return c.json({
+            success: true,
+            data: downloadConfig.metadata
+        });
+    });
+
+    /**
+     * DELETE /file/* - Delete a file
+     */
+    router.delete("/file/*", writeAuthMiddleware, async (c) => {
+        const rawPath = extractWildcardPath(c);
+        if (!rawPath) {
+            return c.json({ success: true,
+message: "No file to delete" });
+        }
+
+        const filePath = decodeURIComponent(rawPath);
+        const { bucket, resolvedPath } = parseBucketAndPath(filePath);
+
+        await controller.deleteObject(resolvedPath, bucket);
+
+        return c.json({
+            success: true,
+            message: "File deleted"
+        });
+    });
+
+    /**
+     * GET /list - List files in a path
+     */
+    router.get("/list", writeAuthMiddleware, async (c) => {
+        // Fallback to path for backward compatibility
+        const storagePrefix = c.req.query("prefix") || c.req.query("path") || "";
+        const bucket = c.req.query("bucket");
+        const maxResults = c.req.query("maxResults");
+        const pageToken = c.req.query("pageToken");
+
+        const result = await controller.listObjects(
+            storagePrefix,
+            {
+                bucket,
+                maxResults: maxResults ? parseInt(maxResults, 10) : undefined,
+                pageToken
+            }
+        );
+
+        return c.json({
+            success: true,
+            data: result
+        });
+    });
+
+    return router;
+}

package/src/storage/storage-registry.ts

@@ -0,0 +1,187 @@
+/**
+ * Storage Registry
+ *
+ * Manages multiple storage controllers for Rebase backend.
+ * Allows different storage backends for different use cases.
+ *
+ * Usage:
+ * - Single storage: Pass a single StorageController → maps to "(default)"
+ * - Multiple storages: Pass a map of { storageId: StorageController }
+ * - String properties use `storageId` in their config to specify which storage to use
+ * - Properties without `storageId` fallback to "(default)"
+ */
+
+import { StorageController } from "./types";
+
+/**
+ * The default storage identifier used when:
+ * - A single storage controller is provided (not a map)
+ * - A property doesn't specify a storageId
+ */
+export const DEFAULT_STORAGE_ID = "(default)";
+
+/**
+ * Registry for managing multiple storage controllers
+ */
+export interface StorageRegistry {
+    /**
+     * Register a storage controller with an ID
+     * @param id - Unique identifier for this storage (e.g., "media", "backups")
+     * @param controller - The StorageController instance
+     */
+    register(id: string, controller: StorageController): void;
+
+    /**
+     * Get the default storage controller (id = "(default)")
+     * @throws Error if no default storage is registered
+     */
+    getDefault(): StorageController;
+
+    /**
+     * Get a storage controller by ID
+     * @param id - Storage identifier, or undefined/null for default
+     * @returns The StorageController, or undefined if not found
+     */
+    get(id: string | undefined | null): StorageController | undefined;
+
+    /**
+     * Get a storage controller by ID, with fallback to default
+     * @param id - Storage identifier, or undefined/null for default
+     * @returns The StorageController (falls back to default if id not found)
+     * @throws Error if neither the specified nor default storage exists
+     */
+    getOrDefault(id: string | undefined | null): StorageController;
+
+    /**
+     * Check if a storage with the given ID exists
+     */
+    has(id: string): boolean;
+
+    /**
+     * List all registered storage IDs
+     */
+    list(): string[];
+
+    /**
+     * Get the number of registered storage controllers
+     */
+    size(): number;
+}
+
+/**
+ * Default implementation of StorageRegistry
+ */
+export class DefaultStorageRegistry implements StorageRegistry {
+    private controllers = new Map<string, StorageController>();
+
+    /**
+     * Create a StorageRegistry from either a single controller or a map
+     * @param input - Single StorageController (maps to "(default)") or Record<string, StorageController>
+     */
+    static create(
+        input: StorageController | Record<string, StorageController>
+    ): DefaultStorageRegistry {
+        const registry = new DefaultStorageRegistry();
+
+        if (isStorageController(input)) {
+            // Single controller → register as "(default)"
+            registry.register(DEFAULT_STORAGE_ID, input);
+        } else {
+            // Map of controllers → register each
+            for (const [id, controller] of Object.entries(input)) {
+                if (isStorageController(controller)) {
+                    registry.register(id, controller);
+                }
+            }
+            // Ensure there's a default if not explicitly provided
+            if (!registry.has(DEFAULT_STORAGE_ID) && registry.size() > 0) {
+                // If no explicit "(default)", use the first one as default
+                const firstId = Object.keys(input).find(k => isStorageController(input[k]));
+                if (firstId) {
+                    console.warn(
+                        `[StorageRegistry] No "${DEFAULT_STORAGE_ID}" storage provided. ` +
+                        `Using "${firstId}" as the default.`
+                    );
+                    registry.register(DEFAULT_STORAGE_ID, input[firstId]);
+                }
+            }
+        }
+
+        return registry;
+    }
+
+    register(id: string, controller: StorageController): void {
+        if (this.controllers.has(id)) {
+            console.warn(`[StorageRegistry] Overwriting storage with id "${id}"`);
+        }
+        this.controllers.set(id, controller);
+    }
+
+    getDefault(): StorageController {
+        const controller = this.controllers.get(DEFAULT_STORAGE_ID);
+        if (!controller) {
+            throw new Error(
+                "[StorageRegistry] No default storage registered. " +
+                `Register one with id "${DEFAULT_STORAGE_ID}" or pass a single StorageController.`
+            );
+        }
+        return controller;
+    }
+
+    get(id: string | undefined | null): StorageController | undefined {
+        if (id === undefined || id === null) {
+            return this.controllers.get(DEFAULT_STORAGE_ID);
+        }
+        return this.controllers.get(id);
+    }
+
+    getOrDefault(id: string | undefined | null): StorageController {
+        // If no ID specified, return default
+        if (id === undefined || id === null) {
+            return this.getDefault();
+        }
+
+        // Try to get by ID
+        const controller = this.controllers.get(id);
+        if (controller) {
+            return controller;
+        }
+
+        // Fallback to default with warning
+        console.warn(
+            `[StorageRegistry] Storage "${id}" not found, falling back to "${DEFAULT_STORAGE_ID}"`
+        );
+        return this.getDefault();
+    }
+
+    has(id: string): boolean {
+        return this.controllers.has(id);
+    }
+
+    list(): string[] {
+        return Array.from(this.controllers.keys());
+    }
+
+    size(): number {
+        return this.controllers.size;
+    }
+}
+
+/**
+ * Type guard to check if an object is a StorageController
+ * vs a Record<string, StorageController> (multiple storages)
+ */
+function isStorageController(obj: unknown): obj is StorageController {
+    if (typeof obj !== "object" || obj === null) {
+        return false;
+    }
+    const controller = obj as StorageController;
+    // Check for required StorageController properties
+    return (
+        typeof controller.putObject === "function" &&
+        typeof controller.getSignedUrl === "function" &&
+        typeof controller.deleteObject === "function" &&
+        typeof controller.listObjects === "function" &&
+        typeof controller.getType === "function"
+    );
+}

package/src/storage/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Storage configuration and types for Rebase backend
+ */
+
+import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, StorageReference } from "@rebasepro/types";
+
+/**
+ * Local filesystem storage configuration
+ */
+export interface LocalStorageConfig {
+    type: "local";
+    /** Base directory for file storage (e.g., './uploads') */
+    basePath: string;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types (if not set, all types allowed) */
+    allowedMimeTypes?: string[];
+    /** Base URL for generating download URLs (default: auto-detected from request) */
+    baseUrl?: string;
+}
+
+/**
+ * S3-compatible storage configuration (works with AWS S3 and MinIO)
+ */
+export interface S3StorageConfig {
+    type: "s3";
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region (e.g., 'us-east-1') */
+    region?: string;
+    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */
+    endpoint?: string;
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Use path-style URLs (required for MinIO) */
+    forcePathStyle?: boolean;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types (if not set, all types allowed) */
+    allowedMimeTypes?: string[];
+    /** URL expiration time in seconds for signed URLs (default: 3600) */
+    signedUrlExpiration?: number;
+}
+
+/**
+ * Storage configuration — local filesystem or S3-compatible.
+ *
+ * **Built-in providers:**
+ * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).
+ * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
+ *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).
+ *
+ * **Custom providers:**
+ * For cloud-native storage (GCS, Azure Blob, etc.), implement the `StorageController`
+ * interface and pass the instance directly to the `storage` config.
+ */
+export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
+
+/**
+ * Storage controller interface for backend implementations
+ */
+export interface StorageController {
+    /**
+     * Upload an object
+     */
+    putObject(props: UploadFileProps): Promise<UploadFileResult>;
+
+    /**
+     * Get a download URL (signed URL equivalent) for an object
+     */
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+
+    /**
+     * Get object as a File
+     */
+    getObject(key: string, bucket?: string): Promise<File | null>;
+
+    /**
+     * Delete an object
+     */
+    deleteObject(key: string, bucket?: string): Promise<void>;
+
+    /**
+     * List objects in a prefix
+     */
+    listObjects(prefix: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult>;
+
+    /**
+     * Get the storage provider identifier.
+     *
+     * Built-in values are `'local'` and `'s3'`. Custom implementations
+     * should return their own identifier (e.g. `'gcs'`, `'azure'`).
+     */
+    getType(): string;
+}
+
+/**
+ * Default maximum file size (50MB)
+ */
+export const DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;
+
+/**
+ * Common image MIME types
+ */
+export const IMAGE_MIME_TYPES = [
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+    "image/bmp",
+    "image/tiff"
+];
+
+/**
+ * Common document MIME types
+ */
+export const DOCUMENT_MIME_TYPES = [
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "text/plain",
+    "text/csv"
+];

package/src/types/index.ts

@@ -0,0 +1,27 @@
+import {
+  Entity,
+  EntityCollection,
+  EntityStatus,
+  FilterValues,
+  FetchCollectionProps,
+  FetchEntityProps,
+  SaveEntityProps,
+  DeleteEntityProps,
+  WebSocketMessage,
+  CollectionUpdateMessage,
+  EntityUpdateMessage
+} from "@rebasepro/types";
+
+// Subscription types
+export interface ListenCollectionRequest<M extends Record<string, unknown> = Record<string, unknown>> extends FetchCollectionProps<M> {
+  subscriptionId: string;
+  onUpdate: (entities: Entity<M>[]) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface ListenEntityRequest<M extends Record<string, unknown> = Record<string, unknown>> extends FetchEntityProps<M> {
+  subscriptionId: string;
+  onUpdate: (entity: Entity<M> | null) => void;
+  onError?: (error: Error) => void;
+}
+