Die Registry abfragen

Dies ist ein fortgeschrittenes Thema für die Entwicklung eigener Software gegen die Plugin-Registry. Wenn Sie nur Plugins auf einer EmDash-Seite installieren möchten, brauchen Sie nichts davon — aktivieren Sie die Registry in Ihrer Konfiguration und nutzen Sie das Admin-Dashboard.

Die Discovery-Seite der Registry ist eine öffentliche, schreibgeschützte API. Das Paket @emdash-cms/registry-client umhüllt diese, sodass Sie ein Plugin-Verzeichnis, eine Suchseite oder einen Release-Feed außerhalb von EmDash erstellen können. Der Client läuft überall dort, wo fetch verfügbar ist — Node, Workers, Browser oder eine Astro-Seite.

Installation

Der discovery-Unterpfad hat keine Authentifizierungs- oder OAuth-Abhängigkeiten. Installieren Sie den Client und pinnen Sie ihn auf eine exakte Version:

npm install @emdash-cms/[email protected]

Pakete auflisten und auflösen

Die folgende Astro-Seite listet alle Plugins in einer Registry auf:

---
import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

const { packages } = await discovery.searchPackages({ q: "", limit: 50 });
---

<ul>
  {
    packages.map((pkg) => (
      <li>
        <a href={`/plugins/${pkg.did}/${pkg.slug}`}>
          {pkg.profile?.name ?? pkg.slug}
        </a>
        {pkg.latestVersion && <span>v{pkg.latestVersion}</span>}
        <p>{pkg.profile?.description}</p>
      </li>
    ))
  }
</ul>

Der Link verwendet pkg.did, das immer vorhanden ist. Der Publisher-handle ist Best-Effort und kann fehlen, erstellen Sie daher keine URLs daraus.

Eine Paket-Detailseite ruft ein Plugin nach seiner DID und seinem Slug ab und holt dann das neueste Release:

import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

export async function getPlugin(did: string, slug: string) {
  const pkg = await discovery.getPackage({ did, slug });
  const latest = await discovery.getLatestRelease({
    did: pkg.did,
    package: pkg.slug,
  });
  return { pkg, latest };
}

Discovery-Methoden

Der Client stellt eine Methode pro Aggregator-Abfrage bereit:

• searchPackages({ q, capability?, limit?, cursor? }) — Volltextsuche, optional gefiltert auf Pakete, die eine bestimmte Zugriffskategorie deklarieren. Gibt { packages, cursor? } zurück.
• resolvePackage({ handle, slug }) — ein Paket über Handle und Slug auflösen.
• getPackage({ did, slug }) — ein Paket nach seiner DID und seinem Slug abrufen.
• listReleases({ did, package, limit?, cursor? }) — alle Releases eines Pakets, neueste Version zuerst.
• getLatestRelease({ did, package }) — die höchste nicht zurückgezogene Release-Version.

Umgang mit nicht vertrauenswürdigen Datensätzen

Der Aggregator ist ein nicht vertrauenswürdiger Index, der Datensätze weiterleitet, die er nicht verfasst hat, daher validiert der Client jeden einzelnen an der Grenze. Daraus ergeben sich zwei Regeln:

• Die Felder profile und release können null sein. Wenn ein weitergeleiteter Datensatz die Validierung nicht besteht, gibt der Client ihn als null zurück, anstatt den gesamten Aufruf fehlschlagen zu lassen, sodass ein fehlerhafter Datensatz keine Suchseite leer macht. Prüfen Sie immer auf null, bevor Sie pkg.profile?.name oder latest.release?.artifacts.package lesen.
• Validieren Sie URL-Schemata selbst vor dem Rendern. Die Validierung prüft die Struktur, nicht die URL-Sicherheit — ein uri-Feld kann ein javascript:-Schema enthalten. Wenden Sie Ihre eigene http/https-Erlaubnisliste an, bevor Sie eine Registry-gelieferte URL in ein href oder src einfügen.

Eine Nicht-2xx-Antwort wirft ClientResponseError (aus dem Paket re-exportiert), mit .error, .description, .status und .headers.

Filterung nach Host-Kompatibilität

Ein Release kann Umgebungsanforderungen (einen EmDash- oder Astro-Versionsbereich) in seinem requires-Block deklarieren. Der Unterpfad @emdash-cms/registry-client/env wertet diese aus, sodass ein Verzeichnis Releases markieren kann, die auf einem bestimmten Host nicht laufen:

import { checkEnvCompatibility, hostEnvFromVersions } from "@emdash-cms/registry-client/env";
import type { ValidatedReleaseView } from "@emdash-cms/registry-client/discovery";

const host = hostEnvFromVersions("0.17.0", "5.6.0");

// Übergeben Sie ein getLatestRelease()-Ergebnis. Das zurückgegebene Array ist leer,
// wenn das Release auf diesem Host läuft.
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

Weiterführende Lektüre

• Die Plugin-Registry — Registry auf einer EmDash-Seite aktivieren und verwenden
• Bundling und Veröffentlichung — ein Plugin in der Registry veröffentlichen