Skip to content

armgit / BYOC

Public Imported from GitHub
0

One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.

15.0 KB
Raw Blame
import {
  withRetry,
  StorageError,
  BYOCErrorCode,
  encodePathSegments,
  type StorageObject,
  type StorageInput,
  type StorageQuota,
  type UploadProgress
} from "@byoc/core";
import { Readable } from "node:stream";

export interface WebDAVClientConfig {
  endpoint: string;
  username?: string;
  password?: string;
  token?: string;
}

export class WebDAVHttpClient {
  private readonly baseUrl: string;

  constructor(public readonly config: WebDAVClientConfig) {
    this.baseUrl = config.endpoint.replace(/\/+$/, "");
  }

  private getAuthHeader(): string | undefined {
    if (this.config.token) {
      return `Bearer ${this.config.token}`;
    }
    if (this.config.username && this.config.password) {
      const creds = `${this.config.username}:${this.config.password}`;
      return `Basic ${Buffer.from(creds).toString("base64")}`;
    }
    return undefined;
  }

  public getFullUrl(path: string): string {
    const encoded = encodePathSegments(path);
    return `${this.baseUrl}/${encoded}`;
  }

  public async put(
    path: string,
    data: StorageInput,
    mimeType?: string,
    onProgress?: (progress: UploadProgress) => void,
    contentLength?: number
  ): Promise<StorageObject> {
    const url = this.getFullUrl(path);
    let bodyPayload: any;
    let payloadSize: number | undefined;
    let isStreaming = false;

    if (typeof data === "string") {
      const bytes = new TextEncoder().encode(data);
      bodyPayload = bytes;
      payloadSize = bytes.byteLength;
    } else if (data instanceof Uint8Array) {
      bodyPayload = data;
      payloadSize = data.byteLength;
    } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
      bodyPayload = data;
      payloadSize = data.byteLength;
    } else if (data instanceof ArrayBuffer) {
      bodyPayload = new Uint8Array(data);
      payloadSize = data.byteLength;
    } else if (typeof Blob !== "undefined" && data instanceof Blob) {
      bodyPayload = data;
      payloadSize = data.size;
    } else if (
      (typeof ReadableStream !== "undefined" && data instanceof ReadableStream) ||
      (typeof Readable !== "undefined" && data instanceof Readable) ||
      // A bare async generator is neither of the above but is the most natural
      // way to write a producer in TypeScript, and StorageInput accepts it.
      typeof (data as AsyncIterable<Uint8Array>)?.[Symbol.asyncIterator] === "function"
    ) {
      bodyPayload = data;
      isStreaming = true;
    } else {
      throw new StorageError({
        code: BYOCErrorCode.INVALID_INPUT,
        message: "Unsupported data payload type for WebDAV upload.",
        provider: "webdav"
      });
    }

    if (contentLength !== undefined) {
      if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
        throw new StorageError({
          code: BYOCErrorCode.INVALID_INPUT,
          message: `WebDAV upload contentLength must be a non-negative safe integer (received ${contentLength}).`,
          provider: "webdav",
          retryable: false
        });
      }
      if (payloadSize !== undefined && payloadSize !== contentLength) {
        throw new StorageError({
          code: BYOCErrorCode.INVALID_INPUT,
          message: `WebDAV upload contentLength ${contentLength} does not match the ${payloadSize}-byte input.`,
          provider: "webdav",
          retryable: false
        });
      }
      payloadSize = contentLength;
    }

    const headers: Record<string, string> = {
      "Content-Type": mimeType || "application/octet-stream"
    };

    if (payloadSize !== undefined) {
      headers["Content-Length"] = String(payloadSize);
    }

    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    // A stream of unknown length still has to report an accurate size, so the
    // bytes are counted as they pass through rather than guessed at.
    let streamedBytes = 0;
    if (isStreaming && payloadSize === undefined) {
      const source = bodyPayload as AsyncIterable<Uint8Array>;
      bodyPayload = (async function* () {
        for await (const chunk of source) {
          streamedBytes += chunk.byteLength;
          onProgress?.({
            bytesUploaded: streamedBytes,
            totalBytes: undefined,
            percentage: undefined
          });
          yield chunk;
        }
      })();
    }

    return withRetry(async () => {
      const response = await fetch(url, {
        method: "PUT",
        headers,
        body: bodyPayload,
        // @ts-ignore Node fetch streaming support
        duplex: "half"
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }

      if (onProgress && payloadSize !== undefined) {
        onProgress({
          bytesUploaded: payloadSize,
          totalBytes: payloadSize,
          percentage: 100
        });
      }

      const etag = response.headers.get("etag")?.replace(/"/g, "");

      return {
        id: `webdav_${path}`,
        path,
        name: path.split("/").pop() || path,
        provider: "webdav",
        providerId: path,
        size: payloadSize ?? streamedBytes,
        mimeType: mimeType || "application/octet-stream",
        checksum: etag,
        updatedAt: new Date()
      };
    }, {
      // WebDAV PUT has no portable offset-resume handshake. A consumed stream
      // cannot be retried safely, while buffered bodies remain replayable.
      maxRetries: isStreaming ? 0 : 3
    });
  }

  public async get(path: string): Promise<Response> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {};
    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    return withRetry(async () => {
      const response = await fetch(url, {
        method: "GET",
        headers
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }

      return response;
    });
  }

  public async delete(path: string): Promise<void> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {};
    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    await withRetry(async () => {
      const response = await fetch(url, {
        method: "DELETE",
        headers
      });

      if (!response.ok && response.status !== 404 && response.status !== 204) {
        throw await this.handleErrorResponse(response);
      }
    });
  }

  public async mkcol(path: string): Promise<void> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {};
    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    await withRetry(async () => {
      const response = await fetch(url, {
        method: "MKCOL",
        headers
      });

      // 201 Created or 405 (Folder already exists) are successful
      if (!response.ok && response.status !== 405 && response.status !== 301) {
        throw await this.handleErrorResponse(response);
      }
    });
  }

  public async head(path: string): Promise<StorageObject> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {};
    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    return withRetry(async () => {
      const response = await fetch(url, {
        method: "HEAD",
        headers
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }

      const contentType = response.headers.get("content-type") || "application/octet-stream";
      const contentLength = response.headers.get("content-length");
      const etag = response.headers.get("etag")?.replace(/"/g, "");
      const lastModified = response.headers.get("last-modified");

      return {
        id: `webdav_${path}`,
        path,
        name: path.split("/").pop() || path,
        provider: "webdav",
        providerId: path,
        size: contentLength ? Number(contentLength) : undefined,
        mimeType: contentType,
        checksum: etag,
        updatedAt: lastModified ? new Date(lastModified) : undefined
      };
    });
  }

  public async copy(sourcePath: string, destPath: string, overwrite: boolean = true): Promise<void> {
    const sourceUrl = this.getFullUrl(sourcePath);
    const destUrl = this.getFullUrl(destPath);
    const headers: Record<string, string> = {
      Destination: destUrl,
      Overwrite: overwrite ? "T" : "F"
    };

    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    await withRetry(async () => {
      const response = await fetch(sourceUrl, {
        method: "COPY",
        headers
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }
    });
  }

  public async move(sourcePath: string, destPath: string, overwrite: boolean = true): Promise<void> {
    const sourceUrl = this.getFullUrl(sourcePath);
    const destUrl = this.getFullUrl(destPath);
    const headers: Record<string, string> = {
      Destination: destUrl,
      Overwrite: overwrite ? "T" : "F"
    };

    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    await withRetry(async () => {
      const response = await fetch(sourceUrl, {
        method: "MOVE",
        headers
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }
    });
  }

  public async propfind(path: string, depth: number = 1, rootFolder: string = ""): Promise<StorageObject[]> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {
      Depth: String(depth),
      "Content-Type": "application/xml; charset=utf-8"
    };

    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    return withRetry(async () => {
      const response = await fetch(url, {
        method: "PROPFIND",
        headers
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }

      const xmlText = await response.text();
      return parseWebDavPropfindXml(xmlText, path, rootFolder);
    });
  }

  /**
   * RFC 4331: Query storage quota via PROPFIND Depth: 0
   */
  public async getQuota(path: string = ""): Promise<StorageQuota> {
    const url = this.getFullUrl(path);
    const headers: Record<string, string> = {
      Depth: "0",
      "Content-Type": "application/xml; charset=utf-8"
    };

    const auth = this.getAuthHeader();
    if (auth) headers["Authorization"] = auth;

    const queryBody = `<?xml version="1.0" encoding="utf-8" ?>
<d:propfind xmlns:d="DAV:">
  <d:prop>
    <d:quota-available-bytes/>
    <d:quota-used-bytes/>
  </d:prop>
</d:propfind>`;

    return withRetry(async () => {
      const response = await fetch(url, {
        method: "PROPFIND",
        headers,
        body: queryBody
      });

      if (!response.ok) {
        throw await this.handleErrorResponse(response);
      }

      const xml = await response.text();
      const availMatch = xml.match(/<[a-zA-Z0-9:]*quota-available-bytes>(\d+)<\/[a-zA-Z0-9:]*quota-available-bytes>/i);
      const usedMatch = xml.match(/<[a-zA-Z0-9:]*quota-used-bytes>(\d+)<\/[a-zA-Z0-9:]*quota-used-bytes>/i);

      const available = availMatch && availMatch[1] ? Number(availMatch[1]) : undefined;
      const used = usedMatch && usedMatch[1] ? Number(usedMatch[1]) : 0;
      const total = available !== undefined ? used + available : undefined;

      return {
        used,
        total,
        available
      };
    });
  }

  private async handleErrorResponse(response: Response): Promise<StorageError> {
    const errorText = await response.text().catch(() => response.statusText);

    if (response.status === 404) {
      return new StorageError({
        code: BYOCErrorCode.OBJECT_NOT_FOUND,
        message: "WebDAV object not found (404).",
        provider: "webdav",
        statusCode: 404,
        retryable: false
      });
    }

    if (response.status === 401 || response.status === 403) {
      return new StorageError({
        code: BYOCErrorCode.PERMISSION_DENIED,
        message: "WebDAV authentication failed: Invalid credentials or permission denied.",
        provider: "webdav",
        statusCode: response.status,
        retryable: false
      });
    }

    if (response.status === 507) {
      return new StorageError({
        code: BYOCErrorCode.QUOTA_EXCEEDED,
        message: "WebDAV insufficient storage / user quota exceeded (507).",
        provider: "webdav",
        statusCode: 507,
        retryable: false
      });
    }

    return new StorageError({
      code: BYOCErrorCode.PROVIDER_UNAVAILABLE,
      message: `WebDAV Server Error (${response.status}): ${errorText}`,
      provider: "webdav",
      statusCode: response.status,
      retryable: response.status >= 500
    });
  }
}

/**
 * Parses WebDAV PROPFIND Multistatus XML responses extracting child files and folders.
 */
export function parseWebDavPropfindXml(xml: string, targetPath: string, rootFolder: string = ""): StorageObject[] {
  const results: StorageObject[] = [];
  const cleanTarget = targetPath.replace(/^\/+|\/+$/g, "");

  const responseMatches = xml.matchAll(/<[a-zA-Z0-9:]*response>([\s\S]*?)<\/[a-zA-Z0-9:]*response>/g);

  for (const match of responseMatches) {
    const block = match[1] || "";
    const hrefMatch = block.match(/<[a-zA-Z0-9:]*href>(.*?)<\/[a-zA-Z0-9:]*href>/);
    if (!hrefMatch || !hrefMatch[1]) continue;

    const rawHref = decodeURI(hrefMatch[1]);
    const normalizedHref = rawHref.replace(/\/+$/, "");
    const segments = normalizedHref.split("/").filter(Boolean);
    const itemName = segments[segments.length - 1] || "";

    // Skip the parent directory self-reference
    if (!itemName || normalizedHref.endsWith(cleanTarget)) {
      continue;
    }

    const isFolder = /<[a-zA-Z0-9:]*collection\s*\/?>/i.test(block);
    const sizeMatch = block.match(/<[a-zA-Z0-9:]*getcontentlength>(\d+)<\/[a-zA-Z0-9:]*getcontentlength>/);
    const typeMatch = block.match(/<[a-zA-Z0-9:]*getcontenttype>(.*?)<\/[a-zA-Z0-9:]*getcontenttype>/);
    const etagMatch = block.match(/<[a-zA-Z0-9:]*getetag>(.*?)<\/[a-zA-Z0-9:]*getetag>/);
    const lastModMatch = block.match(/<[a-zA-Z0-9:]*getlastmodified>(.*?)<\/[a-zA-Z0-9:]*getlastmodified>/);

    const relativePath = cleanTarget ? `${cleanTarget}/${itemName}` : itemName;
    const cleanRoot = rootFolder.replace(/^\/+|\/+$/g, "");
    const virtualPath = cleanRoot && relativePath.startsWith(cleanRoot + "/")
      ? relativePath.substring(cleanRoot.length + 1)
      : cleanRoot && relativePath === cleanRoot
        ? ""
        : relativePath;

    results.push({
      id: `webdav_${relativePath}`,
      path: virtualPath,
      name: itemName,
      provider: "webdav",
      providerId: relativePath,
      type: isFolder ? "folder" : "file",
      size: sizeMatch && sizeMatch[1] ? Number(sizeMatch[1]) : undefined,
      mimeType: typeMatch && typeMatch[1] ? typeMatch[1].trim() : isFolder ? undefined : "application/octet-stream",
      checksum: etagMatch && etagMatch[1] ? etagMatch[1].replace(/"/g, "") : undefined,
      updatedAt: lastModMatch && lastModMatch[1] ? new Date(lastModMatch[1]) : undefined
    });
  }

  return results;
}