레지스트리 쿼리 | 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 };
}

디스커버리 메서드

클라이언트는 애그리게이터 쿼리당 하나의 메서드를 노출합니다:

searchPackages({ q, capability?, limit?, cursor? }) — 자유 텍스트 검색, 선택적으로 지정된 접근 카테고리를 선언하는 패키지로 필터링. { packages, cursor? }를 반환합니다.
resolvePackage({ handle, slug }) — 핸들과 slug로 패키지를 해석.
getPackage({ did, slug }) — DID와 slug로 패키지를 가져옴.
listReleases({ did, package, limit?, cursor? }) — 패키지의 모든 릴리스, 최신 버전 먼저.
getLatestRelease({ did, package }) — 철회되지 않은 가장 높은 릴리스 버전.

신뢰할 수 없는 레코드 처리

애그리게이터는 자신이 작성하지 않은 레코드를 중계하는 신뢰할 수 없는 인덱스이므로, 클라이언트는 경계에서 각 레코드를 검증합니다. 여기서 두 가지 규칙이 따릅니다:

profile과 release 필드는 null일 수 있습니다. 중계된 레코드가 검증에 실패하면 클라이언트는 전체 호출을 실패시키지 않고 null로 표시하므로, 하나의 잘못된 레코드가 검색 페이지를 비우지 않습니다. pkg.profile?.name이나 latest.release?.artifacts.package를 읽기 전에 항상 null 확인을 하세요.
렌더링 전에 URL 스킴을 직접 검증하세요. 검증은 구조를 확인하지만 URL 안전성은 확인하지 않습니다 — uri 필드는 javascript: 스킴을 포함할 수 있습니다. 레지스트리에서 제공한 URL을 href나 src에 넣기 전에 자체 http/https 허용 목록을 적용하세요.

비2xx 응답은 ClientResponseError(패키지에서 재내보내기)를 throw하며, .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 사이트에서 레지스트리를 활성화하고 사용
번들링 및 게시 — 레지스트리에 플러그인 게시