rscc-common 0.2.0__py3-none-any.whl

rscc_common/__init__.py

@@ -0,0 +1,97 @@
+"""rscc-common — RSCC 공통 Python 라이브러리.
+
+기본 설치는 표준 라이브러리만 사용한다. 여기서 재노출하는 심볼은 모두 무의존 모듈의 것이다.
+`rscc_common.response` (pydantic 필요) 와 `rscc_common.handlers` (fastapi 필요) 는
+`rscc-common[fastapi]` extra 설치 후 서브모듈로 직접 임포트한다 — 패키지 임포트만으로
+pydantic/fastapi 를 요구하지 않기 위해 여기서 재노출하지 않는다.
+
+무의존 유틸 모듈(jwt/datetimes/masking/sse)은 서브모듈 네임스페이스로 재노출한다
+(`from rscc_common import jwt; jwt.decode_token(...)`). 함수가 많고 이름이 일반적이라
+플랫 재노출 대신 네임스페이스로 묶었다.
+"""
+
+from . import (
+    api_key,
+    bizno,
+    bulkhead,
+    cache,
+    circuit_breaker,
+    client_ip,
+    constant_time,
+    datetimes,
+    jwt,
+    log_sanitize,
+    masking,
+    metrics,
+    rate_limit,
+    retry,
+    sse,
+    validation,
+)
+from .access_log import install_access_log
+from .errors import CommonException, ResultCode
+from .logging import configure_logging
+from .rate_limit import install_rate_limit
+from .security_headers import install_security_headers
+from .trace import (
+    async_trace_request_hook,
+    get_trace_id,
+    install_trace_middleware,
+    new_trace_id,
+    reset_trace_id,
+    set_trace_id,
+    trace_request_hook,
+)
+from .user_context import (
+    UserContext,
+    async_user_context_request_hook,
+    get_user_context,
+    install_user_context_middleware,
+    reset_user_context,
+    set_user_context,
+    user_context_request_hook,
+)
+
+# 패키지 버전의 단일 소스 — pyproject.toml 은 dynamic version 으로 이 값을 읽는다.
+# 릴리스 절차: 이 값 수정 → py-vX.Y.Z 태그 push (pyproject 는 건드릴 것 없음).
+__version__ = "0.2.0"
+
+__all__ = [
+    "CommonException",
+    "ResultCode",
+    "UserContext",
+    "api_key",
+    "async_trace_request_hook",
+    "async_user_context_request_hook",
+    "bizno",
+    "bulkhead",
+    "cache",
+    "circuit_breaker",
+    "client_ip",
+    "configure_logging",
+    "constant_time",
+    "datetimes",
+    "get_trace_id",
+    "get_user_context",
+    "install_access_log",
+    "install_rate_limit",
+    "install_security_headers",
+    "install_trace_middleware",
+    "install_user_context_middleware",
+    "jwt",
+    "log_sanitize",
+    "masking",
+    "metrics",
+    "new_trace_id",
+    "rate_limit",
+    "reset_trace_id",
+    "reset_user_context",
+    "retry",
+    "set_trace_id",
+    "set_user_context",
+    "sse",
+    "trace_request_hook",
+    "user_context_request_hook",
+    "validation",
+    "__version__",
+]

rscc_common/access_log.py

@@ -0,0 +1,200 @@
+"""PII-세이프 액세스 로그 — 순수 ASGI 미들웨어. 표준 라이브러리만.
+
+Java ``com.rscc.common.web.AccessLogFilter`` 와 동일 계약(수동 동기화) —
+요청당 1라인 INFO 로그, 고정 포맷::
+
+    method=GET path=/v1/items status=200 durationMs=12 traceId=abc12345
+
+(+ 설정된 헤더마다 `` header.<설정표기>=<값>``)
+
+``slow_threshold_ms`` 활성 시(옵트인) 임계 이상(``>=``) 요청은 WARN 으로 승격되고
+traceId **직후·header 토큰 앞** 고정 위치에 `` slow=true`` additive 토큰이 붙는다 —
+Java ``AccessLogFilter`` 와 동일 규칙(수동 동기화).
+
+PII 안전 장치:
+
+- **query string 은 기본 미포함** — 검색어·토큰 등 PII 가 흔해 ``include_query_string``
+  옵트인으로만 포함한다.
+- **헤더 allowlist** — ``headers`` 로 지정한 헤더만 로깅하고, 그중 민감 고정 집합
+  (:data:`SENSITIVE_HEADERS`, 소문자 비교)은 :func:`~rscc_common.masking.mask_secret`
+  으로 마스킹 후 로깅한다.
+- **바디 로깅은 비범위** — SSE/스트리밍 응답 버퍼링과 충돌하고 PII 유입 위험이 커서
+  1차 범위에서 제외했다.
+
+미들웨어는 trace.py 와 동일한 순수 ASGI 관용구다 — fastapi/starlette 임포트가
+전혀 없어 기본 설치(무의존)에서 모듈 임포트가 깨지지 않는다.
+"""
+
+import asyncio
+import logging
+import time
+from collections.abc import Sequence
+
+from .masking import mask_secret
+from .trace import TRACE_HEADER, TRACE_ID_PATTERN, get_trace_id
+
+#: 값이 마스킹되는 민감 헤더 집합(소문자 비교) — Java ``AccessLogFilter.SENSITIVE_HEADERS`` 동일
+SENSITIVE_HEADERS = frozenset(
+    {"authorization", "cookie", "set-cookie", "proxy-authorization", "x-api-key"}
+)
+
+_TRACE_HEADER_LOWER = TRACE_HEADER.lower().encode("latin-1")
+
+
+class _AccessLogMiddleware:
+    """순수 ASGI 미들웨어 — 응답 완료(바디 송신 포함) 후 1라인 INFO 액세스 로그."""
+
+    def __init__(
+        self,
+        app,
+        *,
+        logger_name: str = "rscc_common.access",
+        headers: Sequence[str] = (),
+        include_query_string: bool = False,
+        slow_threshold_ms: int | None = None,
+    ) -> None:
+        if slow_threshold_ms is not None and slow_threshold_ms <= 0:
+            # 0 이하는 "비활성 의도인지 오타인지" 모호한 설정 오류 — fail-fast (비활성은 None)
+            raise ValueError(f"slow_threshold_ms 는 0 보다 커야 합니다: {slow_threshold_ms}")
+        self.app = app
+        self._logger = logging.getLogger(logger_name)
+        # (설정 표기, 소문자 비교용 바이트) 쌍 — 로그 키는 설정한 표기 그대로 쓴다
+        self._headers = [(h, h.lower().encode("latin-1")) for h in headers]
+        self._include_query_string = include_query_string
+        self._slow_threshold_ms = slow_threshold_ms
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        start = time.perf_counter()
+        captured_status: list[int | None] = [None]
+
+        async def send_with_capture(message) -> None:
+            if message["type"] == "http.response.start":
+                captured_status[0] = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_with_capture)
+        except asyncio.CancelledError:
+            # 태스크 취소(클라이언트 조기 이탈·서버 셧다운)는 오류가 아니다 — 응답이 이미
+            # 시작됐으면 실제 송신 상태로 남기고, 아니면 로깅 없이 재raise 한다
+            # (500 오류율 지표 오염 방지 — Java AccessLogFilter 는 취소 계열을 잡지 않는다)
+            if captured_status[0] is not None:
+                self._log(scope, captured_status[0], start)
+            raise
+        except BaseException:
+            # 미처리 예외 경로 — 응답 시작 후면 클라이언트가 실제 받은 상태를, 아니면 500 을
+            # 로깅하고 그대로 재raise (응답 송신은 바깥 계층 몫)
+            status = captured_status[0]
+            self._log(scope, status if status is not None else 500, start)
+            raise
+        status = captured_status[0]
+        self._log(scope, status if status is not None else 500, start)
+
+    def _resolve_trace_id(self, headers) -> str:
+        """traceId — contextvar 우선, 없으면 수신 X-Trace-Id 검증 폴백, 그래도 없으면 '-'.
+
+        폴백 덕에 trace 미들웨어보다 **바깥**에 등록돼(contextvar 가 이미 정리된 시점)도
+        수신 traceId 를 잃지 않는다 — 등록 순서 무관 동작 (install_access_log docstring).
+        """
+        trace_id = get_trace_id()
+        if trace_id is not None:
+            return trace_id
+        for key, value in headers:
+            if key.lower() == _TRACE_HEADER_LOWER:
+                candidate = value.decode("latin-1")
+                if TRACE_ID_PATTERN.fullmatch(candidate):
+                    return candidate
+                break
+        return "-"
+
+    def _log(self, scope, status: int, start: float) -> None:
+        duration_ms = int((time.perf_counter() - start) * 1000)
+        path = scope.get("path", "")
+        if self._include_query_string:
+            query = scope.get("query_string", b"")
+            if query:
+                path = path + "?" + query.decode("latin-1")
+        headers = scope.get("headers", [])
+        parts = [
+            f"method={scope.get('method', '-')}",
+            f"path={path}",
+            f"status={status}",
+            f"durationMs={duration_ms}",
+            f"traceId={self._resolve_trace_id(headers)}",
+        ]
+        # slow 판정(>=) — traceId 직후·header.* 앞 고정 위치 (계약 §4, Java 와 동일)
+        slow = self._slow_threshold_ms is not None and duration_ms >= self._slow_threshold_ms
+        if slow:
+            parts.append("slow=true")
+        for display, lower in self._headers:
+            value: str | None = None
+            for key, raw in headers:
+                if key.lower() == lower:
+                    value = raw.decode("latin-1")
+                    break
+            if value is None:
+                continue  # 미수신 헤더는 키 자체 생략
+            if display.lower() in SENSITIVE_HEADERS:
+                value = mask_secret(value)
+            parts.append(f"header.{display}={value}")
+        log = self._logger.warning if slow else self._logger.info
+        log("%s", " ".join(parts))
+
+
+def install_access_log(
+    app,
+    *,
+    logger_name: str = "rscc_common.access",
+    headers: Sequence[str] = (),
+    include_query_string: bool = False,
+    slow_threshold_ms: int | None = None,
+) -> None:
+    """FastAPI/Starlette 앱에 액세스 로그 미들웨어를 등록한다 (opt-in, 명시 호출형).
+
+    사용::
+
+        from fastapi import FastAPI
+        from rscc_common import install_access_log
+
+        app = FastAPI()
+        install_access_log(app, headers=["Authorization"])  # Authorization 은 마스킹 로깅
+
+    미들웨어 자체는 순수 ASGI 라 이 함수는 ``app.add_middleware`` 만 호출한다 —
+    fastapi 를 이 모듈이 임포트하지 않으므로 기본 설치에서도 임포트 안전.
+
+    trace 미들웨어와의 등록 순서는 **무관**하다 — Starlette 의 ``add_middleware`` 는
+    나중에 등록한 미들웨어가 더 바깥에서 실행되는데, 이 미들웨어가 trace 미들웨어보다
+    바깥이면 로깅 시점에 contextvar 가 이미 정리된 뒤라서 수신 ``X-Trace-Id`` 헤더를
+    :data:`~rscc_common.trace.TRACE_ID_PATTERN` 으로 검증해 폴백으로 쓴다
+    (신규 생성된 traceId 까지 남기려면 trace 미들웨어를 나중에 등록해 바깥에 둘 것).
+
+    durationMs 는 앱 호출 완료(응답 바디 송신 포함)까지의 정수 ms 다. 미처리 예외는
+    ``status=500`` (응답 시작 후면 실제 송신 상태) 으로 로깅 후 재raise 되고,
+    ``asyncio.CancelledError`` 는 오류로 취급하지 않는다 — 응답 시작 전이면 로깅 없이
+    재raise 된다(오류율 지표 오염 방지). 요청/응답 **바디 로깅은 비범위**
+    (모듈 docstring 참고).
+
+    :param logger_name: 로그를 남길 로거 이름. 기본 ``rscc_common.access``.
+    :param headers: 로깅할 요청 헤더 allowlist — 미지정(빈 목록)이면 헤더 미로깅.
+        민감 헤더(:data:`SENSITIVE_HEADERS`)는 값이 마스킹된다.
+    :param include_query_string: path 에 query string 포함 여부 (기본 False — PII 옵트인).
+    :param slow_threshold_ms: 이 값(ms) **이상**(``>=``) 걸린 요청을 WARN 으로 승격하고
+        traceId 직후에 ``slow=true`` 토큰을 붙인다. ``None`` = 비활성(기본).
+        0 이하 값은 설정 오류로 보고 즉시 ``ValueError`` (fail-fast — 비활성은 None 으로).
+        실패(예외) 경로는 슬로우 판정 없음 — 예외가 이미 시그널이다.
+    """
+    if slow_threshold_ms is not None and slow_threshold_ms <= 0:
+        # add_middleware 는 등록만 하고 인스턴스화는 첫 요청 시점이라, 여기서 먼저
+        # 검증해야 설정 오류가 install 호출 지점에서 바로 드러난다 (fail-fast)
+        raise ValueError(f"slow_threshold_ms 는 0 보다 커야 합니다: {slow_threshold_ms}")
+    app.add_middleware(
+        _AccessLogMiddleware,
+        logger_name=logger_name,
+        headers=headers,
+        include_query_string=include_query_string,
+        slow_threshold_ms=slow_threshold_ms,
+    )

rscc_common/api_key.py

@@ -0,0 +1,90 @@
+"""API 키 발급/검증 유틸 — ``contracts/api-key.md`` 형식 규약의 Python 구현.
+
+표준 라이브러리만 사용(``secrets``·``zlib.crc32``·``hashlib``). Java
+``com.rscc.common.crypto.ApiKeyUtils`` 와 수동 동기화(공유 골든 벡터 AK-01~08).
+
+형식 — ``rscc_<env>_<body><checksum>``, 총 48자 고정:
+
+- env: ``"live"`` | ``"test"`` — 고정 접두 ``rscc_live_``/``rscc_test_`` 는
+  시크릿 스캐너(GitHub secret scanning 등) 등록용.
+- body: base62 32자 — CSPRNG(:mod:`secrets`) 생성, 키의 비밀 엔트로피(약 190bit).
+- checksum: base62 6자 — 앞 42자 ASCII 의 CRC32(IEEE)를 base62 인코딩 후 좌측
+  '0' 패딩 (62^6 > 2^32 — 항상 6자 이내). 오탈자·잘림 검출과 스캐너 오탐 제거용이며
+  **보안 기능이 아니다** — 체크섬 통과 ≠ 유효한 키.
+
+검증 순서: :func:`is_well_formed` (형식) → :func:`checksum_ok` (무결성) →
+저장 해시 대조(인증). 앞 두 단계는 저장소 조회 전에 무자격 요청을 차단하는 게이트다.
+
+저장: 원문 저장 금지 — :func:`sha256_hex` 의 lowercase hex 64자를 저장하고,
+대조는 상수시간 비교(:func:`rscc_common.constant_time.compare_digest`)로 한다.
+키 원문은 발급 응답에서 1회만 노출하고 재조회 불가로 설계한다.
+
+인증 미들웨어, 키 회전·폐기 수명주기, 권한(scope) 모델은 비범위.
+"""
+
+import hashlib
+import re
+import secrets
+import zlib
+
+#: base62 알파벳 — 인덱스 0~61 고정(계약값, 순서 변경 금지)
+_BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+#: 형식 정규식 — 접두(live|test) + base62 38자(body 32 + checksum 6), 총 48자
+_KEY_PATTERN = re.compile(r"^rscc_(live|test)_[0-9A-Za-z]{38}$")
+_BODY_LENGTH = 32
+_CHECKSUM_LENGTH = 6
+#: 체크섬 계산 대상 프리픽스 길이 — ``rscc_<env>_``(10자) + body(32자)
+_CHECKSUM_INPUT_LENGTH = 42
+_ENVS = frozenset({"live", "test"})
+
+
+def issue(env: str) -> str:
+    """새 API 키를 발급한다 — CSPRNG 로 base62 32자 body 를 생성하고 체크섬을 부착한다.
+
+    :param env: 키 환경 — ``"live"`` | ``"test"``
+    :return: 48자 고정 키 (예: ``rscc_live_...``)
+    :raises ValueError: env 가 ``"live"``/``"test"`` 가 아닌 경우
+    """
+    if env not in _ENVS:
+        raise ValueError(f'env 는 "live" 또는 "test" 여야 합니다: {env!r}')
+    prefix = f"rscc_{env}_" + "".join(
+        secrets.choice(_BASE62_ALPHABET) for _ in range(_BODY_LENGTH)
+    )
+    return prefix + _checksum_of(prefix)
+
+
+def is_well_formed(key: str | None) -> bool:
+    """형식 검사 — 접두·길이(48자)·base62 문자 집합만 본다(체크섬 값 검증은
+    :func:`checksum_ok`). ``None`` 은 ``False`` — 예외 없음, 게이트 용도."""
+    return key is not None and _KEY_PATTERN.fullmatch(key) is not None
+
+
+def checksum_ok(key: str | None) -> bool:
+    """무결성 검사 — :func:`is_well_formed` 통과 후 CRC32 체크섬 재계산 일치 여부.
+
+    오타·잘림 검출용이며 인증 판정이 아니다(인증은 저장 해시 대조로만).
+    ``None``/형식 불일치는 ``False`` — 예외 없음.
+    """
+    if not is_well_formed(key):
+        return False
+    assert key is not None  # is_well_formed 통과 — 타입 내로잉
+    return _checksum_of(key[:_CHECKSUM_INPUT_LENGTH]) == key[_CHECKSUM_INPUT_LENGTH:]
+
+
+def sha256_hex(key: str) -> str:
+    """저장용 해시 — 키 전체 48자 ASCII 의 SHA-256 을 lowercase hex 64자로 반환한다.
+
+    원문 저장 금지 규약(``contracts/api-key.md``)의 저장 형식. 대조는
+    :func:`rscc_common.constant_time.compare_digest` 로 한다.
+    """
+    return hashlib.sha256(key.encode("ascii")).hexdigest()
+
+
+def _checksum_of(prefix42: str) -> str:
+    """앞 42자 ASCII 의 CRC32(IEEE, 부호 없는 32bit) → base62 → 6자 좌측 '0' 패딩."""
+    value = zlib.crc32(prefix42.encode("ascii"))  # zlib.crc32 는 항상 부호 없는 32bit
+    out = ""
+    while value:
+        value, rem = divmod(value, 62)
+        out = _BASE62_ALPHABET[rem] + out
+    return out.rjust(_CHECKSUM_LENGTH, "0")

rscc_common/bizno.py

@@ -0,0 +1,75 @@
+"""사업자등록번호·법인등록번호 체크섬 검증 — contracts 무관 내부 유틸.
+
+Java ``com.rscc.common.util.BusinessNumberUtils`` / JS ``@rscc/common-core`` 의
+``bizno.ts`` 와 1:1 로 맞춘 Python 대응(수동 동기화). **표준 라이브러리만** 사용한다.
+
+**체크섬만 검증한다** — 번호의 실존 여부(국세청 등록)·구분코드의 의미 검증은
+범위 밖이다. 형식·체크 디지트가 맞는 합성 번호도 유효로 판정된다.
+
+정규화 규칙: 하이픈(``-``)·스페이스(`` ``)·탭(``\\t``)만 제거한다(위치 불문).
+그 외 문자는 보존되어 검증 단계에서 걸러진다.
+
+주의: Python 정규식 ``\\d`` 는 전각 숫자(``１２３``)도 매칭하므로 반드시
+``[0-9]`` 를 쓴다 — 전각 숫자는 3언어 모두 무효 판정(파리티 규칙).
+"""
+
+import re
+
+# 정규화 제거 대상 — 하이픈·스페이스·탭만 (그 외 문자는 보존).
+_SEPARATORS = re.compile(r"[-\t ]")
+
+# ASCII 숫자만 — \d 금지(전각 숫자 매칭 사고 방지). 사업자 10자리 / 법인 13자리.
+_BUSINESS_DIGITS = re.compile(r"^[0-9]{10}$")
+_CORPORATE_DIGITS = re.compile(r"^[0-9]{13}$")
+
+# 사업자등록번호 가중치 — d0..d8 에 적용 (d8 은 추가로 ×5//10 보정).
+_BUSINESS_WEIGHTS = (1, 3, 7, 1, 3, 7, 1, 3, 5)
+# 법인등록번호 가중치 — 1,2 반복 12개, d0..d11 에 적용.
+_CORPORATE_WEIGHTS = (1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2)
+
+
+def normalize_business_number(value: str) -> str:
+    """하이픈·스페이스·탭을 제거한다 (예: ``"123-45-67891"`` → ``"1234567891"``).
+
+    그 외 문자는 보존한다 — 유효성 판정은 :func:`is_valid_business_number` /
+    :func:`is_valid_corporate_number` 의 몫.
+    """
+    return _SEPARATORS.sub("", value)
+
+
+def is_valid_business_number(value: str | None) -> bool:
+    """사업자등록번호(10자리) 체크섬 검증.
+
+    ``None`` / 정규화 후 ASCII 숫자 10자리가 아니면 False.
+    검증식(3언어 공유): d0..d9, 가중치 ``[1,3,7,1,3,7,1,3,5]``::
+
+        sum = Σ(i=0..8) dᵢ×wᵢ + (d₈×5)//10
+        check = (10 − sum%10) % 10   →   유효 ⟺ check == d₉
+    """
+    if value is None:
+        return False
+    digits = normalize_business_number(value)
+    if not _BUSINESS_DIGITS.fullmatch(digits):
+        return False
+    d = [int(c) for c in digits]
+    total = sum(d[i] * w for i, w in enumerate(_BUSINESS_WEIGHTS)) + (d[8] * 5) // 10
+    return (10 - total % 10) % 10 == d[9]
+
+
+def is_valid_corporate_number(value: str | None) -> bool:
+    """법인등록번호(13자리) 체크섬 검증.
+
+    ``None`` / 정규화 후 ASCII 숫자 13자리가 아니면 False.
+    검증식(3언어 공유): d0..d12, 가중치 ``1,2`` 반복 12개::
+
+        sum = Σ(i=0..11) dᵢ×wᵢ
+        check = (10 − sum%10) % 10   →   유효 ⟺ check == d₁₂
+    """
+    if value is None:
+        return False
+    digits = normalize_business_number(value)
+    if not _CORPORATE_DIGITS.fullmatch(digits):
+        return False
+    d = [int(c) for c in digits]
+    total = sum(d[i] * w for i, w in enumerate(_CORPORATE_WEIGHTS))
+    return (10 - total % 10) % 10 == d[12]

rscc_common/bulkhead.py

@@ -0,0 +1,133 @@
+"""동시성 제한 Bulkhead — 실행 슬롯 + 유한 대기 슬롯, 초과는 즉시 거부. 표준 라이브러리만.
+
+특정 다운스트림/작업의 동시 실행 수를 ``max_concurrent`` 로 격벽(bulkhead) 치고,
+``max_queue`` (기본 0) 만큼만 대기를 허용한다. 실행 여유 → 즉시 진입, 대기 여유 →
+슬롯 대기, 둘 다 만석 → 즉시 :class:`BulkheadFullError` (대기 없음 — 빠른 실패로
+부하 전파를 차단한다). 거부 시 보호 대상 코드 블록은 **실행되지 않는다** (BH-04).
+Java ``Bulkhead``(``BulkheadFullException``) / JS ``createBulkhead``(``BulkheadFullError``)
+와 시맨틱을 맞췄다 (수동 동기화 — 공유 벡터 BH-01~05).
+
+동기 :class:`Bulkhead` (``with``) 와 비동기 :class:`AsyncBulkhead` (``async with``)
+두 벌을 제공한다. 슬롯 해제는 ``__exit__``/``__aexit__`` 가 보장한다 — 블록이
+예외로 종료해도 반환된다 (BH-03).
+
+대기 순서: 동기 구현의 :class:`threading.Semaphore` 는 대기자를 깨우는 순서를
+**보장하지 않는다** (Java 는 fair Semaphore FIFO / JS 는 FIFO 큐 — Python 만
+순서 비보장, 공유 벡터는 순서 비의존 설계).
+"""
+
+import asyncio
+import threading
+
+
+class BulkheadFullError(Exception):
+    """실행·대기 슬롯 모두 만석 — 즉시 거부.
+    Java ``BulkheadFullException`` / JS ``BulkheadFullError`` 대칭."""
+
+
+def _validate(max_concurrent: int, max_queue: int) -> None:
+    if max_concurrent <= 0:
+        raise ValueError(f"max_concurrent 는 0 보다 커야 합니다: {max_concurrent!r}")
+    if max_queue < 0:
+        raise ValueError(f"max_queue 는 0 이상이어야 합니다: {max_queue!r}")
+
+
+class Bulkhead:
+    """동기 Bulkhead — ``threading.Semaphore`` + 대기 카운터.
+
+    사용::
+
+        bh = Bulkhead(max_concurrent=8, max_queue=16)
+        try:
+            with bh:
+                call()
+        except BulkheadFullError:
+            ...  # 즉시 거부 — 대기 없이 빠른 실패
+
+    :param max_concurrent: 동시 실행 슬롯 수 (필수 > 0).
+    :param max_queue: 대기 슬롯 수 (기본 0 — 대기 불허, >= 0).
+    """
+
+    def __init__(self, *, max_concurrent: int, max_queue: int = 0) -> None:
+        _validate(max_concurrent, max_queue)
+        self._sem = threading.Semaphore(max_concurrent)
+        self._max_queue = max_queue
+        self._lock = threading.Lock()
+        self._waiting = 0
+
+    def __enter__(self) -> "Bulkhead":
+        """슬롯 획득 — 실행 여유면 즉시, 대기 여유면 블로킹 대기, 만석이면 즉시
+        :class:`BulkheadFullError` (보호 블록 미실행)."""
+        if self._sem.acquire(blocking=False):
+            return self
+        with self._lock:
+            # 대기 슬롯 판정 — 임계 도달(>=)이면 즉시 거부 (BH-01/BH-02)
+            if self._waiting >= self._max_queue:
+                raise BulkheadFullError(
+                    f"동시 실행·대기 슬롯 만석 — 즉시 거부 "
+                    f"(max_concurrent 초과, max_queue={self._max_queue})"
+                )
+            self._waiting += 1
+        try:
+            self._sem.acquire()
+        finally:
+            with self._lock:
+                self._waiting -= 1
+        return self
+
+    def __exit__(self, *exc) -> None:
+        """슬롯 반환 — 블록이 예외로 종료해도 보장된다 (BH-03)."""
+        self._sem.release()
+
+
+class AsyncBulkhead:
+    """비동기 Bulkhead — ``asyncio.Semaphore`` + 대기 카운터.
+
+    **단일 이벤트 루프 전제** — 내부 상태를 락 없이 다루므로 여러 이벤트 루프/
+    스레드에서 같은 인스턴스를 공유하면 안 된다 (그 경우 :class:`Bulkhead` 를 쓸 것,
+    AsyncTtlCache 선례). 시맨틱은 :class:`Bulkhead` 와 동일하다.
+
+    사용::
+
+        bh = AsyncBulkhead(max_concurrent=8, max_queue=16)
+        try:
+            async with bh:
+                await call()
+        except BulkheadFullError:
+            ...
+
+    :param max_concurrent: 동시 실행 슬롯 수 (필수 > 0).
+    :param max_queue: 대기 슬롯 수 (기본 0 — 대기 불허, >= 0).
+    """
+
+    def __init__(self, *, max_concurrent: int, max_queue: int = 0) -> None:
+        _validate(max_concurrent, max_queue)
+        self._sem = asyncio.Semaphore(max_concurrent)
+        self._max_queue = max_queue
+        self._waiting = 0
+
+    async def __aenter__(self) -> "AsyncBulkhead":
+        """슬롯 획득 — :meth:`Bulkhead.__enter__` 의 비동기 버전.
+
+        ``locked()`` 판정과 대기 카운트 증가 사이에 await 가 없어 단일 루프에서
+        원자적이다 (여유 있을 때의 ``acquire()`` 도 내부 양보 없이 즉시 획득).
+        """
+        if self._sem.locked():
+            # 대기 슬롯 판정 — 임계 도달(>=)이면 즉시 거부 (BH-01/BH-02)
+            if self._waiting >= self._max_queue:
+                raise BulkheadFullError(
+                    f"동시 실행·대기 슬롯 만석 — 즉시 거부 "
+                    f"(max_concurrent 초과, max_queue={self._max_queue})"
+                )
+            self._waiting += 1
+            try:
+                await self._sem.acquire()
+            finally:
+                self._waiting -= 1
+        else:
+            await self._sem.acquire()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        """슬롯 반환 — 블록이 예외로 종료해도 보장된다 (BH-03)."""
+        self._sem.release()