@rebasepro/server-core 0.2.3 → 0.2.4

package/src/storage/image-transform.ts

@@ -0,0 +1,202 @@
+/**
+ * Image Transformation Service
+ *
+ * Provides on-the-fly image resize, crop, format conversion, and quality
+ * adjustment using the `sharp` library. Results are cached in an LRU
+ * in-memory cache to avoid redundant processing.
+ */
+
+// Lazy-load sharp to avoid crashing when it isn't installed (e.g. in tests)
+let sharpFactory: ((input: Buffer | Uint8Array) => any) | undefined;
+
+async function getSharp(): Promise<(input: Buffer | Uint8Array) => any> {
+    if (!sharpFactory) {
+        try {
+            // @ts-ignore - sharp is an optional dependency
+            const mod = await import("sharp");
+            sharpFactory = mod.default;
+        } catch (err) {
+            throw new Error("Failed to load optional 'sharp' dependency for image transformation.");
+        }
+    }
+    if (!sharpFactory) {
+        throw new Error("Failed to load optional 'sharp' dependency for image transformation.");
+    }
+    return sharpFactory;
+}
+
+/** Options that can be specified via query parameters. */
+export interface ImageTransformOptions {
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+
+/** Maximum dimension allowed (prevents abuse). */
+const MAX_DIMENSION = 4096;
+/** Maximum quality value. */
+const MAX_QUALITY = 100;
+/** Minimum quality value. */
+const MIN_QUALITY = 1;
+
+const VALID_FORMATS = new Set(["webp", "avif", "jpeg", "png"]);
+const VALID_FITS = new Set(["cover", "contain", "fill", "inside", "outside"]);
+
+/**
+ * Parse transform options from URL query parameters.
+ * Returns `null` when no transformation is requested.
+ */
+export function parseTransformOptions(query: Record<string, string>): ImageTransformOptions | null {
+    const opts: ImageTransformOptions = {};
+    let hasTransform = false;
+
+    if (query.width) {
+        const w = parseInt(query.width, 10);
+        if (!Number.isNaN(w) && w > 0) {
+            opts.width = Math.min(w, MAX_DIMENSION);
+            hasTransform = true;
+        }
+    }
+
+    if (query.height) {
+        const h = parseInt(query.height, 10);
+        if (!Number.isNaN(h) && h > 0) {
+            opts.height = Math.min(h, MAX_DIMENSION);
+            hasTransform = true;
+        }
+    }
+
+    if (query.quality) {
+        const q = parseInt(query.quality, 10);
+        if (!Number.isNaN(q)) {
+            opts.quality = Math.min(Math.max(q, MIN_QUALITY), MAX_QUALITY);
+            hasTransform = true;
+        }
+    }
+
+    if (query.format && VALID_FORMATS.has(query.format)) {
+        opts.format = query.format as ImageTransformOptions["format"];
+        hasTransform = true;
+    }
+
+    if (query.fit && VALID_FITS.has(query.fit)) {
+        opts.fit = query.fit as ImageTransformOptions["fit"];
+        hasTransform = true;
+    }
+
+    return hasTransform ? opts : null;
+}
+
+/** MIME types that can be used as a Content-Type header. */
+const FORMAT_CONTENT_TYPES: Record<string, string> = {
+    webp: "image/webp",
+    avif: "image/avif",
+    jpeg: "image/jpeg",
+    png: "image/png",
+};
+
+/** Check whether a content type is a transformable image. */
+export function isTransformableImage(contentType: string): boolean {
+    return (
+        contentType.startsWith("image/") &&
+        !contentType.includes("svg") &&
+        !contentType.includes("gif")
+    );
+}
+
+/**
+ * Apply image transformations and return the result buffer + content type.
+ */
+export async function transformImage(
+    buffer: Buffer | Uint8Array,
+    options: ImageTransformOptions
+): Promise<{ data: Buffer; contentType: string }> {
+    const sharp = await getSharp();
+    let pipeline = sharp(buffer);
+
+    if (options.width || options.height) {
+        pipeline = pipeline.resize({
+            width: options.width,
+            height: options.height,
+            fit: options.fit || "cover",
+            withoutEnlargement: true,
+        });
+    }
+
+    const format = options.format || "webp";
+    const quality = options.quality || 80;
+
+    switch (format) {
+        case "webp":
+            pipeline = pipeline.webp({ quality });
+            break;
+        case "avif":
+            pipeline = pipeline.avif({ quality });
+            break;
+        case "jpeg":
+            pipeline = pipeline.jpeg({ quality });
+            break;
+        case "png":
+            pipeline = pipeline.png({ quality });
+            break;
+    }
+
+    const data = await pipeline.toBuffer();
+    return { data, contentType: FORMAT_CONTENT_TYPES[format] };
+}
+
+// ---------------------------------------------------------------------------
+// LRU Transform Cache
+// ---------------------------------------------------------------------------
+
+interface CacheEntry {
+    data: Buffer;
+    contentType: string;
+    timestamp: number;
+}
+
+/**
+ * Simple LRU cache for transformed images.
+ *
+ * Entries expire after `maxAgeMs` (default: 1 hour) and the cache
+ * evicts the oldest entry when `maxEntries` is exceeded.
+ */
+export class TransformCache {
+    private cache = new Map<string, CacheEntry>();
+    private readonly maxEntries: number;
+    private readonly maxAgeMs: number;
+
+    constructor(maxEntries = 500, maxAgeMs = 3_600_000) {
+        this.maxEntries = maxEntries;
+        this.maxAgeMs = maxAgeMs;
+    }
+
+    /** Build a deterministic cache key from file key + transform options. */
+    buildKey(fileKey: string, options: ImageTransformOptions): string {
+        return `${fileKey}::${JSON.stringify(options)}`;
+    }
+
+    get(cacheKey: string): { data: Buffer; contentType: string } | null {
+        const entry = this.cache.get(cacheKey);
+        if (!entry) return null;
+        if (Date.now() - entry.timestamp > this.maxAgeMs) {
+            this.cache.delete(cacheKey);
+            return null;
+        }
+        // Move to end (most recently used)
+        this.cache.delete(cacheKey);
+        this.cache.set(cacheKey, entry);
+        return { data: entry.data, contentType: entry.contentType };
+    }
+
+    set(cacheKey: string, data: Buffer, contentType: string): void {
+        // Evict oldest if at capacity
+        if (this.cache.size >= this.maxEntries) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined) this.cache.delete(oldest);
+        }
+        this.cache.set(cacheKey, { data, contentType, timestamp: Date.now() });
+    }
+}

package/src/storage/index.ts

@@ -16,6 +16,9 @@ export { S3StorageController } from "./S3StorageController";
 export { createStorageRoutes } from "./routes";
 export type { StorageRoutesConfig } from "./routes";
 export * from "./storage-registry";
+export { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform";
+export type { ImageTransformOptions } from "./image-transform";
+export { TusHandler } from "./tus-handler";
 
 import { BackendStorageConfig, StorageController } from "./types";
 import { LocalStorageController } from "./LocalStorageController";

package/src/storage/routes.ts

@@ -9,6 +9,11 @@ import { LocalStorageController } from "./LocalStorageController";
 import { requireAuth as jwtRequireAuth, optionalAuth } from "../auth/middleware";
 import { ApiError, errorHandler } from "../api/errors";
 import { HonoEnv } from "../api/types";
+import { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform";
+import { TusHandler } from "./tus-handler";
+
+/** Shared image transform cache (LRU, 500 entries, 1 hour TTL). */
+const transformCache = new TransformCache();
 
 export interface StorageRoutesConfig {
     controller: StorageController;
@@ -129,6 +134,9 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
 
         const filePath = decodeURIComponent(rawPath);
 
+        // Parse image transform query params (e.g. ?width=300&format=webp)
+        const transformOpts = parseTransformOptions(c.req.query() as Record<string, string>);
+
         // For local storage, serve the file directly from disk
         if (controller.getType() === "local") {
             const localController = controller as LocalStorageController;
@@ -153,9 +161,22 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
                 }
             }
 
-            c.header("Content-Type", contentType);
-            // In a better scenario, we should pipe the stream instead of reading whole file
             const fileContent = fs.readFileSync(absolutePath);
+
+            // Apply image transforms if requested and the file is a transformable image
+            if (transformOpts && isTransformableImage(contentType)) {
+                const cacheKey = transformCache.buildKey(filePath, transformOpts);
+                let cached = transformCache.get(cacheKey);
+                if (!cached) {
+                    cached = await transformImage(Buffer.from(fileContent), transformOpts);
+                    transformCache.set(cacheKey, cached.data, cached.contentType);
+                }
+                c.header("Content-Type", cached.contentType);
+                c.header("Cache-Control", "public, max-age=31536000, immutable");
+                return c.body(new Uint8Array(cached.data));
+            }
+
+            c.header("Content-Type", contentType);
             return c.body(new Uint8Array(fileContent));
         }
 
@@ -169,7 +190,23 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
             throw ApiError.notFound("File not found");
         }
 
-        c.header("Content-Type", fileObject.type || "application/octet-stream");
+        const remoteContentType = fileObject.type || "application/octet-stream";
+
+        // Apply image transforms for remote storage too
+        if (transformOpts && isTransformableImage(remoteContentType)) {
+            const cacheKey = transformCache.buildKey(filePath, transformOpts);
+            let cached = transformCache.get(cacheKey);
+            if (!cached) {
+                const buf = Buffer.from(await fileObject.arrayBuffer());
+                cached = await transformImage(buf, transformOpts);
+                transformCache.set(cacheKey, cached.data, cached.contentType);
+            }
+            c.header("Content-Type", cached.contentType);
+            c.header("Cache-Control", "public, max-age=31536000, immutable");
+            return c.body(new Uint8Array(cached.data));
+        }
+
+        c.header("Content-Type", remoteContentType);
         c.header("Cache-Control", "public, max-age=3600, immutable");
         const buf = await fileObject.arrayBuffer();
         return c.body(new Uint8Array(buf));
@@ -288,5 +325,21 @@ message: "No file to delete" });
         }, 201);
     });
 
+    // -----------------------------------------------------------------------
+    // TUS Resumable Uploads
+    // -----------------------------------------------------------------------
+
+    const tusBaseDir = controller.getType() === "local"
+        ? (controller as LocalStorageController).getBasePath()
+        : (process.env.STORAGE_PATH || "./uploads");
+    const tusHandler = new TusHandler(tusBaseDir, controller);
+    tusHandler.startCleanup();
+
+    router.options("/tus", (_c) => tusHandler.options());
+    router.post("/tus", writeAuthMiddleware, async (c) => tusHandler.create(c));
+    router.get("/tus/:id", readAuthMiddleware, (c) => tusHandler.head(c, c.req.param("id")));
+    router.patch("/tus/:id", writeAuthMiddleware, async (c) => tusHandler.patch(c, c.req.param("id")));
+    router.delete("/tus/:id", writeAuthMiddleware, async (c) => tusHandler.delete(c, c.req.param("id")));
+
     return router;
 }

package/src/storage/tus-handler.ts

@@ -0,0 +1,315 @@
+/**
+ * TUS Protocol Handler
+ *
+ * Implements the TUS v1.0.0 resumable upload protocol with the
+ * Creation and Termination extensions. Uploads are stored in a
+ * temporary directory and moved to final storage on completion.
+ *
+ * @see https://tus.io/protocols/resumable-upload
+ */
+
+import { randomUUID } from "crypto";
+import { writeFile, unlink, stat, mkdir, open } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import type { Context } from "hono";
+import type { StorageController } from "./types";
+import { logger } from "../utils/logger.js";
+
+/** Metadata for an in-progress resumable upload. */
+interface TusUpload {
+    id: string;
+    /** Total declared size in bytes. */
+    size: number;
+    /** Bytes received so far. */
+    offset: number;
+    /** TUS metadata parsed from the creation request. */
+    metadata: Record<string, string>;
+    /** Timestamp of creation (epoch ms). */
+    createdAt: number;
+    /** Absolute path to the temp file on disk. */
+    filePath: string;
+    /** Target bucket (from metadata). */
+    bucket?: string;
+    /** Target key / filename (from metadata). */
+    key?: string;
+    /** Whether the upload has been fully received and finalized. */
+    completed: boolean;
+}
+
+/** Maximum upload size: 5 GB. */
+const MAX_UPLOAD_SIZE = 5 * 1024 * 1024 * 1024;
+
+/** Stale upload expiry: 24 hours. */
+const UPLOAD_EXPIRY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * TUS resumable upload handler.
+ *
+ * Each instance manages uploads for a single storage root. The
+ * `storageController` is used to finalize completed uploads by
+ * calling `putObject`.
+ */
+export class TusHandler {
+    private uploads = new Map<string, TusUpload>();
+    private tusDir: string;
+    private cleanupTimer?: ReturnType<typeof setInterval>;
+
+    constructor(
+        storageBaseDir: string,
+        private storageController?: StorageController,
+    ) {
+        this.tusDir = join(storageBaseDir, ".tus-uploads");
+    }
+
+    /** Ensure the temp directory exists. */
+    private async ensureDir(): Promise<void> {
+        if (!existsSync(this.tusDir)) {
+            await mkdir(this.tusDir, { recursive: true });
+        }
+    }
+
+    /** Start periodic cleanup of stale uploads. */
+    startCleanup(): void {
+        if (this.cleanupTimer) return;
+        this.cleanupTimer = setInterval(() => {
+            void this.cleanupStale();
+        }, 60_000); // every minute
+    }
+
+    /** Remove uploads that have been idle for longer than UPLOAD_EXPIRY_MS. */
+    private async cleanupStale(): Promise<void> {
+        const now = Date.now();
+        for (const [id, upload] of this.uploads) {
+            if (now - upload.createdAt > UPLOAD_EXPIRY_MS && !upload.completed) {
+                try { await unlink(upload.filePath); } catch { /* ok */ }
+                this.uploads.delete(id);
+            }
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // TUS Metadata Parsing
+    // -----------------------------------------------------------------------
+
+    /**
+     * Parse the `Upload-Metadata` header.
+     *
+     * Format: `key base64value,key2 base64value2`
+     */
+    private parseMetadata(header: string): Record<string, string> {
+        const metadata: Record<string, string> = {};
+        if (!header) return metadata;
+        for (const pair of header.split(",")) {
+            const trimmed = pair.trim();
+            const spaceIdx = trimmed.indexOf(" ");
+            if (spaceIdx === -1) {
+                metadata[trimmed] = "";
+            } else {
+                const key = trimmed.substring(0, spaceIdx);
+                const value = Buffer.from(trimmed.substring(spaceIdx + 1), "base64").toString("utf-8");
+                metadata[key] = value;
+            }
+        }
+        return metadata;
+    }
+
+    // -----------------------------------------------------------------------
+    // Protocol Endpoints
+    // -----------------------------------------------------------------------
+
+    /** `OPTIONS /tus` — TUS capability discovery. */
+    options(): Response {
+        return new Response(null, {
+            status: 204,
+            headers: {
+                "Tus-Resumable": "1.0.0",
+                "Tus-Version": "1.0.0",
+                "Tus-Extension": "creation,termination",
+                "Tus-Max-Size": String(MAX_UPLOAD_SIZE),
+            },
+        });
+    }
+
+    /** `POST /tus` — Create a new upload. */
+    async create(c: Context): Promise<Response> {
+        await this.ensureDir();
+
+        const uploadLengthHeader = c.req.header("Upload-Length");
+        if (!uploadLengthHeader) {
+            return c.json({ error: "Upload-Length header is required" }, 400);
+        }
+
+        const uploadLength = parseInt(uploadLengthHeader, 10);
+        if (Number.isNaN(uploadLength) || uploadLength <= 0) {
+            return c.json({ error: "Invalid Upload-Length" }, 400);
+        }
+        if (uploadLength > MAX_UPLOAD_SIZE) {
+            return c.json({ error: `Upload-Length exceeds maximum of ${MAX_UPLOAD_SIZE} bytes` }, 413);
+        }
+
+        const metadata = this.parseMetadata(c.req.header("Upload-Metadata") || "");
+        const id = randomUUID();
+        const filePath = join(this.tusDir, id);
+
+        // Create empty temp file
+        await writeFile(filePath, Buffer.alloc(0));
+
+        const upload: TusUpload = {
+            id,
+            size: uploadLength,
+            offset: 0,
+            metadata,
+            createdAt: Date.now(),
+            filePath,
+            bucket: metadata.bucket || undefined,
+            key: metadata.key || metadata.filename || undefined,
+            completed: false,
+        };
+        this.uploads.set(id, upload);
+
+        // Build absolute Location
+        const reqUrl = new URL(c.req.url);
+        const location = `${reqUrl.origin}${reqUrl.pathname}/${id}`;
+
+        return new Response(null, {
+            status: 201,
+            headers: {
+                Location: location,
+                "Tus-Resumable": "1.0.0",
+                "Upload-Offset": "0",
+            },
+        });
+    }
+
+    /** `HEAD /tus/:id` — Query upload progress. */
+    head(c: Context, id: string): Response {
+        const upload = this.uploads.get(id);
+        if (!upload) {
+            return c.json({ error: "Upload not found" }, 404);
+        }
+
+        return new Response(null, {
+            status: 200,
+            headers: {
+                "Tus-Resumable": "1.0.0",
+                "Upload-Offset": String(upload.offset),
+                "Upload-Length": String(upload.size),
+                "Cache-Control": "no-store",
+            },
+        });
+    }
+
+    /** `PATCH /tus/:id` — Append data to an upload. */
+    async patch(c: Context, id: string): Promise<Response> {
+        const upload = this.uploads.get(id);
+        if (!upload) {
+            return c.json({ error: "Upload not found" }, 404);
+        }
+        if (upload.completed) {
+            return c.json({ error: "Upload already completed" }, 400);
+        }
+
+        // Validate offset
+        const offsetHeader = c.req.header("Upload-Offset");
+        if (!offsetHeader) {
+            return c.json({ error: "Upload-Offset header is required" }, 400);
+        }
+        const offset = parseInt(offsetHeader, 10);
+        if (offset !== upload.offset) {
+            return c.json({ error: "Offset mismatch" }, 409);
+        }
+
+        // Validate content type
+        const contentType = c.req.header("Content-Type");
+        if (contentType !== "application/offset+octet-stream") {
+            return c.json({ error: "Content-Type must be application/offset+octet-stream" }, 415);
+        }
+
+        // Read chunk and append to temp file
+        const body = await c.req.arrayBuffer();
+        const chunk = Buffer.from(body);
+
+        // Prevent overrun
+        if (upload.offset + chunk.length > upload.size) {
+            return c.json({ error: "Chunk exceeds declared Upload-Length" }, 413);
+        }
+
+        const fh = await open(upload.filePath, "a");
+        try {
+            await fh.write(chunk);
+        } finally {
+            await fh.close();
+        }
+        upload.offset += chunk.length;
+
+        // Finalize if complete
+        if (upload.offset >= upload.size) {
+            await this.finalize(upload);
+        }
+
+        return new Response(null, {
+            status: 204,
+            headers: {
+                "Tus-Resumable": "1.0.0",
+                "Upload-Offset": String(upload.offset),
+            },
+        });
+    }
+
+    /** `DELETE /tus/:id` — Cancel and remove an upload. */
+    async delete(c: Context, id: string): Promise<Response> {
+        const upload = this.uploads.get(id);
+        if (!upload) {
+            return c.json({ error: "Upload not found" }, 404);
+        }
+
+        try { await unlink(upload.filePath); } catch { /* ok */ }
+        this.uploads.delete(id);
+
+        return new Response(null, {
+            status: 204,
+            headers: { "Tus-Resumable": "1.0.0" },
+        });
+    }
+
+    // -----------------------------------------------------------------------
+    // Finalization
+    // -----------------------------------------------------------------------
+
+    /**
+     * Move a completed upload into the storage controller.
+     */
+    private async finalize(upload: TusUpload): Promise<void> {
+        upload.completed = true;
+
+        if (!this.storageController) {
+            // No controller — leave temp file in place
+            logger.warn("[TUS] Upload completed but no StorageController configured. Temp file remains:", { filePath: upload.filePath });
+            return;
+        }
+
+        try {
+            const { readFile } = await import("fs/promises");
+            const data = await readFile(upload.filePath);
+            const fileName = upload.key || upload.metadata.filename || upload.id;
+            const mimeType = upload.metadata.contentType || upload.metadata.filetype || "application/octet-stream";
+
+            const file = new File([data], fileName, { type: mimeType });
+
+            await this.storageController.putObject({
+                file,
+                key: fileName,
+                bucket: upload.bucket,
+            });
+
+            // Clean up temp file
+            try { await unlink(upload.filePath); } catch { /* ok */ }
+            this.uploads.delete(upload.id);
+
+            logger.info(`[TUS] Upload ${upload.id} finalized → ${fileName}`);
+        } catch (err) {
+            logger.error(`[TUS] Failed to finalize upload ${upload.id}`, { error: err });
+        }
+    }
+}

package/src/utils/dev-port.ts

@@ -43,6 +43,20 @@ export function listenWithPortRetry(
     const maxAttempts = options?.maxAttempts ?? MAX_PORT_ATTEMPTS;
     const portFileDir = options?.portFileDir;
 
+    const isProd = process.env.NODE_ENV === "production";
+    if (isProd) {
+        return new Promise<number>((resolve, reject) => {
+            const onError = (err: Error) => {
+                reject(err);
+            };
+            server.once("error", onError);
+            server.listen(startPort, host, () => {
+                server.removeListener("error", onError);
+                resolve(startPort);
+            });
+        });
+    }
+
     // Read affinity port from a previous run's port file.
     // This ensures tsx watch restarts land on the same port the frontend was
     // configured with, even if the CLI-computed port was different.

package/src/utils/logging.ts

@@ -16,13 +16,16 @@ debug: 3 };
     if (currentLevel < 0) console.error = () => { };
 }
 
+/** Module-scoped backup of the original console methods. */
+let originalConsole: Pick<Console, "log" | "warn" | "error" | "debug"> | undefined;
+
 /**
  * Reset console methods to their original state
  */
 export function resetConsole() {
     // Store original methods if not already stored
-    if (!(global as Record<string, unknown>).__originalConsole) {
-        (global as Record<string, unknown>).__originalConsole = {
+    if (!originalConsole) {
+        originalConsole = {
             log: console.log,
             warn: console.warn,
             error: console.error,
@@ -30,9 +33,8 @@ export function resetConsole() {
         };
     }
 
-    const original = (global as Record<string, unknown>).__originalConsole as Console;
-    console.log = original.log;
-    console.warn = original.warn;
-    console.error = original.error;
-    console.debug = original.debug;
+    console.log = originalConsole.log;
+    console.warn = originalConsole.warn;
+    console.error = originalConsole.error;
+    console.debug = originalConsole.debug;
 }