@tulip-systems/drive 0.7.0

package/src/providers/local/lib/service.server.ts

@@ -0,0 +1,1116 @@
+import stream from "node:stream/consumers";
+import type { TDatabaseSchema } from "@tulip-systems/core/config";
+import type { TableQueryResponse } from "@tulip-systems/core/data-tables/server";
+import {
+  convertOrderByToQueryParams,
+  convertSearchToQueryParams,
+  createTableQueryResponse,
+} from "@tulip-systems/core/data-tables/server";
+import type { Database } from "@tulip-systems/core/database/server";
+import { ServerError } from "@tulip-systems/core/router/server";
+import { type ObjectBodyInput, storageAssets } from "@tulip-systems/core/storage";
+import type { Storage } from "@tulip-systems/core/storage/server";
+import { addSeconds } from "date-fns";
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  getTableColumns,
+  inArray,
+  isNotNull,
+  isNull,
+  type SQL,
+  sql,
+} from "drizzle-orm";
+import { after } from "next/server";
+import type { QueryResult } from "pg";
+import type {
+  DriveArchive,
+  DriveDirectUpload,
+  DriveNodeMutations,
+  DrivePresignedUpload,
+  DrivePreviewGenerator,
+  DriveReader,
+  DriveReadonly,
+} from "../../../lib/contracts";
+import { deviceSizes } from "./constants";
+import {
+  inferLocalDriveNodeSubtype,
+  isLocalDriveFile,
+  isLocalDriveFolder,
+  toLocalDriveNode,
+} from "./helpers";
+import { nodePresignedUrls, nodes, nodeVariants } from "./schema";
+import {
+  type CreateLocalDriveFolderSchema,
+  type GetLocalDriveNodesByParentIdInput,
+  type GetLocalFileURLSchema,
+  getLocalFileURLSchemaDefaults,
+  type ListLocalDriveFlatSchema,
+  type ListLocalDriveTreeSchema,
+  type LocalDriveFileNode,
+  type LocalDriveNode,
+  type LocalDriveNodeChild,
+  type LocalDriveNodeWithAsset,
+  type LocalDriveNodeWithChildren,
+  type LocalNode,
+  type PresignLocalDriveFileInput,
+  type UpdateLocalDriveNodeInput,
+  type UploadLocalDriveFileSchema,
+} from "./validators";
+
+/**
+ * Drive Service Config
+ */
+export type LocalDriveConfig<TSchema extends TDatabaseSchema> = {
+  db: Database<TSchema>;
+  storage: Storage<TSchema>;
+};
+
+/**
+ * Drive Service
+ */
+export class LocalDrive<TSchema extends TDatabaseSchema>
+  implements
+    DriveReader<LocalDriveNode>,
+    DriveNodeMutations<LocalDriveNode>,
+    DriveDirectUpload<LocalDriveNode, ObjectBodyInput>,
+    DrivePresignedUpload<LocalDriveFileNode>,
+    DrivePreviewGenerator,
+    DriveReadonly<LocalDriveNode>,
+    DriveArchive<LocalDriveNode>
+{
+  #db: Database<TSchema>;
+  storage: Storage<TSchema>;
+
+  constructor({ db, storage }: LocalDriveConfig<TSchema>) {
+    this.#db = db;
+    this.storage = storage;
+  }
+
+  /**
+   * Loads and validates the parent folder for write operations.
+   *
+   * The returned parent is guaranteed to exist, be a folder, belong to the
+   * same namespace, and not be archived. Root-level operations return `null`.
+   *
+   * @param input - Parent identifier and target namespace.
+   * @returns The validated parent node or `null` for root operations.
+   */
+  async #getWritableParent(input: { parentId?: string | null; namespace: string }) {
+    if (!input.parentId) return null;
+
+    const [parent] = await this.#db
+      .select()
+      .from(nodes)
+      .where(eq(nodes.id, input.parentId))
+      .limit(1);
+
+    if (!parent) {
+      throw new ServerError("BAD_REQUEST", { message: "Parent not found" });
+    }
+
+    if (!isLocalDriveFolder(parent)) {
+      throw new ServerError("BAD_REQUEST", { message: "Parent is not a folder" });
+    }
+
+    if (parent.namespace !== input.namespace) {
+      throw new ServerError("BAD_REQUEST", {
+        message: "Parent is not in the same namespace",
+      });
+    }
+
+    if (parent.archivedAt) {
+      throw new ServerError("BAD_REQUEST", {
+        message: "Parent is archived",
+      });
+    }
+
+    return parent;
+  }
+
+  /**
+   * Collects the storage asset ids associated with a node subtree.
+   *
+   * This includes both the main file assets attached to file nodes and any
+   * generated variant assets stored in `node_variants`.
+   *
+   * @param nodeIds - Node ids that belong to the subtree.
+   * @param subtree - Lightweight subtree rows returned by `getNodeChildren`.
+   * @returns A de-duplicated list of storage asset ids.
+   */
+  async #getSubtreeAssetIds(
+    nodeIds: string[],
+    subtree: Array<Pick<LocalNode, "id" | "assetId" | "type" | "parentId"> & { depth: number }>,
+  ) {
+    const fileAssetIds = [
+      ...new Set(
+        subtree
+          .filter((node) => node.type === "file")
+          .map((node) => node.assetId)
+          .filter((assetId): assetId is string => assetId != null),
+      ),
+    ];
+
+    const variantAssets = await this.#db
+      .select({ assetId: nodeVariants.assetId })
+      .from(nodeVariants)
+      .where(inArray(nodeVariants.nodeId, nodeIds));
+
+    return [...new Set([...fileAssetIds, ...variantAssets.map((variant) => variant.assetId)])];
+  }
+
+  /**
+   * Retrieves the node row for a given id.
+   *
+   * This is a thin lookup helper that returns the raw database result for the
+   * matching node. It does not load children, variants, or perform namespace
+   * validation.
+   *
+   * @param id - The node identifier.
+   * @returns A promise resolving to the matching node row as a single-item array,
+   * or an empty array when no node exists.
+   */
+  async getNodeById(id: string): Promise<LocalDriveNode | null> {
+    const [node] = await this.#db.select().from(nodes).where(eq(nodes.id, id));
+    return node ? toLocalDriveNode(node) : null;
+  }
+
+  /**
+   * Retrieves a node together with its direct children for a namespace.
+   *
+   * This is used by the drive UI when opening a node detail view that expects
+   * the immediate child nodes in the same payload.
+   *
+   * @param input - The target node id and namespace.
+   * @returns The node with its children when found, otherwise `null`.
+   */
+  async getNodeWithChildren(input: {
+    id: string;
+    namespace: string;
+  }): Promise<LocalDriveNodeWithChildren | null> {
+    const node = await this.getNodeById(input.id);
+    if (!node || node.namespace !== input.namespace) return null;
+
+    const children = await this.getNodesByParentId({
+      filters: {
+        namespace: input.namespace,
+        parentId: node.id,
+        hidden: false,
+        isArchived: false,
+      },
+    });
+
+    return { ...node, children };
+  }
+
+  /**
+   * Lists nodes within a folder scope using the current table-query filters.
+   *
+   * Behavior:
+   * - Scopes results to a namespace
+   * - Resolves either root nodes (`parentId = null`) or a specific parent folder
+   * - Applies optional filters such as ids, types, hidden state, and archive state
+   * - Applies search and sorting through the shared table-query utilities
+   *
+   * @param input - Table query input containing drive filters, search, and sorting.
+   * @returns A promise resolving to the matching child nodes.
+   */
+  async getNodesByParentId({
+    filters,
+    ...query
+  }: GetLocalDriveNodesByParentIdInput): Promise<LocalDriveNode[]> {
+    const orderBy = convertOrderByToQueryParams(query, nodes, asc(nodes.createdAt));
+    const search = convertSearchToQueryParams(query, [nodes.name]);
+    const archivedFilter =
+      filters.isArchived === true
+        ? isNotNull(nodes.archivedAt)
+        : filters.isArchived === false
+          ? isNull(nodes.archivedAt)
+          : undefined;
+    const parentFilter = filters.parentId
+      ? eq(nodes.parentId, filters.parentId)
+      : isNull(nodes.parentId);
+
+    const items = await this.#db
+      .select()
+      .from(nodes)
+      .where(
+        and(
+          filters.nodeIds != null ? inArray(nodes.id, filters.nodeIds) : undefined,
+          filters.types != null ? inArray(nodes.type, filters.types) : undefined,
+          archivedFilter,
+          filters.hidden != null ? eq(nodes.hidden, filters.hidden) : undefined,
+          parentFilter,
+          eq(nodes.namespace, filters.namespace),
+          search,
+        ),
+      )
+      .orderBy(orderBy as SQL);
+
+    return items.map(toLocalDriveNode);
+  }
+
+  /**
+   * Lists tree-scoped nodes with pagination, search, and richer local filters.
+   *
+   * This query is intended for admin table views where additional local fields
+   * such as subtype and contentType are part of the filtering contract.
+   *
+   * @param input - Table query input with tree filters.
+   * @returns A paginated table-query response.
+   */
+  async listTree({
+    filters,
+    ...query
+  }: ListLocalDriveTreeSchema): Promise<TableQueryResponse<LocalDriveNodeWithAsset>> {
+    const orderBy = convertOrderByToQueryParams(query, nodes, desc(nodes.createdAt));
+    const search = convertSearchToQueryParams(query, [nodes.name]);
+
+    const archivedFilter =
+      filters.isArchived === true
+        ? isNotNull(nodes.archivedAt)
+        : filters.isArchived === false
+          ? isNull(nodes.archivedAt)
+          : undefined;
+    const parentFilter = filters.parentId
+      ? eq(nodes.parentId, filters.parentId)
+      : isNull(nodes.parentId);
+
+    const limit = query.limit;
+    const cursor = query.cursor;
+    const offset = cursor * limit;
+
+    const where = and(
+      filters.nodeIds != null ? inArray(nodes.id, filters.nodeIds) : undefined,
+      filters.types != null ? inArray(nodes.type, filters.types) : undefined,
+      filters.subtypes != null ? inArray(nodes.subtype, filters.subtypes) : undefined,
+      filters.contentTypes != null ? inArray(nodes.contentType, filters.contentTypes) : undefined,
+      archivedFilter,
+      filters.hidden != null ? eq(nodes.hidden, filters.hidden) : undefined,
+      parentFilter,
+      eq(nodes.namespace, filters.namespace),
+      search,
+    );
+
+    const [data, total] = await this.#db.transaction(async (tx) => {
+      const data = await tx
+        .select({
+          ...getTableColumns(nodes),
+          asset: storageAssets,
+        })
+        .from(nodes)
+        .where(where)
+        .leftJoin(storageAssets, eq(nodes.assetId, storageAssets.id))
+        .orderBy(orderBy as SQL)
+        .limit(limit)
+        .offset(offset);
+
+      const total = await tx.$count(nodes, where);
+      return [data, total] as const;
+    });
+
+    return createTableQueryResponse({
+      data: data.map(({ asset, ...node }) => ({ ...toLocalDriveNode(node), asset })),
+      input: query,
+      total,
+    });
+  }
+
+  /**
+   * Lists flat nodes with pagination, search, and richer local filters.
+   *
+   * Unlike `listTree`, this query ignores parent scoping and is intended for
+   * flat file-manager style views.
+   *
+   * @param input - Table query input with flat filters.
+   * @returns A paginated table-query response.
+   */
+  async listFlat({
+    filters,
+    ...query
+  }: ListLocalDriveFlatSchema): Promise<TableQueryResponse<LocalDriveNodeWithAsset>> {
+    const orderBy = convertOrderByToQueryParams(query, nodes, desc(nodes.createdAt));
+    const search = convertSearchToQueryParams(query, [nodes.name]);
+    const archivedFilter =
+      filters.isArchived === true
+        ? isNotNull(nodes.archivedAt)
+        : filters.isArchived === false
+          ? isNull(nodes.archivedAt)
+          : undefined;
+    const limit = query.limit;
+    const cursor = query.cursor;
+    const offset = cursor * limit;
+
+    const where = and(
+      filters.nodeIds != null ? inArray(nodes.id, filters.nodeIds) : undefined,
+      filters.types != null ? inArray(nodes.type, filters.types) : undefined,
+      filters.subtypes != null ? inArray(nodes.subtype, filters.subtypes) : undefined,
+      filters.contentTypes != null ? inArray(nodes.contentType, filters.contentTypes) : undefined,
+      archivedFilter,
+      filters.hidden != null ? eq(nodes.hidden, filters.hidden) : undefined,
+      filters.namespace ? eq(nodes.namespace, filters.namespace) : undefined,
+      search,
+    );
+
+    const [data, total] = await this.#db.transaction(async (tx) => {
+      const data = await tx
+        .select({
+          ...getTableColumns(nodes),
+          asset: storageAssets,
+        })
+        .from(nodes)
+        .where(where)
+        .leftJoin(storageAssets, eq(nodes.assetId, storageAssets.id))
+        .orderBy(orderBy as SQL)
+        .limit(limit)
+        .offset(offset);
+
+      const total = await tx.$count(nodes, where);
+      return [data, total] as const;
+    });
+
+    return createTableQueryResponse({
+      data: data.map(({ asset, ...node }) => ({ ...toLocalDriveNode(node), asset })),
+      input: query,
+      total,
+    });
+  }
+
+  /**
+   * Resolves the ancestor chain for a folder or file node.
+   *
+   * The returned list starts with the root-most ancestor and ends with the
+   * requested node. This is primarily used for breadcrumb navigation.
+   *
+   * @param input - The node id and namespace to resolve.
+   * @returns A promise resolving to the ordered ancestor chain.
+   */
+  async getFolderParents(input: { id: string | null; namespace: string }) {
+    if (!input.id) return [];
+
+    const startNodeQuery = this.#db
+      .select({
+        id: nodes.id,
+        name: nodes.name,
+        parentId: nodes.parentId,
+        depth: sql<number>`0`.as("depth"),
+      })
+      .from(nodes)
+      .where(and(eq(nodes.id, input.id), eq(nodes.namespace, input.namespace)));
+
+    const alias = "parent_nodes";
+    const parentNodesQueryAlias = startNodeQuery.as(alias);
+    const recursiveQueryName = sql.raw(`"${alias}"`);
+
+    const recursiveQuery = startNodeQuery.unionAll(
+      this.#db
+        .select({
+          id: nodes.id,
+          name: nodes.name,
+          parentId: nodes.parentId,
+          depth: sql<number>`${parentNodesQueryAlias.depth} + 1`,
+        })
+        .from(nodes)
+        .innerJoin(recursiveQueryName, eq(nodes.id, parentNodesQueryAlias.parentId)),
+    );
+
+    const result = (await this.#db.execute(
+      sql`WITH RECURSIVE ${recursiveQueryName} AS ${recursiveQuery} SELECT * FROM ${recursiveQueryName}`,
+    )) as QueryResult<Pick<LocalNode, "id" | "name" | "parentId"> & { depth: number }>;
+
+    return result.rows?.toSorted((a, b) => Number(b.depth) - Number(a.depth)) ?? [];
+  }
+
+  /**
+   * Retrieves the structural subtree for one or more root node ids.
+   *
+   * The result includes the provided start nodes and all descendant nodes,
+   * returned as a lightweight shape containing only the fields needed for
+   * recursive drive operations such as delete, archive, and validation.
+   *
+   * Depth starts at `0` for the provided root nodes and increases for each
+   * descendant level. Duplicate paths are collapsed by keeping the minimum depth.
+   *
+   * @param ids - Root node ids to traverse from.
+   * @returns A promise resolving to the subtree rows for the provided nodes.
+   */
+  async getNodeChildren(ids: string[]) {
+    if (ids.length === 0) return [];
+
+    const startNodeQuery = this.#db
+      .select({
+        id: nodes.id,
+        assetId: nodes.assetId,
+        type: nodes.type,
+        parentId: nodes.parentId,
+        depth: sql<number>`0`.as("depth"),
+      })
+      .from(nodes)
+      .where(inArray(nodes.id, ids));
+
+    const alias = "child_nodes";
+    const childNodesQueryAlias = startNodeQuery.as(alias);
+    const recursiveQueryName = sql.raw(`"${alias}"`);
+
+    const recursiveQuery = startNodeQuery.unionAll(
+      this.#db
+        .select({
+          id: nodes.id,
+          assetId: nodes.assetId,
+          type: nodes.type,
+          parentId: nodes.parentId,
+          depth: sql<number>`${childNodesQueryAlias.depth} + 1`,
+        })
+        .from(nodes)
+        .innerJoin(recursiveQueryName, eq(nodes.parentId, childNodesQueryAlias.id)),
+    );
+
+    const result = (await this.#db.execute(
+      sql`WITH RECURSIVE ${recursiveQueryName} AS ${recursiveQuery}
+        SELECT
+          ${childNodesQueryAlias.id} as id,
+          ${childNodesQueryAlias.assetId} as "assetId",
+          ${childNodesQueryAlias.type} as type,
+          ${childNodesQueryAlias.parentId} as "parentId",
+          MIN(${childNodesQueryAlias.depth})::int as depth
+        FROM ${recursiveQueryName}
+        GROUP BY
+          ${childNodesQueryAlias.id},
+          ${childNodesQueryAlias.assetId},
+          ${childNodesQueryAlias.type},
+          ${childNodesQueryAlias.parentId}
+      `,
+    )) as QueryResult<Pick<LocalNode, "id" | "assetId" | "type" | "parentId"> & { depth: number }>;
+
+    return (result.rows ?? []) as LocalDriveNodeChild[];
+  }
+
+  /**
+   * Resolves an access URL for a file node and the requested variant.
+   *
+   * Behavior:
+   * - Rejects folder nodes because only file nodes can resolve a file URL
+   * - Reuses a cached URL when an unexpired entry exists for the requested
+   *   variant and disposition
+   * - Resolves the requested preview variant asset when available
+   * - Falls back to the main file asset when the requested variant does not exist
+   * - Delegates final URL generation to the storage service
+   * - Stores the generated URL in the local cache table for future reuse
+   *
+   * @param node - The file node to resolve.
+   * @param options - URL options such as variant and content disposition.
+   * @returns A promise resolving to a temporary file URL.
+   */
+  async getURL(node: LocalNode, options: GetLocalFileURLSchema = getLocalFileURLSchemaDefaults) {
+    if (!isLocalDriveFile(node)) {
+      throw new ServerError("BAD_REQUEST", { message: "Node is not a file" });
+    }
+
+    const [presignedUrl] = await this.#db
+      .select({ url: nodePresignedUrls.url, expiresAt: nodePresignedUrls.expiresAt })
+      .from(nodePresignedUrls)
+      .where(
+        and(
+          eq(nodePresignedUrls.nodeId, node.id),
+          eq(nodePresignedUrls.variant, options.variant),
+          eq(nodePresignedUrls.disposition, options.disposition),
+        ),
+      );
+
+    if (presignedUrl && presignedUrl.expiresAt > new Date()) return presignedUrl.url;
+
+    const expiresIn = 3600 * 24; // 24 hours
+
+    const [variantRecord] =
+      options.variant === "main"
+        ? []
+        : await this.#db
+            .select({
+              id: nodeVariants.id,
+              assetId: nodeVariants.assetId,
+              variant: nodeVariants.variant,
+            })
+            .from(nodeVariants)
+            .where(
+              and(eq(nodeVariants.nodeId, node.id), eq(nodeVariants.variant, options.variant)),
+            );
+
+    // If the requested variant does not exist, fallback to main
+    const variant = variantRecord ? options.variant : "main";
+    const assetId = variantRecord?.assetId ?? node.assetId;
+
+    if (!assetId) {
+      throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
+    }
+
+    console.info(
+      `Generating new signed url for file: ${node.id} with variant: ${variant} and disposition: ${options.disposition}`,
+    );
+
+    // Generate the presigned url that expires in 24 hours
+    const url = await this.storage.getObjectURL(assetId, {
+      disposition: `${options.disposition}; filename="${node.name}"`,
+      expiresIn,
+    });
+
+    // Add the presigned url to the database
+    after(async () => {
+      await this.#db
+        .insert(nodePresignedUrls)
+        .values({
+          nodeId: node.id,
+          url,
+          variant,
+          variantId: variantRecord?.id,
+          disposition: options.disposition,
+          expiresAt: addSeconds(new Date(), expiresIn),
+        })
+        .onConflictDoUpdate({
+          target: [
+            nodePresignedUrls.nodeId,
+            nodePresignedUrls.variant,
+            nodePresignedUrls.disposition,
+          ],
+          set: { url, expiresAt: addSeconds(new Date(), expiresIn) },
+        });
+    });
+
+    return url;
+  }
+
+  /**
+   * Moves a node to a different parent folder.
+   *
+   * The target parent is validated before the move is persisted. Moving a node
+   * into itself or into one of its descendants is rejected to keep the tree
+   * structure valid.
+   *
+   * @param input - The node id and the target parent id.
+   * @returns A promise resolving to the updated node.
+   * @throws {ServerError} If the move is invalid.
+   */
+  async moveNode(input: { id: string; parentId: string | null }) {
+    const [node] = await this.#db.select().from(nodes).where(eq(nodes.id, input.id)).limit(1);
+
+    if (!node) {
+      throw new ServerError("BAD_REQUEST", { message: "Node not found" });
+    }
+
+    if (node.readonly) {
+      throw new ServerError("BAD_REQUEST", {
+        message: "Deze node is alleen leesbaar en kan niet worden gewijzigd",
+      });
+    }
+
+    if (input.parentId === node.id) {
+      throw new ServerError("BAD_REQUEST", { message: "Node cannot be moved into itself" });
+    }
+
+    if (input.parentId !== undefined) {
+      await this.#getWritableParent({ parentId: input.parentId, namespace: node.namespace });
+    }
+
+    if (input.parentId) {
+      const subtree = await this.getNodeChildren([input.id]);
+
+      if (subtree.some((child) => child.id === input.parentId)) {
+        throw new ServerError("BAD_REQUEST", {
+          message: "Node cannot be moved into one of its descendants",
+        });
+      }
+    }
+
+    if (node.parentId === input.parentId) {
+      return toLocalDriveNode(node);
+    }
+
+    const [result] = await this.#db
+      .update(nodes)
+      .set({ parentId: input.parentId })
+      .where(eq(nodes.id, input.id))
+      .returning();
+
+    if (!result) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", {
+        message: "Node kon niet worden gewijzigd",
+      });
+    }
+
+    return toLocalDriveNode(result);
+  }
+
+  /**
+   * Uploads a file through the storage service and creates the matching node.
+   *
+   * Behavior:
+   * - Validates the parent folder when `parentId` is provided
+   * - Uploads the file bytes through the storage service
+   * - Persists the created storage asset id on the node
+   * - Cleans up the uploaded asset when node creation fails
+   *
+   * @param input - File metadata and body.
+   * @returns A promise resolving to the created file node.
+   * @throws {ServerError} If validation or persistence fails.
+   */
+  async uploadFile(input: UploadLocalDriveFileSchema & { body: ObjectBodyInput }) {
+    await this.#getWritableParent({ parentId: input.parentId, namespace: input.namespace });
+
+    const asset = await this.storage.upload({
+      name: input.name,
+      body: input.body,
+      contentType: input.contentType,
+      size: input.size,
+      visibility: "private",
+    });
+
+    try {
+      const [result] = await this.#db
+        .insert(nodes)
+        .values({
+          type: "file",
+          name: input.name,
+          namespace: input.namespace,
+          parentId: input.parentId,
+          size: asset.size ?? input.size,
+          contentType: asset.contentType ?? input.contentType,
+          hidden: input.hidden ?? false,
+          readonly: input.readonly ?? false,
+          subtype: inferLocalDriveNodeSubtype(input),
+          assetId: asset.id,
+        })
+        .returning();
+
+      if (!result) {
+        throw new ServerError("INTERNAL_SERVER_ERROR", {
+          message: "Oep! Er is iets fout gegaan",
+        });
+      }
+
+      return toLocalDriveNode(result);
+    } catch (error) {
+      await this.storage.purgeAsset(asset.id).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  /**
+   * Creates a direct upload intent and the matching file node.
+   *
+   * Behavior:
+   * - Validates the parent folder when `parentId` is provided
+   * - Requests a presigned upload from the storage service
+   * - Creates the file node linked to the pending storage asset
+   * - Purges the pending asset when node creation fails
+   *
+   * @param input - File metadata used to create the upload intent.
+   * @returns The created asset intent, presigned URL, and file node.
+   * @throws {ServerError} If validation or node creation fails.
+   */
+  async presignUpload(input: PresignLocalDriveFileInput) {
+    await this.#getWritableParent(input);
+
+    // Generate the presigned url
+    const { presignedUrl, ...asset } = await this.storage.presignUpload({
+      uploadId: input.uploadId,
+      name: input.name,
+      contentType: input.contentType,
+      size: input.size,
+      visibility: input.visibility,
+    });
+
+    try {
+      const [node] = await this.#db
+        .insert(nodes)
+        .values({
+          type: "file",
+          name: input.name,
+          namespace: input.namespace,
+          parentId: input.parentId,
+          size: asset.size ?? input.size,
+          contentType: asset.contentType ?? input.contentType,
+          hidden: input.hidden ?? false,
+          readonly: input.readonly ?? false,
+          assetId: asset.id,
+          subtype: inferLocalDriveNodeSubtype(input),
+        })
+        .returning();
+
+      if (!node) {
+        throw new ServerError("INTERNAL_SERVER_ERROR", {
+          message: "Oep! Er is iets fout gegaan",
+        });
+      }
+
+      return {
+        uploadId: asset.uploadId,
+        presignedUrl,
+        node: toLocalDriveNode(node) as LocalDriveFileNode,
+        asset,
+      };
+    } catch (error) {
+      await this.storage.purgeAsset(asset.id).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  /**
+   * Finalizes a presigned upload and synchronizes the node metadata.
+   *
+   * Behavior:
+   * - Confirms the pending asset through the storage service
+   * - Finds the matching node by `assetId`
+   * - Synchronizes final asset metadata onto the node
+   * - Schedules preview generation for image files
+   *
+   * @param uploadId - The storage upload id returned by the presign step.
+   * @returns A promise resolving to the finalized file node.
+   * @throws {ServerError} If the asset or node cannot be resolved.
+   */
+  async confirmUpload(uploadId: string) {
+    const asset = await this.storage.confirmUpload(uploadId);
+
+    const [node] = await this.#db.select().from(nodes).where(eq(nodes.assetId, asset.id)).limit(1);
+
+    if (!node) {
+      throw new ServerError("NOT_FOUND", { message: "File not found" });
+    }
+
+    const [result] = await this.#db
+      .update(nodes)
+      .set({
+        size: asset.size ?? node.size,
+        contentType: asset.contentType ?? node.contentType,
+      })
+      .where(eq(nodes.assetId, asset.id))
+      .returning();
+
+    if (!result) {
+      throw new ServerError("NOT_FOUND", { message: "File not found" });
+    }
+
+    /**
+     * Generate the preview version of the file
+     */
+    after(async () => {
+      await this.generatePreviews({ id: result.id });
+    });
+
+    return toLocalDriveNode(result) as LocalDriveFileNode;
+  }
+
+  /**
+   * Generates preview assets for an image node.
+   *
+   * The original file is loaded from storage, resized to the configured device
+   * widths, uploaded as separate storage assets, and linked through
+   * `node_variants`. Existing preview variants are skipped.
+   *
+   * @param input - The target file node identifier.
+   * @returns A promise that resolves once preview generation completes.
+   * @throws {ServerError} If the source node or asset cannot be resolved.
+   */
+  async generatePreviews(input: { id: string }) {
+    const [node] = await this.#db.select().from(nodes).where(eq(nodes.id, input.id)).limit(1);
+
+    if (!node) {
+      throw new ServerError("NOT_FOUND", { message: "Node not found" });
+    }
+
+    if (!node.assetId) {
+      throw new ServerError("BAD_REQUEST", { message: "Node has no storage asset" });
+    }
+
+    /**
+     * Get the main version of the file
+     */
+    const response = await this.storage.getObject(node.assetId);
+
+    const contentType = response.contentType;
+    if (!response.body) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", {
+        message: "Oeps! Er is iets fout gegaan",
+      });
+    }
+
+    /**
+     * Transform the main version of the file to a buffer
+     */
+    const buffer = await stream.buffer(response.body);
+
+    /**
+     * Generate the preview versions for images
+     */
+    if (contentType?.startsWith("image/")) {
+      const sharp = await import("sharp");
+      const sourceAsset = await this.storage.getAssetById(node.assetId);
+
+      if (!sourceAsset) {
+        throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
+      }
+
+      const existingVariants = await this.#db
+        .select({ variant: nodeVariants.variant })
+        .from(nodeVariants)
+        .where(eq(nodeVariants.nodeId, input.id));
+
+      const existingVariantNames = new Set(existingVariants.map((variant) => variant.variant));
+
+      // Generate the preview versions
+      await Promise.allSettled(
+        deviceSizes.flatMap(async (width) => {
+          const variant = `preview-${width}` as const;
+          if (existingVariantNames.has(variant)) return;
+
+          // Generate the preview
+          const preview = await sharp.default(buffer).resize({ width }).webp().toBuffer();
+
+          // Upload the preview and add the variant to the database
+          return this.#db.transaction(async (tx) => {
+            const asset = await this.storage.upload({
+              body: preview,
+              name: `${input.id}-preview-${width}.webp`,
+              contentType: "image/webp",
+              size: preview.byteLength,
+              visibility: sourceAsset.visibility,
+            });
+
+            try {
+              await tx.insert(nodeVariants).values({
+                nodeId: input.id,
+                assetId: asset.id,
+                variant,
+                width,
+              });
+            } catch (error) {
+              await this.storage.purgeAsset(asset.id).catch(() => undefined);
+              throw error;
+            }
+          });
+        }),
+      );
+    }
+  }
+
+  /**
+   * Creates a folder node in the drive tree.
+   *
+   * The parent folder is validated before the folder is inserted. Folders do
+   * not own a storage asset and are stored purely as drive metadata.
+   *
+   * @param input - Folder metadata.
+   * @returns A promise resolving to the created folder node.
+   * @throws {ServerError} If validation or insertion fails.
+   */
+  async createFolder(input: CreateLocalDriveFolderSchema) {
+    await this.#getWritableParent({ parentId: input.parentId, namespace: input.namespace });
+
+    /**
+     * Create the folder
+     */
+    const [result] = await this.#db
+      .insert(nodes)
+      .values({
+        type: "folder",
+        name: input.name,
+        namespace: input.namespace,
+        parentId: input.parentId,
+        hidden: input.hidden ?? false,
+        readonly: input.readonly ?? false,
+      })
+      .returning();
+
+    if (!result) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", {
+        message: "Folder kon niet worden aangemaakt",
+      });
+    }
+
+    return toLocalDriveNode(result);
+  }
+
+  /**
+   * Updates mutable node metadata.
+   *
+   * Supported updates currently include renaming, reparenting, visibility flags,
+   * and archive state. Structural updates are validated before being persisted.
+   *
+   * @param id - The target node id.
+   * @param data - Partial node fields to update.
+   * @returns A promise resolving to the updated node.
+   * @throws {ServerError} If the node does not exist or the update is invalid.
+   */
+  async updateNode(id: string, data: UpdateLocalDriveNodeInput) {
+    const [node] = await this.#db.select().from(nodes).where(eq(nodes.id, id)).limit(1);
+
+    if (!node) {
+      throw new ServerError("NOT_FOUND", { message: "Node not found" });
+    }
+
+    if (data.parentId !== undefined) {
+      await this.#getWritableParent({ parentId: data.parentId, namespace: node.namespace });
+    }
+
+    const [result] = await this.#db
+      .update(nodes)
+      .set({
+        name: data.name,
+        parentId: data.parentId,
+        hidden: data.hidden,
+        readonly: data.readonly,
+        archivedAt: data.archivedAt,
+      })
+      .where(eq(nodes.id, id))
+      .returning();
+
+    if (!result) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", {
+        message: "Node kon niet worden gewijzigd",
+      });
+    }
+
+    return toLocalDriveNode(result);
+  }
+
+  /**
+   * Sets the readonly state for multiple nodes.
+   *
+   * This method is intended for bulk lock and unlock operations in the drive UI.
+   *
+   * @param ids - The node ids to update.
+   * @param readonly - The readonly state to apply.
+   * @returns A promise resolving to the updated nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  async setReadonly(ids: string[], readonly: boolean) {
+    if (ids.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No node ids provided" });
+    }
+
+    const result = await this.#db
+      .update(nodes)
+      .set({ readonly })
+      .where(inArray(nodes.id, [...new Set(ids)]))
+      .returning();
+
+    if (result.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No matching nodes found" });
+    }
+
+    return result.map(toLocalDriveNode);
+  }
+
+  /**
+   * Archives nodes by setting their archive timestamp.
+   *
+   * This is a drive-level archive state and does not delete the underlying
+   * storage assets.
+   *
+   * @param ids - The node ids to archive.
+   * @returns A promise resolving to the archived nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  async archiveNodes(ids: string[]) {
+    if (ids.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No node ids provided" });
+    }
+
+    const result = await this.#db
+      .update(nodes)
+      .set({ archivedAt: new Date() })
+      .where(and(inArray(nodes.id, [...new Set(ids)]), isNull(nodes.archivedAt)))
+      .returning();
+
+    if (result.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No matching nodes found" });
+    }
+
+    return result.map(toLocalDriveNode);
+  }
+
+  /**
+   * Restores archived nodes by clearing their archive timestamp.
+   *
+   * @param ids - The node ids to restore.
+   * @returns A promise resolving to the restored nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  async restoreNodes(ids: string[]) {
+    if (ids.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No node ids provided" });
+    }
+
+    const result = await this.#db
+      .update(nodes)
+      .set({ archivedAt: null })
+      .where(and(inArray(nodes.id, [...new Set(ids)]), isNotNull(nodes.archivedAt)))
+      .returning();
+
+    if (result.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No matching nodes found" });
+    }
+
+    return result.map(toLocalDriveNode);
+  }
+
+  /**
+   * Permanently deletes a node subtree and all linked assets.
+   *
+   * The subtree includes the provided node and all descendants. Associated file
+   * assets and generated preview assets are purged from storage after the nodes
+   * are removed from the drive catalog.
+   *
+   * @param id - The root node id to delete.
+   * @throws {ServerError} If the node does not exist.
+   */
+  async deleteNode(id: string) {
+    const subtree = await this.getNodeChildren([id]); // includes root + descendants
+    if (subtree.length === 0) {
+      throw new ServerError("NOT_FOUND", { message: "Node not found" });
+    }
+
+    const nodeIds = [...new Set(subtree.map((node) => node.id))];
+    const assetIds = await this.#getSubtreeAssetIds(nodeIds, subtree);
+
+    // then DB cleanup
+    await this.#db.delete(nodes).where(inArray(nodes.id, nodeIds));
+
+    if (assetIds.length > 0) {
+      await this.storage.purgeAssets(assetIds);
+    }
+  }
+
+  /**
+   * Permanently deletes multiple node subtrees and their linked assets.
+   *
+   * Each provided id is treated as a subtree root. All descendant nodes are
+   * removed together with their main file assets and generated preview assets.
+   *
+   * @param ids - Root node ids to delete.
+   * @returns A promise that resolves when deletion completes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  async deleteNodes(ids: string[]) {
+    if (ids.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No node ids provided" });
+    }
+
+    const subtree = await this.getNodeChildren(ids);
+    if (subtree.length === 0) {
+      throw new ServerError("BAD_REQUEST", { message: "No matching nodes found" });
+    }
+
+    const nodeIds = [...new Set(subtree.map((node) => node.id))];
+    const assetIds = await this.#getSubtreeAssetIds(nodeIds, subtree);
+
+    /**
+     * Delete files and folders in a database
+     */
+    await this.#db.delete(nodes).where(inArray(nodes.id, nodeIds));
+
+    if (assetIds.length > 0) {
+      await this.storage.purgeAssets(assetIds);
+    }
+  }
+}