Storage Browser for S3와 CloudFront 정액제로 수백 GB 유전체 데이터 배포 포털 만들기
유전체 분석 서비스는 분석이 끝나면끝난 결과 파일을 고객에게 넘겨야전달해야 합니다. 문제는이 크기입니다.파일은 BAM크고, 반복해서 내려받히고, 멀리서 받습니다. BAM(참조 서열에 정렬된 서열 데이터) 하나가 100~150 GB, FASTQFASTQ(원시 서열 데이터) 묶음이 100 GB를 넘고,넘으며, 같은 파일을 해외 연구그룹과 내부국내 인력이 여러서로 다른 장소에서 반복해서여러 번 내려받습니다. 지금까지는월 S3 presigned URL을 메일로 보내는 방식이었는데, 월전송량이 100 TB 규모에서규모가 S3되면 인터넷Amazon S3에서 인터넷으로 나가는 전송 요금이 그대로 비용이운영비가 되고, 브라우저의해외 기본사용자에게는 다운로드는몇 1시간짜리시간짜리 URL이다운로드가 만료되면중간에 이어받기가끊겼을 되지때 않아처음부터 해외에서는다시 실패가받아야 잦았습니다.하는 문제가 비용보다 먼저 체감됩니다.
이 글은 그 문제를요구를 Storage Browser for Amazon S3 + Amazon Cognito + S3 Access Grants + Amazon CloudFront 정액제 플랜으로 풀어낸구성한 참조 구현을 설명합니다. 스펙 작성부터 dev 계정 배포, 통합·e2e 테스트, 53 GiB 파일의 CloudFront 캐시 실측까지 한 번에 끝낸 과정에서 확인한 사실과 함정을 그대로 적었습니다. 코드는 GitHub hmkim/omics-data-delivery-portal에 MIT-0 라이선스로 공개했습니다.공개되어 있고, 글에 나오는 측정값은 개발 계정(서울 리전)에 실제로 배포해 측정한 값입니다. 다루는 내용은 크게 다섯 가지입니다.
로그인·로그인과 폴더 탐색은 StorageBrowser에Browser 컴포넌트에 맡기고,권한은권한 계산은 S3 AccessGrants로Grants에위임한다.위임합니다.- "같은 파일의 두 번째 다운로드부터 CloudFront"라는 경로 규칙을 DynamoDB 원자 카운터 하나로
구현한다.구현합니다. - CloudFront의 단일 객체 한도(50
GB를GB)를 넘는 파일은 브라우저가 8 GiBRange 파트로조각으로 나눠CloudFront를 통과시키고,받고, 브라우저 안에서 이어받기·병합·CRC32검증·저장까지검증까지처리합니다.한다.Chrome/Edge뿐 아니라 Firefox처럼 저장 위치 선택 API가 없는 브라우저도 같은 엔진을 사용합니다. - CloudFront 정액제 플랜(Pro)을 CloudFormation으로 연결하되, 플랜이 허용하는 기능
안에서만안에서설계한다.설계합니다. - 표준
로그 v2 →로그를 Athena로 집계해 캐시 히트율과허용량을허용량 사용률을 매일계산하고, 임계값에계산하고 알람을건다.겁니다.
대상 독자는 AWS 서비스 이름은 알지만 브라우저의 파일 저장 API나 CloudFront 정액제 플랜은 처음 접하는 엔지니어와 기획자입니다. 기술 용어는 처음 나올 때 괄호로 짧게 풀고, 글 끝에 용어 설명을 모아 두었습니다.
1. 요구사항을과제: 어떻게presigned 정리했나URL을 메일로 보내는 방식의 한계
시작점은가장 두단순한 개의배포 공식 문서였습니다. Storage Browser for S3 컴포넌트와 AWS Transfer Family 웹 앱입니다. Transfer Family 웹 앱은 코드 없이 같은 UX를 주지만 IAM Identity Center 전용이라 외부 고객 계정을 Cognito로 발급하는 요구와 맞지 않았습니다. 그래서 그 웹 앱의 기반 컴포넌트인 Storage Browser를 직접 호스팅하고, 로그인·브랜딩·폴더 탐색 UX를 동등하게 재현하는 쪽으로 정했습니다.
요구사항은 다음과 같이 확정됐습니다(스펙의 R1R7, 결정 D1D7).
aria2ccurl한 가지 설계 논쟁이 있었습니다. presigned URL 1시간이 대용량 다운로드에 제약인가?않습니다. 답은URL의 "요청만료 시점에만시각은 만료를요청이 검사하므로S3에 도착하는 순간에만 검사됩니다. 그래서 이미 시작된 전송에는전송은 영향이만료 없다"입니다.뒤에도 문제는끝까지 이어지지만, 만료 뒤에 생기는 새 요청이은 생기는403으로 경우,거절됩니다. 즉브라우저의 기본 다운로드는 연결이 끊긴끊기면 뒤의같은 이어받기와URL로 새 요청을 보내 이어받으려 하므로, 1시간짜리 URL로 몇 시간짜리 파일을 받는 해외 사용자는 끊김 한 번에 다운로드 전체를 잃습니다.
참조 구현은 이 세 가지를 서로 다른 층에서 해결합니다. 이어받기는 브라우저 안의 분할 다운로드의다운로드 다음엔진이(§6), 파트비용은 요청입니다.CloudFront 그래서정액제 (1)플랜과 분할경로 엔진이규칙이(§5, 만료§13), 5분가시성은 전에조직 URL을단위 갱신하고,권한 (2)모델과 1다운로드 GiB만원장이(§4, 넘으면§10) 분할 엔진을 쓰도록 임계값을 낮춰 "브라우저 기본 다운로드가 만료 후 이어받기를 못 하는" 구간을 없앴습니다.담당합니다.
2. 아키텍처솔루션 개요
브라우저(React SPA, Storage Browser)
│ 로그인(Cognito Hosted 없이 Authenticator) · /api/* 는 같은 CloudFront 뒤
▼
CloudFront (웹)웹, 종량제) ──/api/*──▶ API Gateway HTTP API (JWT authorizer) ──▶ Lambda
│ │ ├ listLocations / getLocationCredentials
│ 정적 SPA │ ├ POST /downloads · renew · status
▼ │ └ admin: org · user · location(=grant)
S3 (web) ▼
S3 Access Grants ◀── GetDataAccess(READ, Minimal, 1~12 h)
│
CloudFront (데이터, Pro 정액제, OAC + Key Group 서명 URL) ──────▶ S3 (data, KMS)
│ 표준 로그 v2 (parquet) ▲
▼ │
S3 (logs) ──▶ Glue/Athena ──▶ opsDaily Lambda ──▶ CloudWatch 지표·알람 ──▶ SNS
DynamoDB: orgs · object-downloads(카운터) · audit-events(400일 TTL → Glacier IR 아카이브)
구성 요소와 역할
/api/* 경로
트래픽이 작아 종량제로 둡니다
AWS WAF
두 distribution의 웹 방화벽
정액제 플랜의 필수 조건이기도 합니다
표준 로그 v2 → Athena → opsDaily Lambda
히트율·허용량·국가별 지표와 알람
하루 한 번 집계합니다
요청 흐름 두 가지
폴더 탐색. 사용자가 Cognito로 로그인하면 Storage Browser가 listLocations를 호출하고, Lambda는 그 사용자의 조직에 배정된 위치 목록을 돌려줍니다. 사용자가 위치를 열면 getLocationCredentials가 호출되고, Lambda는 S3 Access Grants의 GetDataAccess로 그 prefix 전용 임시 자격 증명을 받아 브라우저에 넘깁니다. 이후 목록 조회는 브라우저가 그 자격 증명으로 S3에 직접 요청합니다.
다운로드. 파일을 선택하면 브라우저가 POST /downloads를 호출합니다. Lambda는 객체별 카운터를 1 올리고 올리기 전 값으로 경로를 정합니다(첫 번째는 S3 직접, 두 번째부터 CloudFront). 그 경로의 서명 URL(기본 1시간)을 돌려주면, 1 GiB 이하 파일은 브라우저 기본 다운로드로, 1 GiB를 넘는 파일은 분할 다운로드 엔진으로 받습니다. 엔진은 만료 5분 전에 renew로 URL을 갱신하고, 완료 후 체크섬을 대조합니다.
CDK 스택은 8개(auth → waf(us-east-1) → cdn → cdn-logs(us-east-1) → data → api → web → ops)이고 리소스 이름에는 genome-portal- 접두어만접두어를 씁니다. 두 스택이 8개가us-east-1에 된있는 이유는 CloudFront용 WAF Web ACL과 표준 로그 v2 전송 리소스가 그 리전에서만 만들어지기 때문입니다(§7에서 다룹니다.10).
3. 설계 결정
Transfer Family 웹 앱 대신 Storage Browser를 직접 호스팅하는 이유
같은 사용자 경험을 코드 없이 주는 선택지로 AWS Transfer Family 웹 앱이 있습니다. 다만 인증이 IAM Identity Center 전용이어서, 외부 고객 계정을 Cognito로 발급·관리하는 요구와 맞지 않습니다. 그래서 그 웹 앱의 기반 컴포넌트인 Storage Browser for S3를 직접 호스팅하고, 로그인·브랜딩·폴더 탐색을 동등하게 구성합니다.
요구사항과 결정
aria2c/curl 명령 안내
URL 수명
기본 1시간(설정 범위 15분~12시간). 갱신 요청은 횟수로 세지 않고 같은 경로를 유지
세션
60분 무조작 로그아웃. 다운로드 진행 중에는 무조작으로 세지 않음. 리프레시 토큰 24시간
정액제
CloudFront Pro 플랜의 제약(WAF 필수, OAC, 실시간 로그 미사용, 관리형 정책만) 안에서 설계
운영
표준 로그 → Athena 히트율·국가별 지표, 허용량 사용률 50/80/100/200 % 알람
분할 다운로드의 임계값을 50 GB가 아니라 1 GiB로 둔 것은 URL 수명과 관련이 있습니다. 브라우저 기본 다운로드는 만료된 URL로 이어받기를 시도하면 실패하므로(§1), "오래 걸릴 수 있는 파일"은 전부 URL을 스스로 갱신하는 엔진에 맡기는 편이 사용자 경험이 단순합니다. 1 GiB는 느린 회선에서 1시간 안에 받기 어려워지는 크기입니다.
4. 인증과 권한: Storage Browser + S3 Access Grants
Storage Browser는 세 가지 인증 모드를 지원합니다. Amplify Auth, IAM Identity Center, 그리고 우리가애플리케이션이 listLocations/getLocationCredentials 두 함수를 구현하는 customer-managed auth입니다. Amplify Auth는 defineStorage에 정적 규칙을 적기적는 때문에방식이어서 조직별 공유 prefix를 런타임에 바꾸는 요구를 채우지 못합니다. 그래서참조 구현은 customer-managed로managed 가되,모드를 쓰되, 자격 증명 발급의 실질을 S3 Access Grants에 맡겼습니다.맡깁니다.
배포 위치(prefix) 하나가 Access Grants의 grant 하나입니다. 관리자가 위치를 조직에 배정하면 Lambda가 grant를 만들고, 마지막 조직이 해제되면 grant를 지웁니다. 사용자가 브라우저에서 위치를 열면 Lambda는 조직 소속만 확인하고 나머지는 S3에 넘깁니다.
// infra/lambda/shared/accessGrants.ts (발췌)
const out = await s3Control.send(
new GetDataAccessCommand({
AccountId: accountId,
Target: target, // s3://<bucket>/projects/ORG-0001/* 또는 객체 1개
TargetType: targetType, // 'Object' — presigned URL 서명용은 객체 1개로 한정
Permission: 'READ',
Privilege: 'Minimal', // 요청한 Target 범위로 자격 증명을 축소
DurationSeconds: ttl, // 900 ~ 43,200
AuditContext: auditContext // user=<sub>;org=<orgId>;dl=<downloadId> → CloudTrail에 남음
}),
);
이 선택이구성이 준주는 것성질은 세 가지입니다.
- 범위 계산을 S3가
한다.합니다. 세션 정책 JSON을우리가애플리케이션이 만들지않으니않으므로 단위 테스트할 "권한 문자열"이 없습니다. 위치 IAM 역할은 읽기 액션만 가지며s3:AccessGrantsInstanceArn조건으로 AccessGrantsGrants를경유거치지외않은 사용을 막습니다. - Lambda에는 S3 권한이
없다.없습니다. 체크섬 조회용HeadObject(체크섬 조회)조차 사용자용 Access Grants 자격 증명으로 수행합니다. 그래서 CloudFront 경로를 포함한 모든 다운로드가GetDataAccessCloudTrail 이벤트를 남기고,AuditContext에 사용자·조직·다운로드 ID가 기록됩니다(실측CloudTrail에서가시 지연보이기까지 약 2분). - URL 만료 = 자격 증명 만료. S3 presigned URL의 실제 유효기간은
min(요청한 만료, 서명한 자격 증명의 잔여 수명)입니다. Lambda 실행 역할로 서명하면 잔여 수명을 알 수 없어 "1시간"을보장하지보장할못합니다.수 없지만, 객체 1개 전용 자격 증명을DurationSeconds = URL TTL로 받아 서명하면 둘이 정확히 같아집니다.
한전제 가지 확인해야 했던 전제는하나는 Lambda에서 호출해도 12시간 자격 증명이 나오는가였습니다.입니다. IAM AssumeRole은 역할 체이닝이면체이닝(역할이 다른 역할을 맡는 것)이면 1시간 상한이 걸리는데,걸리지만, GetDataAccess는에는 그렇지그 않았습니다.제한이 없습니다. 통합 테스트에서 DurationSeconds=43200 요청에 expiresAt만료 − now =시각이 43,200.2200초 s가뒤로 나왔고, 그 덕에 URL TTL 상한을 설정값(기본 1시간, 최대 12시간)으로 둘 수 있었습니다.
정직하게 적어 둘 한계도 있습니다. 브라우저로 넘어간 1시간짜리 READ 자격 증명은 CLI로도 쓸 수 있으므로, 포털을 우회한 직접 GET(횟수 미집계)이 가능합니다. Storage Browser 구조상 불가피하고, 탐지는 S3 데이터 이벤트로 합니다.
4.5. "두 번째부터 CloudFront": 카운터 하나로 끝내기경로를 정하기
Storage Browser의 기본 download 액션은 임시 자격 증명으로 브라우저가 직접 presign을presigned URL을 만들기 때문에 횟수서버가 기록을횟수를 우회합니다.알 그래서수 없습니다. 참조 구현은 다운로드 핸들러를 교체해 POST /downloads를 경유시켰습니다.경유시킵니다. 서버는 객체별 카운터를 원자적으로 올리고, 이전 값으로 경로를 판정합니다.
// infra/lambda/handlers/downloads.ts (발췌)
const out = await ddb.send(new UpdateCommand({
TableName: DOWNLOADS_TABLE,
Key: { pk: `OBJ#${bucket}/${key}` },
UpdateExpression: 'ADD #c :one SET lastAt = :now, sizeBytes = :size, checksumCrc32 = :crc',
ExpressionAttributeNames: { '#c': 'count' },
ExpressionAttributeValues: { ':one': 1, ... },
ReturnValues: 'ALL_OLD',
}));
const prevCount = Number(out.Attributes?.count ?? 0);
const path = prevCount >= cfThreshold ? 'CF' : 'S3'; // cfThreshold: SSM, 기본 1 (0 = 전량 CloudFront)
동시 요청이 몇여러 개 오더라도들어와도 prevCount = 0을 받는 요청은 정확히 하나라서하나이므로 "첫 번째만 S3"가 보장됩니다(통합 테스트에서 동시 2건 → S3 1건 확인)1건). 임계값을 SSM 파라미터로파라미터(코드 밖에 두는 설정값 저장소)로 둔 것은이유는 "첫§13에서 번째는설명하듯 S3"이 규칙이 비용이 아니라 정액제 허용량을 관리하기관리하는 위한 선택이라서(§10), 몇 달 뒤장치여서, 운영 지표에 따라 전량 CloudFront(0)로 바꿀 가능성이수 크기있어야 하기 때문입니다. 코드 배포 없이 값만값을 바꾸면 됩니다(60초 캐시).안에 반영되고 코드 배포는 필요 없습니다.
CloudFront 경로는 Key Group 서명 URL입니다.URL(CloudFront에 등록한 공개키로 검증하는 서명 링크)입니다. 사용자마다 서명 쿼리가 달라도 캐시가 맞아야 하므로 캐시 정책은 쿼리 문자열을 캐시 키에 넣지 않는 관리형 CachingOptimized를 씁니다. 오리진은 OAC로 잠긴 S3 버킷이고, 버킷·KMS 키 정책은 이 distribution만 허용합니다. 여기서 CDK 순환 참조가 생깁니다. 버킷 정책은정책에는 distribution ARN이 필요하고 distribution은distribution에는 버킷이 필요하니까요.필요한 해법은순환 참조는, cdn 스택이 버킷을 이름 문자열로만 참조하고 data 스택만 cdn 출력을 가져오는 단방향 의존입니다.의존으로 풉니다. CloudFront는 아직 없는 버킷을 오리진으로 받아 줍니다.
함정:캐시 키와 CORS 설계
브라우저의 분할 엔진은 포털 오리진에서 데이터 distribution으로 fetch하므로 CORS(브라우저가 다른 출처의 응답을 스크립트에 허용할지 정하는 규칙)가 필요합니다. 여기서 캐시 키에키와 Origin이오리진 없다응답의
배포관계가 포털에서중요합니다.
Failed to fetchOrigin 값을 그대로 Access-Control-Allow-Origin에 CachingOptimized는 Origin 헤더를 캐시 키에 넣지 않습니다. localhost:5173Access-Control-Allow-Origin:그대로 http://localhost:5173CORS-With-Preflight 응답 헤더 정책은 오리진이 보낸 CORS 헤더를 덮어쓰지 첫 수정은않고, 오리진 헤더를 덮어쓰는 커스텀 응답 헤더 정책이었는데,정책은 이건 Pro 플랜에서 쓸 수 없는없습니다(§9).
그래서 최종참조 수정은 더 단순합니다.구현은 버킷 CORS를 AllowedOrigins: *로 두면두어 S3가오리진 어느응답을 오리진에도요청과 같은무관하게 답을 하므로 Origin 없는 캐시 키로 캐시돼도 문제가 없습니다.만듭니다. 접근 제어는 서명 URL이 하므로담당하므로 *가 새로추가로 노출하는 것은 없습니다. 교훈:원칙으로 적으면 캐시 키에 들어가지 않는 요청 헤더에 따라 오리진 응답이 달라지면달라져서는 안 된다.된다입니다.
5.6. 50 GB를 넘는 파일: 브라우저 안의 분할 다운로드 엔진
6.1 왜 브라우저가 나눠 받는가
CloudFront의CloudFront가 전달할 수 있는 단일 객체객체의 한도는최대 크기는 50 GB입니다. 150 GB BAM을 CloudFront로 보내려면받으려면 클라이언트가 HTTP Range 요청으로요청(파일의 일부 바이트 구간만 요청하는 방식)으로 잘라 받아야 합니다. 참조8 구현의GiB 분할파트를 엔진은동시에 다음처럼4개씩 동작합니다.받으면 150 GB 안팎의 BAM은 파트 18~19개가 되고, CloudFront 입장에서는 각 파트가 50 GB 이하의 독립 요청이므로 캐시도 파트 단위로 됩니다.
엔진의 기본 동작은 다음과 같습니다.
계획: 8 GiB 파트, 동시 4개. 150 GB면 파트 19개.
fetch(Range)로 받아 POST /downloads/{id}/renew로 x-amz-checksum-crc32이어받기를 고르는"정확하게" 만드는 것이 이 엔진의 핵심이고, 그 출발점은 브라우저가 파일을 어떻게 쓰는지입니다.
6.2 브라우저의 파일 쓰기 모델과 진행률의 내구성
사용자가 고른 파일에 웹 페이지가 쓰는 API는 File System Access API가API(showSaveFilePicker)입니다. 없는 브라우저(Firefox, Safari, Brave, iOS 전체)에서는 파트를 OPFS에 받아 검증한 뒤 브라우저 다운로드로 전달합니다(아래 "확장" 절). OPFS까지 없는 브라우저에서만 50 GB 초과 파일에 aria2c -x 4 -s 4 -k 8G ... / curl -L -C - ... 명령을 서명 URL과 함께 보여 줍니다.
함정 1: aws s3 cp --checksum-algorithm CRC32는 검증에 못 쓴다
멀티파트 업로드에 aws s3 cp --checksum-algorithm CRC32를 쓰면 S3에는 COMPOSITE(파트별 체크섬의 체크섬)가 기록됩니다. 클라이언트가 계산하는 전체 파일 CRC32와 비교할 수 없습니다. 시드 업로드 도구를 SDK lib-storage로 바꾸고 ChecksumType: FULL_OBJECT를 선언한 뒤 로컬 CRC32와 대조하도록 했습니다. 데이터 파이프라인이 파일을 올리는 쪽에서도 같은 조건이 필요하므로 운영 문서에 명시했습니다.
함정 2: 브라우저는 저장 버튼을 누를 때만 파일에 쓴다
처음 설계는 FileSystemWritableFileStream.write({ position })으로 사용자가 고른 최종 파일에 직접 쓰는 것이었습니다. 인수 테스트의 "새로고침 후 이어받기" 시나리오에서 CRC32 불일치가 났습니다. 이유는 File System Access이 API의 동작쓰기 방식입니다. 스트림(createWritable())은 임시 사본(swap file) 에 쓰고,기록하고, close()가 성공한 순간에만 진짜실제 파일로 바꿔칩니다. 엔진은웹 진행률을페이지가 IndexedDB에사용자 청크마다파일을 적었지만반쯤 close()는쓴 일시정지·완료채로 때만망가뜨리지 불렀으니,못하게 새로고침(=하는 close()없는안전장치이고, 종료)우회할 뒤에는방법은 기록이없습니다. 17재개할 %인데때 파일에는 마지막 일시정지 시점(5 %)까지만 있었습니다. 재개는 17 %부터 이어받아 중간에 구멍이 난 파일이 완성됐습니다.
덤으로 발견한 비용도 있습니다. 재개 때마다 부르는쓰는 createWritable({ keepExistingData: true })를는 Chromium은Chromium에서 확정된 파일 전체를 새 사본으로 복사하는 방식으로 구현합니다.구현되어 있어, 150 GB를 90 %에서 재개하면 첫 바이트를 받기 전에 135 GB를 로컬로컬에서 복사합니다.
세이 가지모델에서 안을"진행률"을 비교했습니다.
close()close() A를 택하고 C를 폴백으로 넣었습니다. 파트는아니라 브라우저 내부 저장소에서 충족합니다.
OPFS 파트 저장. OPFS(Origin Private File System)는 브라우저가 사이트별로 제공하는 전용 저장소(OPFS)에저장 두고,공간으로, 워커가사용자의 파일 시스템과 분리되어 있고 워커 안에서 FileSystemSyncAccessHandle로 제자리에 즉시 씁니다.쓸 사본이수 없고있습니다. 참조 구현은 파트마다 OPFS 파일을 두고, 워커가 청크를 받을 때마다 지정 위치에 쓰고 64 MiB마다 flush()로 디스크에 확정되며,확정합니다. 진행률은 메모가어디에도 아니라따로 적지 않고 파트 파일의 실제 크기에서 읽습니다. 모든어느 파트가시점에 끝나면끊기더라도 사용자가파일 고른크기만큼은 위치로디스크에 한있으므로, 번재개는 병합합니다.그 지점부터 시작하면 됩니다(마지막 청크는 부분 쓰기 가능성 때문에 다시 받습니다).
// web/src/download/splitWorker.ts (발췌)
const dir = await splits.getDirectoryHandle(spec.downloadId, { create: true });
const fileHandle = await dir.getFileHandle(partFileName(partIdx), { create: true });
const handle = await withLockRetry(() => fileHandle.createSyncAccessHandle());
const size = handle.getSize(); // = 이 파트의 내구성 있는 진행률
if (size > offset) handle.truncate(offset); // 마지막 청크는 부분 쓰기 대비로 다시 받음
// ... 청크마다 handle.write(data, { at }) , 64 MiB마다 handle.flush()
두 가지가 더 필요했습니다.
estimate()navigator.storage.estimate()withLockRetry는 truncate(파일 크기)NoModificationAllowedError가 납니다. 약 6초 범위의 백오프 재시도로 결과:설계 12대안 GiB비교. 파일을사용자 5파일에 %에서직접 쓰는 방식을 유지하면서 내구성을 얻는 대안도 두 가지 있습니다. 150 GB 기준으로 비교하면 다음과 같습니다.
close() 후 재개방
확정된 바이트만 진행률로 인정
비정상 종료 시 유실
청크 1개(64 MiB)
최대 파트 1개(8 GiB)
마지막 일시정지 참조 구현은 OPFS 파트 방식을 기본으로 하고, OPFS를 쓸 수 없는 환경(시크릿 모드, 저장 공간 부족)에서는 세 번째 방식, 즉 사용자 파일에 직접 쓰되 확정된 바이트만 진행률로 인정하는 방식으로 자동 전환합니다. 이 폴백에서는 탭을 닫으면 마지막 일시정지 이후 데이터를 다시 받게 되며, 화면이 그 사실을 시작 전에 안내합니다.
확장:6.3 전달 단계: 저장 위치 선택 API가또는 없는브라우저 브라우저에도 이어받기를다운로드
A안을모든 적용하고파트를 보니받은 Firefox와뒤 Safari가파일을 분할사용자에게 다운로드에서건네는 빠지는단계는 이유는브라우저 OPFS가기능에 아니었습니다.따라 두 브라우저에도가지 OPFS와중 FileSystemSyncAccessHandle은하나를 있습니다(MDN 호환표 기준 Firefox 111+, Safari 17+). 없는 것은 병합 목적지를 고르는 showSaveFilePicker 하나입니다. 그래서 마지막 단계인 "사용자가 고른 파일로 병합"을 "브라우저 다운로드로 전달"로 바꾸는 두 번째 전달 경로를 추가했습니다.씁니다. 판정은 브라우저 이름이 아니라 기능 유무로유무로 합니다.
// web/src/download/planner.ts (발췌)
export function splitCapability(env = defaultEnv()): 'picker' | 'export' | 'none' {
if (hasFileSystemAccess(env.window)) return 'picker'; // 기존 경로: OPFS 파트 -> 선택한사용자가 고른 파일로 병합
const getDirectory = env.navigator?.storage?.getDirectory;
if (typeof getDirectory === 'function' && (env.hasWorker ?? true)) return 'export'; // OPFS 파트 -> 브라우저 다운로드
return 'none'; // 기존 폴백: 일반 다운로드(≤ 50 GB) 또는 명령어 안내
}
저장 위치 선택(picker). showSaveFilePicker가 있는 브라우저(Chrome, Edge 등 데스크톱 Chromium 계열)에서는 시작할 때 저장 위치를 고르고, 파트가 모두 끝나면 그 파일로 한 번 병합합니다. 병합 중 close()가 성공하면 파일이 확정되고, 이어서 파일을 다시 읽어 CRC32를 대조합니다.
브라우저 다운로드로 전달(export). 경로의Firefox와 흐름은Safari에는 showSaveFilePicker가 없지만 OPFS와 동기 접근 핸들은 있습니다(Firefox 111+, Safari 17+). Brave는 Chromium 기반이지만 File System Access API를 기본으로 꺼 두고, iOS에서는 모든 브라우저가 Safari 엔진을 씁니다. 이 브라우저들에서는 파트 수신과 검증을 똑같이 한 뒤 마지막 단계만 "파트브라우저의 수신(기존과일반 동일) → 파트를 순서대로 스트리밍하며 CRC32 검증 →다운로드로 전달"입니다.합니다. 검증을 전달 앞에 두는 이유는, 손상된 데이터라면 브라우저가 100 GB를 복사하기 전에 끝내기 위해서입니다. 전달 방식은 두 가지 중 브라우저가 지원하는 것을 씁니다.
- 서비스 워커 스트림
(:ReadableStream을postMessage로 전송할 수 있는브라우저):브라우저(Firefox 103+, Chromium)에서는 파트 파일들을 하나의ReadableStream으로스트림으로 이어 서비스워커에워커(페이지와 별개로 네트워크 요청을 가로채는 스크립트)에 넘기고, 숨은 iframe으로/portal-export/<id>를 열면 워커가Content-Disposition: attachment와Content-Length를 붙여 응답합니다. 브라우저 다운로드 UI에 총 크기와 남은 시간이 표시되고, 스트림이 끝나는 시점을 엔진이 알 수 있어파트OPFS파일을파트를 즉시 삭제합니다. - Blob 전달
(: 스트림 전송이 없는브라우저):브라우저(SafariOPFS의26파트이하)에서는 OPFS 파트의File참조들을new Blob([...])로 묶어<a download>로 넘깁니다. 참조만 묶으므로 복사나 메모리 적재는 없고, 브라우저가 다운로드 폴더로 복사합니다. 엔진은 완료 시점을 알 수없어없으므로파트는파트를 유지하고, 사용자가 목록에서 제거하거나 24시간이 지나면 삭제합니다.
구현서비스 과정에서워커 두스트림 가지를경로에는 더지켜야 배웠습니다.
브라우저별로 할당량은정리하면 다음과 같습니다.
aria2c -x 4 -s 4 -k 8G ..., curl -L -C - ... 명령 안내
화면이 사유를 안내
6.4 저장 공간 판정
OPFS 파트 방식은 파일 크기만큼의 저장 공간을 시스템 드라이브(브라우저 프로필이 있는 곳)에 요구합니다. 시작 전에 이 공간을 확실하게 판정해야 하는데, 브라우저가 알려 주는 추정치는 믿을 수 없습니다.
Chromium의navigator.storage.estimate()는 할당량을 10 navigator.storage.persist())이 허용되기 전까지 사이트당 OPFS 한도를 10 GiB로 두고, 허용 그래서 할당량참조 예약구현은 프로브보다(1) 먼저 를 navigator.storage.persist()호출해(30초호출해 상한) 사용자사용자가 프롬프트에 응답할 시간을 30초 상한으로 두고, 거부되거나(2) 무시되면OPFS 10스크래치 파일에 truncate(파일 크기 + 여유 256 MiB)를 시도하는 예약 프로브로 판정합니다. truncate는 실제 I/O 없이 할당량만 검사하므로 즉시 끝납니다. 성공하면 OPFS 파트 방식으로, 실패하면 저장 위치 선택이 가능한 브라우저는 직접 기록 폴백으로, 그렇지 않은 브라우저는 일반 다운로드 또는 명령 안내로 내려가며 화면에 사유를 표시합니다. 시크릿 모드는 OPFS가 메모리에 있어 1 GiB 한도에서이상 프로브가쓰기가 실패해실패하므로 기존역시 폴백으로폴백입니다.
6.5 사용자무결성: 안내full-object 문구에 이 프롬프트를 허용하라는 내용을 넣은 이유입니다.
CRC32
실측으로S3는 Firefox에서객체마다 2체크섬을 GiB보관할 수 있는데, 대조에 쓸 수 있는 것은 full-object(파일 전체) 체크섬입니다. 멀티파트 업로드에서 aws s3 cp --checksum-algorithm CRC32가 기록하는 값은 COMPOSITE(파트별 체크섬의 체크섬)이어서 클라이언트가 계산한 전체 파일 CRC32와 비교할 수 없습니다. 참조 구현의 업로드 도구는 SDK lib-storage로 ChecksumType: FULL_OBJECT를 선언해 올리고, 데이터 파이프라인이 파일을 5올리는 %에서 일시정지 → 재개 → 22 %에서 새로고침 → 재개했을 때 493,830,572 B가 손실 없이 보존되고, 서비스 워커 스트림으로 저장된 파일의 CRC32가 S3 값과 일치했습니다. Chromium에서 showSaveFilePicker를 제거해 Brave와쪽에도 같은 조건을 만든운영 12문서로 GiB(2파트)요구합니다. 실행은브라우저는 Blob저장 위치 선택 경로에서는 병합된 파일을, 브라우저 다운로드 전달 경로로경로에서는 완료되어OPFS CRC32가파트를 일치했습니다.순서대로 Safari는읽어 호환표CRC32를 기준으로계산하고 같은x-amz-checksum-crc32 경로를값과 타지만 실기기 검증은 아직 없습니다.대조합니다.
실측:6.6 실측
53 GiB(56.9 GB)도 CloudFront를객체의 통과한다CloudFront
통과와 캐시.
"50 GB 초과 객체도 8 GiB Range 파트로 나누면 CloudFront를 통과하고 캐시된다"는| 패스 | CloudFront 결과 | 요청 | 전송 | 소요(수신 + 병합 + CRC32) |
|---|---|---|---|---|
| 1회차 | Miss 7/7 (파트마다 오리진 인출) |
7 | 56.96 GB | 1,052 s |
| 2회차 | Hit 7/7 |
7 | 56.92 GB | 1,095 s |
두 패스 모두 병합 후 CRC32가 시드S3 값과 일치했습니다. 흥미로운 점은 캐시 히트 패스가 더 빠르지 않다는않은 것입니다.이유는 네트워크 인출은인출이 두 패스 모두 약 4분이고 나머지 13~14분은14분이 로컬 작업(OPFS 기록 → 53 GiB 병합 → CRC32)이었습니다.이기 때문입니다. 데스크톱급 회선에서는 병목이 디스크이고, 캐시의 이득은 대역폭이 좁은 해외 사용자에게서 나타납니다.
6.
새로고침 세션과후 URL이어받기. 수명을12 다운로드GiB 시간에파일을 맞추기5
150 GB를 50 Mbps로 받으면 6.7시간입니다. 60분 무조작 로그아웃과 1시간 URL을 그대로 두면 한 시간마다 멈춥니다. 그래서
fetchAuthSession()AdminUserGlobalSignOut →paused/AUTH_EXPIRED7. 정액제 플랜을 IaC로 연결하기
CloudFront 정액제 플랜은 CloudFormation 리소스 AWS::PricingPlanManager::Subscription으로 만들 수 있습니다. CDK에서는 설정값 하나로 켭니다.
// infra/lib/cdn-stack.ts (발췌) — cfg.flatRatePlan = { tier: 'PRO' } 일 때만
this.flatRatePlan = new pricingplanmanager.CfnSubscription(this, 'FlatRatePlan', {
planFamily: 'CloudFront',
planTier: this.cfg.flatRatePlan.tier, // PRO | BUSINESS | PREMIUM
usageLevel: this.cfg.flatRatePlan.usageLevel ?? 'DEFAULT',
resourceArns: [this.distribution.distributionArn, props.webAclArn],
});
알아 둘 점이 두 가지입니다.
PENDING_APPROVALapprove-paid-subscriptionCreateSubscription8. 운영: 로그새로고침 → Athena재개했을 →때(Chromium) 알람
cdn-logssc_bytesbigintBINARY vs bigintstringtry_castopsDailyGrantDriftenforceSSLFailed to execute actionset-alarm-state9. 검증
NO_GRANTauditContext/downloadsshowSaveFilePicker를 제거해 Brave와 7.
일괄 다운로드(zip): 압축이 아니라 묶음인수여러 과정에서파일을 잡은선택하면 제품 결함은 위에 적은 것들(CORS 캐시 키, swap 파일, 알람 SNS 정책, COMPOSITE 체크섬,포털은 zip 다운로드가하나로 전달합니다. 압축을 위해서가 아니라, 브라우저에서 여러 파일을 한 번에 저장할 수 있는 안정적인 방법이 "하나의 파일로 묶는 것"이기 때문입니다. 웹 페이지가 한 번의 클릭으로 여러 파일을 저장하려 하면 브라우저가 차단하거나 "여러 파일 다운로드 허용" 확인을 띄우고, 폴더 구조도 유지되지 않습니다. 수십~수천 개 파일(포털은 최대 5,000개)을 일일이 저장하게 할 수는 없으므로, 선택한 파일을 폴더 구조 그대로 담은 zip 하나로 전달합니다.
POST /downloads를 호출해 서명 URL을 받고, CloudFront/S3에서 각 파일을 내려받으면서 zip 형식으로 흘려 저장합니다. 그래서 CloudFront 입장에서는 파일별 GET 요청일 뿐이며, 다운로드 횟수 기록·감사 로그·정액제 적용도 파일 단위로 동일하게 동작합니다. 적용되는 시간 제한은 오리진 응답 타임아웃(다음 패킷을 기다리는 시간, 기본 30초)뿐이고, 전체 응답 시간의 상한은 설정하지 않으면 적용되지 않습니다.
다운로드는 서비스 워커가 시작합니다. zip 스트림은 서비스 워커가 다운로드 응답으로 바꾸고, 저장은 서비스 워커 스코프 안의 숨은 iframe 내비게이션으로 시작합니다. 스코프 밖 페이지에서 앵커를 클릭하면 서비스 워커를 index.html자동화가 전부 녹색인 뒤, 사람이 5분 만에 찾은 결함 2건
위 표가 모두 통과한 상태에서 첫 사용자 테스트를 받았습니다. 로그인하고 목록을 보고 zip을 한 번 눌러 본 것뿐인데 결함이 두 개 나왔습니다. 둘 다 "정상 경로"만 검증한 테스트의 빈틈이었습니다.
config.jsonbrand.logoUrl/brand/logo.svg/brand/config.json고친 방법은 세 겹입니다. SPA가 중립적인 기본 로고(web/public/brand/logo.svg)를 함께 배포해 기본 URL이 항상 동작하게 했고, 배포 설정에 brand.logoFile을 추가해 로컬 이미지를 logoUrl 키로 함께 업로드하게 했습니다(고객 로고는 저장소 밖에 둡니다). 그리고 설정 로더가 아무것도 서빙하지 않는 상대 경로를 synth 단계에서 거부합니다. 헤더 컴포넌트는 onError에서 이미지를 숨깁니다. e2e에는 img.complete && img.naturalWidth > 0 한 줄이 추가됐습니다.
2. zip 다운로드를스트림은 취소하면중간부터 화면이이어받을 수 없어 중단되면 처음부터 다시 만들고, 50 GB를 넘는 파일은 zip에 넣을 수 없습니다(해당 파일은 분할 다운로드로 개별 안내). 대용량 파일 소수를 받을 때는 분할 다운로드가 맞고, 화면 문구는 "zip 생성스트리밍 중"에중(브라우저 머물렀다.다운로드 진행, 압축 없음)"으로 압축 단계가 없음을 알립니다.
취소는 반드시 끝나야 합니다. 1사용자가 GiB가장 파일먼저 하나를누르는 zip으로버튼이 받다가 취소를 누르면 진행 숫자만 멈추고취소이고, 취소 버튼이 그대로 남았습니다. 원인은처리에는 두 겹이었고,가지 두조건이 번째는있습니다. 첫 번째를 고친 뒤 배포 환경에서 반복 실행해야만 드러났습니다.
취소가 끝나지 않는다. 취소 버튼은 AbortController를 abort합니다. fetch body가 에러로 끝나고, 서비스 워커에 넘긴첫째, zip 스트림도 에러로 끝나 브라우저 다운로드는 "실패"가 됩니다. 그런데 runZip은라이브러리(client-zip)는 엔트리 제너레이터의 finally에서만 풀리는 promise를 기다리고 있었고, client-zip은 그 제너레이터를 return()이을 없는부르지 않는 이터레이터로 감싸소비하므로, 소비합니다.취소로 for await 루프가 예외로 빠져나갈 때 return()이 없으면빠져나가면 제너레이터는 yield에 멈춘 채로채 남고 finally는 영원히 실행되지 않습니다. 취소 신호 자체를 함께 기다리고 제너레이터를 직접 닫는닫아야 것으로 해결했습니다.합니다.
// web/src/download/zip.ts (발췌) — 취소는 반드시 settle되어야 한다
const aborted = new Promise<void>((r) => signal?.addEventListener('abort', () => r(), { once: true }));
await Promise.race([finishedPromise, aborted]);
if (signal?.aborted && !finished) {
void entryIterator.return(undefined).catch(() => undefined); // client-zip은 return()을 부르지 않는다
return { status: 'cancelled' };
}
취소 뒤에 도착한 진행률이 결과를 덮어쓴다. 위 수정으로 runZip은 cancelled를 돌려주는데, 배포 포털에서 다섯 번 중 두세 번은 여전히 화면이 바뀌지 않았습니다. 트레이스를 넣어 보니 순서는 늘 같았습니다.둘째, 취소 →시점에 runZip 종료 → 뷰가 done 상태를 설정 → 카운팅 스트림에 이미 들어와 있던 청크가 진행률을 한 번 더 보고보고할 →수 뷰가 running 상태를 설정.있습니다. React는 두 상태 업데이트를 한묶어 번에처리하므로 처리하고"완료" 뒤에 도착한 "진행 중" 보고가 마지막 쓰기가쓰기로 이깁니다.남습니다. 엔진은 abort 뒤 보고를 멈추고, 화면은 진행률을 함수형 업데이터로 진행 중일 때만 반영합니다. 이 조건은 로컬 개발 서버에서는서버보다 타이밍이배포 달라환경에서 재현되지더 않았습니다.자주 runZip은나타나므로 aborte2e 뒤에테스트는 보고를배포 멈추고,포털에서 뷰는반복 진행률을 함수형 업데이터로 running일 때만 반영하도록 바꿨습니다.실행합니다(§12).
onProgress: (progress) =>
setPhase((prev) => (prev.kind === 'running' ? { kind: 'running', progress } : prev)),
8. 세션과 URL 수명을 다운로드 시간에 맞추기
단위150 테스트는GB를 "취소50 결과Mbps로 뒤에받으면 늦은6.7시간입니다. 진행률이60분 와도무조작 cancelled가로그아웃과 유지된다"를1시간 고정하고(옛URL을 코드에서는그대로 실패),두면 e2e한 시간마다 멈추므로, 세 가지를 맞춥니다.
fetchAuthSession()으로 AUTH_EXPIRED 사유의 일시정지로 보존합니다. 다시 로그인하면 받은 지점부터 재개합니다.
같은e2e 점검에서테스트는 65분 무조작 동안 토큰 갱신이 일어나며 다운로드가 완료되는 것과, 진행 중 AdminUserGlobalSignOut으로 세션을 끊은 뒤 재로그인해 재개한 파일의 CRC32가 일치하는 것을 확인합니다.
9. 정액제 플랜을 IaC로 연결하기
CloudFront 정액제 플랜은 월 정액으로 일정 전송량(허용량)을 쓰는 요금제이고, CloudFormation 리소스 AWS::PricingPlanManager::Subscription으로 만들 수 있습니다. CDK에서는 설정값 하나로 켭니다.
// infra/lib/cdn-stack.ts (발췌) — cfg.flatRatePlan = { tier: 'PRO' } 일 때만
this.flatRatePlan = new pricingplanmanager.CfnSubscription(this, 'FlatRatePlan', {
planFamily: 'CloudFront',
planTier: this.cfg.flatRatePlan.tier, // PRO | BUSINESS | PREMIUM
usageLevel: this.cfg.flatRatePlan.usageLevel ?? 'DEFAULT',
resourceArns: [this.distribution.distributionArn, props.webAclArn],
});
운영 관점에서 알아 둘 점은 두 가지입니다.
PENDING_APPROVAL 상태로 만들어지고 CloudFormation이 승인하지 않습니다. 콘솔 또는 approve-paid-subscription으로 승인하면 즉시 잔여 일수 비례 과금이 시작되고, 현재 청구 주기가 끝날 때까지 취소할 수 없습니다. 플랜이 붙은 distribution은 삭제도 되지 않으므로(플랜 해지 → 주기 말 적용 → 삭제), 개발 환경에서는 구독을 만들되 승인하지 않은 상태로 두는 것이 안전합니다.
티어의 기능 제약은 설계 단계의 입력입니다. distribution이 플랜에서 지원하지 않는 기능을 쓰고 있으면 CreateSubscription이 ValidationException으로 거절됩니다.
ForwardedValues), Continuous deployment, Anycast IP. 플랜에 연결된 WAF Web ACL·CloudFront Function은 다른 distribution과 공유 불가
정책
캐시 정책·오리진 요청 정책·응답 헤더 정책은 관리형만(커스텀 정책은 Business 이상)
한도
캐시 동작 10개, WAF 규칙 25개
로그
표준 액세스 로그 포함. Parquet 형식 로그 전달은 플랜 밖 종량 과금
허용량
월 50 TB 전송, 1,000만 요청. 하드 리밋이 아니며 첫 스파이크는 3배까지 그 달 서비스에 영향 없음. 지속 초과는 2~3개월 이상 관찰 후 평가. 50/80/100 % 도달 시 이메일 통지
참조 구현의 데이터 distribution은 관리형 CachingOptimized, 관리형 CORS-With-Preflight, OAC, 표준 로그만 사용해 이 조건을 만족합니다. §5의 CORS 설계가 커스텀 응답 헤더 정책 대신 버킷 CORS로 해결되어야 하는 이유도 여기에 있습니다.
10. 운영: 로그 → Athena → 알람
cdn-logs 스택이 us-east-1에 따로 있고, 로그 버킷은 워크로드 리전(서울)에 둡니다.
parquet의 모든 필드는 문자열입니다. Glue 테이블(Athena가 읽는 스키마 정의)에서 sc_bytes를 bigint로 선언하면 Athena 쿼리가 형 불일치로 실패합니다. 전부 string으로 선언하고 집계 쿼리에서 try_cast합니다.
하루 한 번 지표를 만듭니다. opsDaily Lambda가 Athena로 전날 로그를 집계해 캐시 히트율(요청·바이트), 국내/해외 바이트(c-country 기준), 정액제 허용량 사용률, grant와 DynamoDB 원장의 정합성(GrantDrift)을 CloudWatch 지표로 올리고, 감사 이벤트를 S3 Glacier Instant Retrieval(저렴한 장기 보관 클래스)로 아카이브합니다. 감사 이벤트의 DynamoDB 보존은 400일입니다.
알람 10개가 SNS로 나갑니다. 허용량 50/80/100/200 %, 5분 내 403 50건 이상, downloads Lambda 오류율 5 % 초과, grant 누락, GrantDrift, opsDaily 실패, API 5xx 5건 이상입니다.
SNS 토픽 정책에 CloudWatch 발행 허용을 명시합니다. 토픽에 enforceSSL 정책을 붙이면 기본 정책에 있던 CloudWatch의 발행 허용 문이 사라져, 알람이 울려도 Failed to execute action으로 끝납니다. 토픽 정책에 cloudwatch.amazonaws.com의 sns:Publish를 명시하고, 배포 절차에 set-alarm-state로 알람을 한 번 울려 실제 수신을 확인하는 단계를 둡니다.
11. 코드 수정 없이 바꾸는 값
운영 중 바뀔 가능성이 있는 값은 코드가 아니라 설정에 둡니다.
cf-threshold
SSM 파라미터(60초 캐시)
몇 번째 다운로드부터 CloudFront로 보낼지. 기본 1, 0이면 전량 CloudFront
url-ttl-seconds
SSM 파라미터
서명 URL 수명. 기본 3,600, 범위 900~43,200
flatRatePlan
배포 설정(infra/config/<env>.json)
{ tier: 'PRO' }처럼 티어를 적으면 구독 리소스가 생성되고, 비우면 종량제
brand
배포 설정
포털 이름과 로고. logoFile에 로컬 이미지 경로를 적으면 web 스택 배포 때 함께 업로드되며(고객 로고는 저장소 밖에 둠), 아무것도 서빙하지 않는 경로는 synth 단계에서 거부됩니다. 기본 로고가 SPA에 포함되어 있어 설정이 없어도 화면이 깨지지 않습니다
조직 ↔ prefix
관리자 API
위치 하나가 grant 하나. 새 고객사는 조직을 만들고 위치를 배정하면 끝
12. 검증
NO_GRANT), 경로 규칙(동시 2건 → S3 1건), URL 수명(TTL 900초 만료 15초 뒤 403), grant 수명주기, CloudTrail auditContext, /downloads p95 298 ms
23/23
e2e(Playwright)
Chromium: 분할·새로고침 이어받기·65분 무조작 중 토큰 갱신·인증 만료 후 재개·캐시 2패스·zip·zip 취소·저장 위치 교훈은 단순합니다. 다운로드 포털의 테스트는테스트에서 지킨 원칙은 네 가지입니다.
img.complete && img.naturalWidth > 0)를 e2e가 확인하고, 콘솔 오류 0건을 배포 후 점검 항목으로 둡니다. 사용자가 가장 먼저 보는 것은 로고입니다.
zlib로 다시 계산해 S3 값과 대조하고, 알람은 set-alarm-state로 실제 수신을 확인합니다.
10.13. 비용 관찰
비용만CloudFront보면비용은답은전량 CloudFront일 때 가장 단순합니다. S3 → CloudFront 오리진 전송은 무료이고 Pro 정액제는 허용량(50 TB)을 넘어도 초과 과금이 없으므로, 모든 다운로드를 CloudFront로 보내면(cf-threshold=0) 월 전송량이 100TB든 139 TB든TB여도 CloudFront 데이터 전송 비용은 월 $15입니다.
cf-threshold=1로 11.14. 고려 사항
AuditContext로 합니다.
정액제 플랜. 승인은 사람이 하고 승인 후 청구 주기 말까지 취소할 수 없습니다. 플랜이 붙은 distribution은 삭제할 수 없습니다. 허용량 초과는 과금이 아니라 평가 대상이므로 어카운트팀과의 사전 협의 창구를 두는 것이 좋습니다.
업로드 측 요구. 데이터 파이프라인은 ChecksumType: FULL_OBJECT로 올려야 브라우저가 무결성을 대조할 수 있습니다.
운영 배포에서 바꿀 것. 참조 구현은 기본 CloudFront 도메인을 쓰므로 운영에서는 커스텀 도메인과 인증서가 필요합니다. 데이터 버킷 이름은 비인증 설정 파일(config.json)에 포함되므로 계정 ID가 들어가지 않은 이름을 권합니다.
15. 정리
- Storage Browser는 "표시"에, S3 Access Grants는 "권한"에, Lambda는 "규칙"에만 관여하게 나누면 각 층의 테스트가 단순해집니다.
- 경로 규칙은 DynamoDB
ADD+ReturnValues: ALL_OLD한줄이면줄로 충분하고, 임계값은 코드가 아니라설정값으로설정값에 둡니다. - 캐시 키에 없는 요청 헤더(
Origin)에 따라 오리진 응답이달라지면달라져서는 안 됩니다. 버킷 CORS*가정답이었습니다.답입니다. 브라우저브라우저의 파일 쓰기는close()시점에만 확정됩니다. 이어받기가 필요하면 OPFS +FileSystemSyncAccessHandle에 쓰고 마지막에병합하세요.병합하거나용량은브라우저 다운로드로 전달합니다. 저장 공간은estimate()가 아니라truncate()예약으로 판정합니다.저장 위치 선택 API가 없는 브라우저에서는 병합 대신 서비스 워커 스트림(또는 Blob)으로 브라우저 다운로드에 넘기면 같은 이어받기를 얻습니다.- 정액제 플랜은 IaC로 연결할 수 있지만 승인은 사람이 하고, 티어의 기능 제약은 설계 단계의 입력입니다.
- 표준 로그 v2 전송 리소스는 us-east-1, parquet 필드는 전부 문자열, 알람은 만든 뒤 한 번 울려
보기.수신을 확인합니다.
참조 구현(CDK 8스택, Lambda, React SPA, admin CLI, 통합·e2e 테스트, runbook, 요구사항·설계 문서)은 GitHub hmkim/omics-data-delivery-portal에 MIT-0 라이선스로 공개했습니다.공개되어 있습니다. 공개 저장소에서는 계정 ID·도메인·이메일을 자리표시자로 바꿨고,대체했고, 측정값과 날짜는 dev개발 계정 실측 그대로입니다. 질문과 개선 제안은 저장소 이슈로 남겨 주세요.
참고 자료
용어 설명
projects/ORG-0001/)
JWT authorizer
API Gateway가 요청에 담긴 Cognito 토큰(JWT)을 검증해 인증되지 않은 요청을 거절하는 기능
원자 카운터
동시에 여러 요청이 와도 각 요청이 서로 다른 값을 받도록 보장하는 증가 연산. DynamoDB ADD가 제공한다
SSM 파라미터
AWS Systems Manager Parameter Store에 두는 설정값. 코드 배포 없이 값을 바꿀 수 있다
HTTP Range 요청
파일의 일부 바이트 구간만 요청하는 HTTP 기능. 대용량 파일을 조각으로 받거나 이어받을 때 쓴다
캐시 키
CloudFront가 "같은 응답"으로 볼 요청의 식별 기준. 여기에 없는 요청 헤더가 달라도 같은 캐시 항목이 전달된다
CORS
브라우저가 다른 출처(도메인)의 응답을 스크립트에 허용할지 정하는 규칙. 서버가 Access-Control-Allow-Origin 헤더로 허용 범위를 알린다
Web Worker / 서비스 워커
Web Worker는 화면과 분리된 백그라운드 스레드. 서비스 워커는 페이지와 별개로 네트워크 요청을 가로채고 응답을 만들 수 있는 스크립트
File System Access API
웹 페이지가 사용자가 고른 파일에 직접 쓰게 하는 API(showSaveFilePicker). 데스크톱 Chromium 계열만 지원
swap file
File System Access API가 쓰기 중 사용하는 임시 사본. close()가 성공할 때만 실제 파일로 바뀐다
OPFS (Origin Private File System)
브라우저가 사이트별로 제공하는 전용 저장 공간. 사용자의 파일 시스템과 분리되어 있고 즉시 쓰기가 가능하다
FileSystemSyncAccessHandle
OPFS 파일에 워커가 제자리에서 동기적으로 읽고 쓰는 핸들. flush()로 디스크에 확정한다
Blob
브라우저가 다루는 바이너리 데이터 덩어리. 파일 참조를 묶기만 하면 메모리에 올리지 않는다
CRC32 (full-object / COMPOSITE)
오류 검출용 32비트 체크섬. full-object는 파일 전체의 값, COMPOSITE는 멀티파트 업로드의 파트별 체크섬을 다시 체크섬한 값으로 전체 파일 값과 비교할 수 없다
표준 로그 v2
CloudFront의 액세스 로그 전송 방식. CloudWatch Logs 전송을 통해 S3·CloudWatch Logs·Firehose로 보낼 수 있고 parquet 포맷을 지원한다
parquet / Glue / Athena
parquet는 열 지향 압축 파일 형식. Glue 테이블은 그 파일의 스키마 정의, Athena는 S3의 파일을 SQL로 조회하는 서비스
WAF Web ACL
AWS WAF의 규칙 묶음. CloudFront distribution 앞에서 요청을 검사한다
정액제 허용량
정액제 플랜에 포함된 월 전송량·요청 수. 하드 리밋이 아니라 지속 초과 시 평가 대상이 되는 기준
Glacier Instant Retrieval
즉시 조회가 가능한 S3 장기 보관 스토리지 클래스
cdk-nag
CDK 코드에 보안·모범 사례 규칙을 검사하는 도구
e2e 테스트
실제 브라우저로 사용자 흐름 전체를 자동 실행하는 테스트. 참조 구현은 Playwright를 쓴다