DongHyeonka
7bcb54c464
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 추가.
105 lines
8.7 KiB
Markdown
105 lines
8.7 KiB
Markdown
---
|
|
title: MDN — File System API (showOpenFilePicker / showSaveFilePicker / Origin Private File System)
|
|
source_type: official-doc
|
|
url: https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system
|
|
archive_url:
|
|
related_branches: [feature-frontend-binary-file-io-store-contract, feature-frontend-large-object-transfer-contract]
|
|
related_projects: [ca-skeleton-frontend]
|
|
tags: [frontend, file-io, opfs, file-system-access, browser]
|
|
created: 2026-07-28
|
|
---
|
|
|
|
# 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`
|
|
|
|
## 관련
|
|
|
|
- 같은 주제 다른 official-doc: `[[raw/official-docs/mdn-storage-quotas-eviction-persistence]]`, `[[raw/official-docs/mdn-object-url-cache-storage]]`
|
|
- 이 자료를 인용한 wiki 요약: 생성 전
|