target-supabase-sdk 0.2.18 → 0.2.19

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

@@ -0,0 +1,134 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+import { fetchWithRetry } from "../../http/fetch-retry";
+import { isHttpUrl } from "../../utils/fetch-url";
+import type { FeedValue } from "../feed.interface";
+
+export interface CheckFeedLocalAvailabilityInput {
+    value: FeedValue;
+    storageProvider: string;
+    locator: string;
+    /** This host id (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). */
+    localStorageProvider: string;
+}
+
+export interface FeedAvailabilityResult {
+    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();
+}
+
+function isFeedDirectoryValue(value: FeedValue): boolean {
+    return value === "feed.image-list";
+}
+
+/**
+ * Local reachability for feed ingest (`.local` source).
+ *
+ * - Requires `storageProvider === localStorageProvider`.
+ * - `locator` must be an absolute path.
+ * - `feed.image-list`: directory exists.
+ * - Other feed values: non-empty file.
+ *
+ * **Node-only**
+ */
+export async function checkFeedLocalAvailability(
+    input: CheckFeedLocalAvailabilityInput,
+): Promise<FeedAvailabilityResult> {
+    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 (isFeedDirectoryValue(input.value)) {
+            if (!info.isDirectory()) {
+                return { ok: false, reason: `feed.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})` };
+    }
+}
+
+const OSS_CHECK_TIMEOUT_MS = 15_000;
+const OSS_CHECK_MAX_ATTEMPTS = 2;
+
+async function probeHttpLocator(locator: string, method: "HEAD" | "GET"): Promise<Response> {
+    return fetchWithRetry(
+        locator,
+        {
+            method,
+            ...(method === "GET" ? { headers: { Range: "bytes=0-0" } } : {}),
+        },
+        {
+            label: "feed-oss-check",
+            timeoutMs: OSS_CHECK_TIMEOUT_MS,
+            maxAttempts: OSS_CHECK_MAX_ATTEMPTS,
+        },
+    );
+}
+
+/**
+ * Remote reachability for feed ingest (`.oss` source) via HTTP(S).
+ *
+ * Tries `HEAD`, then `GET` with `Range: bytes=0-0` when `HEAD` is not allowed.
+ *
+ * **Node-only**
+ */
+export async function checkFeedOssAvailability(locator: string): Promise<FeedAvailabilityResult> {
+    const trimmed = locator.trim();
+    if (trimmed === "") {
+        return { ok: false, reason: "locator is empty" };
+    }
+    if (!isHttpUrl(trimmed)) {
+        return { ok: false, reason: `oss locator must be an http(s) URL: ${trimmed}` };
+    }
+
+    try {
+        let response = await probeHttpLocator(trimmed, "HEAD");
+        if (response.status === 405 || response.status === 501) {
+            response = await probeHttpLocator(trimmed, "GET");
+        }
+        if (response.ok || (response.status >= 200 && response.status < 400)) {
+            return { ok: true };
+        }
+        return { ok: false, reason: `oss locator HTTP ${response.status}: ${trimmed}` };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `oss locator request failed: ${trimmed} (${message})` };
+    }
+}

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

@@ -0,0 +1,183 @@
+import { getTarget, updateTarget } from "../../../core.api";
+import type { Target } from "../../../core.interface";
+import { CategoryLink, type Link, type LinkDetails } from "../../../link/link.interface";
+import { createLogger } from "../../log/core/create-logger";
+import { buildFeedTagList, resolveFeedOriginalStorageProvider } from "../feed.build";
+import {
+    type FeedIngestSource,
+    type FeedOriginal,
+    type FeedValue,
+    isFeedIngestSource,
+    isFeedValue,
+} from "../feed.interface";
+import { checkFeedLocalAvailability, checkFeedOssAvailability } from "./feed.access";
+
+const logger = createLogger({ module: "feed" });
+
+export interface RegisterFeedInput {
+    /** Existing feed Link row id (must still be `.public` unless already ingested with same payload). */
+    id: string;
+    source: FeedIngestSource;
+    storageProvider: string;
+    locator: string;
+    /** Required when `source` is `.local` (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). Ignored for `.oss`. */
+    localStorageProvider?: string;
+}
+
+export interface RegisterFeedResult {
+    id: string;
+    /** `false` when row was already ingested with the same source, storageProvider, and locator. */
+    updated: boolean;
+}
+
+function parseFeedOriginal(original: unknown): FeedOriginal | null {
+    if (original == null || typeof original !== "object") {
+        return null;
+    }
+    const record = original as Record<string, unknown>;
+    const storageProvider = typeof record.storageProvider === "string" ? record.storageProvider : null;
+    const locator = typeof record.locator === "string" ? record.locator : null;
+    if (storageProvider == null || locator == null) {
+        return null;
+    }
+    const twinList = Array.isArray(record.twinList)
+        ? record.twinList.filter((entry): entry is string => typeof entry === "string")
+        : undefined;
+    return {
+        storageProvider,
+        locator,
+        ...(twinList !== undefined ? { twinList } : {}),
+    };
+}
+
+function assertFeedLink(target: Target): Link {
+    if (target.category !== CategoryLink.LINK) {
+        throw new Error(`registerFeed: target is not a link (category=${target.category})`);
+    }
+    if (!isFeedValue(target.value)) {
+        throw new Error(`registerFeed: target value is not a feed loader: ${target.value}`);
+    }
+    const details = target.details as LinkDetails | undefined;
+    if (details == null || details.loaderKey !== target.value) {
+        throw new Error("registerFeed: invalid feed link details (loaderKey must equal value)");
+    }
+    return target as Link;
+}
+
+function hasIngestSourceTag(tagList: string[]): boolean {
+    return tagList.some((tag) => tag === ".local" || tag === ".oss");
+}
+
+function isSameIngestState(link: Link, source: FeedIngestSource, storageProvider: string, locator: string): boolean {
+    if (!link.tagList.includes(source)) {
+        return false;
+    }
+    const original = parseFeedOriginal(link.details.original);
+    if (original == null) {
+        return false;
+    }
+    return original.storageProvider === storageProvider && original.locator === locator;
+}
+
+/**
+ * Ingest a `.public` feed Link: validate locator, then promote `tagList` source to `.local` or `.oss`
+ * and update `details.original.storageProvider` + `locator`.
+ *
+ * **Node-only** — under `shared/feed/node/`; do not import from the browser entry.
+ */
+export async function registerFeed(input: RegisterFeedInput): Promise<RegisterFeedResult> {
+    const id = input.id.trim();
+    if (id === "") {
+        throw new Error("registerFeed: id is empty");
+    }
+    if (!isFeedIngestSource(input.source)) {
+        throw new Error(`registerFeed: source must be .local or .oss, got ${String(input.source)}`);
+    }
+
+    const resolvedStorageProvider = resolveFeedOriginalStorageProvider(input.source, input.storageProvider);
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("registerFeed: locator is empty");
+    }
+
+    const { data: target } = await getTarget({ id });
+    if (target == null) {
+        throw new Error(`registerFeed: target not found: ${id}`);
+    }
+
+    const link = assertFeedLink(target);
+    const feedValue = link.value as FeedValue;
+
+    if (!link.tagList.includes(".public")) {
+        if (isSameIngestState(link, input.source, resolvedStorageProvider, locator)) {
+            logger.info("feed already ingested", {
+                topic: "dedup",
+                data: { id, source: input.source, locator },
+            });
+            return { id, updated: false };
+        }
+        if (hasIngestSourceTag(link.tagList)) {
+            throw new Error("registerFeed: feed already ingested with different source, storageProvider, or locator");
+        }
+        throw new Error("registerFeed: feed is not .public — cannot ingest");
+    }
+
+    if (input.source === ".local") {
+        const localStorageProvider = input.localStorageProvider?.trim() ?? "";
+        if (localStorageProvider === "") {
+            throw new Error("registerFeed: localStorageProvider is required when source is .local");
+        }
+        const availability = await checkFeedLocalAvailability({
+            value: feedValue,
+            storageProvider: resolvedStorageProvider,
+            locator,
+            localStorageProvider,
+        });
+        if (!availability.ok) {
+            throw new Error(`registerFeed: local locator unavailable — ${availability.reason ?? "unknown"}`);
+        }
+    } else {
+        const availability = await checkFeedOssAvailability(locator);
+        if (!availability.ok) {
+            throw new Error(`registerFeed: oss locator unavailable — ${availability.reason ?? "unknown"}`);
+        }
+    }
+
+    await updateTarget<Link, LinkDetails>({
+        id,
+        optimisticLockFilterList: [
+            { field: "category", operator: "eq", value: CategoryLink.LINK },
+            { field: "details->original->>storageProvider", operator: "eq", value: "" },
+        ],
+        updateFn: (row) => {
+            if (!row.tagList.includes(".public")) {
+                throw new Error("registerFeed: optimistic lock failed — .public tag missing");
+            }
+            if (hasIngestSourceTag(row.tagList) && !row.tagList.includes(".public")) {
+                throw new Error("registerFeed: feed already ingested");
+            }
+
+            const details = row.details;
+            const prior = parseFeedOriginal(details.original);
+            const nextOriginal: FeedOriginal = {
+                storageProvider: resolvedStorageProvider,
+                locator,
+                ...(prior?.twinList !== undefined ? { twinList: prior.twinList } : {}),
+            };
+
+            return {
+                tagList: buildFeedTagList(input.source, row.tagList),
+                details: {
+                    ...details,
+                    original: nextOriginal,
+                },
+            };
+        },
+    });
+
+    logger.info("feed ingested", {
+        topic: "register",
+        data: { id, source: input.source, storageProvider: resolvedStorageProvider, locator },
+    });
+    return { id, updated: true };
+}

package/src/shared/feed/node/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Node-only feed surface — for `src/node.ts` / `target-supabase-sdk/node` only.
+ * Never re-export from `../index.ts` or `browser.ts`.
+ */
+
+export type { FeedIngestSource } from "../feed.interface";
+export { FEED_INGEST_SOURCES, isFeedIngestSource } from "../feed.interface";
+export type { CheckFeedLocalAvailabilityInput, FeedAvailabilityResult } from "./feed.access";
+export { checkFeedLocalAvailability, checkFeedOssAvailability } from "./feed.access";
+export type { RegisterFeedInput, RegisterFeedResult } from "./feed.service";
+export { registerFeed } from "./feed.service";