adapter 가 경계선이야

"선 이쪽에선 Firelink 가 지시하고, 저쪽에선 형제가 실제로 일해. 그 선이 둘이 서로 번지지 않게 막는 자리야."

신전이 끝나고 불꽃이 시작되는 자리

첫 트랙의 규칙이 이거였지. Firelink 는 조율하되 형제 구현은 안 삼킨다. adapter 가 바로 그 선이야. Firelink 가 네이티브 앱을 뿌릴 때 서명이 어떻게 되는지는 몰라. 서명을 맡은 도구를 앞에 세운 deploy adapter 를 부를 뿐이지. repo 트리를 뿌릴 땐 canonical sync 도구를 앞세운 tree adapter 를 부르고. adapter 한쪽엔 Firelink 의 타입 있는 조율이, 다른 쪽엔 형제가 맡은 구현이 있고, 그 사이에 깔끔한 계약이 있어. 어느 쪽도 상대 안으로 손을 안 뻗게.

adapter 는 계약을 선언해

adapter 는 헐렁한 함수가 아니라 계약을 선언해. 안 바뀌는 id, 지원하는 권한, 실제로 돌릴 실행 파일, 멤버나 대상을 어떻게 연결할지, 어느 host 에서만 돌 수 있는지, 어느 peer 까지 허용인지, 미리보기가 되는지, 얼마나 기다릴지, 뭐랑 겹치면 안 되는지. 결과를 어떻게 읽고 제대로 됐는지 어떻게 확인할지까지. 그 계약이 있어서 Firelink 가 진짜 위험한 일을 안전하게 부를 수 있어. 뭐가 돌지, 어디서 돌아도 되는지, 얼마나 기다릴지, 됐는지 어떻게 확인할지를 다 알면서도 형제 로직은 안 베껴 오니까.

Web backend 만, office 에서만, plan 을 거쳐서만

부를 수 있는 경계가 빡빡해. Native Launcher 는 adapter 를 아예 못 불러. Web backend 만 부를 수 있고, 그것도 office 에서, 저장된 plan 을 거쳐야만 해. 그리고 안전장치가 여기저기 route 에 흩어진 검사로 있는 게 아니라 adapter 와 registry 안에 들어 있어. 엄마 Mac 은 deploy 대상이 아니고 Cinder 는 office 전용이라는 것도, registry 랑 adapter 의 계약으로 박혀 있지. 이음매를 한곳에 모은 보상이 이거야. '엄마 Mac 엔 절대 안 뿌린다' 같은 규칙을 열두 군데서 다시 확인하다 결국 어디선가 빠뜨리는 대신, adapter 계약에 한 번만 적어두는 거.

내 조율이랑 남의 구현 사이 경계를 adapter 하나에 몰아넣고, 안전 규칙도 거기 적어. 여기저기 흩뿌리지 말고. 손으로 짚을 수 있는 경계라야 감사도 할 수 있어. adapter 계약에 적힌 규칙은 그 adapter 를 쓰는 데면 어디서나 지켜지지만, 여러 route 에 복사한 규칙은 누가 처음 빠뜨리는 그 자리에서 무너져.

Code

adapter 계약: 경계 하나, 안전장치도 한 번만 선언·python

@dataclass(frozen=True)
class DeployAdapter:
    adapter_id: str                 # stable id, resolved from the registry
    capability: str                 # e.g. "deploy-native"
    executable: Path                # the sibling tool that owns the real work
    target_mapping: dict            # canonical member/target -> adapter args
    required_host_role: str = "office"   # invariant: runs only from office
    allowed_peers: frozenset = ...       # invariant: never yonsuk, never Cinder-fleet
    supports_dry_run: bool = True
    timeout_s: int = 600
    exclusivity: str = "per-target"
    # + result_parser and postcondition_verifier

# Only the WEB backend calls this, only from office, only via a persisted plan.
# The Native Launcher has no path to it. The 'never yonsuk' rule lives HERE,
# in the contract, not re-checked in twelve different routes that could drift.

Exercise

네 주변에서 한쪽이 시키고 다른 쪽이 실제로 일하는 두 시스템을 찾아봐. 결제 처리기를 부르는 앱이든, deploy 도구를 부르는 CI 든. 둘 사이에 이음매가 하나로 모여 있어, 아니면 부르는 쪽이 여기저기서 상대 속사정에 손을 뻗어? 안전 규칙을 하나 골라봐. 지출 한도든 환경 제한이든. 그리고 새로 부르는 자리가 생겨도 못 빠져나가게 하려면 그 규칙이 어디 있어야 할지 정해봐.

Hint

부르는 쪽이 상대 명령이나 인자를 두 군데 넘게 조립하고 있으면 이음매가 아니라 구멍이야. 고치는 법은 옮겨주기랑 안전장치를 함께 쥔 adapter 하나를 두는 거야. 그래야 모든 호출이 감사되는 같은 문으로 지나가.

신전이 끝나고 불꽃이 시작되는 자리

adapter 는 계약을 선언해

Web backend 만, office 에서만, plan 을 거쳐서만

Code

External links

Exercise

Progress

댓글 0