서버 동작 방식¶
Uvicorn은 강력한 서버 구현을 제공하기 위해 연결 및 리소스 관리에 특히 주의를 기울여 설계되었습니다. 서버 또는 클라이언트 오류가 발생해도 정상적으로 작동하고, 클라이언트 동작 불량 또는 서비스 거부 공격에 대한 복원력을 보장하는 것을 목표로 합니다.
HTTP 헤더¶
Server 및 Date 헤더가 모든 발신 요청에 추가됩니다.
만약 Connection: Close 헤더가 포함된 경우, Uvicorn은 응답 후 연결을 닫습니다. 그렇지 않으면 연결이 열려 있는 상태로 유지되며 연결 유지 시간 초과를 기다립니다.
Content-Length 헤더가 포함된 경우, Uvicorn은 응답 본문의 콘텐츠 길이가 헤더의 값과 일치하는지 확인하고 그렇지 않은 경우 오류를 발생시킵니다.
Content-Length 헤더가 포함되지 않은 경우, Uvicorn은 응답 본문에 청크 인코딩을 사용하며, 필요한 경우 Transfer-Encoding 헤더를 설정합니다.
Transfer-Encoding 헤더가 포함된 경우, Content-Length 헤더는 무시됩니다.
HTTP 헤더는 대소문자를 구분하지 않아야 합니다. Uvicorn은 항상 소문자로만 응답 헤더를 전송합니다.
흐름 제어¶
적절한 흐름 제어는 연결의 한 쪽이 상대방이 처리할 수 있는 것보다 빠르게 데이터를 전송할 때, 대량의 데이터가 전송 중에 버퍼링되지 않도록 보장합니다.
쓰기 흐름 제어¶
쓰기 버퍼가 높은 수위(high water mark)를 넘어설 경우, Uvicorn은 쓰기 버퍼가 낮은 수위(low water mark) 이하로 비워진 후에만 ASGI send 메시지가 반환되도록 합니다.
읽기 흐름 제어¶
버퍼된 요청 본문이 높은 수위(high water mark)에 도달하면, Uvicorn은 트랜스포트에서의 읽기를 일시 중지합니다. 그리고 receive가 호출되었거나 응답이 전송되면 다시 읽기를 재개합니다.
요청 및 응답 본문¶
응답 완료¶
응답이 전송되면, Uvicorn은 더 이상 남아 있는 요청 본문을 버퍼링하지 않습니다. 나중에 receive를 호출하면 http.disconnect 메시지가 반환됩니다.
읽기 흐름 제어와 함께 이 동작은 요청 본문을 읽지 않고 반환하는 응답이 상당한 양의 데이터를 메모리로 스트리밍하지 않도록 보장합니다.
Expect: 100-Continue¶
클라이언트는 Expect: 100-Continue 헤더를 보내 요청 본문을 업로드하기 전에 서버의 확인을 요구할 수 있습니다. 이는 클라이언트가 서버가 요청을 받아들일 준비가 되었다는 확인을 받은 후에만 대용량 요청 본문이 전송되도록 하는 데 사용할 수 있습니다.
Uvicorn은 ASGI 애플리케이션이 요청 본문을 읽기 위해 receive를 호출하는 경우에만 필요한 100 Continue 확인을 보내도록 보장합니다.
프록시 구성은 Expect: 100-Continue 헤더를 전달하지 않을 수도 있습니다. 특히, Nginx는 기본적으로 요청 본문을 버퍼링하고, 헤더를 상위 서버로 전달하는 대신 자동으로 100 Continue를 보냅니다.
HEAD 요청¶
Uvicorn은 HEAD 메소드를 가진 HTTP 요청의 모든 응답 본문을 제거합니다.
애플리케이션은 일반적으로 두 경우 모두 동일한 헤더가 전송되고, 헤더를 수정하는 모든 ASGI 미들웨어가 두 경우 모두 동일하게 작동하도록 하기 위해 HEAD 요청을 GET 요청과 동일한 방식으로 처리해야 합니다.
예외적으로 애플리케이션이 대용량 파일 다운로드를 제공하는 경우 응답 헤더만 생성할 수 있습니다.
타임아웃¶
Uvicorn은 다음과 같은 타임아웃을 제공합니다:
- Keep-Alive. 기본값은 5초입니다. 요청 사이에 연결은 이 기간 내에 새 데이터를 받아야 하며, 그렇지 않으면 연결이 끊어집니다.
리소스 제한¶
Uvicorn은 다음과 같은 리소스 제한을 제공합니다:
- Concurrency (동시성). 기본값은
None입니다. 이 값을 설정하면 허용해야 하는 최대 동시 작업 수 또는 열린 연결 수를 제공합니다. 이 한계에 도달한 후 발생하는 새로운 요청이나 연결은 "503 서비스 이용 불가" 응답을 초래할 것입니다. 서버가 지원할 수 있는 한계치로 이 값을 설정하면 상당히 과부하된 서버에 대해서도 신뢰할 수 있는 자원 사용을 보장하는 데 도움이 됩니다. - Max requests (최대 요청 수). 기본값은
None입니다. 이 값을 설정하면 프로세스를 종료하기 전에 처리할 최대 HTTP 요청 수를 제공합니다. 프로세스 관리자와 함께 사용하면 장기 실행 프로세스에 영향을 미치는 메모리 누수를 방지하는 데 사용할 수 있습니다.
서버 오류¶
서버 오류는 'error' 로그 레벨에서 기록됩니다. 모든 로깅은 기본적으로 'stdout'에 기록됩니다.
예외¶
ASGI 애플리케이션에서 예외가 발생하고 연결에 대한 응답이 아직 전송되지 않은 경우, 500 서버 오류 HTTP 응답이 전송됩니다.
잘못된 응답¶
Uvicorn은 ASGI 애플리케이션이 올바른 메시지 시퀀스를 전송하는지 확인하고, 그렇지 않을 경우 오류를 발생시킵니다. 여기에는 응답이 전송되지 않았거나, 부분적인 응답이 전송되었거나, 잘못된 메시지 순서가 전송된 경우를 포함됩니다.
우아한 프로세스 종료¶
재시작 기간 동안 우아한 프로세스 종료는 특히 중요합니다. 이 기간 동안에는:
- 기존 소켓에서 들어오는 요청을 처리하기 위해 새로운 서버 프로세스를 시작합니다.
- 기존 소켓에서 이전 서버 프로세스의 수신을 중지합니다.
- 현재 HTTP 응답을 기다리고 있지 않은 모든 연결을 닫고, 다른 연결이 HTTP 응답을 완료할 때까지 기다립니다.
- 백그라운드 작업이 완료될 때까지 기다립니다(예: ASGI 애플리케이션이 HTTP 응답을 보냈지만 asyncio 작업이 아직 완료되지 않은 경우).
Uvicorn은 프로세스 종료를 우아하게 처리하여, 연결이 적절히 완료되고 모든 작업이 완료될 수 있도록 보장합니다. 종료 기간 동안 Uvicorn은 응답과 작업이 설정된 타임아웃 기간 내에 완료되도록 보장합니다.
HTTP 파이프라이닝¶
HTTP/1.1은 각 해당 응답을 받기 전에 단일 연결에서 여러 요청을 보낼 수 있는 기능을 지원합니다. 서버는 HTTP 파이프라이닝을 지원해야 하지만, 이는 이제 일반적으로 구현 문제로 인식되고 있습니다. 브라우저에서는 활성화되어 있지 않으며, HTTP 요청이 통과하는 프록시에서 반드시 활성화되어 있지 않을 수 있습니다.
Uvicorn은 파이프라이닝을 실용적으로 지원합니다. 파이프라인된 HTTP 요청을 큐에 넣고 기본 전송에서 읽기를 일시 중지합니다. 각 응답이 차례로 처리될 때까지 파이프라인된 요청의 처리를 시작하지 않습니다.