본문으로 건너뛰기

Providers

Provider는 union-cli에서 실제 작업을 수행하는 실행 엔진입니다. 4가지 Provider 타입을 지원하며, 각각 다른 백엔드 시스템과 통신합니다.

Quick Comparison​

어떤 Provider를 선택해야 할지 빠르게 비교할 수 있는 표입니다.

HTTPCLIPythonJS
용도REST API 호출외부 CLI 바이너리 래핑Python 함수 호출Node.js 모듈 호출
통신 방식fetch()child_process.spawn()JSON-RPC over stdioin-process 직접 호출
응답 속도~50ms+ (네트워크 RTT)~100ms+ (프로세스 spawn)~10ms (persistent) / ~500ms+ (one-shot)~1ms (가장 빠름)
인증 지원bearer, basic, jwt, api-key, cookieN/AN/AN/A
대표 사례내부/외부 REST APIkubectl, terraform, dockerML SDK, 데이터 파이프라인유틸리티 모듈
Provider 선택 기준
  • REST API가 있다면 → HTTP Provider
  • 이미 잘 동작하는 CLI 도구가 있다면 → CLI Provider
  • Python 라이브러리/SDK를 사용해야 한다면 → Python Provider
  • 최대 성능이 필요하거나 Node.js 모듈이라면 → JS Provider

Provider 개념​

모든 Provider는 IProvider 인터페이스를 구현합니다:

interface IProvider {
  readonly type: ProviderType;   // 'http' | 'cli' | 'python' | 'js'
  resolveCommands(manifest: PluginManifest): CommandSpec[];
  execute(spec: CommandSpec, input: ExecutionInput): Promise<ExecutionResult>;
  healthCheck?(): Promise<HealthCheckResult>;
}
  • execute(): 커맨드의 args와 flags를 받아 Provider별 방식으로 실행하고 ExecutionResult를 반환합니다.
  • healthCheck(): Provider의 연결 상태를 확인합니다 (doctor 커맨드에서 사용).

Health Check 방식​

ProviderHealth Check 방식
HTTPbaseUrl에 GET 요청 (5초 타임아웃)
CLI{binary} version 또는 --version
Pythonpython3 --version
JS모듈 import() 시도

Provider 설정​

4가지 Provider의 YAML 설정 요약입니다. 전체 설정 필드는 Manifest 레퍼런스를 참조하세요.

# HTTP
provider:
  type: http
  config:
    baseUrl: "${BASE_URL:-https://api.example.com}/v1"
    auth: { ... }               # 인증 설정 (auth 문서 참조)
    headers: { ... }            # 기본 HTTP 헤더
    timeout: 30000              # ms (기본 30000)

# CLI
provider:
  type: cli
  config:
    binary: kubectl
    globalFlags: ["-o", "json"]

# Python
provider:
  type: python
  config:
    module: "my_sdk"
    persistent: true
    venv: "${MY_VENV_PATH}"

# JS
provider:
  type: js
  config:
    module: "./lib/sdk.js"

Provider 별 상세 가이드​

HTTP Provider​

REST API를 fetch()로 호출합니다. 가장 일반적으로 사용되는 Provider입니다.

  • 환경변수 치환 (${VAR:-default}) 지원
  • 인증 내장 (bearer, basic, jwt, api-key, cookie)
  • Flag → query / body / header 자동 매핑

커맨드 설정​

commands:
  - id: users:create
    description: "사용자 생성"
    http:
      method: POST               # GET, POST, PUT, PATCH, DELETE
      path: "/users"             # baseUrl에 이어붙는 경로
      body:                      # 정적 body (flag와 병합됨)
        source: "cli"

주요 기능​

Flag 매핑 (httpMap)

플래그 값을 HTTP 요청의 어떤 부분으로 매핑할지 지정합니다.

Query parameter:

flags:
  - name: status
    httpMap: query
    # -> GET /users?status=active

Request body:

flags:
  - name: name
    httpMap: body
    # -> POST /users  body: {"name": "John"}

Header:

flags:
  - name: trace-id
    httpMap: header
    # -> 요청 헤더에 추가: trace-id: <value>

httpName으로 CLI 플래그 이름과 API 파라미터 이름을 다르게 매핑할 수 있습니다 (--per-page → ?per_page=20).

전체 매핑 옵션과 httpBodyType에 대한 자세한 설명은 Manifest 레퍼런스를 참조하세요.

httpBodyType (Body 값 변환)

body로 매핑된 flag 값의 타입을 변환합니다:

httpBodyType변환입력 예시결과
jsonJSON.parse()'{"k":"v"}'{"k":"v"}
array콤마 split"a,b,c"["a","b","c"]
number-array콤마 split + Number"1,2,3"[1,2,3]

Path Parameter

URL 경로에 동적 값을 삽입합니다. args로 정의한 값이 {param} 위치에 대체됩니다:

commands:
  - id: users:get
    description: "사용자 상세 조회"
    http:
      method: GET
      path: "/users/{user_id}/posts/{post_id}"
    args:
      - name: user_id
        required: true
      - name: post_id
        required: true
my-cli api users get user-123 post-456
# -> GET https://api.example.com/v1/users/user-123/posts/post-456
Path parameter 인코딩

Path parameter 값은 자동으로 encodeURIComponent()로 인코딩됩니다. 특수 문자가 포함된 값도 안전하게 전달됩니다.

실행 순서​

HTTP Provider는 다음 순서로 요청을 구성합니다:

sequenceDiagram
    participant CLI as CLI Input
    participant HP as HTTP Provider
    participant API as API Server

    CLI->>HP: args + flags 전달
    HP->>HP: 1. Path parameter 치환 ({param} -> args 값)
    HP->>HP: 2. Query parameter 구성 (httpMap: query)
    HP->>HP: 3. Request body 구성 (정적 body + httpMap: body)
    HP->>HP: 4. 헤더 구성 (Content-Type + headers + auth)
    HP->>API: 5. fetch() 실행
    API-->>HP: Response
    HP->>HP: 6. 응답 파싱 (JSON 또는 텍스트)
    HP-->>CLI: ExecutionResult

실전 예제​

name: user-service
namespace: api
provider:
  type: http
  config:
    baseUrl: "${API_URL:-https://api.example.com}/v1"
    auth:
      type: bearer
      token:
        env: "API_TOKEN"

commands:
  - id: users:list
    description: "사용자 목록 조회"
    http: { method: GET, path: "/users" }
    flags:
      - name: limit
        type: number
        default: 20
        httpMap: query
      - name: status
        httpMap: query

  - id: users:create
    description: "사용자 생성"
    http: { method: POST, path: "/users" }
    flags:
      - name: name
        required: true
        httpMap: body
      - name: email
        required: true
        httpMap: body
      - name: tags
        httpMap: body
        httpBodyType: array

Provider 선택 가이드​

상세 선택 기준​

상황추천 Provider이유
REST API 호출HTTP네이티브 fetch, 자동 인증, flag-to-query/body 매핑
외부 CLI 도구 래핑 (kubectl, terraform, aws)CLI기존 CLI의 모든 기능을 그대로 활용, 출력 파싱 지원
Python SDK/라이브러리 사용PythonJSON-RPC bridge로 Python 생태계 활용, venv 지원
Node.js 모듈 직접 호출JSin-process 호출로 가장 빠름, 타입 안전성
빠른 응답이 필요한 반복 호출JS 또는 Python (persistent)네트워크 오버헤드 없음
여러 API를 하나로 통합HTTP (여러 manifest)manifest별로 다른 baseUrl/auth 설정 가능

성능 비교​

Provider응답 시간비고
JS Provider~1msin-process, 가장 빠름
Python (persistent)~10ms프로세스 재사용
HTTP Provider~50ms+네트워크 RTT 포함
CLI Provider~100ms+프로세스 spawn + 실행
Python (one-shot)~500ms+프로세스 spawn + Python 초기화

여러 Provider 혼합 사용​

하나의 CLI 프로젝트에서 여러 manifest를 통해 다양한 Provider를 동시에 사용할 수 있습니다:

plugins/
  api-service.yaml       # HTTP Provider  -> my-cli api ...
  k8s.yaml               # CLI Provider   -> my-cli k8s ...
  ml-features.yaml       # Python Provider -> my-cli ml ...
  data-tools.yaml        # JS Provider    -> my-cli data ...
독립적인 namespace

각 manifest는 독립적인 namespace를 가지며, 서로 다른 Provider 타입을 사용할 수 있습니다. 하나의 통합 CLI에서 HTTP API, CLI 도구, Python SDK, JS 모듈을 모두 함께 사용하세요.