1 of 7

Schema Registry

A. Schema Integration

서비스 API 스키마는 서비스 브로커에 의존해 Gateway로 수집되고 처리됩니다. Moleculer 어댑터로 작성된 서비스 브로커의 경우 기본적으로 ServiceSchema의 metadata.api 필드에서 서비스 API 스키마가 수집되기를 기대합니다.

서비스 API 스키마의 병합은 서비스 노드의 연결, 종료, 스키마 변경시 발생합니다. 서비스 API 스키마는 자신의 스키마를 병합 할 브랜치를 스키마에 명시합니다. Gateway에는 기본적으로 master 브랜치가 생성되어있으며, master 브랜치는 제거 될 수 없습니다.

Branch, Version, Integration

Integration Process

병합 규칙은 다음과 같습니다.

discover
- discover 발생 즉시 병합 요청이 생성됩니다.
- 프로토콜 플러그인을 따라 스키마 포맷에 대한 검증을 거칩니다.
  - 포맷 에러는 병합 요청 메세지 리스트에 포함됩니다.
  - 접근 제어를 우회하는 엔드포인트에 대한 경고가 병합 요청 메세지 리스트에 포합됩니다.
- 검증 성공시 병합 요청이 큐에 삽입되면서 특정 시간(2초를 기본값) 동안 debounce 후 순차적으로 처리됩니다.
  - 큐에서 특정 서비스에 대한 병합 요청이 다수인 경우 마지막 요소만 유효합니다.
  - 프로토콜 플러그인에서 integrationDependencyResolver가 구현된 경우 (eg. GraphQL) 큐 안에서 처리 순서가 조정 될 수 있습니다.
- 검증 실패시 report 단계로 건너 뜁니다.
hash
- 서비스 API 스키마에서 branch, description, deprecated등의 메타 정보를 제외한 스키마 객체 전체를 MD5 해싱하여 고유한 버전 해시를 생성합니다.
- 게이트웨이에 버전이 존재하지 않는 경우에는 스키마를 업데이트하기로 합니다.
- 서비스 노드의 연결이 끊긴 경우는 연관된 스키마의 노드풀에서 노드를 삭제합니다.
  - 이 때 연관된 스키마들에서 노드풀이 빈 스키마들을 제거하기로 합니다.
update
- master 브랜치의 스키마는 경우에는 모든 브랜치에 병합이 시도됩니다.
  - 이 때 master 외의 브랜치에서 스키마의 서비스명이 중복되는 경우 병합하지 않습니다. 기존 스키마의 우선 순위가 높습니다.
- 이외의 브랜치에 병합하는 경우에는 주어진 브랜치에만 병합이 시도됩니다.
- 프로토콜 플러그인을 따라 각 프로토콜별 핸들러를 생성합니다.
  - 병합에 성공하면 생성된 Gateway API 스키마 버전에 latest 태그 및 8 글자의 숏 해시(eg. abcdefgh)가 태그로 부착됩니다.
- 옵션이 활성화된 경우 브랜치별 API Catalog를 업데이트합니다.
- 옵션이 활성화된 경우 브랜치별 Service Catalog를 업데이트합니다.
report
- 병합 요청의 메세지 리스트를 기반으로 디버그 메세지를 생성합니다.
- 병합 요청의 출처 노드로 디버그 메세지를 report합니다.
Branch Strategy Diagram
브랜치간 병합 전략을 표로 도식하면 다음과 같습니다.
표에서 a@v1는 a 서비스 스키마 중 v1 버전을 의미합니다.
Routing Rule
Gateway 웹 서버는 [/~BRANCH[@TAG]]/<ENDPOINT>의 규칙대로 API 엔드포인트를 라우트합니다. 첫번째 경로 조각을 브랜치(master를 기본값으로)로 두번째 경로 조각을 태그(latest를 기본값으로)로 이하 경로를 API 엔드포인트로 해석합니다.
라우트 예시
테이블의 각 행은 동일한 버전의 핸들러로 연결됩니다.
브랜치 이름 규칙
- 영문 소문자 및 숫자, -, _만 허용됩니다.
- 기존 스키마 엔드포인트나 플러그인의 base 경로와 중복될 수 없습니다.
태그 이름 규칙
- 영문 소문자 및 숫자로만 구성됩니다.

Protocol Plugin

Plugin

플러그인은 서비스 API 스키마의 포맷과 기능을 확장하는데 쓰입니다. 플러그인은 위임된 스키마에 대한 검증, 해석, 작동 방식을 정의하고 구현합니다.

각 프로토콜 플러그인은 해당 프로토콜 스키마의 양식을 정의하고, 스키마 병합, 요청 프록시, 의존성 파악, 서버 확장 핸들러 등을 구현합니다.

각 접근 제어 플러그인은 해당 접근 제어 스키마의 양식을 정의하고, call, publish, subscribe 커넥터의 정책을 해석하고 접근 제어를 판단하는 핸들러를 구현합니다.

1. Protocol Plugin

프토토콜 플러그인별 스키마 양식은 섹션을 참조하십시오. 이 섹션에서는 기본 플러그인의 구동 방식을 개괄적으로 설명합니다.

A. REST

REST 프로토콜은 분산 서비스에 대한 call, publish 커넥터를 특정 엔드포인트에 맵핑합니다. HTTP 요청의 Paylo,ad는 미들웨어를 통해 파싱되어 params 커넥터를 통해 변환되어 call, publish 커넥터로 전달됩니다.

엔드포인트가 중복되는 경우 병합을 발생시킨 출처 노드로 디버그 메세지가 report되며 병합에 실패합니다.

API Catalog를 통해서 엔드포인트 별 적용된 정책 및 커넥터와 그 파라미터에 대한 설명을 제공합니다.

TODO: $headers, $status, $body field for REST response

B. GraphQL

GraphQL 프로토콜은 분산 서비스에 대한 call 및 publish, subscribe 커넥터를 특정 타입의 필드에 맵핑합니다. HTTP 요청의 Payload는 미들웨어를 통해 파싱되어 params 커넥터를 통해 변환되어 call, publish, subscribe, map 커넥터로 전달됩니다.

GraphQL 스키마 생성에 실패하는 경우 병합을 발생시킨 출처 노드로 디버그 메세지가 report되며 병합에 실패합니다.

API Catalog를 통해서 각 GraphQL Type 별 적용된 정책 및 커넥터와 그 파라미터에 대한 설명을 제공합니다.

서비스 API 스키마를 통해서 GraphQL Custom Scalar 정의를 추가 할 수 없습니다. Gateway 생성시 플러그인 옵션을 통해 Scalar 정의를 추가하거나 오버라이드 할 수 있습니다. 기본적으로 DateTime, Date, Time, JSON가 포함되어있습니다.

C. WebSocket

TODO: WIP

Policy Plugin

2. Access Control Policy

접근 제어 플러그인별 스키마 양식은 Access Control Policy 섹션을 참조하십시오. 이 섹션에서는 기본 플러그인의 구동 방식을 개괄적으로 설명합니다.

프로토콜의 확장성과 접근제어 정책의 정합성을 위해서, 접근 제어 정책은 프로토콜별 엔드포인트가 아니라 액션과 이벤트를 주체로 적용됩니다.

접근 제어 정책의 평가는 API Gateway의 메모리에 LRU 방식으로 캐시되며 한 요청에서 중복 수행되지 않습니다. 캐시 키를 생성 할 때 요청을 정확히 구분하기 위해서 컨텍스트(인증 정보) 및 호출 페이로드 등의 정보가 반영됩니다.

적용되는 플러그인의 순서는 유효합니다. 우선하는 플러그인에서 실패 할 경우 다음 플러그인의 정책은 평가되지 않습니다. 접근 제어 플러그인의 기본 옵션에서 OAuth2 Scope 플러그인(scopes)이 FBAC 플러그인(filter)보다 우선합니다.

A. OAuth2 Scope

OAuth2 Scope 플러그인은 각 정책의 scopes에 나열된 스코프를 context.scopes가 하나 이상의 스코프를 포함하는 경우 접근을 허용합니다.

B. FBAC

FBAC 플러그인은 각 정책의 filter 항목에 맵핑된 Inline JavaScript Function String을 VM에서 실행하고 그 Boolean 값으로 접근 제어 여부를 판단합니다. 평가중 에러가 발생하거나 Boolean 값이 리턴되지 않는 경우, API Gateway에서 출처 노드로 전달되며 접근이 거부됩니다.

디버깅 중에 Inline JavaScript Function String에서 console 객체를 사용해 메세지를 출력하는 경우, 그 메세지는 console 객체에 바인딩된 report 커넥터가 출처 노드로 전달합니다.

API Handler

B. API Handler

Dynamic Handler

동적 핸들러는 웹 서버의 모든 base 경로를 관리하며, 미들웨어 및 플러그인, 엔드포인트 간의 경로 충돌을 방지합니다. 동적 핸들러는 조건에 따라 브랜치 핸들러 및 버전 핸들러를 생성 및 삭제하며 동적으로 라우트 테이블을 구성합니다.

동적 핸들러는 클라이언트의 요청에 따라 미들웨어를 수행하고, 브랜치 핸들러로 요청을 프록시합니다.

Branch Handler

브랜치 핸들러는 태그에 따라 버전 핸들러로 요청을 프록시합니다.

이 브랜치 핸들러들은 아래의 규칙에 따라 삭제됩니다.

master 브랜치를 제외하고, 60분 이상 실행되지 않는 브랜치 핸들러는 삭제됩니다.

Version Handler

서비스 API 스키마의 병합이 일어날 때마다 새로운 버전의 Gateway API 스키마가 생성됩니다. 병합에 성공한 Gateway API 스키마는 latest 및 숏해시로 태그됩니다. 그리고 업데이트된 엔드포인트별로 스키마, 프로토콜 플러그인, 커넥터를 연결해 각 핸들러를 생성합니다. 업데이트되지 않은 스키마의 핸들러는 가능한 재참조됩니다.

이 버전 핸들러들은 아래의 규칙에 따라 삭제됩니다.

10개를 초과(기본값)하는 버전이 존재한는 경우 오래된 순으로 버전 핸들러가 삭제됩니다.

Non-Persistence

API 스키마의 브랜치 및 태그 기능은 버전 관리(/v1, /v2 같은)가 아닌 분산 환경에서의 개발 편의를 위해 개발되었습니다.

주의사항

Gateway에는 Persistence Layer가 존재하지 않습니다.
Gateway 재시작시 브랜치, 버전 및 태그 정보가 복원되지 않습니다.
Gateway 노드간에 데이터 동기화 전략이 존재하지 않습니다.
Gateway 노드간에 서비스 API 스키마 병합의 순서가 동일하게 보장되지 않습니다.

하지만 Gateway 재시작 이후 모든 서비스들에 대한 discover가 진행되면서 자연스럽게 각 브랜치의 latest 버전에는 최신 Gateway API 스키마가 복원됩니다. 각 브랜치의 latest 버전의 신뢰성은 보장됩니다.

API Document Generation

C. Reflection

API Gateway Health Check

Gateway 웹서버 자체의 상태 확인용 HTTP 엔드포인트를 내장하고 있습니다. 로드밸런서나 Kubernetes 등의 컨테이너 오케스트레이션 환경에서 활용 할 수 있습니다.

GET /~health/liveness 엔드포인트에서 웹 서버의 상태를 확인 할 수 있습니다.
GET /~health/readiness 엔드포인트에서 요청 처리가 가능한지 확인 할 수 있습니다.

Gateway 상태에 따른 각 엔드포인트의 HTTP 상태 코드는 다음과 같습니다.

API Endpoint Health Check

Gateway API 스키마의 각 엔드포인트 별 상태 확인 기능을 내장하고 있습니다. 엔드포인트에 연결된 커넥터를 기반으로 상태가 측정됩니다. 대부분의 커넥터의 상태 확인은 서비스 브로커에게 위임됩니다. 자세한 사항은 아래의 섹션을 참조 할 수 있습니다.

API 엔드포인트의 상태는 위처럼 HTTP로 제공되지 않으며 아래의 API Catalog를 통해서 제공됩니다.

API Catalog

API Catalog는 REST, GraphQL, WebSocket 등의 Protocol Plugin에 따라 각 엔드포인트에 대한 문서 정보를 제공하는 기능입니다. API Catalog 기능을 활성화하면 접근 제어 정책이 활성화되지 않은 API 타입이 GraphQL 스키마에 통합됩니다. 접근 제어 정책은 활성화시 옵션으로 주입 할 수 있습니다.

Service Catalog

Service Catalog는 분산 시스템의 서비스들의 각 엔드포인트에 대한 정보를 제공하는 기능입니다. Service Catalog 기능을 활성화하면 접근 제어 정책이 활성화되지 않은 Service 타입이 GraphQL 스키마에 통합됩니다. 접근 제어 정책은 활성화시 옵션으로 주입 할 수 있습니다.

Health Check