Files

T

DongHyeonka 7bcb54c464 docs(branch-spec): feature-frontend-binary-file-io-store-contract 채움

MDN 근거 3건 수집 후 결정 7개를 근거 기반으로 확정하고 §구현 가이드
4개 sub-section 을 채웠다. 조사에서 기존 계약 2건의 사실 오류가 나왔다.

- EVICTION_SCOPE_DRIFT: 브라우저 eviction 은 origin 전량 삭제이므로
  FE-REG-STORAGE.evictionOrder 는 애플리케이션 주도 정리에만 유효
- CACHE_STORAGE_CONSTRAINT_DRIFT: Cache Storage 는 SW 전용이 아니다
  (Window.caches 접근 가능). FE-D027 의 제한은 정책이지 플랫폼 제약이 아님
- NO_GROUND_TRUTH: ca-tmpl 은 backend 전용이라 이 branch 에 미적용
- CAPABILITY_NAME_COLLISION: ca-tmpl capabilities.yaml 과 다른 개념

신규 raw: mdn-storage-quotas-eviction-persistence,
mdn-file-system-access-opfs, mdn-object-url-cache-storage
6개 신규 branch-note 전부에 governing_docs 추가.

2026-07-28 15:24:19 +09:00

8.7 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

MDN — File System API (showOpenFilePicker / showSaveFilePicker / Origin Private File System)

Layer: raw/ — 외부 자료의 원문 발췌·출처 기록.

활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
`[[raw/branch-notes/feature-frontend-binary-file-io-store-contract]]`	`FileDialogPort` 의 메커니즘 선택·fallback 조건, OPFS backend 를 opt-in 으로 두는 근거, picker 취소의 실패 매핑
`[[raw/branch-notes/feature-frontend-large-object-transfer-contract]]`	대용량 순차 write 를 OPFS 로 처리할 때의 worker 제약

출처

원본 URL: https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system
보조 URL: https://developer.mozilla.org/en-US/docs/Web/API/Window/showOpenFilePicker , https://developer.mozilla.org/en-US/docs/Web/API/Window/showSaveFilePicker
아카이브 URL:
저자 / 조직: MDN Web Docs (Mozilla)
발행일: (문서 지속 갱신)
마지막 확인일: 2026-07-28

왜 저장했는지

FileDialogPort 와 BlobStorePort 의 메커니즘을 추측으로 정하지 않기 위해. 특히 (a) File System Access API 를 default 로 삼아도 되는지, (b) OPFS 의 동기 API 가 어느 실행 컨텍스트에서만 가능한지, (c) picker 취소가 어떤 예외로 오는지를 확인했다.

핵심 인용

[§showOpenFilePicker — Baseline] "Limited availability — This feature is not Baseline because it does not work in some of the most widely-used browsers."

[§showOpenFilePicker] "The showOpenFilePicker() method of the Window interface shows a file picker that allows a user to select a file or multiple files and returns a handle for the file(s)."

[§showOpenFilePicker — Security] "Transient user activation is required. The user has to interact with the page or a UI element in order for this feature to work."

[§showOpenFilePicker — Exceptions] "AbortError DOMException — Thrown if the user dismisses the prompt without making a selection, or if the user agent deems any selected files too sensitive or dangerous."

[§showSaveFilePicker] "The showSaveFilePicker() method of the Window interface shows a file picker that allows a user to save a file. Either by selecting an existing file, or entering a name for a new file."

[§showSaveFilePicker — Return value] "A Promise whose fulfillment handler receives a FileSystemFileHandle object."

[§showSaveFilePicker — Exceptions] "AbortError DOMException — Thrown if the user dismisses the file picker without selecting or inputting a file, or if the user agent deems any selected files too sensitive or dangerous."

[§showSaveFilePicker — Secure context] "Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers."

[§OPFS] "The origin private file system (OPFS) is a storage endpoint provided as part of the File System API, which is private to the origin of the page and not visible to the user like the regular file system."

[§OPFS] "The OPFS is subject to browser storage quota restrictions, just like any other origin-partitioned storage mechanism (for example IndexedDB API)."

[§OPFS] "Permission prompts and security checks are not required to access files in the OPFS."

[§OPFS] "It also has a set of synchronous calls available (other File System API calls are asynchronous) that can be run inside web workers only so as not to block the main thread."

[§OPFS] "The OPFS offers low-level, byte-by-byte file access, which is private to the origin of the page and not visible to the user. As a result, it doesn't require the same series of security checks and permission grants and is therefore faster than File System Access API calls."

[§OPFS] "Web Workers don't block the main thread, which means you can use the synchronous file access APIs in this context."

[§OPFS] "Browsers persist the contents of the OPFS to disk somewhere, but you cannot expect to find the created files matched one-to-one. The OPFS is not intended to be visible to the user."

[§OPFS] "Clearing storage data for the site deletes the OPFS."

추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
C1	`showOpenFilePicker()` 는 Baseline 이 아니며 널리 쓰이는 일부 브라우저에서 동작하지 않는다	[§Baseline] "not Baseline because it does not work in some of the most widely-used browsers"	`official-reference`	File System Access picker 계열	어떤 브라우저가 미지원인지 구체 목록
C2	picker 계열은 transient user activation 을 요구한다 — 사용자 제스처 없이 호출할 수 없다	[§Security] "Transient user activation is required."	`official-reference`	`showOpenFilePicker`·`showSaveFilePicker`	`<input type=file>` 도 같은 제약을 갖는다는 뜻은 아님
C3	사용자가 picker 를 닫으면 `AbortError` DOMException 이 던져진다	[§Exceptions] "Thrown if the user dismisses the prompt without making a selection"	`official-reference`	picker 계열	취소와 "위험한 파일 거부"가 구분되어 온다는 뜻은 아님 — 같은 예외다
C4	picker 계열은 secure context(HTTPS)에서만 사용 가능하다	[§Secure context] "available only in secure contexts (HTTPS)"	`official-reference`	picker 계열	localhost 예외 여부
C5	OPFS 의 동기 접근 API 는 web worker 안에서만 실행할 수 있다	[§OPFS] "can be run inside web workers only so as not to block the main thread"	`official-reference`	`createSyncAccessHandle()`	비동기 OPFS API 도 worker 전용이라는 뜻은 아님
C6	OPFS 는 권한 프롬프트·보안 검사를 요구하지 않아 File System Access API 호출보다 빠르다	[§OPFS] "it doesn't require the same series of security checks and permission grants and is therefore faster than File System Access API calls"	`official-reference`	OPFS byte 접근	IndexedDB 보다 빠르다는 뜻은 아님 — 비교 대상은 File System Access API 다
C7	OPFS 는 다른 origin-partitioned storage 와 동일한 quota 제약을 받는다	[§OPFS] "subject to browser storage quota restrictions, just like any other origin-partitioned storage mechanism"	`official-reference`	OPFS	OPFS 가 별도 quota 를 갖는다는 뜻은 아님
C8	OPFS 는 사용자에게 보이지 않으며 사이트 저장소를 지우면 함께 삭제된다	[§OPFS] "Clearing storage data for the site deletes the OPFS."	`official-reference`	OPFS	사용자가 개별 파일만 지울 수 있다는 뜻은 아님

적용 경계

이 자료가 직접 증명하는 것:
- C1~C4: picker 계열의 가용성·활성화 요구·예외·보안 컨텍스트
- C5~C8: OPFS 의 실행 컨텍스트 제약, 성능 비교 대상, quota 귀속, 삭제 조건
이 자료가 증명하지 않는 것:
- <a download> + Blob URL fallback 이 picker 와 동등하다는 것 — MDN 은 fallback 이 덮어쓰기를 지원하지 않는다고만 언급한다
- OPFS 가 IndexedDB 보다 빠르다는 것 (C6 의 비교 대상은 File System Access API 다)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 대상 브라우저 매트릭스 확정 후 picker 지원 여부 실측 (FE-Q-007 브라우저 지원 매트릭스)
- OPFS 순차 write 가 IndexedDB 대비 유리한지의 자체 벤치마크

메모

인용 1 해석 후보 (미검증): C1 때문에 FileDialogPort 는 File System Access 를 default 로 가정할 수 없고, <input type=file> 을 기준선으로 두고 picker 를 progressive enhancement 로 얹는 구조가 안전하다.
인용 2 해석 후보 (미검증): C5 는 OPFS 를 쓰려면 WorkerTaskPort(FE-OC-032)와의 결합이 필요하다는 뜻이 될 수 있다 — 동기 API 를 쓸 경우에 한정.
추가로 봐야 할 동일 출처 페이지: FileSystemFileHandle.createWritable(), FileSystemSyncAccessHandle

8.7 KiB Raw Permalink Blame History