Repository navigation
0.1.6
생명 주기 훅 종합 변경 로그
개요
상위 이슈의 공통 설계와 세 하위 이슈의 구현을 통합해 Application, Extension, RequestRunner에 구성요소별 생명 주기 훅을 도입했다. 기존 요청·응답 필터를 단순히 이름만 바꾸지 않고, 각 구성요소의 책임과 실행 경계에 맞는 공개 계약으로 정리했다.
| 하위 이슈 | 주요 결과 | 상세 변경 로그 |
|---|---|---|
feature/4 |
Application 생성자 훅, 요청 디스패치 경계와 재진입 제어 | Application 변경 로그 |
feature/5 |
Extension 인스턴스·생성자 훅, 시작·정리 구조, Metrics 관찰 연결 | Extension 변경 로그 |
feature/6 |
RequestRunner 클래스 선언 훅, 기존 필터 제거, 직접 출력 후처리 | RequestRunner 변경 로그 |
이 문서는 최종 계약과 하위 작업의 검증 기록을 종합한다. 중간 설계나 이전 하위 작업 시점의 계약이 아니라 세 작업이 반영된 상태를 기준으로 한다.
1. 공통 계약과 책임 경계
훅 등록
- 훅은 이벤트별 ABC 인터페이스의
__call__계약으로 제공하며 패키지 최상위에서 공개한다. - 세 구성요소 모두 단일 훅 인스턴스 또는 해당 인터페이스 인스턴스의 시퀀스를 지원한다. 시퀀스는 순서를 보존한 튜플로 보관한다.
- 잘못된 입력과 반환값은 명시적으로 거부한다. 입력 형태가 비슷해도 각 구성요소의 인터페이스는 별도 계약이다.
- 오류 훅은 오류를 관찰하며, 정상 종료 시 원래 예외를 전파한다. 응답 대체·재시도·예외 소비를 수행하는 오류 복구 훅으로 제공하지 않는다.
| 구성요소 | 최종 등록 지점 | 생략·None 처리 |
|---|---|---|
| Application | 생성자 | 생략은 빈 훅, 명시적 None은 TypeError |
| Extension | 생성자, 인스턴스별 계약 | 생략·None은 빈 훅 |
| RequestRunner | __init_subclass__, 클래스 선언 계약 |
생략·None은 빈 훅 |
Extension은 초기 상위 설계의 클래스 선언 방식 대신 생성자에서 인스턴스별 훅을 받는 방식으로 최종 확정했다. 중간에 검토한 공개 Extension Factory도 최종 API에 포함하지 않는다.
구성요소별 실행 경계
| 구성요소 | 훅이 담당하는 경계 | 포함하지 않는 범위 |
|---|---|---|
| Application | 자신의 시작·정리와 준비된 요청의 디스패치·결과 반환 | HTTP 헤더 수신·파싱, 하위 구성요소의 내부 이벤트, 반환 이후 전송·스트림 소비 |
| Extension | 해당 확장의 시작·정리와 자신의 요청 처리 | 전역 요청 관찰의 암묵적 소유, 다른 확장·일반 핸들러 내부 실행, 전송 제어 |
| RequestRunner | 선택된 핸들러의 RunRequest 실행 파이프라인 | Application 라우팅·사전 검사 실패, 반환 이후 서버의 본문 소비·전송 실패 |
Application·Extension에는 별도 생성 완료 훅을 추가하지 않았다. Application 생성자 입력으로 훅을 계약하는 것과 생성 시 훅 이벤트를 실행하는 것은 구분한다.
전체 요청을 관찰해야 하는 확장은 Application 요청 훅을 명시적으로 등록한다. Extension 요청 훅 자체를 전체 요청 관찰 훅으로 확장하지 않는다.
2. Application 변경
공개 훅 추가
| 생성자 인자 | 인터페이스 | 입력 → 반환 |
|---|---|---|
on_startup |
ApplicationStartup |
인자 없음 → None |
on_cleanup |
ApplicationCleanup |
인자 없음 → None |
on_request |
ApplicationRequest |
Request → Request |
on_request_response |
ApplicationRequestResponse |
Request, Optional[Response] → Optional[Response] |
on_request_error |
ApplicationRequestError |
Request, Exception → None |
- Application 인스턴스를 사용자 훅의 인자로 전달하지 않는다.
- 요청 훅이 반환한 Request를 다음 훅과 디스패치에 전달하며, 응답 훅도 등록 순서대로 결과를 연결한다.
- 직접 출력 완료의 응답값은 None이다. 이 경로에서 새 Response를 만들거나 일반 응답을 None으로 버리는 변경은 허용하지 않는다.
- 같은 Application 훅 안에서 같은 Application의 시작·종료·요청 처리를 동기 재호출하면 RuntimeError로 거부한다. 서로 다른 스레드의 독립 요청은 허용한다.
- 훅 객체의 공유 상태에 대한 동기화는 사용자 책임이다.
확장 수명 및 동적 요청 훅 관리
- 시작 순서: Application 시작 훅 → 등록 순 Extension 시작 → 실행 상태 전환.
- 종료 순서: 시작 완료 Extension 역순 정리 → Application 정리 훅.
- 정리 중 오류가 발생해도 나머지 정리를 시도하고 첫 오류를 전파한다.
add_request_hooks(...)와remove_request_hooks(token), 공개RequestHookRegistration을 추가했다.- 동적 등록은 확장 시작 중, 해제는 소유 확장의 시작·정리 중에만 허용한다. 잘못된 토큰·소유자·중복 등록 및 해제를 거부한다.
- 동적 훅은 등록 순으로 생성자 훅보다 먼저 실행한다. 요청별 훅 구성을 복사해 진행 중인 요청은 같은 구성으로 완료한다.
- 확장 시작 실패나 정리 오류가 있어도 해당 확장 소유 등록을 롤백·해제한다.
3. Extension 변경
인스턴스 등록과 시작 단계 연결
Application(exts=...)는 생성된 Extension 인스턴스 시퀀스를 튜플로 보관한다. 클래스·Factory·동일 인스턴스 중복 및 서로 다른 Application 간 공유를 거부한다.startup(application)에서 Application 연결, 라우트 등록 및 자원 준비를 수행하고 사용자 시작 훅을 실행한다.cleanup()에서 사용자 정리 훅과 확장 자원 회수를 수행한다.- 추상 호출 계약을
__call__(request) -> Optional[Response]로 변경했다. 요청마다 Application을 추가 인자로 전달하지 않는다. - 기존 별도
bind/route/routes계약 대신 시작 단계에서 연결·등록한다. HTTP 라우트 없는 확장도 허용한다. add_extension_route(extension, route)는 현재 시작 중인 소유 확장에만 허용하며, 잘못된 Route·핸들러와 동일 method·URL 충돌을 거부한다.- 시작 실패 시 시작 완료 확장을 역순 정리하고 부분 라우트·동적 훅을 롤백한다. 실패한 확장 자신의 부분 자원 회수는 해당
startup()구현의 책임이다. - 재시작은 같은 등록 인스턴스를 사용하며, 이전 확장 라우트를 제거한 뒤 재등록한다.
공개 훅과 기본 확장 이전
생성자에 on_startup, on_cleanup, on_request, on_request_response, on_request_error를 추가했다. 인터페이스는 각각 ExtensionStartup, ExtensionCleanup, ExtensionRequest, ExtensionRequestResponse, ExtensionRequestError이다.
- 시작·정리 훅은 인자 없이 None을 반환한다.
- 요청 훅은 Request를 받아 Request를 반환한다. 기존 필터의 조기 응답 튜플은 사용하지 않는다.
- 응답 훅은 Request와 Optional[Response]를 받아 Optional[Response]를 반환한다. 직접 출력 완료의 None을 새 응답으로 교체할 수 없다.
- 오류 훅은 Request와 Exception을 받아 None을 반환한다.
- Ping, File, FileSystem, Status, Swagger, Specifications, Metrics와 관련 샘플을 새 계약으로 이전했다.
- Metrics는 시작 시 Application 요청 훅을 자동 연결하고 정리 시 해제한다. 요청 교체·중첩 호출의 집계를 연결하고, 후속 응답 훅 실패를 중복 집계 없이 실패로 재분류한다.
- Metrics 측정은 Application 처리 완료까지이며, 반환 이후 전송 시간·스트림 소비 오류는 포함하지 않는다.
- FileSystemRoute를 FileSystem 모듈로 이관했다. 접두 경로 매칭·디코딩 및 일반 라우트 우선·긴 접두사 우선 규칙은 유지했다.
4. RequestRunner 변경
| 클래스 선언 인자 | 공개 인터페이스 | 입력 → 반환 |
|---|---|---|
on_request |
RequestRunnerRequest |
Request → Request |
on_request_response |
RequestRunnerRequestResponse |
Request, Response → Response |
on_request_error |
RequestRunnerRequestError |
Request, Exception → None |
- 요청 훅은 CORS 원본 검사, 인증·입력 검증, 본문 처리 및 인스턴스 생성 후
run()직전에 실행한다. - Request 교체는 다음 훅·핸들러에 전달되지만 라우팅·검증·본문 처리를 다시 수행하지 않는다.
- 부모 훅을 자동 상속·병합하지 않는다. 재사용하려면 하위 클래스 선언에서 명시적으로 전달한다.
- 훅 객체는 요청마다 복제하지 않는다. 여러 요청·Application에서 공유할 수 있으므로 상태 동기화는 사용자 책임이다.
- 오류 경계는 RunRequest 진입 이후 검증·본문 처리·생성·요청 훅·run·직접 출력·종료·응답 후처리의 Exception을 포함한다.
- 오류 훅 실패 시 후속 오류 훅을 중단하고 원래 처리 오류를 예외 체인에 보존한다. 같은 오류 훅에 재귀 통지하지 않는다.
응답 후처리와 스트리밍
- 일반·iterable Response는 반환 전에 응답 훅과 CORS를 적용한다.
- stream·chunked·SSE 직접 출력은 writer의 begin에서, WebSocket은 upgrade에서 헤더 전송 전에 후처리한다.
- ResponseWriter는 RequestRunner를 직접 참조하지 않고 주입받은
on_request_response콜백을 실행한다. - 직접 출력에서도 RequestRunner 응답 훅은 None이 아닌 헤더용 Response를 받는다. 빈 bytes 본문·Content-Length 금지 및 WebSocket 101 상태 유지 제약을 검증한다.
- 응답 후처리는 반환·writer 종료·서버 전송에서 중복 호출하지 않으며, chunk·SSE 이벤트·WebSocket 프레임별 훅은 추가하지 않았다.
- 콜백은 실행 종료 시 해제해 서버가 생성한 오류 응답에 재적용하지 않는다.
- 응답 교체·body 변경 시 폐기 본문을 중복 없이 정리하고, 다른 응답에 인계한 body는 미리 닫지 않는다. 추가 정리 오류가 원래 처리 오류를 덮지 않도록 했다.
5. 계층 간 호출 및 완료 의미
| 경로 | 응답 훅 순서 |
|---|---|
| 일반 핸들러 반환 | RequestRunner → Application |
| Extension 반환 | Extension → 내부 RequestRunner → Application |
| Extension 직접 출력 | 내부 RequestRunner 전송 전 훅 → Extension 완료 훅 → Application 완료 훅 |
- RequestRunner 응답 훅은 응답 제공 시점의 후처리이며 전체 실행·전송 완료 이벤트가 아니다.
- 직접 출력은 응답 훅 뒤에도 실행·쓰기·flush·종료가 실패할 수 있다. 아직 실행 중인 경계에서 오류 훅이 이어서 호출될 수 있다.
- Extension 안의 writer 콜백 실패는 Extension → RequestRunner → Application 순서로 전파된다.
- 라우팅·Application 사전 검사 실패는 RequestRunner 훅에 전달하지 않는다.
- 반환 이후 서버 전송·스트림 소비 오류로 이미 종료한 Application·RequestRunner 훅을 다시 호출하지 않는다.
6. 호환성 변경 및 이전 안내
| 이전 계약 | 최종 계약 |
|---|---|
| RequestFilter·ResponseFilter | RequestRunnerRequest·RequestRunnerRequestResponse |
onRequest·onResponse |
on_request·on_request_response |
요청 필터의 (Request, Optional[Response]) 조기 응답 |
Request 반환만 허용 |
오류 훅 이름의 초기 제안 on_error |
on_request_error, 호환 별칭 없음 |
writer의 on_response 콜백 |
on_request_response |
| Extension 클래스 선언 훅 | 인스턴스 생성자 훅 |
Extension의 기존 bind/start/stop/begin/end 중심 연결·관찰 |
startup(application)·cleanup() 및 명시적 Application 요청 훅 등록 |
| 확장 호출에 Application 전달 | 시작 단계에서 연결하고 요청 시 extension(request) |
DefEssential.FileSystemRoute 가져오기 |
DefEssential.Extensions.FileSystem에서 가져오기 |
| 명세 생성 시 Application 전달 | Application 시작 후 spec.document() 호출 |
공개 Extension Factory는 제공하지 않는다. 내부 RunExtensionFactory는 라우트에 연결할 RequestRunner 어댑터 생성기로 유지한다.
7. 시작 출력·샘플·문서
- Python·Uvicorn의 시작 순서를 조정해 로고·구성 안내를 시작 훅 로그보다 먼저 출력한다.
- 배너는 확장을 미리 시작하거나 확장 라우트를 조회하지 않고
str(extension)과 개수를 표시한다. - Application 샘플에 다섯 훅 로그를 연결하고 stdout INFO 로깅을 구성했다.
- 일반 요청 5개와 스트리밍 6개 핸들러에 요청·응답·오류 훅 로그를 연결했다. 오류는 traceback을 포함하고 스트리밍 응답에 X-Request-ID를 추가한다.
- 명세 저장 스크립트를 Application 시작 후 생성·finally 종료 구조로 이전했다.
- 각 하위 명세와 공통 요구사항에 최종 계약 및 계층 간 직접 출력 순서를 반영했다.
8. 검증 기록과 한계
아래는 하위 이슈 구현 기록에 남아 있는 실행 결과다. 이 종합 변경 로그 작성 중 새로 실행한 테스트 결과가 아니며, 서로 다른 시점의 테스트 수를 합산하지 않는다.
| 작업·시점 | 기록된 결과 |
|---|---|
| Application 구현 전체 검증 | 153개 통과, 5개 건너뜀. py_compile·공백 검사 및 시작 안내/훅 로그 순서 확인 |
| Extension 재구현 전체 검증 | 총 198개 중 193개 통과, 5개 건너뜀 |
| Extension 후속 검증 | FileSystemRoute 이관 관련 48개 통과, 배너·HTTP 확장 관련 26개 통과 |
| 명세 저장 실행 | OpenAPI 3.1.0, 24경로 생성 확인 |
| RequestRunner 핵심 구현 전체 회귀 | 총 218개 중 213개 성공, 5개 건너뜀 |
| 최종 샘플 훅·로그 보강 후 집중 검증 | 관련 33개 성공 |
| 구현 단계 정적·형식 검사 | 하위 기록에 명시된 범위의 Pylance 진단·구문·공백 검사 통과 |
- 5개 건너뜀은 Windows의 Gunicorn/POSIX 환경 제약이며 실행 통과로 간주하지 않는다.
- RequestRunner 전체 회귀는 최종 샘플 로그 보강 이전 결과다. 이후 관련 33개 테스트는 통과했으나 최종 변경 상태의 전체 회귀를 재실행한 기록은 없다.
- Extension 배너 관련 Linux CI 실패는 로컬 재현·수정 및 관련 테스트로 확인했다. 수정 이후 Linux CI 통과 여부는 기록에서 확인되지 않는다.
- 다른 Python 버전 및 배포 산출물 빌드·설치 검증까지 완료했다고 단정하지 않는다.
상세 근거: Application 구현 기록, Extension 구현 기록, RequestRunner 구현 기록.