sgcREST 기능 매트릭스
sgcREST가 제공하는 모든 기능을, REST 서버와 그 컴패니언, OpenAPI 서버 엔진, OpenAPI 클라이언트 계열을 기준으로 정리했습니다. 모든 기능이 Delphi와 C++ Builder에서 동일하게 동작하며, 모든 라이선스에 전체 소스 코드가 제공됩니다. 이번 출시에서는 컴포넌트 하위 페이지가 아직 게시되지 않아, 아래 각 항목은 이 페이지 안에서 자체적으로 완결됩니다.
sgcREST가 제공하는 모든 기능을, REST 서버와 그 컴패니언, OpenAPI 서버 엔진, OpenAPI 클라이언트 계열을 기준으로 정리했습니다. 모든 기능이 Delphi와 C++ Builder에서 동일하게 동작하며, 모든 라이선스에 전체 소스 코드가 제공됩니다. 이번 출시에서는 컴포넌트 하위 페이지가 아직 게시되지 않아, 아래 각 항목은 이 페이지 안에서 자체적으로 완결됩니다.
CORS, 통계, 테넌시 & 사용자
스펙 우선 & 코드 우선
OpenAPI로 설명된 모든 API 사용
Delphi 7부터 13까지, C++ Builder
sgcREST는 자체 완결형 제품입니다. sgcWebSockets Core 런타임이 함께 포함되어 제공되므로 애드온이 아니며, RAD Studio에 기본으로 포함된 표준 Indy 라이브러리에서 동작합니다.
코드 우선 OpenAPI에는 Delphi XE7 이상이 필요합니다. 애트리뷰트가 지정된 Delphi 클래스에서 스펙을 생성하려면 XE7에서 도입된 RTTI가 필요합니다. REST 서버와 그 컴패니언, 스펙 우선 OpenAPI 엔진은 Delphi 7부터 13까지 동작합니다.
SGC REST 팔레트 페이지의 컴포넌트 4종과, 코드 전용 OpenAPI 서버 및 클라이언트 클래스 3종이 sgcHTTP_REST_Server* 유닛과 sgcHTTP_OpenAPI_* 유닛에 선언되어 있습니다.
| 컴포넌트 | 클래스 | 팔레트? | 설명 |
|---|---|---|---|
| REST 서버 | TsgcHTTPRESTServer | 있음 | TsgcHTTPServer 기반의 REST API 서버이며, CORS 처리와 연결 가능한 통계/테넌시 컴패니언을 갖추고 있습니다. |
| REST 서버 통계 | TsgcHTTPServerStats | 있음 | 요청 카운터, 지연 시간 추적, Prometheus /metrics, JSON /health를 제공합니다. |
| REST 서버 테넌시 | TsgcHTTPServer_Tenancy | 있음 | 호스트, 경로, 헤더, JWT 클레임 기준의 멀티테넌트 해석입니다. |
| REST 서버 사용자 | TsgcHTTPServer_Users | 있음 | 로컬 계정 저장소입니다: 사용자를 추가, 검증, 해싱, 역할 지정, 저장합니다. |
| OpenAPI 서버, 스펙 우선 | TsgcOpenAPIServerHandler | 없음, 코드 전용 | 불러온 OpenAPI 3.0/3.1 문서로 API를 제공하며, 요청 검증을 포함합니다. |
| OpenAPI 서버, 코드 우선 | TsgcOpenAPICodeFirstScanner | 없음, 코드 전용 | RTTI 애트리뷰트가 지정된 Delphi 클래스에서 OpenAPI 스펙을 생성합니다. Delphi XE7 이상 필요. |
| OpenAPI 클라이언트 | TsgcOpenAPI_Client | 없음, 코드 전용 | OpenAPI로 설명된 모든 엔드포인트용 범용 런타임 클라이언트입니다. |
TsgcHTTPRESTServer는 TsgcHTTPServer의 자손이므로, 모든 sgc HTTP 서버가 공유하는 동일한 바인딩과 TLS 처리에서 시작해, 그 위에 REST API에 흔히 필요한 추가 기능을 더합니다.
| 기능 | API | 비고 |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | 기본값은 꺼짐입니다. 활성화하면 프리플라이트 OPTIONS 요청이 자동으로 응답됩니다. |
| 통계 컴패니언 | ServerStats: TsgcHTTPServerStats | 통계 컴포넌트를 연결하면 라우트 핸들러를 건드리지 않고도 모든 요청이 집계되고 시간이 측정됩니다. |
| 테넌시 컴패니언 | Tenancy: TsgcHTTPServer_Tenancy, Tenant | 테넌시 컴포넌트를 연결해 호출자의 테넌트를 해석합니다. Tenant는 현재 요청의 결과 값을 읽어들입니다. |
| 요청 카운터 | TotalRequests, Status1xx부터 Status5xx까지 | TsgcHTTPServerStats에 있습니다. 응답이 전송될 때마다 상태 클래스별로 집계됩니다. |
| 지연 시간 | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | TsgcHTTPServerStats에서 요청별로 추적되며 Reset으로 초기화됩니다. |
| 메트릭 엔드포인트 | GetMetricsText, IsMetricsRequest | Prometheus 텍스트 노출 형식 0.0.4이며 /metrics에서 제공됩니다. |
| 헬스 엔드포인트 | GetHealthJSON, IsHealthRequest | /health에서 제공되는 JSON 헬스 페이로드이며, UptimeSeconds와 ActiveConnections를 포함합니다. |
| 엔드포인트별 통계 | GetEndpointStats, Endpoints | 보고서나 관리 콘솔용으로 엔드포인트별 경로/카운트 쌍을 제공합니다. |
| 테넌트 해석 | Resolution, ResolveTenant | TsgcHTTPServer_Tenancy에 있습니다. 호스트 접미사, 경로 세그먼트, 헤더, JWT 클레임 기준으로 해석합니다. |
| 테넌트 소스 | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | 구성된 Resolution 모드가 읽는 소스와, 결과가 없을 때의 기본값입니다. |
| 사용자 정의 해석 | OnResolveTenant | 내장된 해석 로직을 재정의하거나 확장합니다. |
| 사용자 계정 | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | TsgcHTTPServer_Users에 있습니다. 솔트와 해시가 적용된 자격 증명이며, 평문으로 반환되지 않습니다. |
| 역할 | AddRole, RemoveRole, UserHasRole, GetUserRoles | 계정별 자유 형식 역할 태그이며, 라우트 핸들러에서 확인합니다. |
| 열거 | Count, GetUserCount, GetUserByIndex, GetUsernames | 보고서나 관리 콘솔용 읽기 전용 뷰입니다. 비밀번호 해시와 솔트는 절대 포함되지 않습니다. |
| 영속성 | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest가 저장소를 암호화합니다. OnLoadUsers/OnSaveUsers로 사용자 정의 백엔드를 사용할 수 있습니다. |
| 이벤트 | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | 내장 로직이 다루지 않는 경우를 위해 컴패니언마다 이벤트가 하나씩 있습니다. |
두 방식 모두 동일한 라우트 테이블과 요청 컨텍스트로 이어지며, OpenAPI 문서의 출처만 다릅니다.
| 기능 | API | 비고 |
|---|---|---|
| 라우트 테이블 | TsgcOpenAPIRouteTable (Add, Match) | 스펙의 paths 섹션에서 구축되며, 메서드와 경로를 operationId에 매칭합니다. |
| 요청 컨텍스트 | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | 매칭된 요청마다 하나씩 생성되며, 요청이 끝나면 해제됩니다. |
| 타입 지정 파라미터 | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | 경로나 쿼리 값을 한 번의 호출로 읽고 변환합니다. |
| 본문 접근 | BodyAsString, BodyAsJSON, HeaderValue | 요청 본문을 한 번 파싱해 결과를 캐시합니다. |
| 응답 | RespondJSON, RespondError | 상태 코드와 함께 JSON 본문을 쓰거나, 구조화된 오류 페이로드를 씁니다. |
| 요청 생명 주기 | BeforeHandle, AfterHandle, HandleException | TsgcOpenAPIServerHandler에 있습니다. 재정의해 로깅, 인증 확인, 사용자 정의 오류 매핑을 더할 수 있습니다. |
| 검증 | TsgcOpenAPIJSONValidator | 요청 본문, 쿼리, 경로 파라미터를 스펙이 선언하는 JSON 스키마에 대해 검증합니다. |
| 스펙 생성 | GenerateSpec, Title, Description, Version, BasePath | TsgcOpenAPICodeFirstScanner에 있습니다. 애트리뷰트가 지정된 클래스의 RTTI에서 OpenAPI 3.0 문서를 생성합니다. |
| 계약 애트리뷰트 | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | 생성된 스펙을 채우는 클래스 및 메서드 수준 애트리뷰트입니다. |
| 메서드 애트리뷰트 | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | 애트리뷰트가 지정된 메서드가 응답하는 HTTP 메서드를 선언합니다. |
| 파라미터 바인딩 | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | 각 메서드 파라미터를 어디서 읽어올지 선언합니다. |
| 디스패치 | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | operationId에 등록된 애트리뷰트 지정 메서드를 수동 if 체인 없이 직접 호출합니다. |
| 의존성 | Delphi XE7 이상 | 코드 우선 스캔과 디스패치는 XE7 이전에는 없는 System.Rtti에 의존합니다. 스펙 우선에는 이런 요구 사항이 없습니다. |
OpenAPI로 설명된 모든 엔드포인트용 범용 클라이언트이며, Basic 인증, 베어러 토큰, 범용 OAuth2, 범용 JWT가 내장되어 있습니다.
| 기능 | API | 비고 |
|---|---|---|
| 기본 호출 | HTTP_REQUEST | TsgcOpenAPI_Client에 있습니다. TsgcOpenAPIRequest/TsgcOpenAPIResponse 쌍을 모든 엔드포인트로 전달합니다. |
| 기본 URL | SetBaseURL, GetBaseURL | 요청 안의 모든 상대 경로가 해석되는 기준 엔드포인트입니다. |
| 범용 인증 | Authentication (Basic, Token, OAuth2, JWT) | Basic 인증과 베어러 토큰, 그리고 범용 OAuth2와 JWT 흐름입니다. |
| 전송 | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | 나머지 sgc HTTP 스택과 공유되는 표준 TLS 및 프록시 구성입니다. |
| 진행 상황 & 로깅 | OnUpload, OnDownload, Log, LogFileName | 대용량 요청/응답 본문을 추적하고, 선택적으로 모든 호출을 파일에 기록합니다. |
| 요청 훅 | OnBeforeRequest | 전송 전에 요청을 확인하거나 수정합니다. |
| TLS 훅 | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | 인증서 검증과 핸들러 커스터마이즈이며, 나머지 sgc HTTP 스택과 공유됩니다. |
와이어 위의 공식 표준을, 지원하는 모든 컴파일러에서 동일한 소스로 사용합니다.
| 영역 | 내용 |
|---|---|
| OpenAPI | OpenAPI 3.0과 3.1이며, 서버의 스펙 우선 라우팅과 요청 검증이 대조하는 JSON 스키마 모두에 적용됩니다. |
| 클라이언트 인증 | HTTP Basic 인증과 베어러 토큰, 그리고 범용 OAuth2와 JWT입니다. |
| 메트릭 | /metrics에서 제공되는 Prometheus 텍스트 노출 형식 0.0.4. |
| 플랫폼 | 일곱 개의 클래스 모두 Windows Win32, Windows Win64, Linux64, macOS, iOS, Android를 지원합니다. |
| 의존성 | 번들로 포함된 sgcWebSockets Core 런타임 외에는 없습니다. 일곱 개의 클래스 중 어느 것에도 추가 애드온이 필요하지 않습니다. |
| 컴파일러 | Delphi와 C++ Builder 7부터 13까지. 코드 우선 OpenAPI에는 Delphi XE7 이상이 필요합니다. |
| 에디션 | REST 서버 계열은 sgcWebSockets Professional 에디션부터, OpenAPI 서버는 Enterprise 에디션부터, OpenAPI 클라이언트 계열은 Standard 에디션부터 함께 제공됩니다. |
| 라이선스 | 단독 제품입니다. sgcWebSockets Core 런타임이 함께 포함되며 전체 소스 코드가 제공됩니다. |