SuperRepo 고급 구성

SuperRepo의 루트 foundry.yml은 컴포넌트와 빌드 출력 구조를 정의합니다. 한 제품의 components 또는 여러 제품의 products를 선언할 수 있습니다. Beta 기능이며 실제 템플릿과 CLI 버전이 해당 설정을 지원해야 합니다.

여러 제품

products의 각 항목에 components, SDK 출력 위치, 이름 공간과 bundle을 둡니다. 다음 이름과 Maven 좌표는 가상 예제입니다.

products:
  - components:
      - type: ONTOLOGY
        path: ./ontology
      - type: APP
        path: ./app
    osdkOutput: ontology/osdk-output
    apiNamespace: com.palantir.ontology
    bundle:
      name: "operations-console"
      description: "example description"
      mavenCoordinate: "com.example:operations-console"
      installMode: SINGLETON

  - components:
      - type: ONTOLOGY
        path: ./analytics/ontology
      - type: APP
        path: ./analytics/app
    osdkOutput: analytics/ontology/osdk-output
    apiNamespace: com.palantir.analytics
    bundle:
      name: "analytics-console"
      description: "example description"
      mavenCoordinate: "com.example:analytics-console"
      installMode: SINGLETON

개별 제품을 대상으로 하는 CLI 명령에는 --product로 bundle.name을 선택합니다. 제품의 includeInBundle을 false로 두면 정의를 지우지 않고 패키징 대상에서 제외합니다. 생략하면 true입니다.

제품과 스토어를 따로 묶기

단일 제품용 foundry bundle은 여러 제품 설정을 받지 않습니다. 여러 제품은 먼저 각 컴포넌트를 빌드한 뒤 다음 두 단계로 묶습니다.

각 제품에 foundry bundle product를 실행합니다. 출력은 build/<bundle name>/blockset.zip입니다.
foundry bundle store로 제품 출력을 build/store.zip에 모읍니다.

아래는 위 두 가상 제품의 예입니다. 각각의 SemVer를 외부 변수에 설정하므로 같은 저장소의 제품도 독립적으로 버전 관리합니다.

: "${OPERATIONS_VERSION:?operations-console의 SemVer가 필요합니다}"
: "${ANALYTICS_VERSION:?analytics-console의 SemVer가 필요합니다}"
foundry bundle product --product operations-console --project-version "$OPERATIONS_VERSION" && \
foundry bundle product --product analytics-console --project-version "$ANALYTICS_VERSION" && \
foundry bundle store

store 명령에는 버전 인수가 없으며 --output으로 다른 출력 경로를 지정할 수 있습니다. 필요한 제품 번들이 없으면 예상 경로 및 만들 명령을 안내하며 실패합니다. foundry deploy는 스토어가 이미 있어야 하며 두 번들 단계를 대신 실행하지 않습니다.

컴포넌트 경로 변경

ontology를 platform/ontology로 옮긴다면 컴포넌트 경로, 외부 import 메타데이터와 OSDK 출력 위치를 함께 변경합니다.

 components:
   - type: ONTOLOGY
-    path: ./ontology
+    path: ./platform/ontology

 imports:
-  - ontology: ontology/external-imports/ontology-full-metadata.json
+  - ontology: platform/ontology/external-imports/ontology-full-metadata.json

-osdkOutput: ontology/osdk-output
+osdkOutput: platform/ontology/osdk-output

seed 데이터

로컬 embedded Ontology는 저장소에 정의하거나 가져온 유형을 알지만 실제 플랫폼의 객체 인스턴스를 읽지는 않습니다. 로컬 액션으로 객체를 만들거나 seed 파일로 초기 데이터를 넣습니다.

seed 디렉터리는 ONTOLOGY 컴포넌트 안에 두며 Nx 같은 작업 조정 도구가 미리보기 서버 명령의 인수로 위치를 제공합니다.

디렉터리 최상위 .mts 파일만 컴파일합니다.
파일 이름을 정렬한 순서로 읽으므로 기본 템플릿은 001-, 002-, 003- 접두사를 사용합니다.
각 파일은 createSeed 호출을 default export합니다.
seed.add의 첫 인수는 생성 SDK의 객체 유형 상수입니다.
기본 키를 포함하여 null을 허용하지 않는 모든 속성을 제공해야 합니다.
같은 유형의 기본 키는 seed 디렉터리 전체에서 고유해야 합니다.
seed.link는 seed.add가 반환한 참조를 사용하며 양끝을 같은 createSeed 호출에서 등록해야 합니다.

다음은 가상의 superproduct와 seller를 같은 호출에서 연결합니다. 가격 5,900과 4,720의 통화 단위는 예제 스키마가 정하며 플랫폼 공통 단위가 아닙니다.

import { seller, superproduct } from "@ontology/sdk";
import { createSeed } from "@osdk/seed-helpers";

export default createSeed((seed) => {
  const charger = seed.add(superproduct, {
    pk: "prod-004",
    title: "USB-C 100W GaN Charger",
    price: 5900,
    newPrice: 4720,
    description: "Compact 100W USB-C GaN wall charger",
  });
  const halcyon = seed.add(seller, {
    pk: "seller-003",
    name: "Halcyon Desk Co.",
  });
  seed.link("charger-seller-link", charger, "sellers", halcyon, "superproducts");
});

실행마다 새 로컬 데이터베이스를 사용하여 seed를 다시 적용합니다. 로컬 서버를 재시작하면 그 실행에서 편집한 객체를 버립니다. seed 파일은 제품 데이터로 배포하지 않습니다.

Nx 대신 다른 작업 조정 도구

foundry create는 기본으로 Nx를 구성하지만 CLI가 nx.json이나 project.json을 직접 읽지는 않습니다. 다른 시스템으로 바꾸려면 각 project.json의 Foundry CLI 호출과 실행 의존 순서를 새 도구로 옮깁니다.

Node 의존성을 설치하는 모든 명령은 foundry run-with-auth로 감싸야 합니다. 이 명령이 FOUNDRY_HOSTNAME과 FOUNDRY_TOKEN을 주입하여 .npmrc가 해당 환경 변수를 사용할 수 있게 합니다. 토큰 값을 .npmrc에 직접 적지 않습니다.

웹사이트 CSP

앱이 다른 출처의 리소스를 읽으면 제품 웹사이트의 Content Security Policy에 해당 출처를 허용해야 합니다. 그렇지 않으면 브라우저가 요청을 차단합니다.

contentSecurityPolicyAdditions:
  img-src:
    - tile.openstreetmap.org

이는 지도 타일 이미지를 읽는 예입니다. 출처 값은 실제 필요한 호스트, HTTPS URL 또는 'self' 같은 CSP 값입니다.

지원 directive는 connect-src, frame-src, img-src, media-src, script-src, style-src, font-src와 frame-ancestors입니다. 이 설정은 components 및 bundle과 같은 제품 수준에 두며 APP 컴포넌트가 있을 때만 적용합니다. 단일 제품은 파일 최상위, 여러 제품은 해당 products 항목 안에 둡니다.

미리보기의 원격 플랫폼 API

embedded 서버는 일부 플랫폼 API만 구현합니다. 예를 들어 LLM 제공자 프록시는 실제 플랫폼 인스턴스에 요청해야 합니다. 최상위 platformApiProxy의 passthrough에 경로와 HTTP 메서드를 명시합니다.

platformApiProxy:
  passthrough:
    - path: /api/v2/admin/users/getCurrent
      methods: [GET]
    - path: /api/v2/llm/proxy/openai/v1/responses
      methods: [POST]

getCurrent GET은 실제 사용자 정보를 조회하고 responses POST는 실제 모델 요청을 보낼 수 있습니다. 로컬 미리보기라는 이유로 원격 호출의 비용과 효과가 없어지는 것은 아닙니다.

프록시는 설치 시 임시 TOKEN이 아니라 foundry login으로 저장한 인증을 사용합니다. 인증 오류가 나면 foundry login refresh로 다시 승인합니다. 이 설정은 미리보기에서만 적용하며 배포 제품의 동작은 바꾸지 않습니다.

Keyboard shortcuts

팔란티어 플랫폼 한국어 해설