```
## 진행률 추적
### UploadEntry 속성
| 속성 | 타입 | 설명 |
|------|------|------|
| `ref` | str | 고유 참조 ID |
| `client_name` | str | 원본 파일명 |
| `client_size` | int | 파일 크기 (bytes) |
| `client_type` | str | MIME 타입 |
| `status` | `UploadStatus` | pending/uploading/completed/error/cancelled/consumed. 문자열 열거형(`StrEnum`)이라 `"uploading"`과 같고, `{{ entry.status }}`는 `uploading`을 찍는다 |
| `progress` | int | 0-100 |
| `errors` | list | 에러 메시지 목록 |
### 상태별 처리
```html
{% if entry.status == 'pending' %}
Waiting...
{% elif entry.status == 'uploading' %}
{{ entry.progress }}%
{% elif entry.status == 'completed' %}
Upload complete
{% elif entry.status == 'error' %}
{% for error in entry.errors %}
{{ error }}
{% endfor %}
{% elif entry.status == 'cancelled' %}
Cancelled
{% endif %}
```
## 파일 처리
### ConsumedUpload API
```python
async def process_upload(self):
async for upload in self.consume_uploads("files"):
# 파일 정보
print(upload.name) # 원본 파일명
print(upload.size) # 크기 (bytes)
print(upload.content_type) # MIME 타입
print(upload.ref) # 참조 ID
# 내용 읽기. 임시 파일을 읽을 뿐이라 몇 번이든 된다
content = upload.read() # bytes로 읽기
with upload.open("rb") as f:
header = f.read(16)
# 저장. 한 업로드에 한 번만 — save_to가 임시 파일을 지우고 업로드를 소비한다
path = await upload.save_to("uploads/")
```
원래 이름 대신 다른 이름으로 저장하려면 `filename=`을 넘긴다. 같은 업로드를 두 번 `save_to()`하면
두 번째는 `RuntimeError("Upload already consumed")`다 — 두 곳에 저장하려면 `read()`한 바이트를 직접 쓴다.
```python
path = await upload.save_to("avatars/", filename=f"user_{self.user.pk}.jpg")
```
`save_to()`를 부르지 않아도 루프가 다음 업로드로 넘어가면 그 업로드는 소비되고 임시 파일은 지워진다.
### Django Storage 통합
`save_to()`는 Django의 default storage를 사용합니다:
```python
# settings.py
STORAGES = {
"default": {"BACKEND": "storages.backends.s3boto3.S3Boto3Storage"},
"staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
}
# 컴포넌트
async def save_to_s3(self):
async for upload in self.consume_uploads("files"):
# S3에 저장됨
path = await upload.save_to("media/uploads/")
```
### 직접 처리
```python
from PIL import Image
async def process_image(self):
async for upload in self.consume_uploads("avatar"):
# Pillow로 이미지 처리
with upload.open("rb") as f:
img = Image.open(f)
img = img.resize((200, 200))
# 처리된 이미지 저장
from io import BytesIO
buffer = BytesIO()
img.save(buffer, format='JPEG')
# ...
```
## 보안
### 확장자 검증
```python
self.allow_upload("images", accept=[".jpg", ".png"]) # 허용된 확장자만
```
### Magic Bytes 검증
Wireview는 파일 시그니처를 자동 검증합니다:
```python
# wireview/features/uploads.py
MAGIC_BYTES = {
".jpg": [b"\xff\xd8\xff"],
".png": [b"\x89PNG\r\n\x1a\n"],
".pdf": [b"%PDF"],
# ...
}
```
`.jpg` 확장자지만 실제로 PNG인 경우 → 에러
### 크기 제한
```python
self.allow_upload("images", max_file_size=5 * 1024 * 1024) # 5MB
```
### 수동 검증
```python
errors: list[str] = []
async def save_files(self):
async for upload in self.consume_uploads("files"):
# 추가 검증. 건너뛴 업로드도 소비된 것이라 임시 파일은 지워진다
if upload.size > 1024 * 1024:
self.errors = [*self.errors, f"{upload.name}: too large"]
continue
if not self._is_safe_filename(upload.name):
self.errors = [*self.errors, f"{upload.name}: invalid filename"]
continue
await upload.save_to("uploads/")
def _is_safe_filename(self, name: str) -> bool:
import re
# 안전한 문자만 허용
return bool(re.match(r'^[\w\-. ]+$', name))
```
## 소유권과 수명
업로드는 **연결(connection)의 것**이지 컴포넌트 id의 것이 아니다. 컴포넌트 id는 페이지 안에서만
고유하고, 템플릿이 `{% component 'X' id="bookmarks" %}`처럼 id를 고정하면 같은 페이지를 연 두
연결이 같은 id를 쓴다. 그래서 서버가 업로드에 쓰는 모든 것에 연결 id가 붙는다
([#77](https://github.com/itda-work/django-wireview/issues/77)).
연결 id는 WebSocket 연결이 열려 세션이 시작될 때 `secrets.token_urlsafe(16)`으로 발급된다. 채널 레이어
주소인 `channel_name`과 달리 URL에 넣어도 되는 값이다.
| 무엇 | 모양 |
|------|------|
| HTTP 엔드포인트 | `/__wireview_upload__////` |
| 업로드 토큰 | `connection_id`·`component_id`·`upload_name`·`ref`에 더해 허용 크기와 확장자를 서명한 객체 (salt `wireview.upload`, 유효기간 `UPLOAD_TOKEN_MAX_AGE`) |
| 진행률 통지 그룹 | `wireview_upload_` — 연결마다 하나, 업로드가 있는 첫 컴포넌트가 join할 때 가입 |
| 청크 파일 | `/wireview-uploads//.part` |
엔드포인트는 서버가 `config` 업로드 op으로 클라이언트에 보내 준다. **경로를 직접 적어 두지
않았다면 앱에서 고칠 것은 없다.**
### 정리 시점
| 시점 | 일어나는 일 |
|------|-------------|
| join | 컴포넌트에 업로드가 있으면 이 연결이 진행 통지 그룹에 가입한다(연결당 한 번) |
| LiveComponent 자식의 joined | 부모 렌더 중에 자식의 업로드도 같은 방식으로 준비된다 |
| leave / 재join으로 교체 | 그 컴포넌트의 엔트리마다 취소 마커(`.cancelled`)를 남기고 청크 파일을 지운다 |
| disconnect | 연결 디렉터리에 `.gone`을 남기고 그 안의 청크 파일을 전부 지운 뒤, 가입했다면 통지 그룹에서 탈퇴한다 |
| 취소 뒤 도착한 청크 | 410. 청크를 쓰는 도중에 취소가 나도 파일을 남기지 않는다 |
| leave·disconnect 뒤 도착한 청크 | 410. 마커는 그 청크를 쓰는 워커가 다른 프로세스여도 보인다 |
브라우저도 같은 때 그 컴포넌트의 업로드 상태(기다리는 파일, 진행 중인 요청, 미리보기)를 버린다.
상세는 [chunked-uploads.md의 「브라우저 쪽 수명」](/wireview/reference/chunked-uploads/#브라우저-쪽-수명).
경로와 토큰 양쪽에 소유자가 들어가므로 **한 연결의 leave가 다른 연결의 파일을 건드릴 수 없다.**
A에서 받은 토큰을 B의 URL로 보내면 서명은 검증되지만 소유자가 URL과 달라 403이다.
### 워커가 여럿일 때
청크 HTTP 요청은 아무 워커에나 닿아도 된다([#83](https://github.com/itda-work/django-wireview/issues/83)).
엔드포인트는 업로드 상태를 하나도 들고 있지 않고, 서명된 토큰만으로 판단해 토큰에서 계산한 경로에
쓴다. 대신 워커들이 **청크 저장소**(`WIREVIEW["UPLOAD_TEMP_DIR"]`, `None`이면 시스템 임시
디렉터리 — 한 호스트라면 이미 공유다)와 **서명 키**를 공유해야 한다.
- 설정된 경로는 없으면 만들어지고, 쓸 수 없으면 `ImproperlyConfigured`로 실패한다 — 공유 볼륨을
지정했는데 말없이 로컬 디스크를 쓰는 일은 없다. `manage.py check`의 `wireview.W008`이 미리 잡는다.
- **정상 disconnect 없이 프로세스가 죽으면** 청크 파일이 남는다. 남는 양은 `UPLOAD_TOKEN_MAX_AGE`로
묶이고, 쓰기 경로가 프로세스당 10분에 한 번 청소한다. cron으로 돌리려면
`manage.py wireview_upload_gc`.
- 서버 쪽 동작 전체는 [docs/features/chunked-uploads.md](/wireview/reference/chunked-uploads/), 배포
조건은 `docs/DEPLOYMENT.md`.
## 다중 업로드 필드
### 여러 업로드 설정
```python
async def joined(self):
self.allow_upload("avatar", max_entries=1)
self.allow_upload("documents", max_entries=10)
self.allow_upload("gallery", max_entries=20)
```
### 필드별 처리
```python
async def save_all(self):
# 아바타
async for upload in self.consume_uploads("avatar"):
await upload.save_to("avatars/")
# 문서
async for upload in self.consume_uploads("documents"):
await upload.save_to("documents/")
# 갤러리
async for upload in self.consume_uploads("gallery"):
await upload.save_to("gallery/")
```
## 업로드 취소
### 사용자 취소
```python
async def cancel_file(self, ref: str):
"""특정 파일 업로드 취소"""
await self.cancel_upload("files", ref)
```
### 템플릿
```html
```
## 드래그 앤 드롭
업로드 태그는 넷이다. `upload_input`과 `upload_preview`는 요소를 그리고, `upload_drop_zone`과
`upload_button`은 사용자가 쓴 요소에 붙일 속성을 낸다.
| 태그 | 내는 것 |
|------|---------|
| `{% upload_input "필드" class="…" %}` | ``. `accept`와 `multiple`은 `allow_upload()` 설정에서 온다 |
| `