.. _workflow-base64:

Base64 Encode/Decode
=====================

- Base64 인코딩 방식을 사용하여 데이터를 인코딩하고 디코딩할 수 있습니다.
- 지원되는 기능은 다음과 같습니다:

    - **Base64 인코딩** : Base64 인코딩 방식을 사용하여 데이터를 인코딩합니다.
    - **Base64 디코딩** : Base64 인코딩 방식을 사용하여 데이터를 디코딩합니다.
    - **Base64 URL 인코딩** : Base64 URL 인코딩 방식을 사용하여 데이터를 인코딩합니다.
    - **Base64 URL 디코딩** : Base64 URL 인코딩 방식을 사용하여 데이터를 디코딩합니다.

표준 Base64 vs URL-safe Base64
-------------------------------

두 가지 유형의 Base64 인코딩을 사용할 수 있습니다:

**표준 Base64**
    - 사용 문자: ``A-Z``, ``a-z``, ``0-9``, ``+``, ``/``, ``=`` (패딩용)
    - 일반적인 데이터 저장 및 전송에 적합
    - 특수문자로 인해 URL에서 사용 시 문제가 발생할 수 있음

**URL-safe Base64**
    - 사용 문자: ``A-Z``, ``a-z``, ``0-9``, ``-``, ``_`` (패딩 없음)
    - 문자 치환: ``+`` → ``-``, ``/`` → ``_``, 패딩 ``=`` 제거
    - URL, JWT 토큰, 파일명에서 안전하게 사용 가능
    - 웹 애플리케이션 및 API 토큰에 권장

문자 매핑
----------

.. list-table:: Base64 문자 차이점
   :header-rows: 1
   :widths: 30 35 35

   * - 용도
     - 표준 Base64
     - URL-safe Base64
   * - 플러스 문자
     - ``+``
     - ``-``
   * - 슬래시 문자
     - ``/``
     - ``_``
   * - 패딩
     - ``=`` (포함)
     - (제거됨)
   * - 사용 사례
     - 일반 인코딩
     - URL, JWT, 파일명

다른 결과를 보여주는 예시
-------------------------

표준 Base64와 URL-safe Base64 인코딩이 다른 결과를 생성하는 예시입니다:

**예시 1: 특수문자**

.. code-block:: javascript

   입력: "Hello>World?"
   ${_base64.encode('Hello>World?')}      // 결과: SGVsbG8+V29ybGQ/
   ${_base64.urlEncode('Hello>World?')}   // 결과: SGVsbG8-V29ybGQ_

**예시 2: 패딩 차이**

.. code-block:: javascript

   입력: "Test+Data/Info"
   ${_base64.encode('Test+Data/Info')}      // 결과: VGVzdCtEYXRhL0luZm8=
   ${_base64.urlEncode('Test+Data/Info')}   // 결과: VGVzdCtEYXRhL0luZm8

**예시 3: 복합 특수문자**

.. code-block:: javascript

   입력: "Data??>><<++//=="
   ${_base64.encode('Data??>><<++//==')}      // 결과: RGF0YT8/Pj48PCsrLy89PQ==
   ${_base64.urlEncode('Data??>><<++//==')}   // 결과: RGF0YT8_Pj48PCsrLy89PQ

URL 사용 예시
-------------

**문제가 있는 경우: URL에서 표준 Base64 사용**

.. code-block:: text

   https://example.com/api?token=dXNlcjpwYXNzd29yZEBkb21haW4uY29tL3BhdGg/cXVlcnk9dmFsdWU=
   
   문제점:
   - '+' 문자가 URL에서 공백으로 해석됨
   - '/' 문자가 경로 구분자로 해석됨
   - '=' 문자가 파싱 문제를 일으킬 수 있음

**권장 방법: URL에서 URL-safe Base64 사용**

.. code-block:: text

   https://example.com/api?token=dXNlcjpwYXNzd29yZEBkb21haW4uY29tL3BhdGg_cXVlcnk9dmFsdWU
   
   장점:
   - URL 파라미터에서 안전함
   - 특수문자 충돌 없음
   - 패딩 없이 깔끔한 외관

기본 사용 예시
--------------

.. code-block:: javascript

   // 표준 Base64 인코딩/디코딩
   ${_base64.encode('안녕하세요! base64 테스트')}
   ${_base64.decode('7JWI64WV7ZWY7IS47JqUISBiYXNlNjQg7YWM7Iqk7Yq4')}
   
   // URL-safe Base64 인코딩/디코딩  
   ${_base64.urlEncode('안녕하세요! base64 테스트')}
   ${_base64.urlDecode('7JWI64WV7ZWY7IS47JqUISBiYXNlNjQg7YWM7Iqk7Yq4')}

언제 어떤 방법을 사용할지
-------------------------

**표준 Base64 (encode/decode)를 사용하는 경우:**
    - 데이터베이스에 데이터 저장
    - 일반적인 데이터 전송
    - 이메일 첨부파일
    - URL/파일명 제한이 없는 경우

**URL-safe Base64 (urlEncode/urlDecode)를 사용하는 경우:**
    - URL 파라미터로 데이터 전달
    - JWT 토큰 생성
    - 파일명 생성
    - API 인증 토큰
    - 모든 웹 기반 애플리케이션