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

package/src/storage/index.ts

@@ -1,32 +1,43 @@
 /**
  * Storage module for Rebase backend
  *
- * Provides file storage functionality with support for:
- * - Local filesystem storage (default, zero config)
- * - S3-compatible storage (AWS S3, MinIO)
+ * Provides pluggable file storage with two built-in providers:
+ * - **Local filesystem** — zero config, great for dev and single-server deployments.
+ * - **S3-compatible** — works with AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
+ *   Backblaze B2, DigitalOcean Spaces, and GCS (via S3 interop).
+ *
+ * For other providers (native GCS SDK, Azure Blob, etc.), implement the
+ * `StorageController` interface and pass the instance directly to the `storage` config.
  */
 
-export * from './types';
-export { LocalStorageController } from './LocalStorageController';
-export { S3StorageController } from './S3StorageController';
-export { createStorageRoutes } from './routes';
-export type { StorageRoutesConfig } from './routes';
-export * from './storage-registry';
+export * from "./types";
+export { LocalStorageController } from "./LocalStorageController";
+export { S3StorageController } from "./S3StorageController";
+export { createStorageRoutes } from "./routes";
+export type { StorageRoutesConfig } from "./routes";
+export * from "./storage-registry";
 
-import { BackendStorageConfig, StorageController } from './types';
-import { LocalStorageController } from './LocalStorageController';
-import { S3StorageController } from './S3StorageController';
+import { BackendStorageConfig, StorageController } from "./types";
+import { LocalStorageController } from "./LocalStorageController";
+import { S3StorageController } from "./S3StorageController";
 
 /**
- * Factory function to create a storage controller based on configuration
+ * Create a storage controller from a config object.
+ *
+ * For custom providers, implement `StorageController` directly instead
+ * of going through this factory.
  */
 export function createStorageController(config: BackendStorageConfig): StorageController {
     switch (config.type) {
-        case 'local':
+        case "local":
             return new LocalStorageController(config);
-        case 's3':
+        case "s3":
             return new S3StorageController(config);
         default:
-            throw new Error(`Unknown storage type: ${(config as Record<string, unknown>).type}`);
+            throw new Error(
+                `Unknown storage type: ${(config as Record<string, unknown>).type}. ` +
+                "Built-in types: local, s3. " +
+                "For other providers, implement the StorageController interface directly."
+            );
     }
 }

package/src/storage/routes.ts

@@ -2,13 +2,13 @@
  * 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 } from '../api/errors';
-import { HonoEnv } from '../api/types';
+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;
@@ -34,11 +34,11 @@ export interface StorageRoutesConfig {
  * 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 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 '';
+    if (idx < 0) return "";
     // +1 to skip the '/' after the prefix
     return fullPath.substring(idx + prefix.length + 1);
 }
@@ -48,6 +48,7 @@ export function extractWildcardPath(c: { req: { path: string; routePath: string
  */
 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
@@ -60,19 +61,19 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
      * Parse bucket and path from a combined file path.
      */
     const parseBucketAndPath = (filePath: string): { bucket: string; resolvedPath: string } => {
-        const parts = filePath.split('/');
+        const parts = filePath.split("/");
 
         // Only recognize 'default' as an explicit bucket prefix
-        if (parts.length > 1 && parts[0].toLowerCase() === 'default') {
+        if (parts.length > 1 && parts[0].toLowerCase() === "default") {
             return {
-                bucket: 'default',
-                resolvedPath: parts.slice(1).join('/')
+                bucket: "default",
+                resolvedPath: parts.slice(1).join("/")
             };
         }
 
         // All other paths use 'default' bucket with the full path
         return {
-            bucket: 'default',
+            bucket: "default",
             resolvedPath: filePath
         };
     };
@@ -82,34 +83,48 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
      * Body: multipart/form-data with 'file' field
      * Request body can also contain metadata keys 'metadata_*'
      */
-    router.post('/upload', writeAuthMiddleware, async (c) => {
+    router.post("/upload", writeAuthMiddleware, async (c) => {
         const body = await c.req.parseBody();
-        const uploadedFile = body['file'];
+        const uploadedFile = body["file"];
 
-        if (!uploadedFile || typeof uploadedFile === 'string') {
-            throw ApiError.badRequest('No file provided');
+        if (!uploadedFile || typeof uploadedFile === "string") {
+            throw ApiError.badRequest("No file provided");
         }
 
-        const storagePath = typeof body['path'] === 'string' ? body['path'] : '';
-        const bucket = typeof body['bucket'] === 'string' ? body['bucket'] : undefined;
-        let fileName = typeof body['fileName'] === 'string' ? body['fileName'] : undefined;
-        
-        if (!fileName) {
-            fileName = uploadedFile.name;
+        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 [key, value] of Object.entries(body)) {
-            if (key.startsWith('metadata_')) {
-                metadata[key.replace('metadata_', '')] = value;
+        for (const [k, value] of Object.entries(body)) {
+            if (k.startsWith("metadata_")) {
+                metadata[k.replace("metadata_", "")] = value;
             }
         }
 
-        const result = await controller.uploadFile({
+        const result = await controller.putObject({
             file: uploadedFile,
-            fileName: fileName || 'unnamed',
-            path: storagePath,
+            key: finalKey,
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
             bucket
         });
@@ -124,16 +139,16 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
      * GET /file/* - Download/serve a file
      * Path: /file/{bucket}/{path} or /file/{path}
      */
-    router.get('/file/*', readAuthMiddleware, async (c) => {
+    router.get("/file/*", readAuthMiddleware, async (c) => {
         const rawPath = extractWildcardPath(c);
         if (!rawPath) {
-            throw ApiError.notFound('File not found');
+            throw ApiError.notFound("File not found");
         }
 
         const filePath = decodeURIComponent(rawPath);
 
-        // For local storage, serve the file directly
-        if (controller.getType() === 'local') {
+        // For local storage, serve the file directly from disk
+        if (controller.getType() === "local") {
             const localController = controller as LocalStorageController;
             const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
@@ -141,31 +156,31 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
 
             // Check if file exists
             if (!fs.existsSync(absolutePath)) {
-                throw ApiError.notFound('File not found');
+                throw ApiError.notFound("File not found");
             }
 
             // Get content type from metadata or infer from extension
-            let contentType = 'application/octet-stream';
+            let contentType = "application/octet-stream";
             const metadataPath = `${absolutePath}.metadata.json`;
             if (fs.existsSync(metadataPath)) {
                 try {
-                    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+                    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
                     contentType = metadata.contentType || contentType;
                 } catch {
                     // Ignore metadata errors
                 }
             }
 
-            c.header('Content-Type', contentType);
+            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)); 
+            return c.body(new Uint8Array(fileContent));
         }
 
-        // For S3 storage, redirect to signed URL
-        const downloadConfig = await controller.getDownloadURL(filePath);
+        // 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');
+            throw ApiError.notFound("File not found");
         }
 
         return c.redirect(downloadConfig.url);
@@ -174,7 +189,7 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
     /**
      * GET /metadata/* - Get file metadata
      */
-    router.get('/metadata/*', readAuthMiddleware, async (c) => {
+    router.get("/metadata/*", readAuthMiddleware, async (c) => {
         const rawPath = extractWildcardPath(c);
         if (!rawPath) {
             return c.json({
@@ -187,10 +202,10 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
         const filePath = decodeURIComponent(rawPath);
         const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
-        const downloadConfig = await controller.getDownloadURL(resolvedPath, bucket);
+        const downloadConfig = await controller.getSignedUrl(resolvedPath, bucket);
 
         if (downloadConfig.fileNotFound) {
-            throw ApiError.notFound('File not found');
+            throw ApiError.notFound("File not found");
         }
 
         return c.json({
@@ -202,34 +217,36 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
     /**
      * DELETE /file/* - Delete a file
      */
-    router.delete('/file/*', writeAuthMiddleware, async (c) => {
+    router.delete("/file/*", writeAuthMiddleware, async (c) => {
         const rawPath = extractWildcardPath(c);
         if (!rawPath) {
-            return c.json({ success: true, message: 'No file to delete' });
+            return c.json({ success: true,
+message: "No file to delete" });
         }
 
         const filePath = decodeURIComponent(rawPath);
         const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
-        await controller.deleteFile(resolvedPath, bucket);
+        await controller.deleteObject(resolvedPath, bucket);
 
         return c.json({
             success: true,
-            message: 'File deleted'
+            message: "File deleted"
         });
     });
 
     /**
      * GET /list - List files in a path
      */
-    router.get('/list', writeAuthMiddleware, async (c) => {
-        const storagePath = 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.list(
-            storagePath,
+    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,

package/src/storage/storage-registry.ts

@@ -121,7 +121,7 @@ export class DefaultStorageRegistry implements StorageRegistry {
         const controller = this.controllers.get(DEFAULT_STORAGE_ID);
         if (!controller) {
             throw new Error(
-                `[StorageRegistry] No default storage registered. ` +
+                "[StorageRegistry] No default storage registered. " +
                 `Register one with id "${DEFAULT_STORAGE_ID}" or pass a single StorageController.`
             );
         }
@@ -178,10 +178,10 @@ function isStorageController(obj: unknown): obj is StorageController {
     const controller = obj as StorageController;
     // Check for required StorageController properties
     return (
-        typeof controller.uploadFile === "function" &&
-        typeof controller.getDownloadURL === "function" &&
-        typeof controller.deleteFile === "function" &&
-        typeof controller.list === "function" &&
+        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

@@ -8,7 +8,7 @@ import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, Stora
  * Local filesystem storage configuration
  */
 export interface LocalStorageConfig {
-    type: 'local';
+    type: "local";
     /** Base directory for file storage (e.g., './uploads') */
     basePath: string;
     /** Maximum file size in bytes (default: 50MB) */
@@ -23,12 +23,12 @@ export interface LocalStorageConfig {
  * S3-compatible storage configuration (works with AWS S3 and MinIO)
  */
 export interface S3StorageConfig {
-    type: 's3';
+    type: "s3";
     /** S3 bucket name */
     bucket: string;
     /** AWS region (e.g., 'us-east-1') */
     region?: string;
-    /** Custom endpoint URL (required for MinIO) */
+    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */
     endpoint?: string;
     /** AWS access key ID */
     accessKeyId: string;
@@ -45,7 +45,16 @@ export interface S3StorageConfig {
 }
 
 /**
- * Storage configuration - either local filesystem or S3-compatible
+ * 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;
 
@@ -54,38 +63,41 @@ export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
  */
 export interface StorageController {
     /**
-     * Upload a file
+     * Upload an object
      */
-    uploadFile(props: UploadFileProps): Promise<UploadFileResult>;
+    putObject(props: UploadFileProps): Promise<UploadFileResult>;
 
     /**
-     * Get a download URL for a file
+     * Get a download URL (signed URL equivalent) for an object
      */
-    getDownloadURL(path: string, bucket?: string): Promise<DownloadConfig>;
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
 
     /**
-     * Get file as a File object
+     * Get object as a File
      */
-    getFile(path: string, bucket?: string): Promise<File | null>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
 
     /**
-     * Delete a file
+     * Delete an object
      */
-    deleteFile(path: string, bucket?: string): Promise<void>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
 
     /**
-     * List files in a path
+     * List objects in a prefix
      */
-    list(path: string, options?: {
+    listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
 
     /**
-     * Get the storage configuration type
+     * Get the storage provider identifier.
+     *
+     * Built-in values are `'local'` and `'s3'`. Custom implementations
+     * should return their own identifier (e.g. `'gcs'`, `'azure'`).
      */
-    getType(): 'local' | 's3';
+    getType(): string;
 }
 
 /**
@@ -97,26 +109,26 @@ 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'
+    "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'
+    "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

@@ -1,7 +1,7 @@
-import { 
-  Entity, 
-  EntityCollection, 
-  EntityStatus, 
+import {
+  Entity,
+  EntityCollection,
+  EntityStatus,
   FilterValues,
   FetchCollectionProps,
   FetchEntityProps,