レジストリへのクエリ | EmDash CMS Everything

これはプラグインレジストリに対して独自のソフトウェアを構築するための高度なトピックです。EmDashサイトにプラグインをインストールするだけであれば、これは不要です — 設定でレジストリを有効にし、管理ダッシュボードを使用してください。

レジストリのディスカバリー側は公開の読み取り専用APIです。@emdash-cms/registry-client パッケージがこれをラップしているので、EmDash外部でプラグインディレクトリ、検索ページ、またはリリースフィードを構築できます。クライアントは fetch が利用可能なあらゆる場所 — Node、Workers、ブラウザ、またはAstroサイト — で動作します。

インストール

discovery サブパスには認証やOAuthの依存関係はありません。クライアントをインストールし、正確なバージョンに固定します：

npm install @emdash-cms/[email protected]

パッケージの一覧と解決

以下のAstroページはレジストリ内のすべてのプラグインを一覧表示します：

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

リンクは常に存在する pkg.did を使用します。パブリッシャーの handle はベストエフォートで欠落する可能性があるため、そこからURLを構築しないでください。

パッケージ詳細ページはDIDとslugでプラグインを取得し、最新のリリースを取得します：

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

ディスカバリーメソッド

クライアントはアグリゲーターのクエリごとに1つのメソッドを公開します：

searchPackages({ q, capability?, limit?, cursor? }) — フリーテキスト検索、オプションで指定されたアクセスカテゴリを宣言するパッケージにフィルタリング。{ packages, cursor? } を返します。
resolvePackage({ handle, slug }) — ハンドルとslugからパッケージを解決。
getPackage({ did, slug }) — DIDとslugでパッケージを取得。
listReleases({ did, package, limit?, cursor? }) — パッケージのすべてのリリース、最新バージョンが先頭。
getLatestRelease({ did, package }) — 取り下げられていない最高のリリースバージョン。

信頼できないレコードの処理

アグリゲーターは自身が作成していないレコードを中継する信頼できないインデックスであるため、クライアントは境界で各レコードを検証します。これから2つのルールが導かれます：

profile と release フィールドは null になることがあります。 中継されたレコードが検証に失敗すると、クライアントは呼び出し全体を失敗させるのではなく null として提示するため、1つの不正なレコードが検索ページを空白にすることはありません。pkg.profile?.name や latest.release?.artifacts.package を読み取る前に常にnullチェックしてください。
レンダリング前にURLスキームを自分で検証してください。 検証は構造をチェックしますが、URLの安全性はチェックしません — uri フィールドは javascript: スキームを含む場合があります。レジストリが提供するURLを href や src に入れる前に、独自の http/https 許可リストを適用してください。

非2xxレスポンスは ClientResponseError（パッケージから再エクスポート）をスローし、.error、.description、.status、.headers を持ちます。

ホスト互換性によるフィルタリング

リリースは requires ブロックで環境要件（EmDashまたはAstroのバージョン範囲）を宣言できます。@emdash-cms/registry-client/env サブパスがそれらを評価するため、ディレクトリは指定されたホストで実行されないリリースにフラグを立てることができます：

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

// getLatestRelease() の結果を渡します。返される配列は、
// リリースがこのホストで実行される場合は空です。
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

次に読むもの

プラグインレジストリ — EmDashサイトでレジストリを有効にして使用する
バンドルと公開 — レジストリにプラグインを公開する