add: support the codeberg (#173)

Author: XiangYyang

src/base/base64.ts

@@ -0,0 +1,18 @@
+/*
+    Copyright (c) 2025 Xiang Yang.
+    Published under the standard MIT License.
+    Full text available at: https://opensource.org/licenses/MIT
+*/
+export class BaseDecodeError extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+export function base64_decode(str: string): string {
+    try {
+        return atob(str);
+    } catch (error) {
+        throw new BaseDecodeError("Failed to decode base64 string: " + error);
+    }
+}

src/kicanvas/elements/kicanvas-shell.ts

@@ -11,8 +11,8 @@ import { CSS, attribute, html, query } from "../../base/web-components";
 import { KCUIElement, KCUIIconElement } from "../../kc-ui";
 import { sprites_url } from "../icons/sprites";
 import { Project } from "../project";
-import { GitHub } from "../services/github";
 import { GitHubFileSystem } from "../services/github-vfs";
+import { CodebergFileSystem } from "../services/codeberg-vfs";
 import { FetchFileSystem, type VirtualFileSystem } from "../services/vfs";
 import { KCBoardAppElement } from "./kc-board/app";
 import { KCSchematicAppElement } from "./kc-schematic/app";
@@ -82,7 +82,11 @@ class KiCanvasShellElement extends KCUIElement {
 
     override initialContentCallback() {
         const url_params = new URLSearchParams(document.location.search);
-        const github_paths = url_params.getAll("github");
+
+        const urls = [
+            ...url_params.getAll("github"),
+            ...url_params.getAll("repo"),
+        ];
 
         later(async () => {
             if (this.src) {
@@ -91,8 +95,12 @@ class KiCanvasShellElement extends KCUIElement {
                 return;
             }
 
-            if (github_paths.length) {
-                const vfs = await GitHubFileSystem.fromURLs(...github_paths);
+            if (urls.length) {
+                const vfs = await this.load_repo(...urls);
+                if (!vfs) {
+                    return;
+                }
+
                 await this.setup_project(vfs);
                 return;
             }
@@ -104,15 +112,18 @@ class KiCanvasShellElement extends KCUIElement {
 
         this.link_input.addEventListener("input", async (e) => {
             const link = this.link_input.value;
-            if (!GitHub.parse_url(link)) {
+            const vfs = await this.load_repo(link);
+
+            if (!vfs) {
+                // TODO: show error message: invaild URL
+                console.error(`Invalid URL: ${link}`);
                 return;
             }
 
-            const vfs = await GitHubFileSystem.fromURLs(link);
             await this.setup_project(vfs);
 
             const location = new URL(window.location.href);
-            location.searchParams.set("github", link);
+            location.searchParams.set("repo", link);
             window.history.pushState(null, "", location);
         });
 
@@ -123,6 +134,15 @@ class KiCanvasShellElement extends KCUIElement {
         });
     }
 
+    private async load_repo(
+        ...url: string[]
+    ): Promise<VirtualFileSystem | null> {
+        return (
+            (await GitHubFileSystem.fromURLs(...url)) ??
+            (await CodebergFileSystem.fromURLs(...url))
+        );
+    }
+
     private async setup_project(vfs: VirtualFileSystem) {
         this.loaded = false;
         this.loading = true;
@@ -174,7 +194,7 @@ class KiCanvasShellElement extends KCUIElement {
                     <input
                         name="link"
                         type="text"
-                        placeholder="Paste a GitHub link..."
+                        placeholder="Paste a GitHub/Codeberg link..."
                         autofocus />
                     <p>
                         or drag & drop your KiCad files, or<button

src/kicanvas/services/api-error.ts

@@ -0,0 +1,50 @@
+/*
+    Copyright (c) 2025 Xiang Yang.
+    Published under the standard MIT License.
+    Full text available at: https://opensource.org/licenses/MIT
+*/
+export class BaseAPIError extends Error {
+    constructor(
+        public override name: string,
+        public url: string,
+        public description: string,
+        public response?: Response,
+    ) {
+        super(`API Error: ${name}: ${url}: ${description}`);
+    }
+}
+
+export class UnknownError extends BaseAPIError {
+    constructor(url: string, description: string, response: Response) {
+        super(`UnknownError`, url, description, response);
+    }
+}
+
+export class NotFoundError extends BaseAPIError {
+    constructor(url: string, response: Response) {
+        super(`NotFoundError`, url, "not found", response);
+    }
+}
+
+export class ForbiddenError extends BaseAPIError {
+    constructor(url: string, response: Response) {
+        super(`ForbiddenError`, url, "forbidden", response);
+    }
+}
+
+export async function request_error_handler(response: Response) {
+    switch (response.status) {
+        case 200:
+            return;
+        case 403:
+            throw new ForbiddenError(response.url, response);
+        case 404:
+            throw new NotFoundError(response.url, response);
+        case 500:
+            throw new UnknownError(
+                response.url,
+                await response.text(),
+                response,
+            );
+    }
+}

src/kicanvas/services/codeberg-vfs.ts

@@ -0,0 +1,97 @@
+/*
+    Copyright (c) 2025 Xiang Yang.
+    Published under the standard MIT License.
+    Full text available at: https://opensource.org/licenses/MIT
+*/
+import { base64_decode } from "../../base/base64";
+import { initiate_download } from "../../base/dom/download";
+import { extension } from "../../base/paths";
+import { Codeberg, GetBlobResponse, RepoContentResponse } from "./codeberg";
+import { VirtualFileSystem } from "./vfs";
+
+export class CodebergFileSystem extends VirtualFileSystem {
+    static readonly kicad_extensions = ["kicad_pcb", "kicad_pro", "kicad_sch"];
+
+    constructor(private files_to_urls: Map<string, URL>) {
+        super();
+    }
+
+    public static async fromURLs(
+        ...urls: (string | URL)[]
+    ): Promise<CodebergFileSystem | null> {
+        const files_to_urls = new Map<string, URL>();
+
+        for (const url of urls) {
+            const info = Codeberg.parse_url(url);
+            if (!info) {
+                continue;
+            }
+
+            // API:
+            // https://codeberg.org/api/swagger#/repository/repoGetContents
+            const api_url = `repos/${info.owner}/${info.repo}/contents/${info.path}`;
+
+            let files = await Codeberg.request_json<
+                RepoContentResponse | RepoContentResponse[]
+            >(api_url);
+
+            if (!Array.isArray(files)) {
+                files = [files];
+            }
+
+            for (const file of files) {
+                if (!file.name || !file.git_url || file.type !== "file") {
+                    continue;
+                }
+
+                if (
+                    !CodebergFileSystem.kicad_extensions.includes(
+                        extension(file.name),
+                    )
+                ) {
+                    continue;
+                }
+
+                files_to_urls.set(file.name, new URL(file.git_url));
+            }
+        }
+
+        if (files_to_urls.size == 0) {
+            // no valid URL and files, return null.
+            return null;
+        }
+
+        return new CodebergFileSystem(files_to_urls);
+    }
+
+    override *list(): Generator<string> {
+        yield* this.files_to_urls.keys();
+    }
+
+    override async get(name: string): Promise<File> {
+        const url = this.files_to_urls.get(name);
+        if (!url) {
+            throw new Error(`File ${name} not found.`);
+        }
+
+        // API: https://codeberg.org/api/swagger#/repository/GetBlob
+        const blob = await Codeberg.request_json<GetBlobResponse>(url.pathname);
+
+        if (blob.encoding !== "base64") {
+            throw new Error(`Unsupported encoding: ${blob.encoding}`);
+        }
+
+        const content = base64_decode(blob.content);
+        const file = new File([content], name);
+
+        return file;
+    }
+
+    override has(name: string): Promise<boolean> {
+        return Promise.resolve(this.files_to_urls.has(name));
+    }
+
+    override async download(name: string): Promise<void> {
+        initiate_download(await this.get(name));
+    }
+}

src/kicanvas/services/codeberg.ts

@@ -0,0 +1,116 @@
+/*
+    Copyright (c) 2025 Xiang Yang.
+    Published under the standard MIT License.
+    Full text available at: https://opensource.org/licenses/MIT
+*/
+import { request_error_handler } from "./api-error";
+
+export class RepoContentResponse {
+    name: string;
+    path: string;
+    type: string;
+    sha: string;
+    url: string;
+    git_url: string;
+}
+
+export class GetBlobResponse {
+    content: string;
+    encoding: string;
+    sha: string;
+    size: number;
+    url: string;
+}
+
+export class Codeberg {
+    static readonly host_name = "codeberg.org";
+    static readonly html_base_url = "https://codeberg.org/";
+    static readonly base_url = "https://codeberg.org/api/v1/";
+    static readonly accept_header = "application/json";
+
+    static parse_url(url: string | URL) {
+        url = new URL(url, Codeberg.html_base_url);
+        if (url.hostname !== Codeberg.host_name) {
+            return null;
+        }
+
+        const path_parts = url.pathname.split("/");
+
+        if (path_parts.length < 3) {
+            return null;
+        }
+
+        const [, owner, repo, ...parts] = path_parts;
+
+        let ref, path;
+        if (parts.length > 0) {
+            // owner/repo/src/<commit|branch>/<ref>/<rel_path>
+            const typ = parts.shift();
+            if (typ !== "src") {
+                return null;
+            }
+
+            const ref_type = parts.shift();
+            if (ref_type !== "commit" && ref_type !== "branch") {
+                return null;
+            }
+
+            ref = parts.shift();
+            if (!ref) {
+                return null;
+            }
+
+            path = parts.join("/");
+        } else {
+            // owner/repo
+            ref = "main";
+            path = ".";
+        }
+
+        return {
+            owner: owner,
+            repo: repo,
+            ref: ref,
+            path: path,
+        };
+    }
+
+    static async request(
+        path: string,
+        params?: Record<string, string>,
+        data?: unknown,
+    ): Promise<string> {
+        const url = new URL(path, Codeberg.base_url);
+
+        if (params) {
+            const url_params = new URLSearchParams(params).toString();
+            url.search = `?${url_params}`;
+        }
+
+        const request = new Request(url, {
+            method: data ? "POST" : "GET",
+            headers: {
+                Accept: Codeberg.accept_header,
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+
+        const response = await fetch(request);
+        await request_error_handler(response);
+
+        return await response.text();
+    }
+
+    static async request_json<T>(
+        path: string,
+        params?: Record<string, string>,
+        data?: unknown,
+    ): Promise<T> {
+        const text = await Codeberg.request(path, params, data);
+        try {
+            return JSON.parse(text) as T;
+        } catch (error) {
+            throw new Error("Failed to parse JSON response: " + error);
+        }
+    }
+}

src/kicanvas/services/github-vfs.ts

@@ -21,7 +21,9 @@ export class GitHubFileSystem extends VirtualFileSystem {
         super();
     }
 
-    public static async fromURLs(...urls: (string | URL)[]) {
+    public static async fromURLs(
+        ...urls: (string | URL)[]
+    ): Promise<GitHubFileSystem | null> {
         // Handles URLs like this:
         // https://github.com/wntrblm/Helium/blob/main/hardware/board/board.kicad_sch
 
@@ -81,6 +83,11 @@ export class GitHubFileSystem extends VirtualFileSystem {
             }
         }
 
+        if (files_to_urls.size == 0) {
+            // no valid URL and files, return null.
+            return null;
+        }
+
         return new GitHubFileSystem(files_to_urls);
     }