로그인브리핑 예약

챕터 2.21

Plugin SDK

Plugin SDK(소프트웨어 개발 키트) 설치, 명령줄 도구, 풀 서비스 템플릿 둘러보기, 필드별 v2 매니페스트, 그리고 플러그인이 규칙을 준수하도록 하는 22개의 게이트를 알아봅니다.

이 페이지는 AI에 의해 영어 원문에서 번역되었습니다. 불명확한 내용이 있는 경우 영어 페이지를 기준으로 삼으십시오. 이 페이지를 영어로 읽기

읽는 시간 22분

두 번째 플러그인을 만들 때는 첫 번째의 3분의 1밖에 시간이 걸리지 않았는데, 절약된 시간의 거의 전부는 SDK(소프트웨어 개발 키트) 덕분이었습니다. 첫 번째에는 스코프 검사, 구성 로더, 마이그레이션 러너를 직접 작성했지만 리뷰어가 그 모든 것을 반려했습니다. 두 번째에는 스캐폴드 명령어를 한 번 실행하고 샘플 감성 스킬을 삭제한 뒤, 비행 역학 팀이 실제로 필요로 하던 이상 징후 검토 레코드 작업에 온전히 시간을 쏟았습니다.

@adverant-nexus/plugin-sdk은 하나의 npm 패키지입니다. 여기에는 v2 매니페스트 스키마와 이를 읽는 검증기(definePlugin, defineSkill), 스코프, 데이터베이스, 디스패치 등을 위해 플러그인이 임포트하는 런타임 모듈, 테스트 헬퍼, 준수 게이트, 그리고 명령줄 도구가 들어 있습니다. 이 장에서는 패키지 설치, 도구, 템플릿, 매니페스트 및 게이트를 다룹니다. 2.22장, 플러그인 런타임에서는 실행 중인 코드 내의 런타임 모듈을 다룹니다.

설치하기

이 패키지는 공개 npm 레지스트리가 아닌 https://registry.adverant.ai/npm/의 Adverant 레지스트리에서 제공되며, 계정의 "Pull tokens and install commands" 페이지에서 풀 토큰을 받아야 합니다. 리포지토리의 .npmrc에서 @adverant-nexus 스코프가 해당 레지스트리를 가리키도록 설정하십시오:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token>은 계정 페이지에서 받은 토큰입니다. 파이프라인에서는 이를 시크릿으로 전달하고 절대 커밋하지 마십시오. 템플릿의 Dockerfile은 이 토큰이 없으면 빌드를 거부하며 npm ci이 실행된 후 빌드 스테이지에서 .npmrc을 삭제하므로, 토큰이 이미지에 포함되어 배포되는 일은 없습니다.

그런 다음 버전을 정확히 고정하십시오:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

첫 설치 시 package-lock.json을 커밋하십시오. 템플릿의 이미지 빌드는 npm ci을 실행하며 npm install로의 폴백을 거부합니다. 즉, 락파일이 곧 계약입니다. SDK 자체의 최소 요구 사양은 Node 18이며, 템플릿은 Node 20을 대상으로 합니다.

명령줄 도구는 패키지 내부에 포함되어 배포되므로, 이 문서의 모든 명령어는 npx -p을 사용하여 패키지와 그 버전을 지정합니다. 단독으로 실행할 경우 npx create-nexus-plugin는 공개 레지스트리에서 조회되는데, 해당 이름은 이 패키지가 아닙니다.

명령줄 도구

도구 수행 작업
create-nexus-plugin 플러그인을 스캐폴딩하고, 매니페스트를 검증하며, v1 매니페스트를 v2로 마이그레이션하고, 프런트엔드 개발자를 위한 컨슈머 가이드를 렌더링합니다
nexus-tenancy 매니페스트로부터 스키마의 테넌시 SQL(역할, 권한 부여, 행 수준 보안 템플릿 및 그래프 테이블)을 렌더링합니다
nexus-migrate 마이그레이션을 적용합니다. 역할을 한 번 프로비저닝한 다음, 번호가 매겨진 각 파일을 마이그레이터 역할로 실행합니다
nexus-gates 모든 준수 게이트와 각 게이트 자체의 셀프 테스트를 실행합니다

create-nexus-plugin은 네트워크 호출을 하지 않으며 원격 코드도 로드하지 않습니다. 플랫폼의 온보딩이 실행하는 것과 동일한 인프로세스 검증기를 실행하므로, "내 머신에서는 검증을 통과함"과 "플랫폼이 이를 수락함" 사이에 불일치가 발생하지 않습니다.

명령어 플래그 수행 작업 종료 코드(Exit code)
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print 새 플러그인 디렉터리를 작성합니다. --print은 매니페스트만 출력합니다 0 작성됨 · 1 덮어쓰기 거부됨 · 2 잘못된 사용법
validate <file> nexus.manifest.json 또는 이를 익스포트하는 .ts이나 .js 모듈을 검증합니다 0 유효함 · 1 유효하지 않거나 읽을 수 없음 · 2 잘못된 사용법
migrate <file> --write v1 매니페스트를 v2로 격상하여 출력하거나 제자리에 덮어씁니다 0 · 1 · 2, 위와 같음
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint 매니페스트와 설명 텍스트로부터 컨슈머 가이드를 렌더링합니다. --check은 커밋된 사본과 비교하며 아무것도 작성하지 않습니다 0 · 1 드리프트 또는 린트 위반 · 2 잘못된 사용법
help 사용법을 출력합니다 0

스캐폴딩 및 세 가지 티어

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier의 기본값은 full-service입니다. 스캐폴더는 이미 존재하는 디렉터리에 쓰기를 거부하며, 스캐폴더가 작성하는 매니페스트는 이미 검증을 통과한 상태입니다. 즉, 유효하지 않은 매니페스트는 절대 생성하지 않습니다.

플러그인이 가진 구성 요소에 따라 티어를 선택하십시오.

티어 보유 구성 요소 필수 선언 항목
skills-only 매니페스트 스킬만 있고 다른 것은 없음 최소 하나 이상의 항목이 있는 skills[]
ui-only 셸 내부의 프런트엔드 서피스 frontend
full-service 백엔드 및 프런트엔드(보통 자체 스키마 포함) backend 및 frontend, 그리고 백엔드가 있으므로 runtime.healthCheck

확신이 서지 않는다면 full-service을 스캐폴딩한 뒤 필요 없는 부분을 삭제하십시오. 반대로 진행하면 템플릿이 제공했을 부분들을 직접 작성해야 합니다.

풀 서비스 템플릿 둘러보기

이 템플릿은 이후의 모든 장에서 전제로 하는 엄격한 패턴에 맞춰 구축된 레퍼런스 플러그인입니다. 샘플 로직이 아니라 그 구조를 복제하십시오.

경로 설명
nexus.manifest.json v2 매니페스트: 재천명된 3대 법칙, 라우트 테이블 및 권한 레지스터
src/config.ts 구성 로더. 단일 스펙을 한 번 읽으며, 프로세스가 부팅을 거부하기 전에 모든 문제를 수집합니다
src/scope.ts SDK의 엄격한 토큰 검증기와 두 가지 체제(개인의 베어러 토큰 및 플랫폼의 서비스 호출)를 사용하여 요청을 스코프로 변환하는 단일 파일
src/db.ts 모든 구문은 tenantFence()을 구성하며 withScopedTx 내부에서 실행됩니다
src/uno.ts 단일 디스패치 파일: 하나의 URL, 하나의 클라이언트, 폐쇄형 허용 목록
src/routes/*.ts health(익명, 정확한 경로), /api 라우트(스코프 적용됨) 및 /internal 콜백(서비스 가드 적용됨)
src/skills/sentiment.ts 결정론적 host_callback 스킬. 어휘 목록을 자체 로직으로 교체하십시오
src/server.ts 컴포지션 루트: 거부 원장을 한 번 설치하고, 데이터베이스를 대기(시간 제한 있음)한 다음, 리스닝을 시작하기 전에 격리 및 원장 검사를 실행합니다
migrations/000_tenancy.sql 스캐폴딩 시점에 nexus-tenancy render에 의해 렌더링됨: 역할, 스키마, 행 수준 보안 템플릿
migrations/001_init.sql 테넌트 선행 복합 키와 테넌트를 포함하는 복합 외래 키가 있는 두 개의 테이블
migrations/002_refusal_ledger.sql 거부 원장이 기록하는 테이블
scripts/ci/required-env 부팅에 필요한 환경 변수 이름을 JSON으로 출력합니다
scripts/ci/shadow-migrate-*.sh nexus-migrate을 통한 파이프라인의 마이그레이션 드라이 런
gates/ 게이트의 면제 디렉터리: 비어 있으며, 이는 새 플러그인의 올바른 상태입니다
test/ 모든 테스트가 주입하는 스코프 더블을 포함한 스코프, 라우트, 데이터베이스, 디스패치 및 부팅에 대한 테스트
Dockerfile 마이그레이션이 내부에 포함된 비루트 이미지(사용자 ID 10001)

이 파일들 중 몇 가지는 좀 더 자세히 살펴볼 가치가 있습니다.

src/config.ts은 두 가지 규칙을 따릅니다. 예외를 던지기 전에 모든 문제를 수집하므로, 다섯 번 재시작하며 누락된 변수를 하나씩 알려주는 대신 한 번의 재시작으로 누락된 변수 다섯 개를 모두 알려줍니다. 또한 잘못된 값이 조용히 잘못된 결과를 만들어내지 않는 경우에만 기본값을 설정합니다. 예를 들어 PORT는 잘못된 포트가 바인딩 실패를 명확히 드러내므로 기본값을 8080으로 설정할 수 있지만, DATABASE_URL과 UNO_DISPATCH_URL는 필수 항목이며 클러스터 내부 주소여야 합니다. 공개 주소는 부팅 시 거부됩니다.

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

템플릿 자체 테스트는 해당 파일을 실행하고 그 출력을 구성 스펙이 필수로 표시한 이름들과 비교하므로, 목록을 업데이트하지 않고 필수 변수를 추가하면 npm test에서 실패합니다.

src/server.ts은 데이터베이스가 응답할 때까지 리스닝하지 않으며, 대기 시간을 120초로 제한하고 실패한 모든 시도를 원인과 함께 로깅합니다. 그런 다음 순서대로 앱 역할이 테넌트를 다시 바인딩할 수 없고 모든 테이블에 행 수준 보안이 강제되어 있는지, 각 파드의 풀이 역할의 연결 제한에 부합하는지, 그리고 거부 원장 테이블이 행을 받을 수 있는지를 증명합니다. 이 세 가지 중 어느 하나라도 거부되면 전체 내용이 출력되고 프로세스는 코드 2로 종료됩니다.

필드별 v2 매니페스트

매니페스트는 플러그인이 플랫폼과 맺는 기계 판독 가능한 계약입니다. 이는 작성할 때, 플랫폼이 온보딩할 때, 그리고 그 이후에도 지속적으로 검증됩니다. 스키마는 모든 수준에서 additionalProperties: false입니다. 플러그인에 섹션이 있다면 그에 해당하는 속성이 존재하며, 선언되지 않은 키는 거부됩니다. 해결책은 항상 올바른 선택적 속성을 사용하는 것입니다.

필수 코어

필드 규칙
manifestVersion 정확히 "2"이어야 합니다. v1 문서는 마이그레이션되며, 제자리에서 재검증되지 않습니다
name ^[a-z0-9]+([-.][a-z0-9]+)*$, 최대 64자. 등록, 디스패치 네임스페이스 지정 및 테넌트 스코프 행에 사용되는 플러그인 ID입니다. 스킬을 선언하는 플러그인은 마침표가 없고 숫자로 시작하지 않는 이름도 필요합니다
displayName 1~120자
version 시맨틱 버전; 자체 릴리스 트레인
description, author, license 각각 최소 1자 이상
tier skills-only, ui-only 또는 full-service
trust core, verified, community 또는 untrusted
runtime 필수: executionMode, isolationLevel(1~4), entrypoint. 선택: nodeVersion, healthCheck, readinessCheck, livenessCheck(각각 /로 시작하는 경로). 모드는 레벨에서 파생됩니다: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture 플랫폼 3대 법칙을 재천명한 compute, ai 및 deploy. 검증기가 문구를 고정합니다

자체 설치 환경을 위해 구축하는 플러그인의 경우, 세 문장은 다음과 같습니다. ai 문장은 AI(인공지능)를 다루며, 플러그인이 모델 자격 증명을 보유하지 않음을 명시하는 곳입니다.

"architecture": {
  "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
  "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
  "deploy": "Deploy is through the installation's release channels only."
}

라우트 테이블: api 및 rights

api에는 version와 basePath가 필요하며, 선택적으로 websocket(path, auth)와 endpoints[]을 받습니다. 라우트 테이블은 스키마에서 가장 강력한 개념입니다. 게이트가 이를 코드가 실제로 등록하는 라우트와 양방향으로 비교(diff)하므로, 매니페스트는 단순한 문서가 아니라 검증 가능한 계약이 됩니다.

각 엔드포인트에는 method(GET, POST, PUT, PATCH 또는 DELETE)과 path이 필요합니다. 나머지 항목은 다음과 같습니다:

필드 설명
auth 다섯 가지 클래스 중 하나: scope(스코프 가드 뒤에 있는 개인의 라우트), service-key 및 internal(서버 간 통신용으로 브라우저에서는 절대 접근 불가), public(항상 allowAnonymous가 있는 정확한 경로만 허용), 그리고 device(디바이스 가드 뒤에 있는 자체 자격 증명을 가진 머신)
right 스코프 가드가 제공하는 모든 라우트에는 필수이며 다른 모든 라우트에서는 거부됨: rights 레지스터에 있는 권한의 이름
needsUnit 호출자의 유닛을 확인할 수 없을 때 라우트가 거부합니다
allowAnonymous 정확히 일치하는 허용 목록만 가능. 프리픽스 규칙을 사용하면 /health-of-tenant-42이 공개 상태로 노출될 수 있습니다
group, serves, screens release 블록 하위: 라우트가 제공하는 기능 그룹, 해당 그룹의 라이선스 기능이 잠겨 있을 때 응답하는 방식(data, teaser, sighting 또는 ask), 그리고 라우트가 제공하는 화면
query required(예제 값이 포함된 각 이름) 및 allowed: 라우트가 읽는 쿼리 파라미터
body example: 쓰기 라우트의 자체 검증기가 수락하는 예제 바디. GET에서는 절대 사용되지 않음

rights은 해당 라우트들이 지정하는 레지스터입니다. 각 권한에는 roles(상한선)가 있으며, 선택적으로 summary, never(다른 어떤 권한을 보유하든 절대 이 권한을 행사할 수 없는 역할), barred(never 역할을 거부할 때 제품이 자체적으로 사용하는 문구), seat(활성 시트도 필요함), self(자신의 세션에 대한 권한을 위해 검증된 모든 사람이 보유함), grants(보유자가 시트를 부여함. 최대 하나의 권한만 이를 명시할 수 있음), licence(조직의 라이선스에 포함되어야 하는 라이선스 기능), installation(설치 환경 자체의 관리자만 보유함) 및 platform(Adverant의 플랫폼 관리자만 보유하며 역할을 지정하지 않음)가 있습니다. 권한 이름에는 최소 하나의 마침표가 포함됩니다: project.read, money.pay.

"api": {
  "version": "1",
  "basePath": "/",
  "endpoints": [
    { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
    { "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
    { "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
    { "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
  ]
},
"rights": {
  "project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
  "project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}

definePlugin은 권한이 없는 스코프 라우트(ENDPOINT_RIGHT_MISSING), 레지스터에 없는 권한(ENDPOINT_RIGHT_NOT_REGISTERED), 그리고 어떤 가드도 제공하지 않는 라우트의 권한(ENDPOINT_RIGHT_UNGUARDED)을 거부합니다. 또한 자체 모순이 있는 레지스터와 하나의 라우트에 대한 두 가지 표기(:id 및 :recordId)를 DUPLICATE_ENDPOINT로 거부합니다.

데이터: databases, schema 및 db

schema은 플러그인이 소유하는 단일 Postgres 스키마입니다. public, plugins, auth 및 nexus는 금지되며, databases[] 또한 Postgres 스키마를 지정하는 경우 이 둘은 일치해야 합니다.

databases[]은 엔진별로 각 스토어를 선언합니다: postgresql(schema, tables, migrations, 그리고 기록된 권한 부여에 따라 다른 조직이 읽을 수 있는 테이블인 granted), neo4j(schemas), qdrant(collections) 또는 redis(purpose).

db은 플러그인이 여는 모든 연결에 대한 세션 제한을 보유하며, 리뷰어와 배포 환경 모두가 이를 읽을 수 있도록 코드가 아닌 여기에 선언됩니다:

필드 제한 대상
maxConnections 레플리카당 풀
pods 동시에 풀을 보유하는 최대 파드 수(레플리카 수에 롤링 업데이트의 서지를 더한 값). 각 역할의 연결 제한은 maxConnections × pods로 렌더링되며, 이를 생략하면 definePlugin가 DB_PODS_UNDECLARED 경고를 표시합니다
statementTimeoutMs 단일 구문
idleInTransactionTimeoutMs 아무것도 실행하지 않고 열려 있는 트랜잭션
workMemKB 쿼리당이 아닌 노드당 단일 정렬 또는 해시 노드
piiMask[] 개인 데이터를 보유하며 관리형 SQL 콘솔과 로그에서 마스킹되는 table.column 항목

스킬 및 도구: skills, mcpTools, entitlements

skills[]은 매니페스트 스킬을 보유하며, 해당 필드와 티어는 2.20장, 스킬에서 다룹니다. mcpTools[]는 플러그인이 게시하는 MCP(Model Context Protocol) 도구를 보유하며, 각 도구는 최상위 oneOf, allOf 또는 anyOf이 없는 name, description 및 inputSchema입니다.

entitlements은 featureIdPattern를 필수로 요구하며 alwaysOn[], source 및 store를 받습니다. 이 패턴은 기능 ID가 상주하는 네임스페이스를 지정하며, 관례적으로 플러그인의 name에 서피스별로 코드가 채워 넣는 세그먼트 하나를 더한 형태입니다. alwaysOn[]은 자격 판정을 받을 수 없을 때조차 응답해야 하는 짧고 정확한 목록입니다(헬스, 준비 상태, 로그인, 그리고 관리자가 자격을 복구하는 데 필요한 설정).

변경 제어: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

승인은 서로 다른 사람을 기준으로 집계되며, 변경을 제안한 사람은 절대 그중에 포함되지 않습니다. 이 두 가지 조건이 모두 갖춰지지 않으면 "두 번의 승인"은 한 사람이 두 번 클릭하는 것으로 변질됩니다. enabled: true은 classes를 필수로 요구하며, 지정된 모든 클래스에는 자체 카운트가 필요합니다. 생략한 클래스는 비관리 대상이 되며, 이는 스키마가 명시적으로 기록하도록 만드는 정당한 선택입니다.

자체 식별 정보: domains, branding, routing

domains[](각각 primary 및 aliases[]이며, domain는 단일 도메인 형식임)은 플러그인이 응답하는 위치를 나열합니다. branding는 appName을 필수로 요구하며 tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId 및 gaId를 받습니다. branding에 있는 모든 내용은 공개됩니다. 누군가 자격 증명을 갖기도 전에 로그인 페이지가 이를 읽으므로, 여기에는 시크릿이나 내부 주소가 절대 포함되지 않습니다. routing(type, gateway, virtualService)은 자체 라우팅을 기술하는 플러그인을 위한 것입니다.

사이징 및 기타 항목

resources은 cpuMillicores(10~64,000)와 memoryMB(16~262,144)를 필수로 요구하며, diskGB, timeoutMs, port 및 wsPort을 받습니다. backend은 port, healthPath, apiPrefix, framework 및 백엔드가 이름으로 임포트하는 SDK 클라이언트인 platformClients[]을 보유합니다. 이 목록은 폐쇄형이며, 게이트가 이를 임포트 내역과 대조하여 검사합니다. 스키마는 열네 개의 이름을 허용합니다: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin 및 uno, 그리고 내부 이름을 유지하는 플랜 자격 거부에 응답하는 클라이언트 하나입니다. 기능 자격 클라이언트인 runtime/entitlements은 그중 하나가 아니며 목록에 절대 올라가지 않는데, 이는 entitlements 블록이 이미 이를 선언하고 있기 때문이며 entitlements 블록 없이 이를 임포트하는 백엔드는 동일한 게이트에서 실패합니다. frontend은 basePath, mountPath 및 framework을 보유합니다. nexus는 minVersion, maxVersion, capabilities[] 및 permissions[]을 보유합니다.

나머지 블록들은 각각 하나의 작업을 위해 존재합니다:

블록 용도
settings 공유 프레임워크에 대한 설정: 각각이 지정하는 레벨에서 설정되는 groups 및 keys
people sweep(service, port): ID 서비스에서 동기화되며 누군가 퇴사할 때 시트가 비활성화되는 조직의 구성원
ontology entityTypes 및 relationshipTypes: 자체 스키마에 유지되는 타입 지정 그래프
release groups 및 frame: 라우트가 스테이징되고 카나리로 먼저 릴리스되는 기능 그룹
cells[] 여러 배포 단위로 구성된 플러그인: 각각 name, kind, entrypoint, port, wsPort
pricing 카탈로그 리스팅을 위한 model, currency, tiers[]
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords 게시자 및 코드가 상주하는 위치
metrics, atlas 자체 메트릭 이름 및 아키텍처 문서 생성을 위해 의도적으로 열어 둔 두 개의 객체

스키마가 표현할 수 없는 것

JSON Schema는 형태를 결정하며, definePlugin은 스키마가 표현할 수 없는 규칙을 추가합니다. 스킬의 classification는 신뢰 상한선을 초과할 수 없습니다. core 및 verified 플러그인만 tool_using 및 llm_only 스킬을 선언할 수 있습니다. 선언된 모든 경로는 스킴, //, 백슬래시가 없는 상대 경로이자 동일 출처여야 하는데, 이는 URL 파서가 \을 /으로 축약하고 /\evil.example/x은 교차 출처로 확인되기 때문입니다. 레지스트리 동기화가 스킬에 적용하는 모든 규칙은 동기화 자체의 코드와 함께 여기서 먼저 적용되므로, validate과 동기화는 위반된 규칙을 동일한 방식으로 지정합니다.

검증 및 v1에서 전환하기

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0

실패 시 정확한 경로가 출력되며, 동기화 규칙의 경우 코드가 먼저 출력됩니다. 이를 커밋 훅으로 만드십시오.

v1 매니페스트는 기계적으로 격상됩니다. migrate은 세 가지 법칙 문장을 추가하고, domain를 domains[]로 이동하며, 원래 없던 엔트리포인트를 임의로 만들어내는 것을 거부합니다. 무언가를 출력하거나 작성하기 전에 결과를 검증하므로, 마이그레이션이 도구의 실패를 리포지토리로 가져오는 일은 절대 없습니다.

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

커밋하기 전에 diff를 확인하십시오. 도구가 추가하는 법칙 문장은 검증기가 고정하는 문구이며, 자체 설치 환경의 경우 deploy을 앞서 보여드린 문장으로 설정하십시오.

테넌시 렌더링 및 역할 프로비저닝

역할 권한 부여나 행 수준 보안 템플릿은 절대 수동으로 작성하지 않습니다. nexus-tenancy render이 매니페스트의 schema와 db로부터 이를 작성합니다:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

렌더링된 파일은 스키마를 위해 다섯 가지 역할을 생성하며, 각 역할에는 보유해서는 안 되는 권한이 설정됩니다. 소유자만 될 수 있는 마이그레이터, 로그인할 수 없는 소유자, 요청 경로를 위한 앱 역할, 집계만 볼 수 있는 리포트 역할, 그리고 추가만 할 수 있는 원장 역할입니다. 어떤 역할도 BYPASSRLS을 보유하지 않습니다. 테넌트를 바인딩하는 유일한 방법은 단일 데이터베이스 함수뿐이며, set_config는 소유자를 제외한 모든 역할에서 회수됩니다.

적용된 테넌시 파일은 절대 편집하지 않습니다. 변경 사항은 자체 0번 파일을 가진 리비전으로 처리되며, 교차 조직 권한 부여를 위한 읽기 시트는 리비전 2로서 그러한 방식으로 제공됩니다. --graph은 ontology가 선언하는 타입 지정 그래프의 두 테이블을 다음 번호의 마이그레이션으로 렌더링합니다.

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sql

테넌시 파일은 러너가 연결할 때 사용하는 바로 그 역할들을 생성하므로, 데이터베이스 소유자가 nexus-migrate provision을 사용하여 적용합니다:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

<database-owner-url>은 데이터베이스 소유자의 연결 문자열이고, <dir>는 비공개 디렉터리입니다. 프로비저닝은 기본 테넌시 파일과 모든 리비전을 순서대로 적용하고, migrator.url와 app.url(그리고 리비전 2가 존재하면 seat.url)를 0600 모드로 <dir>에 작성하며, 비밀 정보는 아무것도 출력하지 않습니다. 또한 실행할 때마다 db.maxConnections × db.pods로부터 각 역할의 연결 제한을 설정합니다. 다시 실행하더라도 요청하지 않는 한 기존 비밀번호가 유지됩니다. --passwords <dir>은 파일로부터 비밀번호를 설정하고 --rotate <roles>은 지정된 역할에 새 비밀번호를 부여합니다. 이 파일들을 배포 환경의 시크릿으로 전환하십시오.

그 후에는 프로비저닝이 작성한 마이그레이터의 연결 문자열로 연결하여 적용을 수행합니다:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

001번 이후의 파일들을 마이그레이터로서 실행하며, SET ROLE <schema>_owner 하위의 모든 파일을 파일당 하나의 트랜잭션으로 실행합니다. 각 파일의 체크섬이 포함된 원장인 <schema>.schema_migrations를 유지하며, 바이트가 변경된 적용된 파일은 이름으로 거부되고(CHECKSUM_DRIFT) 절대 다시 실행되거나 건너뛰어지지 않습니다. 대기 중인 모든 파일은 첫 번째 파일이 실행되기 전에 실제 Postgres 문법으로 파싱되므로, 거부되더라도 데이터베이스는 건드리지 않은 상태로 유지됩니다. 파일이 가질 수 있는 유일한 헤더는 선택적 잠금 및 구문 타임아웃이 있는 -- nexus-migration: transaction=file|per-statement이며, per-statement는 CREATE INDEX CONCURRENTLY을 위한 것입니다.

게이트

nexus-gates은 스물두 개의 게이트를 실행합니다. 각 게이트는 한 가지 부류의 결함을 인코딩하여 동일한 결함이 두 번 배포되지 않도록 하며, 이를 유발하도록 제작된 픽스처에서 실패함을 증명하는 셀프 테스트를 가지고 있습니다. 푸시하기 전에 이를 실행하십시오:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
게이트 감지 대상
scope-adherence 스코프 가드가 없는 /api 라우트; 정확히 선언된 경로가 아닌 익명 경로; 디바이스 가드가 없거나 그 옆에 개인의 가드가 있는 디바이스 라우트
one-fence 수동으로 작성한 시트나 권한 부여 펜스를 포함하여, 지정된 한 곳 외의 위치에 정의된 테넌트 조건자
sql-fence FROM, JOIN, USING 또는 UPDATE 대상에서 펜스 없이 스코프 테이블을 읽거나 업데이트하는 구문
migrations-are-scoped 축, 테넌트 선행 복합 키, 테넌트를 포함하는 외래 키 또는 데모 컬럼이 누락된 테이블
migrations-commit-what-they-open BEGIN 카운트가 COMMIT 및 ROLLBACK 카운트와 일치하지 않는 마이그레이션
no-direct-compute 모델 제공자, 엔진, 큐 또는 워크플로 호스트에 대한 직접 호출; 디스패치 URL을 읽는 두 번째 리더
no-credentials 리포지토리나 환경에서 읽을 수 있는 모델 제공자 자격 증명
crud-adherence 권한 검사에서 레지스터에 있는 어떤 것도 지정하지 않는 변경(mutating) 라우트
blocked-backends 제공되지도, 이름으로 차단되지도, 법칙에 의해 거부되지도, 다른 곳에서 소유하지도 않는 라우트
every-test-runs 테스트 스크립트의 글로브(glob)가 절대 도달하지 못하는 테스트
tiles-are-invariant 테넌트 값을 읽거나 인증을 건너뛰는 테넌트 불변 캐시 심(seam)
api-contract 매니페스트가 선언하지 않은 등록된 라우트, 또는 코드가 전혀 등록하지 않는 선언된 라우트
rls-present 강제된 행 수준 보안이 없는 테이블; 고정된 search_path가 없는 SECURITY DEFINER 함수
no-set-config 테넌트 설정을 스스로 바인딩하는 플러그인 코드
db-role-honest 소유자나 마이그레이터로 연결하거나 SUPERUSER 또는 BYPASSRLS를 요청하는 요청 경로
platform-clients 임포트되었으나 backend.platformClients에 나열되지 않은 SDK 클라이언트, 또는 나열되었으나 전혀 임포트되지 않은 클라이언트
rights-register 선언된 권한이 없는 스코프 라우트; 레지스터를 우회하는 권한 검사
refusal-ledger 원장이 설치되지 않은 선언된 거부 테이블, 또는 원장을 우회하여 전송된 거부 바디
grants-declared 매니페스트가 선언하지 않은 권한 부여된 테이블; 수동으로 배포된 읽기 시트 권한
people-declared 스윕(sweep) 라우트, 가드 및 테이블이 없는 people 블록
functions-closure 제공되는 라우트와 선언된 라우트가 일치하지 않는 Azure Functions 플러그인
declared-input 라우트의 선언된 query과 일치하지 않는 핸들러의 쿼리 파라미터 목록

gates/ 디렉터리는 게이트가 읽을 수 있는 다섯 개의 면제 파일(demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json 및 invariant-seams.json)을 보유하며, 항목당 하나의 사유가 들어갑니다. 빈 사유는 항목이 없는 것으로 간주되며, 더 이상 존재하지 않는 대상을 지정하는 항목은 게이트를 실패하게 만듭니다. 또한 여기에 자체 게이트 모듈을 넣어 두면 nexus-gates이 내장 게이트와 함께 이를 인식하여 실행합니다.

호환성
호환성
호환성은 퀵스타트의 야간 실행 결과를 바탕으로 어떤 SDK 버전이 어떤 플랫폼 버전과 함께 작동하는지 보여줍니다. 테스트되지 않은 조합은 그렇다고 표시되며, 실패한 조합은 문제를 일으킨 변경 사항을 지정합니다.

템플릿의 파이프라인

템플릿은 수동으로 작성된 워크플로를 배포하지 않습니다. 파이프라인 구성은 Dockerfile, 단일 빌드 인수(레지스트리 토큰), 마이그레이션 드라이 런 및 부팅 프로브, 그리고 머지 큐가 실행하는 게이트를 지정합니다. 이 순서는 실패가 발생하기를 바라는 순서와 같습니다.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest(즉, create-nexus-plugin validate nexus.manifest.json)
  6. npm run gates(즉, nexus-gates --self-test)
  7. node scripts/ci/required-env

이미지 전후로 두 가지 검사가 더 실행됩니다. 마이그레이션 드라이 런(dry run)은 이미지를 릴리스하기 전에 프로덕션과 동일한 러너를 사용하여 일회용 Postgres에 모든 파일을 적용합니다. 즉, 슈퍼유저 권한으로 nexus-migrate provision을 한 번 실행한 다음, 마이그레이터 권한으로 번호가 매겨진 각 파일을 실행합니다. 부트 프로브(boot probe)는 자체 엔트리포인트 및 required-env가 출력하는 모든 변수를 사용하여 빌드된 이미지를 시작하며, 이때 연결만 수락하고 응답하지 않는 대역(stand-in)을 가리킵니다. 서버는 지정된 제한 시간 내에 데이터베이스를 기다리며, 이 대기 상태가 곧 통과 신호가 됩니다. 부팅을 거부하는 구성 로더는 프로덕션이 아닌 이 단계에서 빌드를 실패 처리합니다.

Community에서 빌드하기
Community에서 빌드하기
Community에서 개발자는 자체 Git 호스트에 코드를 두고, 단일 서버에서 동일한 골든 패스(golden path), 개발 공간 및 데이터 브랜치를 제공받습니다. 스테이징, 파일럿 유닛 및 마스킹 처리된 라이브 데이터 사본은 Enterprise에서 제공됩니다.

소요 비용

SDK는 개발자 대신 결정을 내리며, 그중 일부는 여러분이 생각했던 방식과 다를 수 있습니다. 매니페스트는 인식하지 못하는 키를 거부하고, 라우트 테이블은 코드와 정확히 일치해야 하며, 데이터베이스 역할은 직접 설계할 수 없고, 게이트는 읽기 작업에 대한 권한이 누락된 경우 빌드를 실패 처리합니다. 첫 번째 플러그인을 만들 때, 저는 코드에 등록만 하고 선언하는 것을 잊어버린 라우트 때문에 api-contract과 씨름하며 하루를 보냈습니다. 결과적으로 그 도구가 옳았습니다. 해당 라우트는 보호되지 않은 상태였기 때문입니다. 첫 번째 플러그인은 작업이 더디게 느껴지겠지만, 두 번째 플러그인은 시간이 3분의 1로 줄어들 것으로 기대하셔도 좋습니다.