E EmDash CMS Everything Guides, use cases, plugins, templates
Italiano

Interrogare il registro

In questa pagina

Questo è un argomento avanzato per costruire il proprio software contro il registro dei plugin. Se vuoi solo installare plugin su un sito EmDash, non hai bisogno di nulla di questo — abilita il registro nella tua configurazione e usa il pannello di amministrazione.

Il lato discovery del registro è un’API pubblica di sola lettura. Il pacchetto @emdash-cms/registry-client lo avvolge, così puoi costruire una directory di plugin, una pagina di ricerca o un feed di release al di fuori di EmDash. Il client funziona ovunque fetch sia disponibile — Node, Workers, il browser o un sito Astro.

Installazione

Il sottopercorso discovery non ha dipendenze di autenticazione o OAuth. Installa il client e fissalo a una versione esatta:

npm install @emdash-cms/[email protected]

Elencare e risolvere pacchetti

La seguente pagina Astro elenca ogni plugin in un registro:

---
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>

Il link usa pkg.did, che è sempre presente. L’handle del publisher è best-effort e può essere assente, quindi non costruire URL da esso.

Una pagina di dettaglio del pacchetto recupera un plugin tramite il suo DID e slug, poi recupera l’ultima 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 };
}

Metodi di discovery

Il client espone un metodo per query dell’aggregatore:

  • searchPackages({ q, capability?, limit?, cursor? }) — ricerca a testo libero, opzionalmente filtrata ai pacchetti che dichiarano una data categoria di accesso. Restituisce { packages, cursor? }.
  • resolvePackage({ handle, slug }) — risolvere un pacchetto da un handle e slug.
  • getPackage({ did, slug }) — recuperare un pacchetto tramite il suo DID e slug.
  • listReleases({ did, package, limit?, cursor? }) — tutte le release di un pacchetto, versione più recente per prima.
  • getLatestRelease({ did, package }) — la versione di release più alta non ritirata.

Gestione di record non affidabili

L’aggregatore è un indice non affidabile che inoltra record che non ha scritto, quindi il client valida ciascuno al confine. Due regole derivano da questo:

  • I campi profile e release possono essere null. Quando un record inoltrato fallisce la validazione, il client lo presenta come null invece di far fallire l’intera chiamata, così un record malformato non svuota una pagina di ricerca. Controlla sempre null prima di leggere pkg.profile?.name o latest.release?.artifacts.package.
  • Valida gli schemi URL tu stesso prima del rendering. La validazione controlla la struttura, non la sicurezza URL — un campo uri può portare uno schema javascript:. Applica la tua lista di permessi http/https prima di inserire qualsiasi URL fornito dal registro in un href o src.

Una risposta non-2xx lancia ClientResponseError (ri-esportato dal pacchetto), con .error, .description, .status e .headers.

Filtraggio per compatibilità host

Una release può dichiarare requisiti ambientali (un range di versione EmDash o Astro) nel suo blocco requires. Il sottopercorso @emdash-cms/registry-client/env li valuta, così una directory può segnalare le release che non funzioneranno su un dato host:

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");

// Passa un risultato di getLatestRelease(). L'array restituito è vuoto quando
// la release funziona su questo host.
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

Cosa leggere dopo