공식 SDK 아키텍처 및 설계 원칙
7개 공식 SmallPict SDK가 엄격히 준수하는 공통 설계 규격, 보안 보증 및 내결함성 시맨틱.
SmallPict는 현대 개발 생태계를 이끄는 주요 언어들을 위해 7개의 공식 SDK를 제공하며, 모든 기술 스택에서 일관되고 견고한 개발 경험을 보장합니다.
표준화된 4가지 핵심 인터페이스
언어별 네이밍 관례와 관계없이 모든 공식 SDK는 동일한 4가지 핵심 동작을 충실히 구현하고 있습니다:
| 메서드명 | 기능 설명 |
|---|---|
optimize(source, options) | 이미지 바이너리, 파일 버퍼 또는 원격 URL을 압축, 변환(AVIF, WebP, JPEG, PNG) 및 크기 조절 |
getQuota() | 처리된 바이트 수, 월간 쿼터 한도 및 CDN 대역폭 사용량을 실시간 조회 |
purgeCdn(urls, purgeType) | 전 세계 SmallPict Edge PoP 노드의 캐시를 즉각적으로 무효화 |
validateKey() | 자격증명 상태 점검 및 계정 활성화 상태를 안전하게 검증 |
보조 메서드: getJobStatus(jobId) | 대용량 비동기 변환 작업의 진행 상태와 결과 다운로드 URL 폴링 |
자격증명 제로 리크 마스킹 (Zero-Leak Redaction)
모든 SDK는 정규식 기반 마스킹 엔진을 내장하고 있습니다. Secret Key(sec_...) 및 API Key(sp_sdk_..., sp_wp_..., sp_test_...)는 표준 출력, 디버거 검사창 또는 예외 스택 트레이스에 결코 평문으로 노출되지 않습니다:
TEXT
로그 출력 예시: "Request failed for key sp_sdk_9a8b...c4d3 and secret ***REDACTED***"고탄력성 요청 파이프라인과 멱등성 보장
1. 지터가 포함된 지수 백오프 재시도 (Exponential Backoff with Jitter)
일시적인 네트워크 순단, HTTP 429 (호출 빈도 제한) 또는 5xx 서버 에러가 발생하면 SDK는 무작위 지터가 포함된 지수 백오프 알고리즘으로 자동 재시도합니다 (기본값: 최대 3회):
TEXT
delay = baseDelay * (2 ^ (attempt - 1)) + jitter서버 응답에 Retry-After 헤더가 포함되어 있다면 해당 시간을 엄격히 준수합니다.
2. UUID v4 멱등성 키 자동 주입
상태를 변경하는 모든 요청에는 SDK가 고유한 Idempotency-Key 헤더를 자동 주입합니다. 네트워크 재시도로 인한 중복 결제나 중복 쿼터 차감은 원천 차단됩니다.
장애 조치 모드 (Fallback Modes)
모든 SDK는 fallbackMode 옵션을 통해 서비스 연속성을 보장합니다:
throw모드 (기본값): 쿼터가 모두 소진되면 타입화된QuotaExceededError예외를 발생시킵니다.passthrough모드: 가용성이 최우선인 핵심 서비스용. HTTP 402(쿼터 소진) 발생 시 에러를 던져 서비스를 중단시키는 대신 원본 비압축 이미지 Buffer를 안전하게 반환하여(savingsPercentage: 0.0) 24/7 무중단 운영을 보장합니다.