Engine Operations API¶

Engine Operations API는 Hub와 운영 자동화가 Engine runtime을 등록, 점검, 동기화하기 위해 사용하는 운영 API다. 일반 애플리케이션, Direct API 클라이언트, Wrapper 연동 코드, DB UDF 호출자가 직접 사용하는 실행 API가 아니다.

일반 연동자가 직접 호출할 수 있는 암복호화 실행 계약은 Engine API를 기준으로 본다.

문서 범위¶

이 문서는 Engine 운영에 필요한 runtime identity, heartbeat, cache sync, key sync, stats 연결 점검 경로를 정리한다.

구분	대표 경로	호출 주체	목적
Runtime identity	`/engine/api/v1/runtime/identity`	Hub	Engine runtime identity 등록
Runtime status	`/engine/api/v1/runtime/info`	Hub	Engine runtime capability와 상태 조회
Heartbeat	`/engine/api/v1/runtime/heartbeat`	Hub	Engine heartbeat와 runtime sync 반영
Cache management	`/engine/api/v1/cache/*`	Hub	정책/키 캐시 동기화와 상태 조회
Stats connection	`/engine/api/v1/stats/test-connection`	Hub	stats target 연결 점검

호출 경계¶

Engine Operations API는 Hub와 Engine 사이의 신뢰 경로에서 호출한다.

일반 고객 애플리케이션은 이 API를 호출하지 않는다.
Wrapper와 DB UDF는 runtime 실행 시 Engine API의 /api/* 실행 경로를 사용한다.
운영자는 보통 Hub UI, Hub CLI, 배포 자동화, 운영 절차를 통해 이 경로를 간접적으로 사용한다.
장애 분석 시에는 Engine 실행 API 실패와 운영 API 동기화 실패를 분리해서 본다.

Runtime tenant header¶

runtime identity가 설정된 이후 운영 API는 Engine runtime tenant header를 검증한다.

X-DADP-Tenant-Id: <engine-runtime-tenant-id>

이 값은 Hub가 발급한 Engine runtime identity다. 애플리케이션 사용자 식별자나 Wrapper alias가 아니다.

Operations 경로¶

경로	메서드	인증	역할
`/engine/api/v1/runtime/identity`	`POST`	최초 등록 경로	Hub가 발급한 Engine runtime identity 등록
`/engine/api/v1/runtime/info`	`GET`	`X-DADP-Tenant-Id`	Engine 버전, 상태, provider family, capability 조회
`/engine/api/v1/runtime/heartbeat`	`POST`	`X-DADP-Tenant-Id`	Hub heartbeat 수행 및 runtime sync 반영
`/engine/api/v1/cache/status`	`GET`	`X-DADP-Tenant-Id`	현재 정책/키 캐시 항목 수 조회
`/engine/api/v1/cache/clear`	`POST`	`X-DADP-Tenant-Id`	Engine 런타임 캐시 초기화
`/engine/api/v1/cache/policies/sync`	`POST`	`X-DADP-Tenant-Id`	정책 증분 동기화
`/engine/api/v1/cache/policies/sync-all`	`POST`	`X-DADP-Tenant-Id`	정책 전체 동기화
`/engine/api/v1/cache/keys/sync`	`POST`	`X-DADP-Tenant-Id`	키 증분 동기화
`/engine/api/v1/cache/keys/sync-all`	`POST`	`X-DADP-Tenant-Id`	키 전체 동기화
`/engine/api/v1/stats/test-connection`	`GET`	`X-DADP-Tenant-Id`	stats target 연결 점검

Runtime identity 등록¶

POST /engine/api/v1/runtime/identity

요청 본문:

{
  "hubUrl": "http://dadp-hub:9004",
  "tenantId": "etenant_example"
}

응답 본문:

{
  "success": true
}

등록된 Hub URL과 다른 Hub URL로 변경하려 하면 409 Conflict를 반환한다. Hub URL 변경이 필요한 경우에는 Engine runtime identity와 캐시 초기화 절차를 운영 절차로 처리한다.

Runtime info¶

GET /engine/api/v1/runtime/info

응답에는 Engine version, status, provider family, capability가 포함된다. 이 경로는 실행 API의 health endpoint를 대체하지 않는다. 실행 API 가용성은 /api/health와 실제 암복호화 round trip으로 확인한다.

Heartbeat¶

POST /engine/api/v1/runtime/heartbeat

Engine은 현재 runtime version과 crypto metric을 기준으로 Hub heartbeat를 수행한다. Hub가 runtime 변경을 응답하면 Engine은 정책과 키 snapshot을 런타임 캐시에 반영한다.

이 경로는 일반 클라이언트가 직접 호출해 정책을 강제로 갱신하는 경로가 아니다. 운영자는 Hub UI, Hub CLI, 운영 자동화 경로를 통해 동기화 상태를 관리한다.

Cache status¶

GET /engine/api/v1/cache/status

응답 본문:

{
  "policyCount": 12,
  "keyCount": 4
}

이 응답은 Engine 로컬 런타임 캐시의 항목 수를 보여 준다. 정책 원본의 전체 개수나 Hub 저장소 상태를 의미하지 않는다.

Cache clear¶

POST /engine/api/v1/cache/clear

응답 본문:

{
  "success": true
}

캐시 초기화는 실행 영향이 있는 운영 작업이다. 단독으로 호출하기보다 Hub 기준 runtime sync 또는 운영 절차와 함께 수행한다.

Policy sync¶

정책 동기화 경로는 단건, 배열, envelope 형태를 수용한다.

경로	의미
`/engine/api/v1/cache/policies/sync`	정책 증분 동기화
`/engine/api/v1/cache/policies/sync-all`	정책 전체 동기화

허용 payload 형태:

{
  "policy": {
    "policyCode": "ABCD2345"
  }
}

{
  "policies": [
    {
      "policyCode": "ABCD2345"
    }
  ]
}

{
  "items": [
    {
      "policyCode": "ABCD2345"
    }
  ]
}

응답 본문:

{
  "success": true,
  "count": 1
}

Key sync¶

키 동기화 경로는 단건, 배열, envelope 형태를 수용한다.

경로	의미
`/engine/api/v1/cache/keys/sync`	키 증분 동기화
`/engine/api/v1/cache/keys/sync-all`	키 전체 동기화

허용 payload 형태:

{
  "key": {
    "alias": "main-key"
  }
}

{
  "keys": [
    {
      "alias": "main-key"
    }
  ]
}

{
  "items": [
    {
      "alias": "main-key"
    }
  ]
}

응답 본문:

{
  "success": true,
  "count": 1
}

Stats connection test¶

GET /engine/api/v1/stats/test-connection?statsTargetUrl=<url>

Engine이 지정된 stats target에 연결 가능한지 확인한다. 운영자는 이 경로를 직접 호출하기보다 Hub 운영 화면 또는 운영 자동화 결과를 기준으로 확인한다.

오류 응답¶

상황	HTTP status	응답 예
지원하지 않는 메서드	`405`	`{"error":"method not allowed"}`
runtime identity 미설정	`503`	`{"error":"runtime identity is not configured"}`
runtime tenant header 불일치	`401`	`unauthorized`
runtime identity Hub URL 변경 시도	`409`	`{"error":"runtime identity hubUrl cannot be changed through registration"}`
sync payload 오류	`400`	`{"error":"policy sync request has no policies"}`
heartbeat upstream 실패	`502`	`{"success":false,"error":"..."}`

운영 해석¶

Control-plane API가 정상이어도 실행 API의 암복호화 성공을 보장하지 않는다.
실행 API가 정상이어도 Hub 원본 정책과 Engine 캐시가 최신이라는 뜻은 아니다.
runtime identity 문제는 배포, 등록, 재등록 절차와 연결해서 본다.
cache sync 문제는 Hub 정책 원본, runtime version, Engine 로컬 캐시 상태를 함께 확인한다.