@brightsideoy/kama 0.1.0-alpha.99 → 1.0.0-alpha.11

package/templates/astro-starter/src/lib/media/media-proxy.ts

@@ -0,0 +1,148 @@
+// src/lib/media/media-proxy.ts
+
+import type { APIContext } from "astro";
+
+export function getMimeType(filePath: string): string {
+    const ext = filePath.split(".").pop()?.toLowerCase();
+    switch (ext) {
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "png": return "image/png";
+        case "webp": return "image/webp";
+        case "avif": return "image/avif";
+        case "svg": return "image/svg+xml";
+        case "gif": return "image/gif";
+        case "pdf": return "application/pdf";
+        case "mp4": return "video/mp4";
+        case "webm": return "video/webm";
+        default: return "application/octet-stream";
+    }
+}
+
+export async function handleMediaProxy({ request, params, url, locals }: APIContext): Promise<Response> {
+    // 🎯 Safely extract Cloudflare context from Astro locals dual-environment
+    const runtime = locals.runtime || (locals as any).cfContext;
+    const workerEnv = runtime?.env || {};
+    const cfContext = runtime?.ctx || {};
+
+    // 🎯 Detect if Astro is requesting a resized variant
+    const hasResizeParams = url.searchParams.has('w') || url.searchParams.has('h') || url.searchParams.has('q') || url.searchParams.has('f');
+
+    // 🎯 Resolve Negotiated Format for Edge Cache Key
+    const acceptHeader = request.headers.get('Accept') || '';
+    const fParam = url.searchParams.get('f');
+    let resolvedFormat = fParam && fParam !== 'auto' ? fParam : '';
+
+    if (!resolvedFormat && hasResizeParams) {
+        if (acceptHeader.includes('image/avif')) resolvedFormat = 'avif';
+        else if (acceptHeader.includes('image/webp')) resolvedFormat = 'webp';
+    }
+
+    // 🎯 Construct a safe Cache Key that accounts for format negotiation
+    let cacheKeyUrl = request.url;
+    if (hasResizeParams && resolvedFormat && !fParam) {
+        const cacheUrlObj = new URL(cacheKeyUrl);
+        cacheUrlObj.searchParams.set('_resolvedFormat', resolvedFormat);
+        cacheKeyUrl = cacheUrlObj.toString();
+    }
+    const cacheKey = new Request(cacheKeyUrl, request);
+
+    // 1. Cloudflare Edge Cache API
+    let edgeCache: Cache | null = null;
+    try {
+        if (typeof caches !== "undefined" && caches.default) {
+            edgeCache = caches.default;
+            const cachedResponse = await edgeCache.match(cacheKey);
+            if (cachedResponse) return cachedResponse;
+        }
+    } catch (err) {
+        console.warn("[Media Proxy] Edge cache match failed:", err);
+    }
+
+    const rawPath = params.path || "";
+    const cleanPath = rawPath.replace(/^\/+|\/+$/g, "");
+
+    // 2. Direct R2 Lookup (ONLY IF NO RESIZING PARAMS ARE PRESENT AND WE ARE IN PROD)
+    const mediaBucket = workerEnv.MEDIA_BUCKET;
+    if (mediaBucket && cleanPath && !hasResizeParams) {
+        try {
+            let r2Object = await mediaBucket.get(cleanPath);
+            if (!r2Object) r2Object = await mediaBucket.get(cleanPath.startsWith("media/") ? cleanPath.replace(/^media\//, "") : `media/${cleanPath}`);
+
+            if (r2Object) {
+                if (request.headers.get("if-none-match") === r2Object.httpEtag) {
+                    return new Response(null, { status: 304 });
+                }
+
+                const headers = new Headers();
+                r2Object.writeHttpMetadata(headers);
+                headers.set("etag", r2Object.httpEtag);
+                headers.set("Cache-Control", "public, max-age=31536000, immutable");
+                headers.set("Access-Control-Allow-Origin", "*");
+                if (!headers.get("content-type") || headers.get("content-type") === "application/octet-stream") {
+                    headers.set("content-type", getMimeType(cleanPath));
+                }
+
+                const r2Response = new Response(r2Object.body, { status: 200, headers });
+
+                if (edgeCache) {
+                    const cachePromise = edgeCache.put(cacheKey, r2Response.clone());
+                    if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                    else cachePromise.catch(e => console.warn(e));
+                }
+
+                return r2Response;
+            }
+        } catch (r2Err) {
+            console.warn("[Media Proxy] R2 lookup error:", r2Err);
+        }
+    }
+
+    // 3. Forward to Backend (Handles Local Sharp Resizing AND Cloudflare Images Resizing)
+    try {
+        let backendResponse: Response;
+
+        // A. Production Mode (Cloudflare Service Binding)
+        if (workerEnv.CMS_WORKER) {
+            backendResponse = await workerEnv.CMS_WORKER.fetch(request);
+        }
+        // B. Local Dev Mode (Standard HTTP Fetch to local Hono Server)
+        else {
+            const cmsUrl = import.meta.env.PUBLIC_CMS_URL || 'http://localhost:8787';
+            const targetUrl = `${cmsUrl}${url.pathname}${url.search}`;
+
+            // Forward request headers (like Accept for WebP/AVIF negotiation)
+            backendResponse = await fetch(targetUrl, {
+                headers: {
+                    'Accept': request.headers.get('Accept') || 'image/webp,image/avif,image/*,*/*;q=0.8'
+                }
+            });
+        }
+
+        if (backendResponse.ok) {
+            const newHeaders = new Headers(backendResponse.headers);
+            newHeaders.set("Cache-Control", "public, max-age=31536000, immutable");
+            newHeaders.set("Access-Control-Allow-Origin", "*");
+
+            const proxyResponse = new Response(backendResponse.body, {
+                status: backendResponse.status,
+                statusText: backendResponse.statusText,
+                headers: newHeaders,
+            });
+
+            if (edgeCache) {
+                const cachePromise = edgeCache.put(cacheKey, proxyResponse.clone());
+                if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                else cachePromise.catch(e => console.warn(e));
+            }
+
+            return proxyResponse;
+        }
+
+        return backendResponse;
+    } catch (error) {
+        console.error("❌ Media Proxy Forwarding Error:", error);
+    }
+
+    return new Response("Not found", { status: 404 });
+}

package/templates/astro-starter/src/lib/media/media-url.ts

@@ -0,0 +1,112 @@
+// src/lib/media/media-url.ts
+
+/**
+ * Normalizes absolute CMS URLs into clean relative /media/... paths.
+ * Ensures CSP compliance by routing requests through the Astro frontend proxy.
+ */
+export function toRelativeMediaPath(rawUrl: string): string {
+    if (!rawUrl) return "";
+
+    let clean = String(rawUrl).trim();
+
+    try {
+        // Parse absolute or relative URLs safely using a dummy origin fallback
+        const urlObj = new URL(clean, "http://localhost");
+        clean = urlObj.pathname;
+    } catch {
+        // Fallback cleanup for malformed strings
+        clean = clean.replace(/^https?:\/\/[^/]+/, "").split("?")[0].split("#")[0];
+    }
+
+    const mediaIndex = clean.indexOf("/media/");
+    if (mediaIndex !== -1) {
+        return `/media/${clean
+            .slice(mediaIndex + "/media/".length)
+            .replace(/^\/+/, "")}`;
+    }
+
+    return clean.startsWith("/") ? clean : `/${clean}`;
+}
+
+/**
+ * Checks whether a given path or MIME type represents a vector SVG image.
+ */
+export function isSvgImage(urlOrMime: string): boolean {
+    if (!urlOrMime) return false;
+    const lower = urlOrMime.toLowerCase();
+    return lower.endsWith('.svg') || lower.includes('image/svg+xml') || lower.includes('.svg?');
+}
+
+/**
+ * Constructs an agnostic /media/... URL with standard optimization query parameters.
+ */
+export function buildAgnosticImageUrl(
+    url: string,
+    width: number,
+    quality = 75,
+): string {
+    const cleanPath = toRelativeMediaPath(url);
+    if (!cleanPath) return "";
+
+    // 🎯 Vector Guard: Return pristine path for SVGs without width/quality query parameters
+    if (isSvgImage(cleanPath)) {
+        return cleanPath;
+    }
+
+    const urlObj = new URL(cleanPath, "http://localhost");
+    urlObj.searchParams.set("w", String(width));
+    urlObj.searchParams.set("q", String(quality));
+    urlObj.searchParams.set("f", "auto");
+
+    return urlObj.pathname + urlObj.search;
+}
+
+export interface GetImageUriOptions {
+    width?: number;
+    quality?: number;
+    fallback?: string;
+    absoluteOrigin?: string; // e.g. siteOrigin for OG/Twitter tags or JSON-LD
+}
+
+/**
+ * Universal CMS Image Helper
+ * Safely resolves strings, asset objects, and array-wrapped media into relative or absolute CSP-compliant URLs.
+ */
+export function getImageUri(
+    imgObj: any,
+    options: GetImageUriOptions = {}
+): string | null {
+    const { width, quality = 75, fallback = null, absoluteOrigin } = options;
+
+    if (!imgObj) return fallback;
+
+    // 1. Unpack arrays (e.g. favicon: [{ url: '/media/...' }])
+    const target = Array.isArray(imgObj) ? imgObj[0] : imgObj;
+    if (!target) return fallback;
+
+    // 2. Detect mimeType if present on asset object
+    const isSvgAsset = isSvgImage(target?.mimeType || "") || isSvgImage(target?.filename || "");
+
+    // 3. Extract raw URL path across standard CMS field variations
+    const rawPath =
+        typeof target === "string"
+            ? target
+            : target?.variants?.standard?.url || target?.url || target?.path || null;
+
+    if (!rawPath) return fallback;
+
+    // 4. Process URL through buildAgnosticImageUrl (SVGs bypass raster params automatically)
+    let finalPath = (width && !isSvgAsset && !isSvgImage(rawPath))
+        ? buildAgnosticImageUrl(rawPath, width, quality)
+        : toRelativeMediaPath(rawPath);
+
+    if (!finalPath) return fallback;
+
+    // 5. Prepend absolute origin if requested (for Open Graph, Twitter cards, or JSON-LD)
+    if (absoluteOrigin) {
+        const cleanOrigin = absoluteOrigin.replace(/\/+$/, "");
+        return `${cleanOrigin}${finalPath.startsWith("/") ? "" : "/"}${finalPath}`;
+    }
+
+    return finalPath;
+}