로그인브리핑 예약

챕터 2.22

플러그인 런타임

범위 가드와 데이터베이스 펜스부터 UNO 디스패치, AI(인공지능) 라우트 읽기 및 라이선스 확인에 이르기까지 플러그인이 실행되는 기반 SDK(소프트웨어 개발 키트) 모듈입니다. 그런 다음 실제 데이터베이스를 대상으로 한 테스트, 스킬 등록 및 온보딩을 다룹니다.

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

읽는 시간 21분

SDK(소프트웨어 개발 키트)의 런타임 영역은 @adverant-nexus/plugin-sdk/runtime/* 아래의 모듈 세트와 testing/* 아래의 테스트 헬퍼로 구성됩니다. 이들은 임포트해서 사용하며, 직접 다시 구현하지 않습니다. 이것이 핵심 개념이며, 저는 한 번의 리뷰 거절을 겪고 나서야 이를 진지하게 받아들였습니다. 제 첫 번째 플러그인에 직접 작성한 범위(scope) 검사에 대한 리뷰어의 메모는 단 한 줄이었습니다. "SDK에 이미 이 기능이 있으며, 귀하의 코드는 MFA(다중 요소 인증) 챌린지 토큰을 세션으로 허용합니다."

이 장에서는 풀 서비스 템플릿이 연결하는 방식대로 실행 중인 플러그인을 통과하는 요청의 흐름을 따라갑니다. 즉, 범위 가드(scope guard), 데이터베이스 펜스(database fence), 유일하게 허용된 교차 접근, UNO를 통한 디스패치, AI(인공지능) 라우트 읽기 및 라이선스 검사를 다룹니다. 그런 다음 테스팅, 매니페스트 스킬 등록, 온보딩 단계를 설명합니다.

범위: 프레임워크당 하나의 가드

모든 /api 라우트는 범위 가드를 포함합니다. 이 가드는 베어러 토큰을 검증하고, 토큰에서 세 가지 축(테넌트, 소유자, 유닛)을 확인하며, 테넌트를 지정하는 본문을 거부하고, 매니페스트 레지스터에서 라우트의 권한을 적용한 후에만 핸들러가 실행되도록 합니다. SDK는 프레임워크당 하나의 어댑터를 제공하며, 모두 @adverant-nexus/plugin-sdk/runtime/scope에서 가져오고 동일한 옵션을 사용합니다.

프레임워크 어댑터
Express scopeMiddleware
Fastify requireScope, preHandler로 사용
Next 핸들러를 래핑하는 withScope; Next 핸들러는 자신의 라우트를 전달받지 않으므로 withScope에서 이를 세 번째 인수로 받습니다

다음은 간추린 템플릿의 Express 연결 코드입니다. 검증기는 SDK의 것을 사용하며, 토큰이 ID 서비스의 세션 형식을 따르도록 강제합니다. 즉, HS256만 허용되고, iss, exp, iat 및 jti가 필수이며, 수명은 최대 1시간이고, MFA 챌린지, 가장(impersonation) 또는 OAuth(위임된 권한 부여를 위한 개방형 표준) 리소스 토큰은 세션으로 허용되지 않습니다.

import { platformAccessTokenVerifier } from "@adverant-nexus/plugin-sdk/runtime/platform-token";
import { scopeMiddleware } from "@adverant-nexus/plugin-sdk/runtime/scope";

const requireScope = scopeMiddleware({
  verify: platformAccessTokenVerifier(config.PLATFORM_JWT_SECRET),
  rights: { manifest },
});

router.get("/api/projects", requireScope, async (req, res) => {
  res.json({ projects: await db.listProjects(scopeOf(req)) });
});

권한 가드(rights guard)는 라우트의 권한을 4단계로 적용합니다. 권한의 never 목록에 있는 역할은 AUTHORITY_EXCEEDED 및 barred 문구와 함께 거부되며, 어떤 시트(seat)로도 이를 해제할 수 없습니다. roles에 있는 역할은 허용되며, 권한에 seat: true가 명시된 경우 활성 시트도 함께 필요합니다. 그렇지 않은 경우 해당 권한을 가진 활성 시트가 있으면 허용됩니다. 그 외의 경우 요청은 AUTHORITY_EXCEEDED로 거부되며, 시트를 부여할 수 있는 사람들의 이름이 표시됩니다. 가드에 스토어(rights: { manifest, store: { pool, schema } })를 제공하면 호출자 자신의 범위 아래에서 시트를 읽습니다. licence를 지정하는 권한에는 아래에서 다룰 라이선스 리더도 필요합니다.

핸들러 내부에서 scopeOf(req)은 확인된 범위를 읽는 유일한 방법이며, 가드가 실행되지 않았다면 예외를 발생시킵니다. 프리픽스에 등록되어 라우트가 매칭되기 전에 실행되는 가드는 500 MIDDLEWARE_ORDERING_ERROR를 응답합니다. 매니페스트에 선언되지 않았지만 코드에서 등록한 라우트는 500 UNHANDLED_ERROR를 응답합니다. 두 경우 모두 안전하게 실패(fail closed) 처리됩니다.

플랫폼이 호출하는 템플릿의 /internal 라우트는 다른 체계를 사용합니다. 서비스 가드는 상수 시간 내에 X-Service-Key를 확인하고 플랫폼의 X-Organization-ID에서 테넌트를 가져오며, MISSING_SERVICE_KEY, INVALID_SERVICE_KEY 또는 MISSING_ORG_ID_HEADER는 거부합니다. 플랫폼의 서명된 호출별 토큰을 위해 SDK는 requireService(Fastify) 및 serviceMiddleware(Express)를 제공하며, 이들은 토큰이 어떤 스킬과 라우트를 위해 발급되었는지도 확인하고 두 번 사용된 토큰을 거부합니다.

데이터베이스 펜스: tenantFence 및 withScopedTx

범위가 지정된 테이블에 대한 모든 구문은 펜스를 구성하고 범위가 지정된 트랜잭션 내부에서 실행됩니다.

import { withScopedTx } from "@adverant-nexus/plugin-sdk/runtime/db";
import { tenantFence } from "@adverant-nexus/plugin-sdk/runtime/fence";

async function listProjects(scope: ResolvedScope) {
  // Projects are owner-private inside the organisation, so the owner axis is passed explicitly.
  const f = tenantFence(scope, { alias: "p", owner: scope.owner });
  const r = await withScopedTx(pool, scope, { schema: SCHEMA }, (db) =>
    db.query(`SELECT p.* FROM anomaly_review.reviews p WHERE ${f.where} ORDER BY p.created_at DESC`, f.params),
  );
  return r.rows;
}

tenantFence(scope, options)은 확인된 범위에서 조건자(predicate)와 그 매개변수를 생성합니다. 개인 테이블의 경우 owner를 전달하고, 소유자가 출처(provenance)를 나타내는 조직 아티팩트의 경우 이를 생략합니다. 구문에 이미 매개변수가 있는 경우, startIndex는 펜스에 번호 매기기를 시작할 위치를 알려줍니다. 삽입(insert) 작업은 절대 축을 입력으로 받지 않으며, 범위에서 가져온 scope.tenant, scope.owner 및 scope.unit를 기록합니다.

withScopedTx은 스키마의 단일 바인드 함수를 통해 하나의 트랜잭션에 대해 세 가지 축을 모두 바인딩한 다음 콜백을 실행합니다. 동일한 트랜잭션에서 두 번째 바인딩을 시도하면 SCOPE_ALREADY_BOUND가 발생합니다(500: 호출자의 잘못이 아니라 코드가 두 번 바인딩함). 테넌트나 소유자가 없거나 0이면 SCOPE_PREDICATE_INVALID가 발생합니다(403). 이 설정은 트랜잭션 로컬이므로 풀링된 연결이 하나의 테넌트를 다음 요청으로 넘길 수 없습니다.

두 개의 형제 함수는 사람의 요청이 아닌 경우를 처리합니다. withTenantScopedTx은 기계가 읽는 행(디바이스 레지스트리)을 위해 소유자 없이 테넌트와 유닛을 바인딩하며, 소유자를 포함한 범위는 거부합니다. maintenanceScope(reason)는 소유자의 트랜잭션이 열리기 전에 조직 전체 작업이 무엇인지 명시적으로 선언하도록 합니다. 코드 펜스와 강제 행 수준 보안(RLS)은 하나의 법칙을 위한 두 가지 메커니즘입니다. 부팅 검사는 데이터베이스가 두 번째 메커니즘이 유효함을 증명할 때까지 수신 대기를 거부합니다(그렇지 않으면 DB_ROLE_BYPASSES_ISOLATION 발생).

모든 거부는 하나의 행으로 기록됨

템플릿은 바디 파서와 라우터 사이에 거부 원장(refusal ledger)이라는 미들웨어를 한 번 더 설치합니다.

import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";

app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));

이 미들웨어는 응답을 래핑하여, 권한 가드, 핸들러 또는 스토어 중 어디에서 발생했든 사용자가 읽는 모든 거부가 본문이 전송되기 전에 해당 사용자 자신의 범위가 지정된 트랜잭션 내부에 있는 스키마의 refusal 테이블에 기록되도록 합니다. 익명의 401은 아무것도 기록하지 않습니다. 행을 기록할 수 없는 경우 응답은 UNHANDLED_ERROR가 됩니다. 제품이 기록할 수 없는 "거부"는 마치 기록된 것처럼 전송되지 않습니다. 부팅 시 assertRefusalLedger를 실행하여 테이블이 원장의 행을 받을 수 있는지 확인하며, 스토어는 모든 거부가 관련 레코드를 지정할 수 있도록 noteSubject({ recordId, isDemo })를 호출할 수 있습니다. 고객이 지난 화요일에 왜 누군가가 거부되었는지 물으면, 그 답은 추측이 아니라 쿼리입니다.

유일한 교차: 기록된 읽기 전용 권한 부여

고객 중 한 명이 다른 고객을 위해 작업을 수행하고 다른 고객이 이를 검사할 수 있는 경우, 경계를 넘는 공인된 방법이 하나 있습니다. 행을 보유한 조직이 권한 부여(grant)를 기록합니다. 읽는 측 조직은 never에 owner와 admin를 지정해야 하는 granted.read 권한을 가진 시트를 통해 사용자를 승인합니다. 읽기 작업은 여섯 번째 데이터베이스 역할인 읽기 시트(read seat)로 실행되며, 이는 databases[].granted가 나열한 테이블만 조회(select)할 수 있습니다.

const r = await withSeatTx({ app: appPool, seat: seatPool }, seatsOf(req), { holder, grantId }, { schema: "anomaly_review" }, (db) => {
  const f = grantFence(db.seat, { alias: "r" });
  return db.query(`SELECT r.review_id FROM anomaly_review.reviews r WHERE ${f.where}`, f.params);
});
if (!r.ok) return res.status(r.status).json(r.refusal);

withSeatTx은 먼저 읽는 측의 자체 테넌트에 조회 기록(look)을 작성한 다음, 읽기 시트를 권한 부여에 바인딩하여 보유자의 테넌트에 조회 기록을 작성합니다. 데이터베이스 자체 정책은 권한 부여가 읽는 측의 조직을 지정하는지, 해당 테이블을 포함하는지, 시작되었는지, 종료되지 않았는지, 철회되지 않았는지, 그리고 이 트랜잭션이 조회 기록을 작성했는지 확인합니다. 조회 기록을 건너뛴 읽기 작업은 아무것도 볼 수 없습니다. 부팅 시 assertSeatAtBoot(seatPool, schema)는 seat.url에서 열린 풀이 실제로 해당 시트이며 그 이상이 아닌지 확인하고, 그렇지 않으면 DB_SEAT_ROLE_INVALID로 거부합니다.

UNO를 통한 디스패치

모든 컴퓨팅은 닫힌 허용 목록(allow-list)을 사용하여 하나의 파일에 빌드된 단일 클라이언트를 통해 이루어집니다.

import { UnoClient } from "@adverant-nexus/plugin-sdk/runtime/uno";

/** The namespaced job types this surface may dispatch. Closed; edit in code. */
export const DISPATCHABLE = Object.freeze([`${manifest.name}.sentiment_score`] as const);

export function createUno(deps: UnoDeps): UnoClient {
  return new UnoClient({
    baseUrl: deps.dispatchUrl,
    serviceKey: deps.serviceKey,
    callerService: manifest.name,
    dispatchable: DISPATCHABLE,
  });
}

허용 목록은 의도적으로 모듈 수준의 상수로 지정됩니다. 만약 운영자가 구성에서 이를 확장할 수 있다면, 라우트는 전체 레지스트리에 대한 디스패치 프록시가 될 것입니다. 템플릿 자체 테스트는 목록이 매니페스트가 컴파일하는 작업 유형을 정확히 지정하는지 검증합니다.

엔벨로프

디스패치는 필수 코어에 6개의 필드를 포함합니다. 클라이언트는 요청이 아닌 검증된 범위에서 테넌트와 액터(actor)를 채웁니다.

필드 포함 내용
jobType 네임스페이스가 지정된 작업 유형, <plugin name>.<skill id>
organizationId 범위에서 가져온 테넌트
userId 감사 및 청구를 위해 범위에서 가져온 액터
inputParams 스킬의 입력. 테넌트 ID를 절대 포함하지 않으며, 포함하는 경우 디스패치 시 거부됩니다
priority critical, high, normal 또는 low
pluginId 매니페스트 name. 모든 디스패치는 시작된 플러그인을 선언합니다

선택적 필드에는 correlationId(UUID(범용 고유 식별자)이며, 없는 경우 새로 생성됨) 및 워커가 결과를 게시할 위치를 알기 위해 plugin_queue 스킬에 필요한 callbackUrl가 포함됩니다.

const accepted = await uno.dispatch(scope, {
  jobType: DISPATCHABLE[0],
  inputParams: { text: text.body },
  priority: "normal",
  pluginId: manifest.name,
  correlationId: crypto.randomUUID(),
});
if (!accepted.ok) return res.status(statusFor(accepted.refusal.code)).json(accepted.refusal);
res.status(202).json(accepted.value);

202 응답 후 폴링

모든 디스패치는 대기열에 추가됩니다. 응답은 항상 식별자(jobId, runId, traceId, status)가 포함된 202이며, 절대 결과가 아닙니다. 결과는 작업을 폴링하거나 콜백에서 얻을 수 있습니다. uno.peek(jobId, { scope })는 이를 한 번 읽고 awaitJob은 종료 상태가 될 때까지 폴링합니다. 둘 다 검증된 범위에서 테넌트를 전송하며, 네트워크 호출의 사용자 측에서 반환된 행의 organization_id를 호출자의 테넌트와 대조하여 불일치할 경우 SCOPE_REFUSED로 거부합니다.

실행 행(run row)은 고유의 철자대로 읽어야 합니다. 디스패치 응답은 jobId이라고 표시하지만, 행은 job_id, organization_id 및 plugin_id라고 표시합니다. 결과 및 실패 열은 result, error, error_code 및 error_troubleshooting입니다. completed와 failed은 종료 상태입니다. timed_out, cancelled 및 system_failure은 리퍼(reaper)에서 오며 늦게 도착한 결과가 이를 수정할 수도 있습니다. 이 중 하나라도 구문 분석할 수 없는 것으로 처리하는 클라이언트는 플랫폼이 매일 기록하는 행을 거부하게 됩니다.

승인 보류

approval을 선언하는 매니페스트 스킬은 디스패치 시 보류됩니다. 그러면 202는 status: "awaiting_approval"를 표시하고 매니페스트가 제공한 사유와 함께 waitpointId를 전달합니다. 실행은 지정된 사람이 결정을 내릴 때까지 보류 상태로 유지됩니다. uno.approve와 uno.resolveWaitpoint는 테넌트와 호출자를 액터로 전송하며, 검증된 호출자가 아닌 다른 사람의 결정은 거부됩니다. 승인하면 작업이 한 번 해제되고 디스패치 검사가 다시 실행되며, 거절하면 failed 상태로 종료됩니다. 두 번째 결정은 거부되며, 보류가 만료된 후의 결정도 거부됩니다. 제품에서 승인자가 제안자와 다른 사람이어야 하는 경우, 결정을 내리는 라우트에서 이를 강제하십시오. 플랫폼은 두 사람 모두를 기록합니다.

보류된 작업은 보류된 것으로 렌더링하십시오. 실행 행에 해제되었다고 표시될 때까지 사용자에게 클릭으로 작업이 해제되었다고 알리지 마십시오.

AI: 스킬 행의 희망 조건과 한 번의 읽기

플러그인은 모델을 직접 호출하지 않습니다. 매니페스트 스킬에 모델이 필요한 경우(신뢰 수준 core 또는 verified에서의 llm_only 또는 tool_using), 레지스트리 행에 선호 사항을 표현하면 라우터가 조직의 자체 풀에서 결정합니다.

{
  "execution_config_skill": {
    "preferredProvider": "gemini",
    "capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
  }
}

preferredProvider 및 preferredModel는 조직에서 해당 공급자를 활성화하고 자격 증명을 부여한 경우에만 라우터가 존중하는 희망 사항입니다. capabilityProfile는 필터링만 하고 선택은 하지 않으며, 그 dataResidency(eu_only, us_only 또는 any)는 라우터가 충족하거나 거부하는 엄격한 제약 조건입니다. 일반적으로 이들을 모두 생략하는 것이 맞습니다. modelOverride는 정확히 하나의 모델이 필요한 드문 스킬을 위해 존재하며, 함께 지정된 희망 사항들을 무효화합니다. 다른 모델에서는 스킬이 무의미한 경우가 아니라면 사용을 피하는 것이 좋습니다.

인터페이스에서 라우터가 사용할 모델을 표시해야 하는 경우, 예측하지 말고 읽어 오십시오.

import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";

createAIRouteClient(...).effectiveRoute()은 AI 공급자 라우터(AI Provider Router)의 유일하게 공인된 읽기 방법입니다. 게이트웨이의 주소, 호출자 자신의 베어러 토큰, 플랫폼의 슬러그를 받으며 AI 요청은 보내지 않습니다. 공급자와 모델, 정책이 허용하는 공급자, 선택한 엔드포인트가 local 또는 external를 실행하는지 여부를 응답합니다. 라우트를 사용할 수 없는 경우 기본 모델이 아니라 라우터의 거부 사유(NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE 또는 NO_MODEL_FOR_ROLE_AND_PROVIDER, 해결 방법 포함)를 문구로 응답합니다. 해당 거부 내용을 사용자에게 표시하십시오. 이는 소속 조직의 구성이 알려주는 메시지입니다.

라이선스 확인

세 가지 메커니즘이 세 가지 단위(grain)에서 라이선스를 확인합니다.

라이선스를 지정하는 권한. 가장 간단합니다. 매니페스트에서 권한이 licence: "<feature>"을 포함하면, 가드는 역할을 읽기 전에 호출자 자신의 토큰을 사용하여 조직의 라이선스에 해당 기능이 포함되어 있는지 ID 서비스에 문의합니다. 리더를 포함하여 가드를 빌드하십시오.

import { createLicenceReader } from "@adverant-nexus/plugin-sdk/runtime/licence";

const requireScope = scopeMiddleware({
  verify,
  rights: { manifest, store: { pool, schema: SCHEMA }, licence: createLicenceReader({ baseUrl: config.NEXUS_AUTH_URL }) },
});

기능을 포함하지 않은 라이선스는 LICENCE_LOCKED로 모든 사람을 거부하며, 해당 기능을 포함하는 항목을 지정하고 조직의 소유자와 관리자가 이를 켤 수 있다고 안내합니다. 읽을 수 없는 라이선스는 UNHANDLED_ERROR로 거부합니다. 라이선스에 접근할 수 없다고 해서 잠긴 기능이 제공되는 일은 절대 없습니다. 응답은 조직 및 기능별로 30초 동안 기억됩니다.

제품 게이트. runtime/product-gate의 createProductGate({ baseUrl, product })은 호출자의 조직이 해당 제품을 보유하고 있는지 자격 검사(entitlement check)에 문의하며, 그 middleware()는 범위 가드 다음에 실행됩니다. 부정적인 판정은 ENTITLEMENT_DENIED이고, 도달할 수 없는 검사는 ENTITLEMENT_UNREACHABLE이며, 게이트는 절대 이 둘을 혼동하여 처리하지 않습니다.

라이선스 문서 자체. 도메인 팩의 비공개 모듈과 같이 서명된 라이선스를 근거로 스스로 판단해야 하는 코드는 runtime/licence-document의 verifyLicenceDocument(docText, opts)을 사용합니다. 이는 네트워크 호출, 환경 변수, 파일을 사용하지 않는 순수 함수입니다. 빌드에 포함된 신뢰 루트(trust roots)를 기준으로 두 서명을 모두 확인하고, 권한 부여, 애드온 및 도메인 팩과 함께 상태(VALID, WARN, GRACE, RESTRICT, TERMINATE 또는 ABSENT)를 응답합니다. 그런 다음 licenceAllows(verdict, featureGroup, action, tenantId?)는 그룹 아래에서 use 또는 provision을 수행할 수 있는지 여부를 알려줍니다. RESTRICT는 use을 허용하고 provision 요청에는 LICENCE_LOCKED로 응답하므로, 실행 중인 작업은 계속되고 새로운 작업은 시작되지 않습니다.

테스트

템플릿의 테스트는 패턴을 보여주며, 그 이면에 있는 도구들은 다음과 같습니다.

범위 페이크(Scope fakes). test/scope-fakes.ts에서 확인된 범위 대역(double)을 한 번 빌드하고, 유닛 없음, 토큰 없음, 조직이 0인 토큰 등 누락된 사례를 포함하여 모든 곳에 주입하십시오. 거부 경로가 곧 제품입니다.

페이크 디스패치 전송. UnoClient은 fetch, now 및 sleep를 받으므로 단위 테스트가 네트워크에 절대 접촉하지 않습니다. 엔벨로프의 필드, 202 형태, organization_id가 포함된 종료 행까지의 폴링, 그리고 다른 테넌트에 대한 행이 삭제되는지 검증하십시오.

실제 Postgres. 페이크 쿼리 함수는 SQL 문자열만 증명합니다. 강제 행 수준 보안이 유지되는지 또는 파일이 마이그레이터로서 순서대로 적용되는지는 증명할 수 없습니다. testing/ephemeral-postgres은 일회용 서버를 시작하고 프로덕션이 실행하는 것과 동일한 nexus-migrate를 실행합니다.

import { EPHEMERAL_REMEDY, migrated, startEphemeralPostgres } from "@adverant-nexus/plugin-sdk/testing/ephemeral-postgres";

const pg = await startEphemeralPostgres();          // null off CI: skip each case by name with EPHEMERAL_REMEDY
const db = migrated(pg!, "plugin_test", { root });  // provision as the superuser, then every file as the migrator
// connect as db.appUrl and run the boot checks the server runs

CI(지속적 통합) 외부에서는 Postgres 서버가 없는 머신이 각 데이터베이스 케이스를 녹색(성공)으로 처리하지 않고 해결 방법과 함께 이름별로 건너뜁니다. CI에서는 동일한 부재 시 스위트가 실패합니다(EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI). 건너뛴 행 수준 보안 테스트는 아무것도 측정하지 않은 녹색 게이트이기 때문입니다. 서버는 시작되기까지 최대 180초를 기다리며, 테스트 프로세스가 종료되면 워치독이 서버를 중지합니다.

격리 하네스(isolation harness). testing/isolation-harness의 runIsolationHarness(target)은 앱이 마운트하는 모든 라우트를 읽고 다른 조직의 관리자 및 동료로서 각각을 공격합니다. 그런 다음 코드 펜스를 제거한 상태, 데이터베이스 펜스를 제거한 상태, 그리고 둘 다 제거한 상태로 다시 공격합니다. 라우트는 두 펜스 중 하나라도 있을 때 공격이 실패하고 둘 다 제거되었을 때 피해자의 데이터에 도달하는 경우에만 PROVEN가 됩니다. 따라서 테스트가 유출을 실제로 감지할 수 있는지 알 수 있습니다. 각 라우트의 선언된 쿼리와 예제 본문을 전송하므로 빈 요청을 거부하는 라우트에도 여전히 도달합니다. 테스트에서 ledgerOf(report)를 고정하고 defectsOf(report)에서 실패하도록 설정하십시오.

등록: 매니페스트에서 스킬 레지스트리로

매니페스트 스킬은 단일 경로를 통해 스킬 레지스트리에 도달합니다.

manifest.skills[]  →  compileRegistry(manifest)  →  POST /api/v1/plugins/sync

compileRegistry은 검증된 매니페스트를 nexus.plugin-sync/v1 본문으로 변환합니다. 템플릿은 임포트 시 이를 수행하므로 유효하지 않은 매니페스트는 빌드를 실패시킵니다.

import { compileRegistry, definePlugin } from "@adverant-nexus/plugin-sdk";

export const manifest = definePlugin(raw);
export const registryPayload = compileRegistry(manifest);
{
  "contract": "nexus.plugin-sync/v1",
  "pluginId": "anomaly-review",
  "version": "0.3.0",
  "skills": [ { "job_type": "anomaly-review.excursion_summary", "tier": "host_callback", "classification": "tenant" } ]
}

동기화는 선언적입니다. 매번 전체 스킬 세트를 전송하며, 누락된 스킬은 기록이 유지된 채 비활성화됩니다. 또한 엄격합니다. 알 수 없는 필드, 다른 티어의 필드 또는 null은 거부되고, 모든 위반 사항이 하나의 400 SYNC_CONTRACT_VIOLATION에 함께 반환되며, 위반 사항이 하나라도 있으면 아무것도 기록되지 않습니다. 그리고 네임스페이스가 지정된 작업 유형을 키로 하고 디스패처가 읽는 모든 열을 포함하여 스킬당 하나의 레지스트리 행을 기록하므로, 동기화가 200를 응답하는 순간 스킬을 실행할 수 있습니다.

인증된 호출자는 본문 필드가 아니라 플러그인입니다. mTLS(상호 TLS: 양쪽 끝에 인증서가 있는 전송 계층 보안)를 통해 플러그인 자체 워크로드에서 동기화를 호출하십시오. Skills Engine은 SPIFFE ID(spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>)가 네임스페이스와 서비스 계정을 지정하는 워크로드의 클라이언트 인증서를 읽고, 해당 네임스페이스에 대해 기록된 플러그인과 소유 조직을 조회합니다. 본문의 pluginId가 일치해야 하며, 이는 선택기가 아니라 검사입니다. 모든 행은 해당 플러그인과 조직으로 기록됩니다.

상태 코드 의미
200 {contract, pluginId, version, created, updated, unchanged, disabled, skills}
400 SYNC_CONTRACT_VIOLATION violations[]에 나열된 모든 위반 사항; 아무것도 기록되지 않음
401 UNAUTHORIZED 잘못되었거나 누락된 서비스 키
401 CALLER_IDENTITY_UNVERIFIED 읽을 수 있는 클라이언트 ID 없음
403 DELIVERY_IDENTITY_MISSING 호출 네임스페이스가 어떤 플러그인에도 속하지 않음
403 PLUGIN_ID_MISMATCH 본문이 다른 플러그인을 지정함
409 REGISTRY_CONFLICT 작업 유형이 다른 곳에서 소유되었거나 동기화 외부에서 등록됨; 아무것도 기록되지 않음

200 이외의 상태에서는 배포 단계를 실패 처리하십시오. 다른 어떤 상태도 스킬이 등록되었음을 의미하지 않습니다.

온보딩

온보딩은 순서가 지정된 10개의 단계로 실행되며, 각 단계는 자체적으로 다시 실행하거나 취소하거나 롤백할 수 있습니다.

  1. 리포지토리를 복제하고 검증합니다.
  2. 매니페스트를 구문 분석합니다.
  3. 보안 문제를 스캔합니다.
  4. 이미지를 빌드합니다.
  5. 설치 환경의 레지스트리에 푸시합니다.
  6. 도메인 이름을 설정합니다.
  7. 설치 환경의 릴리스 채널을 통해 배포합니다.
  8. 상태 확인(health check)을 기다립니다.
  9. 플러그인을 등록합니다.
  10. 개발자에게 알립니다.

배포 전에 매니페스트와 빌드된 이미지에 대해 5가지 적합성 검사가 실행됩니다. 매니페스트가 구문 분석되고 필수 필드를 포함하는지, 선언된 모든 라우트가 실제 등록된 라우트인지, 플러그인이 스키마를 소유하고 그 외부에는 아무것도 기록하지 않는지, 리소스 요청이 선언되고 범위 내에 있는지, 이미지에 작동하는 상태 핸들러가 있는지 확인합니다. 부팅 시 자체 등록하는 플러그인은 자체 권한 아래에서 동일한 계약을 실행하므로, 검사가 파이프라인이 아닌 자체 CI가 됩니다. 하나를 건너뛴다고 해서 온보딩이 단축되지는 않으며, 실패를 런타임으로 미룰 뿐입니다.

매니페스트의 브랜딩은 누군가 자격 증명을 갖기 전에 로그인 페이지에서 필요하기 때문에 도메인별로 인증 없이 제공됩니다. branding의 모든 항목을 공개된 것으로 취급하십시오.

환경 및 프로모션
환경 및 프로모션
환경 및 프로모션은 모든 게이트와 그 상태를 한 페이지에 표시하여 각 릴리스를 개발 공간에서 스테이징을 거쳐 파일럿 유닛으로, 그런 다음 모든 유닛으로 이동시킵니다. 게이트를 건너뛰는 프로모션은 GATE_CANNOT_BE_SKIPPED로 거부됩니다.
채널 및 설치
채널 및 설치
채널 및 설치는 어떤 유닛이 어떤 버전을 실행하는지 보여주며, 오류율은 콘텐츠가 아닌 횟수로 표시합니다. 하나의 유닛을 롤백하는 것은 해당 유닛에만 영향을 미치는 검토된 변경 사항입니다.

런타임이 대신해 주지 않는 작업

런타임은 격리, 디스패치 및 모델 접근에 대한 기준을 엄격히 유지합니다. 런타임이 제품 로직을 올바르게 만들어 주지는 않으며, 느린 쿼리를 빠르게 만들어 주지도 않습니다. 모든 구문은 매니페스트의 db 블록이 선언한 타임아웃이 적용된 바인딩된 트랜잭션 내부에서 실행되며, statementTimeoutMs를 초과하는 구문은 대기하지 않고 취소됩니다. 이에 맞춰 쿼리 크기를 조정하십시오. 그리고 승인 보류, 읽기 시트, 라이선스 리더는 모두 왕복(round trip)이나 트랜잭션을 추가합니다. 제 이상 징후 검토 플러그인에서 라이선스 검사는 30초 메모리가 워밍업될 때까지 요청당 몇 밀리초를 추가했는데, 이는 잠긴 기능을 절대 제공하지 않는 대가로는 합당한 수준이었습니다.