"""카페24 디자인 보관함 FTP — 스킨에 올라간 개별 파일(예: product-swiper.js) 읽기/쓰기. Admin API(OAuth)로는 스킨 파일을 다루지 못한다(`config.py` 상단 설명 참고). 카페24가 스킨 파일에 제공하는 유일한 프로그램적 접근은 "디자인 보관함" FTP 계정이며, Admin API 와는 별개의 인증(호스트/포트/아이디/비밀번호)이다. 그래서 여기는 `Cafe24Client` (httpx 기반)를 쓰지 않고 표준 라이브러리 `ftplib` 를 직접 쓴다. 실물 확인(스크린샷): 호스트 `{mall_id}.ftp.cafe24.com`, 포트 21, SSL/TLS 미사용 (평문 FTP). 파일은 텍스트(UTF-8)로 다룬다. 쓰기는 원본에 직접 STOR 하지 않는다 (write_text_file) 직접 STOR 는 전송 도중 끊기면 원본이 **앞부분만 남은 채** 잘린다(스킨 템플릿이면 모든 상품 페이지가 깨진다). 그래서 1) 같은 폴더의 임시 파일에 올리고 (원본은 아직 그대로) 2) 다시 받아 바이트 단위로 검증하고 3) 교체 직전 원본을 다시 읽어 편집 시작 값과 같은지 확인하고(충돌 방지) 4) RNFR/RNTO 로 이름을 바꿔 교체한다 서버가 "이미 있는 이름으로 바꾸기"를 거부하면 원본을 옆 이름으로 비킨 뒤 교체하고, 실패하면 원본을 제자리로 되돌린다. 이름 바꾸기 자체를 지원하지 않으면 **중단**한다 (직접 STOR 로 물러서지 않는다). """ from __future__ import annotations import ftplib import io import posixpath import uuid from .config import Cafe24FtpConfig from .errors import Cafe24FtpConflict, Cafe24FtpError # 응답이 없을 때 무한 대기하지 않도록 — 관리 화면 요청 안에서 동기 호출되므로 # 너무 길면 안 되지만, 파일 하나(수십 KB) 전송에는 충분히 넉넉해야 한다. _TIMEOUT_SECONDS = 20 def _connect(config: Cafe24FtpConfig) -> ftplib.FTP: try: ftp = ftplib.FTP() ftp.connect(config.host, config.port, timeout=_TIMEOUT_SECONDS) ftp.login(config.user, config.password) ftp.set_pasv(True) return ftp except ftplib.all_errors as exc: # OSError 포함 — 연결 실패도 여기서 잡힌다 # 비밀번호가 예외 메시지에 섞여 나오지 않는다 — ftplib 오류는 서버 응답 # 문자열이며 우리가 보낸 자격증명을 되풀이하지 않는다. raise Cafe24FtpError(f"FTP 연결/로그인에 실패했습니다: {exc}") from exc def _close(ftp: ftplib.FTP) -> None: try: ftp.quit() except Exception: # noqa: BLE001 — 정리 실패는 무시 ftp.close() def _retr(ftp: ftplib.FTP, path: str) -> bytes: buf = io.BytesIO() ftp.retrbinary(f"RETR {path}", buf.write) return buf.getvalue() def _delete_quiet(ftp: ftplib.FTP, path: str) -> None: try: ftp.delete(path) except ftplib.all_errors: pass # 임시 파일 정리 실패는 무시(이름에 cf24tmp 가 붙어 있어 구분된다) def read_text_file(config: Cafe24FtpConfig, path: str) -> str: """디자인 보관함의 파일 1개를 읽어 텍스트로 돌려준다.""" ftp = _connect(config) try: try: raw = _retr(ftp, path) except ftplib.all_errors as exc: raise Cafe24FtpError(f"파일을 읽지 못했습니다({path}): {exc}") from exc try: return raw.decode("utf-8") except UnicodeDecodeError as exc: raise Cafe24FtpError(f"파일 인코딩을 UTF-8로 해석하지 못했습니다({path}): {exc}") from exc finally: _close(ftp) def temp_names(path: str, tag: str) -> tuple[str, str]: """(임시 업로드 이름, 원본을 잠시 비킬 이름) — 같은 폴더, 원본 이름 + 표식.""" folder, name = posixpath.split(path) return (posixpath.join(folder, f"{name}.cf24tmp-{tag}"), posixpath.join(folder, f"{name}.cf24old-{tag}")) def write_text_file( config: Cafe24FtpConfig, path: str, content: str, *, expected_current: str | None = None ) -> None: """디자인 보관함의 파일 1개를 안전하게 교체한다(모듈 설명 참고). expected_current: 편집 시작(또는 백업) 때 읽은 원본. 주면 교체 직전 원본을 다시 읽어 다르면 Cafe24FtpConflict 로 멈춘다(원본 그대로). 실패 시 Cafe24FtpError — maybe_applied=True 면 원본이 이미 바뀌었을 수 있다. """ data = content.encode("utf-8") tmp, aside = temp_names(path, uuid.uuid4().hex[:10]) ftp = _connect(config) try: # 1) 임시 파일에 올린다 — 원본은 아직 그대로다. try: ftp.storbinary(f"STOR {tmp}", io.BytesIO(data)) except ftplib.all_errors as exc: _delete_quiet(ftp, tmp) raise Cafe24FtpError(f"임시 파일을 올리지 못했습니다 — 원본은 그대로입니다({path}): {exc}") from exc # 2) 검증 — 다시 받아 바이트 단위로 비교한다(전송이 잘렸으면 여기서 잡힌다). try: uploaded = _retr(ftp, tmp) except ftplib.all_errors as exc: _delete_quiet(ftp, tmp) raise Cafe24FtpError(f"올린 임시 파일을 확인하지 못했습니다 — 원본은 그대로입니다: {exc}") from exc if uploaded != data: _delete_quiet(ftp, tmp) raise Cafe24FtpError( f"올린 임시 파일이 보낸 내용과 다릅니다({len(uploaded)}/{len(data)}바이트) — 원본은 그대로입니다." ) # 3) 충돌 확인 — 교체 직전의 원본이 편집 시작 값 그대로인가. if expected_current is not None: try: now = _retr(ftp, path) except ftplib.all_errors as exc: _delete_quiet(ftp, tmp) raise Cafe24FtpError(f"교체 직전 원본을 다시 읽지 못했습니다 — 원본은 그대로입니다: {exc}") from exc if now != expected_current.encode("utf-8"): _delete_quiet(ftp, tmp) raise Cafe24FtpConflict( "적용하는 사이 FTP 파일이 바뀌었습니다 — 원본은 그대로입니다. 새로고침해 확인한 뒤 다시 적용하세요." ) # 4) 교체 — 이름 바꾸기. 덮어쓰기를 거부하는 서버면 원본을 비킨 뒤 교체한다. moved_aside = False try: ftp.rename(tmp, path) except ftplib.all_errors as first: try: ftp.rename(path, aside) except ftplib.all_errors as exc: _delete_quiet(ftp, tmp) raise Cafe24FtpError( "이 FTP 서버가 파일 이름 바꾸기(rename)를 지원하지 않아 중단했습니다 — 원본은 그대로입니다. " f"({first} / {exc})" ) from exc try: ftp.rename(tmp, path) except ftplib.all_errors as exc: try: ftp.rename(aside, path) except ftplib.all_errors as exc2: raise Cafe24FtpError( f"교체에 실패했고 원본 되돌리기도 실패했습니다. FTP 에서 {aside} 를 {path} 로 " f"직접 되돌리세요: {exc} / {exc2}", maybe_applied=True, ) from exc2 _delete_quiet(ftp, tmp) raise Cafe24FtpError(f"교체에 실패해 원본을 되돌렸습니다: {exc}") from exc moved_aside = True # 5) 확인 — 교체 뒤 원본 경로가 새 내용인가. try: final = _retr(ftp, path) except ftplib.all_errors as exc: raise Cafe24FtpError( f"교체 뒤 확인 조회에 실패했습니다 — 적용됐을 수 있으니 파일을 다시 열어 확인하세요: {exc}", maybe_applied=True, ) from exc if final != data: raise Cafe24FtpError( "교체 뒤 파일 내용이 보낸 것과 다릅니다 — 파일을 다시 열어 확인하세요.", maybe_applied=True ) if moved_aside: _delete_quiet(ftp, aside) finally: _close(ftp)