Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

8.3 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

tus.io — Open protocol for resumable file uploads

Layer: raw/official-docs/ — tus.io 공식 protocol v1.0.0 발췌. 대용량/이어올리기 시나리오에서 ca-tmpl Spring 10MB multipart enforcement 의 한계 비교 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-file-resource-handling-contract	tus 가 resumable 표준이라는 사실 → ca-tmpl 의 Spring multipart 단일 stream 가정과 충돌하는 영역 식별 (Tus-Max-Size 헤더 enforcement, session vs orphan threshold 분리 필요성)

컨텍스트

ca-tmpl의 multipart 10MB limit은 short file 기준. 대용량(영상, 백업) upload는 connection drop → 처음부터 재시도라는 운영 문제 발생. tus는 byte offset 기반 resume 표준. ca-tmpl이 현재 채택하지 않은 이유와 채택 시 size limit 결정에 어떤 영향이 있는지 비교용.

출처 / Source

원본 URL: https://tus.io/protocols/resumable-upload
보조 1: tus-java-server (reference Java implementation) — https://github.com/tomdesair/tus-java-server
보조 2: Vimeo "How we built a resumable upload service" — https://medium.com/vimeo-engineering-blog/from-zero-to-100mbs-how-we-massively-improved-vimeos-upload-speed-71f72ca1ca5e
아카이브 URL: (미수집)
저자/조직: transloadit / tus.io community (Marius Kleidl 외)
발행일: v1.0.0 — 2018-02 (지속 업데이트)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Abstract] "The protocol provides a mechanism for resumable file uploads via HTTP (RFC 9110)."

[§HEAD] "The Server MUST always include the Upload-Offset header in the response for a HEAD request, even if the offset is 0."

[§PATCH] "All PATCH requests MUST use Content-Type: application/offset+octet-stream, otherwise the server SHOULD return a 415 Unsupported Media Type status."

[§PATCH] "If the offsets do not match, the Server MUST respond with the 409 Conflict status without modifying the upload resource."

[§Tus-Max-Size] "The Tus-Max-Size response header MUST be a non-negative integer indicating the maximum allowed size of an entire upload in bytes."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TUS-RUP-C1	tus 는 HTTP (RFC 9110) 위에서 동작하는 resumable file upload 프로토콜이다	[§Abstract] "The protocol provides a mechanism for resumable file uploads via HTTP (RFC 9110)."	`official-standard`	resumable upload 표준 채택 평가	RFC 9110 자체가 tus 를 정의/승인한다는 뜻은 아님 — tus 는 HTTP 위에 정의된 프로토콜
TUS-RUP-C2	Server 는 HEAD 응답에 `Upload-Offset` 헤더를 항상 포함해야 한다 (offset 이 0 이어도 포함 — MUST)	[§HEAD] "The Server MUST always include the `Upload-Offset` header in the response for a `HEAD` request, even if the offset is `0`."	`official-standard`	tus core protocol 구현 시 HEAD 핸들러	client 측 retry 로직의 정확한 형태나 idempotency 보장은 본 조항 범위 밖
TUS-RUP-C3	PATCH 요청은 `Content-Type: application/offset+octet-stream` 을 반드시 사용해야 하며 (MUST), 그렇지 않으면 server 는 `415 Unsupported Media Type` 응답을 권장 (SHOULD)	[§PATCH] "All `PATCH` requests MUST use `Content-Type: application/offset+octet-stream`, otherwise the server SHOULD return a `415 Unsupported Media Type` status."	`official-standard`	tus PATCH 요청/응답 처리	Spring 의 default multipart parser 가 이 content-type 을 처리한다는 뜻이 아님 — 별도 controller 필요
TUS-RUP-C4	클라이언트 offset 과 서버 offset 이 일치하지 않으면 server 는 `409 Conflict` 로 응답하고 upload 리소스를 수정하지 않아야 한다 (MUST)	[§PATCH] "If the offsets do not match, the Server MUST respond with the `409 Conflict` status without modifying the upload resource."	`official-standard`	concurrent / out-of-order PATCH 처리	conflict 후 클라이언트의 정확한 복구 절차 (재 HEAD 후 재 PATCH) 형태는 본 인용에 명시 없음
TUS-RUP-C5	`Tus-Max-Size` 응답 헤더는 전체 upload 의 허용 최대 byte 수를 나타내는 non-negative integer 여야 한다 (MUST)	[§Tus-Max-Size] "The `Tus-Max-Size` response header MUST be a non-negative integer indicating the maximum allowed size of an entire upload in bytes."	`official-standard`	tus server 의 size limit 알림	per-PATCH chunk size limit 이 동일 메커니즘으로 표현된다는 뜻은 아님 — chunk-level limit 은 별도 확장

Strength 허용값 사용

official-standard — tus.io v1.0.0 protocol specification (open standard)

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- TUS-RUP-C1: tus 의 HTTP 기반 정의
- TUS-RUP-C2, TUS-RUP-C3, TUS-RUP-C4: HEAD/PATCH 의 핵심 의무사항 (Upload-Offset / Content-Type / 409 Conflict)
- TUS-RUP-C5: Tus-Max-Size 헤더의 단위와 의미
이 자료가 증명하지 않는 것:
- tus 가 모든 production 환경에서 multipart 대비 더 안정적이라는 일반화 (Vimeo case study 는 별도 company-tech-blog 영역)
- tus-java-server reference impl 의 Spring Boot 통합 정확한 절차
- tus session 의 server-side storage backend 선택 (memory / disk / object store) 의 trade-off
- chunk-level retry 와 session-level resume 의 정확한 경계 (Tus-Max-Size 외 chunk extension)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 "1h orphan cleanup" 정책과 tus unfinished upload session 의 충돌 가능성
- Spring 환경에서 PATCH + application/offset+octet-stream 처리 controller 의 직접 구현 패턴
- Tus-Max-Size 와 nginx/gateway level body size limit 의 상호작용

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

ca-tmpl과의 trade-off:
- tus 채택 시 장점: 100MB 영상 업로드도 disconnect 무관, mobile 사용자 friendly, 서버 메모리 부담 분산 (chunk 단위).
- tus 채택 시 비용: PATCH 기반 protocol → Spring multipart는 동작 안 함, 별도 controller + storage layer 필요. ca-tmpl의 Spring 10MB enforcement가 직접 적용 안 됨 (Tus-Max-Size 헤더로 대체).
- temp file cleanup 정책 변경 필요: tus는 unfinished upload가 hours 동안 잔존 가능 → ca-tmpl의 "1h orphan cleanup"이 tus upload session을 잘못 삭제할 수 있음. session timeout과 orphan threshold 분리 필요.
대안 비교:
- multipart only (ca-tmpl 현재): 단순, 작은 파일에 최적, resume 불가.
- tus: resumable, 큰 파일 적합, 서버 stateful (session storage 필요).
- direct S3 multipart upload (S3 SDK): S3 자체의 multipart API. 5MB 미만 last part 외엔 chunk 단위 retry 가능. tus와 유사한 효과지만 vendor-specific.
ca-tmpl 결정 영향: 현재 "streaming 100MB max + 60s timeout"이 단일 stream 가정. tus 채택 시 session-level limit과 chunk-level limit 분리 필요.

8.3 KiB Raw Blame History