target-supabase-sdk 0.2.15 → 0.2.17

package/src/shared/media/node/media.access.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+import { MEDIA_CONTENT_HASH_ALGORITHM, type MediaOriginal, type MediaValue } from "../media.interface";
+import { guessMediaMime } from "../media.mime";
+
+export interface CheckMediaAvailabilityInput {
+    value: MediaValue;
+    storageProvider: string;
+    locator: string;
+    /**
+     * This host's storage id (e.g. from `LOCAL_STORAGE_PROVIDER`).
+     * Local path checks only run when it equals `storageProvider`.
+     */
+    localStorageProvider: string;
+}
+
+export interface MediaAvailabilityResult {
+    ok: boolean;
+    /** Absolute path when the locator was resolved on this host. */
+    absolutePath?: string;
+    reason?: string;
+}
+
+function sameStorageHost(storageProvider: string, localStorageProvider: string): boolean {
+    return storageProvider.trim() === localStorageProvider.trim();
+}
+
+async function sha256FileStreaming(absolutePath: string): Promise<string> {
+    return await new Promise((resolveHash, reject) => {
+        const hash = createHash(MEDIA_CONTENT_HASH_ALGORITHM);
+        const stream = createReadStream(absolutePath);
+        stream.on("data", (chunk) => {
+            hash.update(chunk);
+        });
+        stream.on("error", reject);
+        stream.on("end", () => {
+            resolveHash(hash.digest("hex"));
+        });
+    });
+}
+
+async function countFilesOneLevel(dirPath: string): Promise<number> {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        if (entry.isFile()) {
+            count += 1;
+        }
+    }
+    return count;
+}
+
+/**
+ * Fast local reachability check for a media locator.
+ *
+ * - Requires `storageProvider === localStorageProvider` (cross-host → not ok).
+ * - `locator` must be an absolute path.
+ * - `image-list`: directory exists; only immediate children are considered.
+ * - other values: path exists and is a non-empty file.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export async function checkMediaAvailability(input: CheckMediaAvailabilityInput): Promise<MediaAvailabilityResult> {
+    const storageProvider = input.storageProvider.trim();
+    const localStorageProvider = input.localStorageProvider.trim();
+    const locator = input.locator.trim();
+
+    if (storageProvider === "" || localStorageProvider === "") {
+        return { ok: false, reason: "storageProvider and localStorageProvider are required" };
+    }
+    if (locator === "") {
+        return { ok: false, reason: "locator is empty" };
+    }
+    if (!sameStorageHost(storageProvider, localStorageProvider)) {
+        return {
+            ok: false,
+            reason: `storageProvider not on this host (${storageProvider} !== ${localStorageProvider})`,
+        };
+    }
+    if (!isAbsolute(locator)) {
+        return { ok: false, reason: `locator must be an absolute path: ${locator}` };
+    }
+
+    const absolutePath = resolve(locator);
+
+    try {
+        const info = await stat(absolutePath);
+        if (input.value === "image-list") {
+            if (!info.isDirectory()) {
+                return { ok: false, reason: `image-list locator is not a directory: ${absolutePath}` };
+            }
+            return { ok: true, absolutePath };
+        }
+        if (!info.isFile()) {
+            return { ok: false, reason: `locator is not a file: ${absolutePath}` };
+        }
+        if (info.size <= 0) {
+            return { ok: false, reason: `file is empty: ${absolutePath}` };
+        }
+        return { ok: true, absolutePath };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `locator not reachable: ${absolutePath} (${message})` };
+    }
+}
+
+/**
+ * Derive `contentHash` / `size` / `mimeType` for {@link MediaOriginal} after availability succeeds.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export async function probeMediaOriginal(input: {
+    value: MediaValue;
+    storageProvider: string;
+    locator: string;
+    absolutePath: string;
+}): Promise<MediaOriginal> {
+    const storageProvider = input.storageProvider.trim();
+    const locator = input.locator.trim();
+
+    if (input.value === "image-list") {
+        const size = await countFilesOneLevel(input.absolutePath);
+        return {
+            storageProvider,
+            locator,
+            contentHash: "",
+            size,
+            mimeType: "",
+        };
+    }
+
+    const info = await stat(input.absolutePath);
+    const mimeType = guessMediaMime(input.absolutePath, input.value);
+    if (mimeType == null) {
+        throw new Error(`probeMediaOriginal: cannot guess mimeType for ${input.value}: ${input.absolutePath}`);
+    }
+    const contentHash = await sha256FileStreaming(input.absolutePath);
+    return {
+        storageProvider,
+        locator,
+        contentHash,
+        size: info.size,
+        mimeType,
+    };
+}

package/src/shared/media/node/media.service.ts

@@ -0,0 +1,129 @@
+import { getPossibleTarget, isCreateTargetAlreadyExistsError, postTarget } from "../../../core.api";
+import type { Link } from "../../../link/link.interface";
+import { createLogger } from "../../log/core/create-logger";
+import { buildMediaLinkDraft } from "../media.build";
+import { isMediaValue, type MediaValue } from "../media.interface";
+import { mediaLinkDedupFilters } from "../media.query";
+import { checkMediaAvailability, probeMediaOriginal } from "./media.access";
+
+const logger = createLogger({ module: "media" });
+
+export interface FindMediaLinkInput {
+    value: MediaValue;
+    name: string;
+}
+
+/** Dedup lookup: same `category` + `value` + `name`. */
+export async function findMediaLink(input: FindMediaLinkInput): Promise<Link | null> {
+    if (!isMediaValue(input.value)) {
+        throw new Error(`findMediaLink: unsupported media value: ${String(input.value)}`);
+    }
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("findMediaLink: name is empty");
+    }
+    const { data } = await getPossibleTarget({
+        filterList: mediaLinkDedupFilters({ value: input.value, name }),
+    });
+    return data != null ? (data as Link) : null;
+}
+
+export interface RegisterMediaLinkInput {
+    value: MediaValue;
+    name: string;
+    storageProvider: string;
+    locator: string;
+    /** This host id for availability (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). */
+    localStorageProvider: string;
+    description?: string;
+    tagList?: string[];
+}
+
+export interface RegisterMediaLinkResult {
+    id: string;
+    created: boolean;
+}
+
+/**
+ * Register a media Link: dedup → availability → probe → `postTarget`.
+ * Idempotent when `category`+`value`+`name` already exist.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export async function registerMediaLink(input: RegisterMediaLinkInput): Promise<RegisterMediaLinkResult> {
+    if (!isMediaValue(input.value)) {
+        throw new Error(`registerMediaLink: unsupported media value: ${String(input.value)}`);
+    }
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("registerMediaLink: name is empty");
+    }
+
+    const existing = await findMediaLink({ value: input.value, name });
+    if (existing != null) {
+        logger.info("media already registered", {
+            topic: "dedup",
+            data: { id: existing.id, value: input.value, name },
+        });
+        return { id: existing.id, created: false };
+    }
+
+    const availability = await checkMediaAvailability({
+        value: input.value,
+        storageProvider: input.storageProvider,
+        locator: input.locator,
+        localStorageProvider: input.localStorageProvider,
+    });
+    if (!availability.ok || availability.absolutePath == null) {
+        throw new Error(`registerMediaLink: unavailable — ${availability.reason ?? "unknown"}`);
+    }
+
+    const probed = await probeMediaOriginal({
+        value: input.value,
+        storageProvider: input.storageProvider,
+        locator: input.locator,
+        absolutePath: availability.absolutePath,
+    });
+
+    const draft = buildMediaLinkDraft({
+        value: input.value,
+        name,
+        storageProvider: probed.storageProvider,
+        locator: probed.locator,
+        contentHash: probed.contentHash,
+        size: probed.size,
+        mimeType: probed.mimeType,
+        description: input.description,
+        tagList: input.tagList,
+    });
+
+    try {
+        const { data, error } = await postTarget({
+            name: draft.name,
+            value: draft.value,
+            category: draft.category,
+            tagList: draft.tagList,
+            details: draft.details,
+        });
+        if (error != null || data == null) {
+            throw new Error(error?.message ?? "registerMediaLink: postTarget failed");
+        }
+        logger.info("media registered", {
+            topic: "register",
+            data: { id: data.id, value: input.value, name, size: probed.size },
+        });
+        return { id: data.id, created: true };
+    } catch (error) {
+        if (isCreateTargetAlreadyExistsError(error)) {
+            const raced = await findMediaLink({ value: input.value, name });
+            if (raced != null) {
+                logger.info("media register race — using existing", {
+                    topic: "dedup",
+                    data: { id: raced.id, value: input.value, name },
+                });
+                return { id: raced.id, created: false };
+            }
+        }
+        throw error;
+    }
+}