98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# 함수 설계서: `runProbe` (#424)
|
|
|
|
> **부모 설계서**: ./README.md · **상태**: Draft
|
|
> **작성**: [AI] Architect · **구현**: `OrdsProbeService.runProbe` · **테스트**: `OrdsProbeServiceTest`
|
|
|
|
## 1. 시그니처
|
|
|
|
```java
|
|
ProbeResult runProbe(ProbeCommand command)
|
|
```
|
|
|
|
## 2. 책임 (단일 책임, 1줄)
|
|
|
|
선택된 Bearer Token과 보호 객체 whitelist를 사용해 ORDS 검증 호출을 실행하고 결과 또는 오류를 분류한다.
|
|
|
|
## 3. 입력
|
|
|
|
| 파라미터 | 타입 | 제약/검증 | 설명 |
|
|
|----------|------|-----------|------|
|
|
| `command.keyId` | `long` | 활성 token이어야 함 | 사용할 Bearer Token |
|
|
| `command.objectId` | `long` | 활성 보호 객체 | ORDS 호출 대상 |
|
|
| `command.limit` | `int` | 1 이상 500 이하 | 조회 행 제한 |
|
|
|
|
## 4. 출력
|
|
|
|
- **반환**: `ProbeResult`
|
|
- `status`: 성공/차단/오류 분류
|
|
- `columns`: 반환 컬럼
|
|
- `rows`: 결과 행
|
|
- `rowCount`: 행 수
|
|
- `maskedColumns`: NULL 또는 마스킹으로 판단된 컬럼
|
|
- `errorCode`, `errorMessage`: 오류 시 분류 정보
|
|
- **부수효과**: ORDS HTTP 호출, audit insert
|
|
|
|
## 5. 동작 / 알고리즘
|
|
|
|
1. `keyId`로 token 상태를 조회한다.
|
|
2. token이 만료 또는 회수 상태면 ORDS 호출 없이 실패 결과를 반환한다.
|
|
3. `objectId`로 보호 객체를 조회하고 활성 상태를 확인한다.
|
|
4. ORDS URL은 설정된 base URL과 보호 객체의 `ords_path`로 만든다.
|
|
5. 요청 timeout과 행 제한 parameter를 적용한다.
|
|
6. `Authorization: Bearer <token>` 헤더로 ORDS를 호출한다.
|
|
7. 2xx 응답이면 JSON을 파싱해 컬럼과 행 수를 계산한다.
|
|
8. 민감 컬럼이 모두 NULL인 경우 Redaction 적용 표시를 만든다.
|
|
9. 비 2xx 또는 Oracle 오류 body이면 `classifyProbeError`로 분류한다.
|
|
10. audit log를 저장한다.
|
|
11. 화면 표시용 `ProbeResult`를 반환한다.
|
|
|
|
## 6. 에러 & 실패 모드
|
|
|
|
| 조건 | 처리 | 반환/예외 |
|
|
|------|------|-----------|
|
|
| token 없음 | ORDS 호출 안 함 | `TOKEN_NOT_FOUND` |
|
|
| token 만료/회수 | ORDS 호출 안 함 | `TOKEN_INACTIVE` |
|
|
| 보호 객체 없음/비활성 | ORDS 호출 안 함 | `OBJECT_DISABLED` |
|
|
| ORDS timeout | audit 후 오류 반환 | `ORDS_TIMEOUT` |
|
|
| `ORA-20002` | 잘못된 key로 분류 | `INVALID_TOKEN` |
|
|
| `ORA-00942` / `ORA-01031` | 객체 권한 없음으로 분류 | `OBJECT_NOT_ACCESSIBLE` |
|
|
| 2xx + 빈 rows | VPD deny 가능성 표시 | `VPD_DENY_EMPTY_RESULT` |
|
|
| 알 수 없는 오류 | 원문 일부만 표시 | `UNKNOWN_ERROR` |
|
|
|
|
## 7. 엣지케이스
|
|
|
|
- 응답이 JSON이 아니면 성공으로 보지 않고 `INVALID_ORDS_RESPONSE`로 분류한다.
|
|
- 결과가 500행을 넘지 않도록 limit 기본값과 최대값을 둔다.
|
|
- audit에는 token 원문을 저장하지 않고 `key_id`, `key_prefix`만 저장한다.
|
|
- ORDS 응답 body 전체를 audit에 저장하지 않고 오류 코드와 짧은 메시지만 저장한다.
|
|
|
|
## 8. 복잡도 / 성능
|
|
|
|
- 네트워크 I/O가 지배적이다.
|
|
- 기본 timeout은 10초다.
|
|
- 화면 검증 호출이므로 자동 재시도는 하지 않는다.
|
|
|
|
## 9. 의존성
|
|
|
|
- `BearerTokenMapper`
|
|
- `ProtectedObjectMapper`
|
|
- `RestClient` 또는 `WebClient`
|
|
- `ProbeErrorClassifier`
|
|
- `AuditService`
|
|
- `Clock`
|
|
|
|
## 10. 테스트 케이스
|
|
|
|
- [ ] 정상: 2xx JSON 응답에서 컬럼과 행 수 추출
|
|
- [ ] 정상: 빈 rows를 VPD deny 가능성으로 표시
|
|
- [ ] 정상: 민감 컬럼 NULL을 masked column으로 표시
|
|
- [ ] 실패: 만료 token이면 ORDS 호출하지 않음
|
|
- [ ] 실패: 비활성 객체이면 ORDS 호출하지 않음
|
|
- [ ] 실패: `ORA-20002` 분류
|
|
- [ ] 실패: timeout 분류
|
|
|
|
## 11. 추적성
|
|
|
|
- 인수조건: #424의 "ORDS 호출 검증 화면에서 Bearer Token과 보호 객체를 선택하면 ORDS 호출 결과, 반환 컬럼, 행 수, 오류 유형을 확인할 수 있다."
|
|
- 관련 ADR: 없음
|