> Source: https://clickhouse.github.io/loom/ko/architecture/cells/ (Markdown: https://clickhouse.github.io/loom/ko/architecture/cells.md)

<!-- i18n: source=docs/architecture/cells.md blob=78e1d4c689a18b65208ce7c9b2d1a0593744a238 model=claude-sonnet-5-5 -->
> 이 페이지는 [영어 원문](https://clickhouse.github.io/loom/architecture/cells/)을 기계 번역한 것이며, 영어 원문이 기준입니다.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/cells/), which is authoritative.

<a id="cells"></a>

# 셀

배포의 메모리가 Postgres 프라이머리 하나와 ClickHouse 서비스 하나의 한계를 넘어설 수 있고, 조직이 자신만의 서비스에 메모리를 두기를 원할 수도 있습니다. **셀**(cell)은 이 문서가 설명하는 하나의 완전한 Loom 배포입니다. 셀은 자체 레플리카와 워커, Postgres 유닛 하나(프라이머리와 그 스탠바이), ClickHouse 서비스 하나, 문서 버킷 프리픽스 하나, 고유한 공개 호스트, 그리고 고유한 서명 키, 권한 부여(grant), 워커, 삭제(erasure) 기능을 가집니다. 배포의 공유 호스트에 있는 **라우터**(router)는 요청을 그 요청이 가리키는 대상을 가진 셀로 보냅니다. 조직은 정확히 하나의 셀에 속하며, 그 조직을 배치한 셀이고, 이후 다른 셀로 옮겨 가지 않습니다. 조직은 attach 시점(셀이 보유하던 조직과 셀에 구성된 조직), `loom cell update`(변경된 구성 조직) 또는 `loom cell place`, 혹은 해당 조직으로 범위가 지정된 principal의 첫 번째 검증된 요청에서 배치됩니다. 셀이 하나이고 라우터가 없는 배포는 단일 배포와 동일하게 동작합니다.

셀에는 Postgres authority(`LOOM_STORAGE_AUTHORITY=postgres`)와 모든 전송 방식에서 강제되는 인증(`auth_actually_required()`이며 `LOOM_MCP_AUTH_MODE`가 `open`이 아님)이 필요합니다. 이 조건이 없으면 `loom cell attach`가 거부되고, `LOOM_CELL`이 설정된 프로세스는 부팅을 거부합니다. [스토리지 authority](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md)는 셀이 무엇을 보유하며 두 저장소가 어떻게 일치하는지 설명합니다.

<a id="why-whole-deployments"></a>

## 배포 전체를 셀로 나누는 이유

셀은 다른 셀과 저장소, 키, 리스, 워커를 공유하지 않습니다. 단일 배포가 보장하는 모든 사항(테넌트 격리, 즉시 적용되는 폐기, 삭제 범위, 워커 리스, 감사 체인, 복원)은 셀 단위로 그대로 유지되며, 조직의 데이터, 권한 부여, 삭제는 여러 셀에 걸치지 않습니다. 라우터는 아래의 디렉터리와 라우팅 규칙을 추가하고, 각 셀은 요청이 가리키는 조직을 자신이 보유하고 있는지 확인하는 검사를 추가합니다.

여러 조직에 걸쳐 있던 항목은 셀 단위로 바뀝니다.

- 토큰은 발급한 셀에서만 유효하며 다른 셀에서는 유효하지 않습니다.
- 배포 전체에 적용되던 행은 셀마다 따로 존재합니다. 전역 블랙리스트(`org='*'`), 런타임 설정과 재정의, 정책 규칙, 속도 제한 및 예산 재정의, 서명 키 교체, 주체의 폐기가 해당합니다. `loom cell each -- <command>`는 조직이 필요 없는 관리 명령을 셀마다 발급한 단기 자격 증명으로 모든 셀에서 실행하고, 각 셀의 결과를 기록하며, 실패한 셀을 이어서 실행하고, 모든 셀이 성공할 때까지 실패로 처리합니다. `loom doctor`는 셀들의 설정과 구성 지문을 비교하여 서로 다른 부분을 알려 줍니다.
- 코드 조직과 트래커 조직(`LOOM_CODE_ORG`, `LOOM_TRACKER_ORG`)은 각 셀 고유의 것입니다. 각 셀은 자신의 리포지토리를 직접 인덱싱하며, 인제스트 비용도 셀마다 각각 발생합니다.
- 운영자의 플랫폼 보기와 대시보드는 셀 단위이며, 해당 셀의 호스트에서 제공됩니다.

<a id="the-router"></a>

## 라우터

라우터는 상태를 갖지 않는 HTTP 프록시입니다. 배포의 공유 호스트 뒤에서 여러 레플리카로 실행되고, 독립적으로 릴리스되며, 빌드 N-1과 N의 셀을 지원합니다. 라우터는 자체 Postgres 데이터베이스에 디렉터리를 보관합니다.

- `cells`: 셀, 공개 호스트, 셀만 수락하는 bearer 토큰 발급자(자체 `LOOM_JWT_ISSUER`, `LOOM_JWT_TRUSTED_ISSUERS`, 최종 사용자 발급자), 스토어(배포 id와 버킷 이름 및 프리픽스), 상태(`attaching`, `serving`), attach가 시작된 시각(`attach_started_at`. attach는 모든 거부 검사를 통과한 뒤 디렉터리 잠금 아래에서, 셀에서 프로브와 `--revoke-unprovisioned`의 폐기를 제외한 어떤 행이든 쓰기 전에 이 값을 기록하며, 재개된 attach가 이를 읽습니다), 테넌시 모드와 설정된 시각(prepare가 첫 값을 쓰고, attach가 올리거나 올리려 시도하는 값을 각각 기록합니다), 새 org에 대해 닫혀 있는지 여부와 배치 할당량(`placements_max`), 셀이 라우터를 호출할 때 쓰는 자격 증명의 SHA-256(`current`, 교체 중에는 `next`), 루트 시크릿 지문(`keys_fp`), `probe_url`(첫 셀의 경우 라우터 자체의 것), break-glass 봇의 이름과 키 지문, 구성 지문(`current`, 변경 중에는 `next`. "지속적으로 검사되는 항목"에 명시된 필드이며, attach와 `loom cell update`가 셀 자체의 지문 사본(`loom.cell_self`)과 함께 기록합니다)을 보관합니다.
- `placements`: org, 셀. org당 한 행이며, 한 번 기록되고 삭제되지 않습니다.
- `hosts`: 모든 셀의 호스트와 공유 호스트의 별칭(아래 참조).

라우터에는 디렉터리가 아니라 자체 구성에 설정된 별도의 운영자 자격 증명이 있습니다. 디렉터리에 대한 모든 운영자 변경은 이 자격 증명으로 수행되며, 배치를 포함한 모든 변경은 라우터의 감사 로그에 기록됩니다. 셀을 attach하려면 attach 대상 셀의 플랫폼 관리자 자격 증명도 필요합니다. 라우터는 어떤 셀과도 별개로 자체 liveness와 readiness를 보고합니다.

라우터는 기존 배포 앞에 먼저 놓이며 모든 요청을 그 배포로 전달합니다. 그 배포는 attach될 때 첫 번째 셀이 되고 공유 호스트를 자신의 호스트로 유지하므로, 클라이언트, 토큰, 리프레시 토큰, OAuth 클라이언트, 등록된 콜백이 계속 동작합니다. 라우터는 자신의 경로(`/cells/`, `/livez`, `/readyz`)에는 직접 응답하고, 그 외 모든 요청은 셀의 `/v1/health` 경로를 포함해 `attaching` 셀과 `serving` 셀 모두에 다음 순서로 라우팅합니다.

1. **호스트 기준.** 다른 셀 자신의 호스트로 온 요청은 그 셀로 갑니다. 공유 호스트와 `hosts`에 기록된 별칭은 라우터 자체 구성이며 규칙 2~4로 처리되고(규칙 4의 셀은 첫 셀이 등록되기 전과 후 모두 패스스루 업스트림입니다. prepare가 그 주소로 등록하기 때문입니다) 421로 응답하지 않습니다. `cells` 행이 지정하지 않은 다른 호스트는 421로 응답합니다. 셀이 내보내는 모든 URL은 자신의 호스트를 가리킵니다. OAuth 및 OIDC 엔드포인트, 디바이스 플로우의 verification URI, 로그인 콜백(`LOOM_OAUTH_ISSUER`, 셀마다 ID 공급자에 등록), JWKS, 대시보드의 페이지와 에셋, MCP 리소스 메타데이터가 그렇습니다. 첫 셀이 아닌 셀의 MCP 클라이언트는 그 셀의 호스트를 사용하며, 이는 셀의 setup 출력 줄에 표시됩니다.
2. **SCIM**은 규칙 1처럼 호스트 기준으로 갑니다. 각 셀의 ID 공급자 애플리케이션이 자기 호스트에서 프로비저닝합니다(아래 참조). 공유 호스트의 SCIM은 첫 셀의 것이지만, JWT를 담은 `/scim/v2/Groups` 요청은 규칙 3처럼 발급자 기준으로 갑니다. Groups 경로는 테넌시 검사를 받습니다(org의 `loom.principal_groups`에 기록하기 때문입니다).
3. **발급자 기준.** 공유 호스트로 온 토큰 포함 요청은 검증 없이 읽은 `iss` 클레임을 수락하는 단일 셀로 갑니다. 검증은 셀이 합니다. 어느 셀도 수락하지 않는 발급자는 401로 응답합니다. 첫 셀이 `serving`이 되기 전까지 규칙 2~4는 공유 호스트의 모든 요청을 규칙 4의 셀로 보내고 그 셀이 검증하므로, 라우터 뒤의 배포는 prepare, `LOOM_CELL` 롤아웃, attach 동안에도 자신이 보유한 org를 이전처럼 처리합니다. 롤아웃부터 `serving`까지는 새 org에 대해서도 `LOOM_CELL`이 설정된 모든 프로세스에서 디렉터리가 필요합니다(디렉터리를 읽을 수 없으면 503으로 응답합니다). 이는 본문이 어떤 org를 지정하든 MCP와 모든 op에 적용되며, 통합의 연합 발급자 및 최종 사용자 발급자 토큰에도 적용됩니다.
4. **공유 호스트의 나머지는 모두 첫 셀로 갑니다.** OAuth 및 디바이스 플로우, 리프레시, 콜백, 비밀번호 및 셀프 가입 요청, 헬스 프로브, 로그인 페이지가 해당합니다. JWT의 토큰 폐기(`/oauth/revoke`)는 규칙 3처럼 발급자 기준으로 가고, 불투명 리프레시 토큰의 폐기는 첫 셀로 갑니다. 공유 호스트를 쓰는 것은 첫 셀의 클라이언트뿐이기 때문입니다(`loom logout`은 로그인한 호스트에서 폐기합니다). 공유 호스트의 디스커버리 문서는 첫 셀의 것입니다.

라우터는 디렉터리 행에 기록된 `upstream_url`로 셀에 접근합니다. 이는 배포 네트워크 내부의 주소이며(첫 셀의 주소는 prepare가 기록하는 `LOOM_ROUTER_UPSTREAM_URL`이므로, 등록해도 어떤 경로도 바뀌지 않습니다. 이후 셀은 attach가 기록합니다), 라우터 자신을 가리키는 셀의 공개 호스트로는 접근하지 않습니다. 첫 셀이 등록되기 전에는 규칙 4의 셀이 라우터를 앞에 둔 그 배포(`LOOM_ROUTER_UPSTREAM_URL`)입니다. 공유 호스트는 `LOOM_ROUTER_SHARED_HOST`, 첫 셀 자신의 호스트, 그리고 그 셀의 `hosts` 별칭입니다. 라우터는 각 요청을 클라이언트가 보낸 그대로(원본 경로와 쿼리, 자신의 `Host`) 전달하되, 클라이언트의 주소, 스킴, 호스트에 대한 라우터 자신의 관점을 `X-Forwarded-For`, `-Proto`, `-Host`에 담아 클라이언트가 주장한 값을 대체합니다(따라서 각 셀은 라우터의 주소를 `LOOM_TRUSTED_PROXIES`에 나열해야 하며, 그렇지 않으면 로그인 제한에서 모든 클라이언트를 라우터로 간주하고 스킴을 라우터의 것으로 읽습니다). 한 연결을 설명하는 헤더(와 `Connection`이 지명한 헤더)는 제거하고, 응답의 모든 헤더 줄(두 번째 `Set-Cookie` 포함)을 유지하며, 양쪽 본문을 스트리밍하고(서버 전송 이벤트 스트림 포함), 셀에 접근할 수 없으면 502로 응답하며, `/cells/` 아래의 경로는 절대 전달하지 않습니다(라우터가 제공하지 않는 경로는 404로 응답합니다). 업스트림 주소가 없는 등록된 첫 셀은 다른 모든 셀과 마찬가지로 503으로 응답합니다. 라우터는 `LOOM_ROUTER_DIRECTORY_CACHE_S`마다 한 번 셀, 발급자, 호스트를 읽으며, 오래된 표는 그 뒤에서 다시 읽는 동안 마지막 표로 응답하므로, 멈추거나 읽을 수 없는 디렉터리가 어떤 요청도 지연시키지 않습니다. 첫 읽기 전에는 503으로 응답합니다. 두 셀이 나열한 발급자(attach가 거부합니다)는 어느 쪽으로도 라우팅되지 않습니다.

클라이언트는 `GET /cells/lookup?org=<org>`로 org의 셀을 찾습니다. 이 요청은 인증이 없고 속도 제한이 걸려 있습니다. 배치가 없는 org는 그곳에 배치된 org와 같은 본문으로 첫 셀을 응답합니다(배치된 org의 응답만 캐시되므로 타이밍과 장애로는 여전히 구별할 수 있습니다. org 이름은 비밀이 아닙니다). 어떤 셀도 등록되기 전에는 조회가 코드 `NO_CELL`과 함께 503으로 응답하고, 캐시되지 않은 org에 대해 디렉터리를 읽을 수 없으면 `BACKEND_UNAVAILABLE`과 함께 503으로 응답합니다. 클라이언트는 메시지가 아니라 코드를 기준으로 판단합니다. `NO_CELL`이거나 라우터가 없는 배포에서 404가 오면 `loom login --org`는 지정받은 호스트(규칙 4가 이전처럼 처리하는 공유 호스트, 또는 단일 배포)를 유지합니다. 429에서는 `Retry-After`만큼 기다렸다가 다시 묻되 최대 `--wait`(기본값 2분) 동안만 하고, 그 후에는 속도 제한 거부로 종료합니다. 그 밖의 응답에서는 라우터를 지목하며 거부하므로, org를 보유하지 않을 수 있는 셀에서 플로우가 시작되지 않습니다. org의 셀은 워크스페이스의 URL처럼 공개 정보입니다. 조회를 통해 첫 셀 밖에 org가 존재한다는 사실을 알 수 있습니다. `loom login --org`, 첫 셀의 로그인 페이지(먼저 org를 묻습니다), setup 출력 줄은 모든 OAuth, 디바이스, 로그인 플로우를 org의 셀 호스트에서 시작하므로 어떤 플로우도 셀을 넘나들지 않으며, 브라우저는 새 플로우의 시작점으로만 리디렉션됩니다.

`recording` 상태가 될 수 있는 것은 첫 셀뿐입니다. `first` 행이 `(false, …)`인 셀은 org 트리거, 모드 캐시, CLI에서 `enforced` 이외의 모든 모드를 `enforced`로 취급하므로, 이후 셀의 모드 행을 `recording`으로 설정해도 아무것도 기록되지 않습니다. `recording` 상태의 셀은 라우터 자격 증명으로 `GET /cells/v1/cells/<cell>`을 호출해 자신의 상태를 읽습니다. 이 호출은 디렉터리의 고유 인덱스가 첫 번째로 지목한 셀에 대해서만 응답되고, 자격 증명의 SHA-256이 디렉터리가 `<cell>`에 대해 기록한 해시 중 하나일 때만 수락되며, `LOOM_CELL_ROUTER_TIMEOUT_S`(기본값 5초, 배치 호출의 타임아웃) 안에 이루어져야 합니다. 거부되거나 실패하거나 늦은 응답은 읽을 수 없는 것으로 간주합니다.

디렉터리에 접근할 수 없으면 규칙 1~4는 라우터가 캐시한 셀로 라우팅하고, 캐시되지 않은 org의 조회와 배치는 503으로 응답합니다.

운영자 경로는 모두 라우터의 운영자 자격 증명으로 호출하며 `/cells/v1/operator/cells/<cell>` 아래에 있습니다. `limit`, `credential`, `register`(prepare의 것), 행 자체(`GET`. 다른 행의 이름을 지정할 수 있으며 attach가 거부 검사, 완료 검사, 재개를 위해 이를 읽습니다), 첫 셀의 attach(`attach/begin`, `attach/place`, `attach/enforced`, `attach/serving`, 이 순서대로), 그리고 `DELETE`입니다. `register`를 제외한 각 경로는 디렉터리에 없는 셀에 대해 코드 `NO_SUCH_CELL`과 함께 404로 응답하므로, 이 코드가 없는 404는 이전 빌드의 라우터 레플리카입니다. 읽기를 포함해 성공한 모든 호출은 감사 로그에 기록되며(아무것도 바꾸지 않는 등록 재실행은 기록하지 않습니다), 모든 호출은 고정된 개수의 구문을 실행하고 각 구문은 디렉터리의 구문 타임아웃(디렉터리 서버에서도 적용됨)으로 제한됩니다. 읽기와 제거에는 `loom cell`이 기다리는 파생된 한도가 적용됩니다. 모든 변경은 디렉터리 잠금을 잡은 뒤 셀의 행 잠금을 잡습니다(등록, 운영자 변경, 제거가 따르는 순서). 모든 라우터 레플리카는 첫 셀의 attach가 시작되기 전에 이 경로를 갖춘 빌드를 실행해야 합니다. 이전 빌드의 배치는 attach 배치와 충돌해 일시적인 503이 되고, 이전 빌드의 등록은 attach 도중 이후 셀을 추가할 수 있으며, 그러면 제거될 때까지 모든 attach 호출이 거부됩니다. 각 attach 호출은 행이 첫 셀의 행이고, 그 상태가 `attaching`이며, 호출이 지정한 배포 id를 행이 기록하고 있지 않으면 거부됩니다. 이 조건 중 하나라도 충족되지 않으면 각각 독립적으로 거부됩니다. 또한 다른 행이 존재하는 동안에도 거부됩니다(등록은 첫 셀이 `serving`이 될 때까지 이후 셀을 거부하지만, 이전 빌드의 라우터 레플리카는 여전히 하나를 등록할 수 있습니다).

- `attach/begin`은 `loom.cell_self`가 저장하는 그대로의 셀 지문, 루트 시크릿 지문, attach가 스토어를 판단한 허용 목록, 새로운 nonce를 담습니다. 배포 id, 버킷, 프리픽스, 공개 호스트, 발급자 호스트가 행과 다른 지문은 거부하며(셀 자신의 것이 아닌 발급자 호스트는 거부됩니다), org 이름이 가장 긴 경우의 실시간 배치 본문이 라우터의 본문 한도를 넘게 되는 지문도 가장 큰 필드를 지목하며 거부합니다. 디렉터리 트랜잭션 밖에서 행의 `probe_url`로 등록의 프로브를 실행하고 행의 `upstream_url`에 배포 id를 물어, attach가 읽는 스토어가 실제 셀이 사용하는 스토어와 같도록 합니다. 그런 다음 잠금 아래에서 `attach_started_at`을 한 번 기록하고, 지문은 행에 아직 없을 때만 기록하며(다른 지문이 있으면 409로 응답합니다. 지문은 `loom cell update`로 바뀝니다), `keys_fp`는 호출마다 기록하고, 허용 목록을 감사합니다. 멱등입니다. 본문에는 자체 한도 256 KiB가 있으며 이를 넘으면 413으로 응답합니다.
- `attach/place`는 `begin`이 실행되고 디렉터리 모드가 `enforced`가 된 뒤, 최대 500개 org의 배치를 처리합니다(64 KiB 본문 한도 이내). 이 attach 배치는 이미 존재하는 org를 대상으로 하므로 셀의 닫힘 표시와 할당량의 거부 대상에서 제외됩니다. 새 org에 대한 일반적인 실시간 배치만 이 닫힘 표시와 할당량의 적용을 받습니다. 고정된 개수의 구문을 실행합니다. 이미 배치된 org를 건너뛰는 배치 삽입 한 번, 다른 셀에 배치된 org가 있으면 배치를 거부하는(롤백되며 org를 지목함) 읽기 한 번, 카운트 한 번, 그리고 배치한 org마다 감사 행 하나와 호출에 대한 감사 행 하나입니다. 모드가 `enforced`가 되면 같은 org의 실시간 배치가 나란히 실행될 수 있으며, 둘 다 셀의 행 잠금을 잡고, 실시간 배치는 잠금을 잡은 뒤 승자를 다시 읽으며, 모든 삽입은 이미 배치된 org를 건너뛰고 자신이 쓴 것만 카운트하므로 org는 한 번만 배치되고 카운트됩니다.
- `attach/enforced`는 디렉터리 모드 `enforced`를 기록하며, 그 이후 첫 셀은 새 org를 실시간으로 배치합니다. 멱등입니다.
- `attach/serving`은 프로브와 업스트림 검사를 다시 실행한 뒤, 잠금 아래에서 행의 지문으로부터 행의 발급자(`current`와 `next`의 `bearer_issuers`)를 계산하고 셀을 `serving`으로 표시합니다. 이미 `serving`인 셀에는 즉시 응답하며 감사됩니다. `serving` 셀에 대한 `begin`, `place`, `enforced`는 409로 응답합니다.

`DELETE`는 배치가 없는 `attaching` 셀의 행을 디렉터리 모드와 관계없이 호스트 행과 함께 제거하며, 감사됩니다. 첫 셀은 첫 배치 전까지 되돌릴 수 있고, 이전 빌드가 등록한 이후 셀은 더 이상 첫 attach를 막지 않게 됩니다. 진행 중인 배치는 먼저 커밋되어 제거가 거부되거나, 행을 찾지 못합니다. 라우터는 셀의 스토어를 읽을 수 없으므로, 이를 호출하는 `loom cell remove`는 먼저 첫 셀의 Postgres를 확인합니다([운영](#operations)).

<a id="scim-and-sign-in-across-cells"></a>

## 셀 간 SCIM과 로그인

각 셀은 아이덴티티 제공자(identity provider)에서 독립된 애플리케이션입니다. 셀의 호스트에서 로그인에 쓰는 OIDC 클라이언트와 셀의 `/scim/v2`를 프로비저닝하는 SCIM 애플리케이션이 있으며, 둘 다 같은 사용자 그룹, 즉 그 셀 조직의 사용자에게 할당됩니다. 아이덴티티 제공자가 비활성화하거나 삭제하거나 할당을 해제한 사용자는, 그가 할당되어 있던 모든 셀에서 프로비저닝이 해제됩니다. Loom은 할당되지 않은 사용자를 허용하도록 설정되었거나 할당 해제 시 비활성화를 건너뛰도록 설정된 애플리케이션을 알아낼 수 없으므로, 운영자는 각 애플리케이션이 할당을 요구하고 할당 해제 시 비활성화하도록 구성해야 합니다. 각 셀은 SCIM 사용자, 비활성화, 툼스톤을 단일 배포와 똑같이 유지하며([SSO 및 SCIM](https://github.com/ClickHouse/loom/blob/main/docs/operations/sso.md)), 라우터는 아이덴티티를 보관하지 않습니다.

SCIM이 켜진 `enforced` 상태의 셀은 SCIM을 요구합니다. 사용자는 해당 셀의 SCIM에 활성 행이 있는 동안에만 그 셀에서 동작할 수 있습니다. 검사는 subject의 표기 방식이 아니라 사용자의 계정을 기준으로 합니다. `scim.refuses_subject(subject)`는 subject 자신의 이메일 표기들과, 그 subject가 소유한 활성 계정(비밀번호 계정 포함)의 연락처 이메일 및 검증된 이메일을 받아, 그중 하나라도 활성 행이 없으면 거부합니다. 활성 행이란 id가 `scim.user_id(email)`인 행이며, 해당 id의 비활성 또는 삭제된 행은 항상 거부합니다. 자체 행이 없는 이메일은 기본 이메일이 subject 자신의 표기 중 하나인 활성 행의 업무용 주소일 때만 통과합니다. SCIM 밖의 주체는 닫힌 목록 중 하나입니다. 봇(추가로 `:`가 있다면 그 앞까지의 `sa:<name>` 전체 접두사가 `loom.machine_identities` 행을 가리키는 subject로, 봇과 그 에이전트이며 `check_acted_for`가 파싱하는 방식입니다), 머신 또는 워크로드 subject, 최종 사용자(`user:`)입니다. 그 밖의 `sa:` subject, 즉 개인 서비스 계정은 생성자(`service_accounts.sa_creator`)와 해당 행의 `lineage`에 나열된 모든 subject를 통해 검사되므로, 그것을 대신해 동작하는 것은 그것을 만든 사람을 대신해 동작하는 것입니다. 이 경로의 다른 모든 subject는 사람으로 간주되며, 이메일 표기가 있거나 이메일이 있는 계정을 소유하지 않으면 거부됩니다. SCIM 읽기가 실패하면 `scim.deactivated`와 마찬가지로 `OAuthError`가 아니라 `SignInUnavailable`을 발생시키므로, 갱신 시 토큰이 되돌려지고 장애로 세션이 끝나지 않습니다. 사용자를 허용하는 모든 경로가 이 검사를 사용합니다.

- SSO 로그인: 계정을 찾거나 만들기(JIT) 전에, 아이덴티티 제공자가 검증한 이메일로 검사합니다.
- 세션의 모든 갱신(`_refresh_session`): grant에 저장된 검증된 이메일로 검사하고, 이메일이 없는 grant라면 subject의 계정으로 검사합니다.
- 사용자를 대신한 동작(`authz.check_acted_for`): subject의 표기와 무관하게 검사합니다.
- 게이트웨이 토큰의 subject: 검증 시 검사하며, 검증의 다른 응답과 마찬가지로 기억해 둡니다.
- 위임된 토큰 또는 개인 서비스 계정의 생성자(`authz._check_creator`): acted-for 검사와 같은 방식으로 캐시되므로, 프로비저닝된 적 없는 사람이 만든 토큰은 셀이 `enforced`가 되면 거부됩니다.

SCIM이 켜져 있으면 비밀번호 로그인과 자체 가입은 이미 닫혀 있으며(`oauth_login_provider=oidc`), 디바이스 플로우는 SSO로 로그인하므로 같은 검사를 거칩니다. 이메일이 없는 주체는 SCIM 밖에 있으며, 그것을 만든 쪽이 프로비저닝 해제를 맡습니다. 봇과 발급된 토큰은 운영자가, 최종 사용자 발급자의 사용자는 그들을 대신해 서명하는 서비스가, 워크로드 트러스트는 해당 규칙이 담당합니다.

**Break-glass.** 모든 셀에는 키 증명(key-proof) 방식의 플랫폼 관리자 봇(`loom bot create --platform-admin`)이 있습니다. 이 봇은 이메일이 없고 SCIM이 폐기하지 않습니다. attach와 `loom cell each`를 위한 별도의 두 번째 봇도 있습니다. 이들의 키는 운영자의 시크릿 저장소에 두고 사용할 때마다 읽으며, 디렉터리에는 각 봇의 이름과 키 지문만 기록되므로 라우터는 어떤 셀의 자격 증명도 보유하지 않습니다. break-glass 봇의 모든 사용은 셀의 감사 로그에 남고 `loom doctor`가 이름을 표시합니다. 운영자는 대시보드를 위해 모든 셀의 애플리케이션에 할당되며, 아이덴티티 제공자 애플리케이션이 고장 난 셀에는 해당 셀의 봇을 통해 접근합니다.

**셀의 SCIM 토큰은 구조상 그 셀의 것입니다.** 셀 이름은 `[a-z0-9-]{1,32}`와 일치합니다(`_` 불가, 정확히 비교하며, prepare, attach, 부팅 시 강제되고 디렉터리에서 고유합니다). `lsc_`로 시작하는 토큰은 셀을 지정하며 전체가 `lsc_[a-z0-9-]{1,32}_[0-9a-f]{32,}`와 일치해야 하고, 그렇지 않으면 모든 셀이 거부합니다. 해당 접두사가 없는 토큰만 셀을 지정하지 않습니다. `LOOM_CELL`이 설정된 경우 SCIM 토큰은 `lsc_<cell>_<secret>` 형식이며, `loom cell scim-token new --cell <name>`이 이를 만듭니다(오프라인에서 실행됩니다). `_`로 나눈 필드는 정확히 세 개이고, 가운데 필드는 `LOOM_CELL`과 같으며, 시크릿은 소문자 16진수 32자 이상(128비트)입니다.

`scim.tokens()` 옆의 파서 하나가 토큰의 셀 이름 또는 아무것도 반환하지 않으며, 호출자는 그 결과를 `LOOM_CELL` 및 셀의 `first` 행(아래 참고)과 비교합니다. `scim_settings_problem`은 둘 다 받으므로 부팅과 `loom doctor`가 하나의 함수를 통해 거부하며, `LOOM_CELL`이 설정되어 있으면 세 번째로 구성된 토큰을 거부합니다(두 개는 교체(rotation)를 위해 허용됩니다). 함수 `scim.authorized(presented)`가 두 SCIM 라우트(`_authorized`, `scim_groups._caller`)의 상수 시간 비교를 맡습니다. `LOOM_CELL`이 설정되지 않았으면 단일 배포처럼 구성된 토큰과 비교하며 아무것도 읽지 않습니다. 설정되어 있으면 파서가 `LOOM_CELL`에 대해 허용하는 토큰 및 `first` 행과 비교하며, 그 행을 아직 읽지 못했다면 `AuthUnavailable`처럼 예외를 발생시켜 라우트가 `Retry-After`와 함께 503으로 응답하고 아이덴티티 제공자가 재시도합니다.

- 다른 셀을 지정하는 SCIM 토큰이 있으면 프로세스가 부팅을 거부하며, `/scim/v2`는 그런 토큰에 401로 응답합니다.
- 이후에 추가된 셀은 셀을 지정하지 않는 토큰을 거부합니다. 공유 호스트를 유지하는 첫 번째 셀은 `first` 행이 `(true, LOOM_CELL)`인 동안에만 기존의 이름 없는 토큰도 허용하므로, 교체 없이 전환(cutover) 기간 동안 SCIM이 계속 동작합니다.
- 따라서 다른 셀의 설정에 복사된 토큰이나 잘못된 셀의 호스트를 가리키는 아이덴티티 제공자 애플리케이션은 안전하게 실패(fail closed)하며, 어떤 셀도 자신의 토큰을 다른 셀의 토큰과 비교하지 않습니다.

<a id="preparing-a-cell"></a>

## 셀 준비

`loom cell prepare`는 디렉터리에 셀을 등록하고, 셀의 프로세스가 읽는 행을 기록합니다. 테넌시 검사(아래)는 무엇을 기록하고 어떻게 재개하는지를 설명하며, 이 섹션은 prepare가 올바른 셀을 받았음을 어떻게 증명하는지를 설명합니다.

**어느 셀이 첫 번째인지**는 설정이 아니며 준비 순서도 아닙니다. prepare는 호스트가 라우터의 공유 호스트이고, 배포 id가 라우터의 pass-through 업스트림이 업스트림의 프로브 주소에서 보고하는 id와 같은 셀에만 첫 번째 자격을 부여합니다. 이 주소는 라우터 자체의 설정(`LOOM_ROUTER_UPSTREAM_PROBE_URL`)과 첫 번째 셀의 `probe_url`이며, prepare의 인자가 아닙니다. 라우터는 prepare와 재실행 때마다 그 주소를 읽고, 다른 배포 id를 보고하거나 id가 없는 응답은 거부합니다. 라우터는 pass-through 업스트림의 메인 포트(`LOOM_ROUTER_UPSTREAM_URL`, 등록 시 행에 복사됨)에도 질의하여 다른 배포 id를 보고하는 경우 거부하므로, 행이 두 배포를 가리키는 일은 없습니다. prepare는 첫 번째 셀이 등록되어 `serving` 상태가 될 때까지 디렉터리 락 아래에서 다른 모든 셀을 거부하므로, 첫 번째 셀이 연결되는 동안 이후의 셀이 나타나지 않습니다.

**저장소는 실제로 운영 중인 것이어야 합니다.** prepare는 무엇이든 기록하기 전에 임의의 nonce를 대상 Postgres, 대상 ClickHouse의 `loom._migration_lock`의 예약된 키, 그리고 대상 버킷 프리픽스 아래의 프로브 객체에 기록합니다. 셀의 프로브 라우트는 해당 요청에서 프라이머리에 대한 자체 연결로 읽은 각 값을 그대로 응답해야 합니다. 이후 nonce는 삭제되며, 그 행에는 메모리나 org가 없고 그렇게 분류됩니다. 같은 배포 id를 가진 복사본은 거부됩니다. prepare는 등록과 함께 세 개의 nonce를 라우터에 보내고(`POST /cells/v1/operator/cells/<cell>/register`, 운영자 자격 증명 사용), 라우터는 프로브 리스너를 직접 읽어서 리스너가 셀의 배포 id, 해당 nonce, 그리고 등록에 명시된 버킷과 프리픽스를 응답할 때에만 셀을 등록합니다(따라서 버킷을 명시하지 않은 등록은 버킷이 있는 셀로 통과할 수 없습니다). 라우터는 속도 제한을 넘은 리스너(429)를 `PROBE_BUSY`로, 도달할 수 없거나 저장소를 읽을 수 없는 리스너, 또는 아직 도달할 수 없는 첫 번째 셀의 업스트림 메인 포트를 `PROBE_UNREACHABLE`로 응답하며, 둘 다 503이고 prepare는 `--wait` 안에서 이를 기다립니다. 주소가 행의 주소와 다른 재실행은 프로브 전에 거부됩니다.

**프로브 라우트**인 `GET /v1/health/deployment`는 자격 증명이 필요 없으며 핑거프린트 게이트 밖에 있습니다.

- 메인 포트에서는 요청의 Host와 무관하게 각 프로세스가 부팅 시 검증하여 메모리에 보관한 배포 id만 응답합니다. 저장소를 읽지 않고 속도 제한도 없으므로, 메인 포트에 대한 폭주가 attach의 호스트 검사를 지연시키지 않습니다.
- prepare의 예약된 nonce 키 아래 값을 포함한 전체 응답은 별도의 프로브 리스너 포트(`LOOM_CELL_PROBE_PORT`, `0`이면 꺼짐. Postgres 권한과 인증이 켜져 있어야 하며 호스트의 모든 주소에 바인딩됨)에서만 제공됩니다. 즉 `cell-probe`라는 이름의 Postgres 행 `loom.cell_probe`와 KeeperMap 키, 그리고 객체 `<prefix>/_cell_probe`이며, 저장 위치인 버킷과 프리픽스도 함께 알려 줍니다. 이 값들은 비밀이 아닙니다. 리스너에서 프로세스당 고정 속도를 넘으면 429로 응답합니다.
- 셀의 프로브 주소(`probe_url`)만 리스너를 대상으로 합니다. 이는 어떤 인그레스도 노출하지 않고 라우터도 라우팅하지 않는 내부 주소이며, 배포는 이를 준비 여부와 관계없이 모든 살아 있는 프로세스로 보내므로, prepare와 attach는 게이트가 미준비 상태로 잡아 둔 프로세스에도 도달합니다.
- 차트의 프로브 리스너는 기본적으로 꺼져 있으며, 기존 배포에서도 첫 `loom cell prepare` 전에 켜야 합니다. 차트는 해당 포트에 미준비 주소를 게시하는 Service를 렌더링하며 NetworkPolicy는 변경하지 않습니다. 누가 포트에 접근할 수 있는지는 ClickHouse와 마찬가지로 운영자의 네트워크 정책에 달려 있습니다. `http` 포트만 허용하는 차트 자체 정책이 켜져 있다면, 운영자는 라우터의 파드(prepare의 등록은 라우터가 프로브함)와 CLI가 실행되는 곳에서 프로브 포트로의 접근을 허용하는 정책을 추가해야 하며(정책은 합산됨), 정책이 없으면 어떤 파드든 접근할 수 있습니다. 마찬가지로 셀에서 라우터의 배치 주소와 Postgres로 나가는 egress도 차트의 정책이 켜져 있다면 `networkPolicy.extraEgress`를 통해 운영자가 설정합니다.
- prepare는 라우터의 `PROBE_BUSY`와 `PROBE_UNREACHABLE`(시작 중인 리스너는 한동안 도달할 수 없음)을, attach와 `loom cell update --probe-url`은 자신이 프로브하는 리스너의 429를 최대 `--wait`(기본 10분) 동안 재시도한 뒤 이를 명시합니다.

이후 셀의 `probe_url`은 prepare에 주어지며, 정규화(`http` 또는 `https`, userinfo 없음)된 뒤 대상 저장소에서 prepare가 읽는 배포 id를 보고할 때에만 받아들여집니다. 이어서 attach는 셀 자신의 호스트가 같은 id를 보고하는지 확인합니다. prepare는 첫 번째 셀에 대한 프로브 주소 인자를 거부합니다. `loom cell update --probe-url`은 같은 검사와 새 nonce 에코 후 디렉터리 락 아래에서 이후 셀의 주소를 교체합니다. 첫 번째 셀의 프로브 주소와 업스트림 주소는 등록 시 라우터 설정에서 복사되며, `loom cell update`는 모든 라우터 레플리카가 새 값으로 실행된 후 같은 프로브와 새 업스트림이 셀의 배포 id를 보고하는지 확인한 뒤 설정에서 그 주소를 교체합니다. prepare 재실행은 주소를 옮기지 않으며, 접속한 라우터 레플리카가 다른 값으로 설정되어 있으면 거부합니다.

**`first` 행.** prepare는 모든 셀의 Postgres에 명시적이고 불변인 `first` 행을 기록합니다(`loom.cell_first`: 행 트리거가 update와 delete를, 문장 트리거가 truncate를 거부하며, 둘 다 `ENABLE ALWAYS`로 생성되고 org 트리거와 마찬가지로 attach와 `loom doctor`가 확인함). 첫 번째 셀은 `(true, <cell>)`, 그 외 셀은 `(false, <cell>)`이며, 테넌시 모드와 같은 트랜잭션에서 기록되므로 어느 한쪽만 존재하지 않습니다. 두 행을 함께 읽으면 네 가지 상태 중 하나가 됩니다. 둘 다 없고 테넌시 행이나 own 행도 없는 경우는 open으로, 단일 배포의 상태이며 검사가 없습니다. `LOOM_CELL`이 설정된 프로세스는 여기서 미준비 상태를 유지합니다(모드 행 없음). 디렉터리가 등록한 셀에서 이런 상태는 Postgres가 prepare 이전으로 복원된 경우(`loom cell restore`로 해소) 또는 prepare가 등록과 행 기록 사이에서 중단된 경우(prepare 재실행으로 해소)에만 발생하며, 그동안 트리거와 `LOOM_CELL`이 설정되지 않은 프로세스는 prepare된 적 없는 배포처럼 open 상태로 남습니다. 상태를 보관하는 셀의 Postgres는 두 경우를 구별할 수 없고(ClickHouse에는 셀 상태가 없으며, 추가하면 쓰기 경로가 테넌시를 위해 두 번째 저장소를 읽게 됨) 그런 프로세스는 디렉터리를 읽지 않기 때문입니다. 모든 프로세스에 `LOOM_CELL`이 설정되지 않은 곳에서는 `loom doctor`가 이를 지목하는 것(디렉터리를 읽으며 attach와 함께 제공됨)이 유일한 신호입니다. `(true, …)` 행에 `recording`과 own 행이 있으면 첫 번째 셀이 기록 중입니다. 둘 다 있고 own 행이 그 외의 경우이면 `enforced`이며, 이후 셀의 모드는 행의 내용과 관계없이 `enforced`로 읽힙니다(트리거, 모드 캐시, CLI가 그렇게 취급하며 `loom cell prepare`는 그렇지 않은 행을 지목함). 한쪽 행만 있거나, own 행 없이 둘 다 있거나, 테넌시 행이나 own 행 옆에 둘 다 없는 경우(`partial` 상태: `first`, 모드, own 행 중 일부 상태 행만 존재)는 prepare가 남기지 않는 상태이며, 셀에 org 트리거가 있다면 `enforced`처럼 동작하고(부팅은 여기에 트리거를 만들지 않음), 모든 프로세스는 읽지 않은 행처럼 게이트되고, `loom doctor`가 이를 지목하며, `loom cell prepare` 재실행은 셀이 실행 중인 동안 디렉터리에서 누락된 행을 다시 기록합니다. 디렉터리의 고유 인덱스는 첫 번째 셀을 하나만 허용하며, 값에는 메모리 내용이 없고 그렇게 분류됩니다. attach는 호스트와 배포 id를 다시 확인합니다. 프로세스는 이 값을 모드와 함께 읽으며, "아직 읽지 않음", "없음", "false"는 서로 구별됩니다. 읽은 행만이 프로세스를 준비 상태로 만들고, 셀이 `LOOM_CELL`과 다른 행은 프로세스를 게이트하며(아래) `scim_settings_problem`이 이를 보고합니다. 부팅은 설정만으로 거부합니다(행을 읽지 않은 상태의 `scim_settings_problem`은 토큰의 형식만 `LOOM_CELL`과 대조함). `first` 행과의 비교는 행을 읽은 후 요청마다 실행되며, `loom doctor`는 셀의 Postgres에서 이 값을 읽거나 알 수 없다고 보고합니다.

<a id="the-cells-own-row"></a>

## 셀 자체의 행

**attach 시점에만 확인하지 않고 지속적으로 확인합니다.** 각 프로세스는 자신의 구성 핑거프린트를 계산합니다. 핑거프린트는 스키마 버전 아래의 이름 붙은 필드로 이루어집니다(`LOOM_PUBLIC_BASE_URL`과 확정된 `LOOM_OAUTH_ISSUER`의 호스트, OIDC 발급자와 클라이언트 id, SCIM 사용 여부, 프로세스가 받아들이는 bearer 발급자(`trusted_issuers()`와 최종 사용자 발급자), 구성된 조직, `jwt_end_user_issuers_json`의 `orgs`, 부팅 시 확인한 배포 id, 버킷 이름과 프리픽스). 프로세스의 Postgres와 ClickHouse는 둘 다 배포 id를 가지고 있습니다(단일 배포가 이미 수행하는 짝 확인입니다). 버킷은 설정된 경우 이름과 프리픽스로 식별하며(버킷이 없는 셀은 버킷 확인에 참여하지 않습니다), 어떤 엔드포인트에서도 두 셀이 이를 공유하지 않습니다. 같은 이름의 버킷에서 한 셀의 프리픽스가 다른 셀의 프리픽스 안에 중첩되거나 그것을 포함하지 않으므로, 환경에서 가져온 엔드포인트가 다른 셀의 프리픽스에 도달할 수 없습니다. 어떤 저장소도 주소로 식별하지 않으므로, 스탠바이 교체, 페일오버, 환경에서 가져온 주소, 새 엔드포인트로의 복원은 셀이 확인하는 어떤 것도 바꾸지 않습니다. 배포 id, 버킷 이름, 프리픽스는 prepare 이후 바뀌지 않습니다. `loom cell update`는 이 중 어느 하나의 변경도 거부하며, 버킷 없이 준비된 셀에 버킷을 추가하는 것도 포함됩니다. 셀의 데이터를 다른 저장소로 옮기거나 저장소를 추가하는 일은 별도의 설계 대상입니다(운영). 봇은 여기에 포함되지 않습니다. `loom bot create`가 실행 중에 각각 하나의 조직으로 봇을 추가하며, 배치가 이미 봇의 범위를 제한합니다. `loom.cell_self`에 있는 셀 자체의 행은 승인된 핑거프린트 `current`를 가지며, 변경 중에는 두 번째 값 `next`도 가집니다. 이 행들과 셀 하트비트(`loom.cell_heartbeats`)는 메모리 콘텐츠를 담지 않으며 삭제 처리에서도 그렇게 분류됩니다. 하트비트는 프로세스의 `loom.instances` 행을 키로 하여 그 행과 함께 기록되는데, KeeperMap 테이블은 새 컬럼을 받지 않기 때문입니다. 하트비트에는 프로세스가 실행 중인 `LOOM_CELL`, 마지막 읽기가 만드는 상태, 핑거프린트, [그 옆의 키](#the-heartbeats-keys)가 들어 있습니다. 프로세스는 두 값이 모두 아는 모든 필드가 같을 때 해당 값과 일치한다고 봅니다. 값에 없는 필드는 기본값일 때에만 같은 것으로 취급하므로, 같은 구성을 가진 빌드 N과 N+1은 하나의 행과 일치합니다. `LOOM_CELL`이 설정된 상태에서 셀 자체의 행, `first` 행 또는 모드 행을 아직 읽지 못했거나, 상태 행이 `partial` 상태이거나(위의 `first` 행 규칙), 셀 자체의 행이 없거나 어느 값과도 일치하지 않거나, `first` 행이 다른 셀을 가리키면, 프로세스는 헬스 프로브와 프로브 라우트를 제외한 모든 요청에 503 `AuthUnavailable`로 응답합니다. 대상은 bearer 요청(`verify_token`의 첫 번째 확인으로, 최종 사용자 발급자 분기보다 앞서 수행됨), SCIM, 그리고 토큰을 로그인, 발급, 갱신 또는 교환하는 모든 라우트이며, 가입, OAuth 및 디바이스 엔드포인트, 로그인 콜백도 포함됩니다. 또한 스스로 준비되지 않았다고 보고하며, 드리프트된 프로세스처럼 워커에서 물러납니다. 즉 패스를 중단하고, 리스를 반납하며, 인스턴스 행에 어떤 리스도 기록하지 않습니다. 이는 모든 `LOOM_BACKGROUND_WORKERS` 모드에서 동일합니다(`on`도 포함됩니다. 유지할 리스가 없으므로, 셀의 `on` 프로세스는 리스 루프를 실행하고, 이 루프가 `LOOM_TENANCY_MODE_CACHE_S`와 루프 주기 한 번 이내에 게이트에 따라 슈퍼바이저를 시작하고 중지합니다). 인스턴스 행은 이 프로세스를 서빙 중으로 세지 않으므로, 옆에 있는 이전 빌드가 워커를 계속 실행합니다. 읽기에 실패하면 마지막 행을 최대 `LOOM_JWT_REVOCATION_MAX_STALE_SECONDS` 동안 유지하며, 이는 서명 키링과 폐기 스냅샷의 방식과 같습니다. 이 시간이 지나면 읽기가 성공할 때까지 프로세스는 게이트됩니다. 모드(아래)도 같은 제한을 따릅니다. 따라서 다른 셀의 발급자, 연결되지 않은 호스트 또는 부여되지 않은 조직 패턴을 받아들이도록 구성된 셀은, 요청이 어디로 도달하든 그 구성으로는 아무것도 서빙하지 않습니다. 하트비트는 핑거프린트를 보고하고, 라우터는 필드가 디렉터리 행의 두 값 중 어느 것과도 일치하지 않는 배치 호출을 거부하며, `loom doctor`는 불일치, 다른 셀과 OIDC 클라이언트를 공유하는 셀, SCIM이 꺼진 셀이 SCIM이 켜진 셀들과 함께 있는 경우를 알려 줍니다.

`loom cell prepare`는 `first` 행 및 모드 행과 함께 `current`를 `loom.cell_self`에 기록합니다. 디렉터리 행에 핑거프린트가 생기기 전(attach 이전)에는, 셀 자체의 행이 없을 때 모든 라이브 프로세스가 하트비트로 보고하는 핑거프린트를 기록합니다. 이때 핑거프린트를 보고하지 않는 N 이전 빌드를 실행하는 라이브 프로세스가 있거나 보고된 핑거프린트들이 서로 다르면 거부합니다. 이미 있는 셀 자체의 행은 그대로 유지되며, `current`도 `next`도 아닌 값을 가진 라이브 프로세스가 있으면 거부합니다. 매 실행마다 등록하기 전에, 배포 id, 버킷 이름 또는 프리픽스가 prepare 자신의 구성과 다른 라이브 프로세스가 있으면 거부합니다(보고하지 않는 필드는 기본값으로 읽습니다). 디렉터리 행에 핑거프린트가 생기면, 재실행은 `loom cell restore`처럼 그 값에서 `current`와 `next`를 기록하며, 라이브 프로세스의 핑거프린트가 둘 중 어느 것과도 일치하지 않을 때에만 거부합니다. 어느 경우든 `LOOM_CELL` 롤아웃 동안 셀은 준비된 상태를 유지합니다. 셀이 `attaching` 또는 `serving` 상태인 동안의 이후 구성 변경은 `loom cell update`를 거칩니다. attach가 셀의 핑거프린트를 디렉터리 행에 기록하기 전에는 `next`를 `loom.cell_self`에만 기록하고 아무것도 예약하지 않으며(이때 `--finish`와 `--revert`도 `loom.cell_self`만 건드립니다), 재개된 attach는 `loom.cell_self`의 두 값 모두에 대해 겹침 거부를 실행하고 디렉터리에 기록합니다. 준비된 셀의 발급자와 조직 패턴은 어디에도 예약되지 않습니다. attach가 겹침 거부를 실행하고 디렉터리 행을 기록하기 전까지, 라우터는 어떤 발급자도 그 셀로 라우팅하지 않고 그 셀에서 배치를 받지도 않습니다.

셀이 받아들이는 대상의 변경은 attach와 같은 디렉터리 락 아래에서 `loom cell update --config <file>`로 수행합니다. 이 명령은 프로세스가 사용하는 것과 같은 함수로 해당 구성에서 `next`를 계산하며, 다른 `next`가 보류 중이면 거부합니다. 같은 구성으로 다시 실행하거나 `--finish`를 실행하면 먼저 `next`가 없는 곳에 이를 기록합니다. 이 명령은 다른 모든 셀의 디렉터리 행에 대해 각 행의 두 값을 모두 세어 attach의 겹침 거부를 다시 실행하고, 새 핑거프린트를 디렉터리에 `next`로 기록한 다음 `loom.cell_self`에 기록하므로, 새 구성이 롤아웃되는 동안 이전 프로세스와 새 프로세스가 모두 서빙합니다. `loom cell update --finish`는 최대 `--wait`(기본값 10분) 동안, 모든 라이브 프로세스가 `next`를 보고하고 가장 긴 요청 데드라인이 지날 때까지 기다립니다. 변경이 SCIM을 켜거나 셀의 OIDC 클라이언트를 바꾸는 경우에는 attach의 SCIM 사전 조건을 실행합니다(거부하거나 `--revoke-unprovisioned`를 사용). 그 후에야 `next`를 유일한 값으로 만들며, `loom.cell_self`가 먼저, 디렉터리가 마지막입니다. 넓어진 발급자나 패턴은 어떤 프로세스가 받아들이기 전에 디렉터리에 예약되고, 좁아진 것은 어떤 프로세스도 받아들이지 않게 된 후에만 해제됩니다. 거부되거나 대기 시간이 초과되면 두 값을 모두 유지하고 아직 `next`를 보고하지 않은 프로세스를 출력합니다. 다시 실행하면 이어서 진행되며, `loom cell update --revert`는 `next`에만 일치하는 라이브 프로세스가 없어질 때까지 같은 방식으로 기다린 뒤(`--wait`가 소진되면 거부), 같은 락 아래에서 `loom.cell_self`가 먼저가 되도록 `next`를 제거합니다. 업데이트가 배치한 구성된 조직은 그 셀에 배치된 채로 남습니다(배치는 삭제되지 않습니다).

새 SCIM 토큰은 어떤 핑거프린트도 바꾸지 않으며 `loom cell update`가 필요하지 않습니다. 셀은 단일 배포와 동일하게, 같은 제한 아래에서 자신의 ID 공급자 애플리케이션을 변경합니다([SSO와
SCIM](https://github.com/ClickHouse/loom/blob/main/docs/operations/sso.md)). 여기에는 셀에 특유한 사항이 없습니다.

<a id="the-heartbeats-keys"></a>

### 하트비트의 키

프로세스의 셀 하트비트는 실행 중인 `LOOM_CELL` 옆에 테넌시 모드를 보고합니다. 이는 상태 행의 마지막 읽기가 만드는 상태(`open`, `recording`, `enforced` 또는 `partial`이며, 이후 셀의 `recording`은 `enforced`로 읽음)이고, 읽기가 성공하기 전이거나 상태 행을 읽지 않는 프로세스에서만 `''`입니다. `fingerprint` JSON은 핑거프린트의 버전과 필드를 담고, 그 옆에 어떤 핑거프린트도 비교하지 않는 키를 담습니다. 이 키들은 `loom.cell_self`, 디렉터리의 핑거프린트, 배치 본문에 나타나지 않으며, KeeperMap 행에는 이를 위한 컬럼이 필요하지 않습니다(`server.core.instances.cell_row`). 이 키가 있다는 것은 그것을 보고하는 빌드임을 증명하며, 세대 키는 없습니다.

- `serves`: `LOOM_SERVES_TRAFFIC`.
- `marked`: 이 프로세스의 풀링된 Postgres 세션이 테넌시 마커(`loom.tenancy_checked`)를 유지하는지 여부. 셀 갱신은 같은 트랜잭션에서 `RESET ALL` 이후 상태 행과 함께 이를 읽습니다. 시작 값은 리셋 후에도 남지만 `SET`은 남지 않으므로, 셀에 있어서는 안 되는 풀러([Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md))는 시작 파라미터를 제거하든 `SET`으로 다시 보내든 마커가 없는 것으로 읽히고, 이 읽기는 리셋이 실행된 서버 연결에서 수행됩니다. 갱신마다 왕복이 세 번(`BEGIN`, `RESET ALL`, `COMMIT`) 더 들며, 모든 프로세스가 프로버 없이 새 값을 보고합니다. 풀러가 제거한 세션이나, Postgres 권한 하에서 `LOOM_CELL`이 설정되지 않은 프로세스는 `false`로 읽힙니다. `null`은 아직 읽기가 성공하지 않았음을 뜻할 뿐입니다(Postgres 마이그레이션을 건너뛰고 부팅했는데 첫 읽기가 실패한 경우, 또는 아무것도 읽지 않는 ClickHouse 권한). `LOOM_CELL`이 설정된 프로세스의 `cell_marker` 준비 상태 확인은 같은 값을 읽습니다. `enforced`와 `partial`에서는 실패하는데, 이 상태에서 트리거가 마커 없는 세션이 셀이 보유하지 않은 조직에 쓰는 것과 새로 배치된 각 조직의 테넌시 행을 거부하기 때문입니다. `recording`에서는 경고와 함께 통과하므로, 그런 풀러 뒤의 첫 셀은 프로세스를 거부하는 attach 이전에 롤아웃이 멈추지 않습니다([문제 해결](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#the-cell_marker-readiness-check-names-the-tenancy-marker)).
- `router`와 `router_why`: `LOOM_CELL`이 설정된 경우, `first` 행을 읽기 전에는 `router`가 `null`이고 `router_why`가 그 이유를 알려 주며, 이후에는 첫 셀에서만 둘 다 존재합니다(이후 셀의 상태 라우트는 404로 응답하므로 요청도 보고도 하지 않습니다). `router`는 이 프로세스가 자신의 자격 증명으로 마지막에 읽은 `GET /cells/v1/cells/<cell>`이 그 셀을 지명하며 200으로 응답했는지 여부입니다. 첫 응답이 올 때까지(아직 부팅 중)는 `null`이고, 그런 응답이면 `true`이며, 결코 동작하지 않는 구성에서는 `false`입니다. 해당 구성은 설정되지 않은 라우터 설정(프로세스가 요청하지 않음), 요청할 수 없는 URL, 404, 다른 셀에 대한 응답, 또는 `LOOM_ROUTER_DIRECTORY_CACHE_S` 한 번 이상 지속되는 401입니다. 이는 라우터의 설정이며 셀의 프로세스도 이를 가지고 있습니다. 라우터 레플리카의 캐시된 자격 증명 해시는 방금 교체된 토큰에 401로 응답하므로, 그때까지는 마지막 값이 유지되고 `router_why`에는 "401, possibly a rotation"이라고 표시됩니다(더 긴 캐시로 실행한 라우터는 교체 중에 attach가 거부되게 할 수 있으며, 다시 실행하면 해소됩니다). 일시적 실패(타임아웃, 연결 오류, 503, 그 셀을 지명하는 JSON 객체가 아닌 200)는 마지막 값을 유지하며, `router`가 `null`인 동안 `router_why`는 마지막 그런 원인을 알려 줍니다.

서버 프로세스마다 하나의 백그라운드 리더가, 첫 셀에서 `serving`을 읽을 때까지 `min(LOOM_INSTANCE_HEARTBEAT_SECONDS, LOOM_TENANCY_MODE_CACHE_S)`마다 이 라우트에 요청합니다(`server/core/cell_router.py`). 어떤 것도 이를 기다리지 않으므로 느린 라우터가 비트나 요청을 지연시키지 않으며, 비트는 마지막으로 읽은 값을 보고합니다. 비트가 이를 기록할 때 그 값은 최대 한 주기에 `LOOM_CELL_ROUTER_TIMEOUT_S`를 더한 만큼 오래된 것입니다. 모든 uvicorn 프로세스가 리더를 하나씩 실행하므로, 워커가 8개인 파드 천 개는 초당 최대 1,600번 요청합니다. 각 라우터 레플리카는 셀 행을 `LOOM_ROUTER_DIRECTORY_CACHE_S`마다 최대 한 번 읽은 자기 결과로 이 라우트에 응답하므로, 디렉터리는 윈도마다 레플리카당 한 번의 읽기를 봅니다. 읽기에 실패하면 그 윈도 동안 503으로 응답하므로, 디렉터리가 내려가도 더 자주 요청받지 않으며 여전히 503으로 응답합니다. 하트비트가 없는 프로세스(CLI, 워커 자식 프로세스)는 대신 필요할 때 요청하며, `LOOM_TENANCY_MODE_CACHE_S`마다 최대 한 번입니다.

리더는 디렉터리의 마지막 응답을 테넌시 확인용으로도 보관하며, 네 가지 중 하나입니다. `attaching`, `serving`, 다른 상태, 또는 알 수 없음이며, 알 수 없음은 아직 읽기가 성공하지 않았거나, 마지막 읽기가 실패했거나, 이 셀의 어떤 상태에도 해당하지 않는 응답(401, 404 또는 다른 셀에 대한 응답)이었거나, 늦은 경우(이 프로세스가 읽는 주기, 즉 백그라운드 리더 또는 온디맨드 윈도에 `LOOM_CELL_ROUTER_TIMEOUT_S`를 더한 것보다 오래됨)입니다. 프로세스가 한 번 `serving`을 읽으면 평생 그 값을 유지하고 더 이상 요청하지 않습니다. 이를 낮추는 것은 `loom cell restore`뿐이며, 이 명령은 프로세스를 재시작합니다. `recording` 상태의 첫 셀은 `attaching`일 때에만 새 조직을 기록합니다. 플랫폼 또는 `*` 조직 주체나 주체가 없는 호출은 어떤 조직도 배치하지 않습니다. 디렉터리가 `attaching`으로 응답하거나 `serving`을 읽기 전에 읽을 수 없는 첫 셀에서는, 셀이 보유하지 않은 조직에 대한 그런 호출이 503("attach in progress" 또는 디렉터리를 읽을 수 없음)으로 응답합니다. attach가 조직을 배치하기 전까지는 조직의 데이터가 이 셀에 있을 수 있기 때문입니다. `serving`이 된 후와 이후 셀에서는 409 `WRONG_CELL`로 응답합니다. `serving` 이후에 부팅하는 프로세스는 라우터가 내려가 있으면 첫 읽기가 성공할 때까지 그런 호출에 503으로 응답합니다.

`LOOM_CELL`이 설정된 상태에서, http(s) URL이 아니거나 호스트가 없거나 포트가 65535를 초과하거나 `?` 또는 `#`을 포함하는 비어 있지 않은 `LOOM_CELL_ROUTER_URL`은 부팅을 거부합니다(`cell.settings_problem`). 빈 값은 워커 전용 파드(`LOOM_SERVES_TRAFFIC=false`)에서 허용되며, 이 경우 하트비트는 `router`를 `false`로 보고하고 `router_why`에 설정되지 않은 항목을 담으며 아무것도 로깅하지 않습니다.

<a id="the-tenancy-check-and-placement"></a>

## 테넌시 검사와 배치

`LOOM_CELL`이 설정되지 않은 프로세스는 테넌시 검사를 실행하지 않습니다. Postgres authority(`LOOM_STORAGE_AUTHORITY=postgres`, 셀이 실행하는 유일한 authority) 아래에서 서버 프로세스는 여전히 모드 행, `first` 행, 그리고 `loom.tenancy` 또는 `loom.cell_self` 행이 하나라도 있는지를 모드 캐시의 규칙(아래)에 따라 한 번의 문장으로 읽습니다. org를 선언하는 CLI 명령은 자체의 제한된 세션에서 같은 내용을 읽습니다. 상태 테이블이 모두 없으면(`to_regclass`로 판단하므로 권한이 빠진 역할은 여전히 거부됨) `open`으로 읽고, 읽기에 실패하면 거부합니다. 토큰 폐기, `loom migrate`, `loom doctor`처럼 org가 없는 명령은 모드의 제어를 받지 않으며, Postgres 장애 중에도 실행됩니다. 두 행이 모두 없고 테넌시 행이나 자체 행도 없는 경우(준비된 적 없는 배포나 `recording` 상태의 첫 셀), 프로세스는 단일 배포로 계속 서비스합니다. `first` 행의 규칙(위)이 `enforced`로 세는 모든 상태와 `partial` 상태는 `enforced`와 마찬가지로 프로세스를 제어합니다. `enforced`(첫 셀에서는 모든 라이브 프로세스에 `LOOM_CELL`이 설정된 뒤 attach가, 이후 셀에서는 첫 부팅부터 그것으로 실행되는 프로세스를 두고 prepare가 설정함)는 서버 프로세스를 준비되지 않은 상태로 만들고, 워커를 실행하지 않으며, 상태 프로브와 프로브 경로(prepare를 다시 실행해도 도달할 수 있도록) 외에는 아무것도 응답하지 않게 하고, CLI 명령은 거부하게 합니다. 준비 상태 사유와 거부 메시지에는 `LOOM_CELL`이 명시됩니다. 따라서 `enforced` 셀에서 `LOOM_CELL`을 잃은 파드나 운영자의 CLI는 어떤 org에도 쓰지 않습니다. `LOOM_PG_DSN`이나 `LOOM_STORAGE_AUTHORITY`까지 잃은 경우에는 배포가 이미 실행하는 authority 검사(ClickHouse의 `loom.storage_authority` 레코드)에 의해 거부됩니다. 셀의 스토어에 연결하는 `loom cell` 명령(prepare, attach, place, restore, update)은 `LOOM_CELL` 없이는 거부하며, 디렉터리에 `LOOM_CELL`에 대한 행이 생긴 뒤에는 배포 id가 그 행에 기록된 값과 다른 스토어도 거부합니다. `LOOM_CELL` 없이 시작한 배포는 준비되기 전까지 단일 배포이며, 다른 배포의 버킷 prefix를 가리키게 하는 것은 어떤 배포에서든 잘못된 구성입니다. 첫 셀에서는 `LOOM_CELL`이 롤아웃되기 전에 `loom cell prepare`를 실행합니다. 이후 셀은 첫 부팅부터 `LOOM_CELL`이 설정된 채로 실행되므로, 그 프로세스는 prepare가 행을 쓸 때까지 제어를 받고 워커(블롭 스윕 포함)에서 물러나 있으며, prepare는 라이브 프로세스의 하트비트에 `LOOM_CELL`이 없거나 다른 셀을 가리키는 동안에는 이후 셀을 거부합니다. prepare는 다음 세 가지를 순서대로 수행합니다.

1. **스토어에 이미 다른 셀의 신원이 있는 셀을 거부합니다.** 디렉터리에 기록된 배포 id이거나, 디렉터리가 그곳에 배치하지 않은 상태가 해당합니다. 이는 prepare가 보내는 개수를 바탕으로 라우터가 등록 자체의 트랜잭션 안에서 검사합니다. 디렉터리에 행이 없는 셀은 테넌시, `first`, 모드, 자체 행을 가져서는 안 되며, 이후 셀은 prefix 아래에 prepare의 프로브 외에 어떤 객체도 없어야 하고 `LOOM_CELL`이 없는 라이브 프로세스도 없어야 합니다. 다시 실행하면 테넌시 및 상태 행과 prefix의 객체를 자신의 것으로 셉니다. 이후 셀의 프로세스는 매 실행마다 `LOOM_CELL`로 실행되며, 이는 prepare가 직접 확인합니다.
2. **디렉터리 잠금 아래에서 셀을 `attaching`으로 디렉터리에 등록합니다.** 호스트, 셀에서 읽은 배포 id, 라우터를 호출할 때 쓰는 자격 증명의 SHA-256, 그리고 버킷 이름과 prefix를 등록하며, 준비되었거나 attach된 다른 모든 셀의 값과 대조해 검사합니다. 자격 증명은 `lcr_`와 소문자 16진수 128자(512비트)이며, `loom cell credential new`가 오프라인으로 만들어 자격 증명과 그 해시를 출력합니다. 부팅과 `loom doctor`는 다른 형식의 `LOOM_CELL_ROUTER_TOKEN`을 거부합니다. prepare는 해시를 소문자 16진수 64자 인자로 받으므로 어떤 CLI도 비밀 값을 필요로 하지 않습니다. 자격 증명이나 그 128자 비밀 값을 포함해 다른 값은 `loom cell credential new`를 언급하며 거부되고 어디에도 저장되지 않습니다. 다른 셀의 행이 현재 값이나 다음 값으로 그 해시를 가지고 있어서는 안 됩니다.
3. **셀의 행을 씁니다.** 모드(첫 셀은 `recording`, 이후 셀은 `enforced`), `first` 행, 그리고 `current`입니다.

prepare는 재개할 수 있습니다. 이름, 배포 id, 호스트가 같은 디렉터리 행에 대해 다시 실행하면, `first` 행과 모드 행 중 없는 것을 디렉터리의 상태로부터 쓰고, 위에서 설명한 대로 `loom.cell_self`도 씁니다(attach 전에는 없을 경우 하트비트로부터, 디렉터리가 지문을 가진 뒤에는 그로부터 `current`와 `next`를 쓰며 다른 기존 값은 덮어씀). attach 전에는 기존 자체 행이 그대로 유지되며, `current`도 `next`도 실행하지 않는 라이브 프로세스가 있으면 거부합니다. 디렉터리의 상태는 고유 인덱스가 지정하는 `first` 값과 그 셀에 대해 기록된 가장 높은 모드입니다. 즉 등록 시 행과 같은 트랜잭션에 기록되는 첫 셀의 `recording` 또는 이후 셀의 `enforced`, 그리고 attach가 올리는 각 모드이며, 이는 attach가 셀의 모드 행에 설정하기 전에 디렉터리에 기록됩니다(거부 시에는 `recording`으로 되돌아간 뒤 attach가 읽어 온 모드 행을 보고하며, 디렉터리의 기록은 절대 낮추지 않음). 다시 실행할 때, 디렉터리의 상태보다 높은 모드 행과 이후 셀의 `recording` 행은 이 셀의 것이 아니므로 거부하고, 첫 셀의 그보다 낮은 행은 attach가 마무리하도록 둡니다. 행의 `current`도 `next`도 아닌 자격 증명 해시는 거부하며(교체는 `loom cell credential`의 일), 자체 등록 이후에 배치되거나 기록된 테넌시 행은 자신의 것으로 세고, 이미 통과한 등록 검사(빈 prefix와 prefix 겹침)는 건너뛰므로, 데이터가 있는 prefix를 가진 `serving` 셀에서도 실행됩니다.

`LOOM_CELL`이 설정되었지만 모드 행이 없는 프로세스는 준비 상태가 되지 않습니다. 설정된 경우 각 셀의 Postgres에는 `loom.tenancy`(org, since)와 `loom.tenancy_mode`(`recording`, `enforced`)가 있으며, 프로세스는 최대 `LOOM_TENANCY_MODE_CACHE_S`(기본 5초)의 캐시를 통해 모드를 읽고, 읽을 수 없으면 마지막으로 읽은 모드를 유지하며, 최대 `LOOM_JWT_REVOCATION_MAX_STALE_SECONDS` 동안 보유한 org를 계속 서비스하고, 그 시간이 지나면 읽기가 성공할 때까지 제어를 받습니다. Postgres authority 아래의 모든 서버 프로세스는 `LOOM_CELL` 설정 여부와 무관하게 스토어를 열고 마이그레이션한 직후, 첫 하트비트와 리스 결정 전에 행을 읽으며, 첫 읽기에 실패하면 부팅이 실패합니다(Postgres 마이그레이션이 보류 중이면 제어를 받고 준비되지 않은 상태로 부팅하여 읽기가 성공할 때까지 유지됨). 그 후 `LOOM_CELL`이 설정된 프로세스는 위의 오래됨 한도를 유지하고, 설정되지 않은 프로세스는 단일 배포가 Postgres 장애를 견디듯 오래됨 한도 없이 읽기 실패 중에도 판정을 유지합니다(불변 조건의 첫 번째 예외). 셀의 워커 자식 프로세스는 자체 행을 읽으며 읽기가 성공할 때까지 제어를 받습니다. `LOOM_CELL`이 설정되지 않은 경우 모드와 `first` 행이 없고 테넌시나 자체 행도 없으면 준비된 적 없는 배포이며, 읽기 실패를 행이 없는 것으로 간주하는 일은 없습니다. 상태를 읽지 않는 프로세스(`LOOM_CELL`이 없는 워커 자식과 CLI, 그리고 ClickHouse authority 아래의 모든 프로세스)는 이 제어를 받지 않습니다. `enforced`에서 셀은 자신이 행을 가진 org만 정확히 서비스합니다. 다른 org에서 동작하는 호출자를 위해 프로세스가 보유하지 않은 것으로 읽은 org는 `LOOM_TENANCY_MODE_CACHE_S` 후에 다시 읽습니다. `recording` 행은 모드가 `recording`인 동안에만 삽입하는 한 문장으로 쓰이며, 모드 행을 `FOR SHARE`로 읽고, 자체 트랜잭션에서 `READ COMMITTED`로 실행되어 요청이 진행되기 전에 커밋됩니다. attach의 `enforced` 쓰기와 이 삽입들은 서로 교차하지 않습니다. attach가 모드를 쓸 때 이미 실행 중이던 삽입은 4단계에서 배치되고, 그 뒤에 시작한 삽입은 `enforced`를 읽으며, 삽입이 연달아 들어와도 쓰기를 막을 수 없고, 새 org 요청은 attach를 최대 몇 초만 기다리며, 쓰기의 잠금을 쥔 채 멈춘 attach는 몇 초 안에 이를 해제합니다. attach는 서버 측 타임아웃이 걸린 하나의 트랜잭션에서 짧게 반복 시도하며 `LOCK TABLE loom.tenancy_mode IN EXCLUSIVE MODE`(실행 중인 삽입을 기다리고 이후 삽입을 뒤에 대기시킴)를 잡은 다음 모드를 쓰고 커밋합니다. 그 트랜잭션에서 오류가 나면 해당 세션의 백엔드를 종료(`pg_terminate_backend`, attach가 연결할 때 확보한 pid와 `backend_start`로 지정된 백엔드)하고 그것이 `pg_stat_activity`에서 사라질 때까지 기다린 뒤, 재시도하거나 보고하기 전에 모드를 다시 읽습니다. `enforced`로 읽힌 모드는 attach가 계속 진행하기 전에, 커밋이 스탠바이를 기다리는 새 트랜잭션에서 다시 쓰는데, 대기 중에 끝난 커밋은 프라이머리에만 있기 때문입니다. attach 명령이 이 타임아웃들을 정하며 테스트가 각 경우를 다룹니다. 모드 캐시는 행 잠금을 잡지 않고 attach를 기다리지도 않는 일반 `SELECT`로 모드를 읽습니다. `enforced`를 발견한 삽입(캐시가 아직 `recording`을 읽는 프로세스)은 아무것도 쓰지 않으며, 요청은 `enforced`에서처럼 배치 호출로 넘어가고 CLI 명령은 `enforced`에서처럼 org를 명시하며 거부합니다. 3단계나 4단계가 셀을 `recording`으로 되돌린 뒤에도 캐시가 여전히 `enforced`를 읽는 프로세스는 캐시가 만료될 때까지 라우터의 게이트를 통해 배치합니다.
`loom doctor`는 디렉터리가 배치하지 않은 테넌시 행을 모두 나열합니다.

- **검증 후, org에 대해 무엇이든 쓰기 전에 실행됩니다.** op 게이트(`gates.authorize`)는 트랜스포트가 확인한 org(`gates.resolve_org`, 호출자 기본값과 plane org 포함)를 `check_acted_for`와 개인 네임스페이스 프로비저닝보다 먼저 검사하며, HTTP와 MCP 모두 마찬가지입니다(MCP에서는 다른 셀의 org에 대한 호출이 `isError`로 응답하므로 배치의 다른 응답은 유지되고, `gates.resolve_org`가 확인한 토큰 자신의 org에 대한 호출은 호출자의 기본값이 그 org에 있으므로 기본값을 읽기 전에 검사됨). 레지스트리 밖의 경로는 `check_authorized`, `admit_org` 또는 검사 자체를 통해 검사하며, 미들웨어는 자신의 org에서 동작하는 경로(census가 `token`으로 표시한 경로)에 대해 검증된 bearer 자신의 org를 검사합니다. org 전체 범위이거나 org가 없는 토큰이 이에 의존하는 호출자 경로의 경우, 가입 org를 주체 없이 검사하므로 기록되거나 거부될 뿐 배치되지는 않습니다. org에서 동작할 수 없는 주체(다른 org의 토큰)는 게이트의 403으로 먼저 거부되므로, 기록도 배치도 하지 않고 아무것도 알아내지 못합니다. 셀이 그 org를 보유하는지도, 어디에 배치되어 있는지도 알 수 없습니다. org 필드의 이름이 다른 op(`from_org`)는 `check_authorized`를 통해 같은 검사에 도달하며, census 테스트가 이러한 필드를 모두 나열합니다. 검사 이전에 쓰인 거부(잘못된 JSON, 알 수 없는 인자, 검증 실패)는 텔레메트리나 코드 트레이스에 셀이 보유하지 않은 org를 명시하지 않습니다. 단위 테스트가 앱의 모든 경로를 나열하며, 경로가 테넌시 검사됨 또는 org 없음으로 표시되지 않으면 실패합니다.
- **CLI는 자신의 org를 선언합니다.** 연결하는 모든 CLI 명령은 `run_connected`, `connect_checked` 또는 `connect_declared`(`server/cli/_ch.py`)를 거치며, 이들은 명령이 쓰는 org 또는 어떤 org에도 쓰지 않는 이유를 받습니다. org를 선언하는 명령은 먼저 자신의 배포를 검사하므로(`check_configured`), Postgres authority 아래에서는 `LOOM_PG_DSN`이 필요합니다. 셀에서는 선언된 org를 검사하기 전에 셀의 행을 읽고, `first` 행이 이 CLI의 셀을 가리키고 동시에 그 스토어(`deployment_id`, `bucket`, `bucket_prefix`)가 셀의 자체 행이 허용하는 값 중 하나와 일치하는 경우가 아니면 명령을 거부합니다. CLI는 토큰을 검증하지 않고 그 지문이 라우터에 도달하지도 않으므로, 트랜스포트가 다른 지문 필드를 이유로 거부하는 곳에서도 실행될 수 있습니다. `LOOM_CELL`이 설정되지 않은 경우 `recording`을 지난 셀에서는 명령이 거부됩니다(위). 셀이 보유하지 않은 org는, 요청의 org와 마찬가지로 `recording` 상태의 첫 셀에서는 기록되고(첫 셀의 CLI 구성에서 모드가 `recording`인 동안, 그리고 디렉터리가 `attaching`으로 응답하는 동안에만, 셀의 라우터 자격 증명 `LOOM_CELL_ROUTER_TOKEN`으로 셀의 상태를 읽음), `enforced`에서는 거부되며, 배치되지는 않습니다. 코드 인덱스 명령은 자신이 쓰는 org를 선언합니다. `--org`, 없으면 `LOOM_CODE_ORG`입니다. 구성된 모든 저장소를 한 번에 처리하는 작업은 org를 선언하지 않는데, 구성된 org는 attach 또는 이를 바꾸는 `loom cell update`가 배치하기 때문입니다. 읽기 전용 명령이나 dry run도 읽기는 아무것도 기록하지 않으므로 선언하지 않습니다. org가 없는 명령은 스토어에 무엇을 하는지 밝힙니다. 읽기, 쓰기(`loom ch-setup`, `secrets`, 설정 변경, prepare 등. dry run은 읽기) 또는 폐기(`loom revoke-token`, SQL 사용자 폐기, `loom signing-key retire`, `loom bot disable`, `loom sso unlink`. 접근을 되돌릴 수 있는 것은 쓰기)입니다. 하나의 연결이 여러 하위 명령을 처리하는 경우에는 하위 명령별로 구분합니다(`loom signing-key`: `list`는 읽기, `retire`는 폐기, `rotate`와 `record-root`는 쓰기). `LOOM_CELL`이 설정된 경우 쓰기나 폐기는 자신의 ClickHouse를 Postgres와 대조해 검사하고(`check_configured`), 제한된 자체 세션에서 `first` 행을 읽어 그것이 다른 셀을 가리키면(다른 셀의 스토어를 가리키는 CLI는 항상 이 경우를 만남) 또는 읽기가 실패하면 거부합니다. 행이 없거나 상태 테이블이 아직 마이그레이션되지 않았으면 통과하므로, 이후 셀은 prepare되기 전에 이들을 실행합니다. 폐기는 장애 중에도 실행되고(불변 조건의 네 번째 예외), 쓰기는 장애 중에 거부되며, 읽기는 제어를 받지 않습니다. 자체 클라이언트로 ClickHouse를 설정하는 `loom ch-setup`은 쓰기 전에 같은 게이트를 실행하며, 아직 레코드가 없는 ClickHouse는 통과합니다. `loom migrate`와 `loom provider-lock clear`는 스키마 러너 자체의 클라이언트를 통해 쓰며 제어를 받지 않습니다. census 테스트는 둘 중 어느 쪽도 선언하지 않는 연결, 어느 종류인지 밝히지 않는 org 없는 연결, `_ch.py` 밖의 `server/cli/` 아래 연결, 그리고 연결 없이 org를 확인하는 `loom code` 명령에서 실패합니다. 셀의 라우터 자격 증명을 가진 쪽은 셀의 속도와 `placements_max` 범위 안에서 셀을 위해 org를 배치할 수 있고, `loom cell place`가 쓰는 운영자 자격 증명은 어느 셀이든 그 `placements_max` 범위 안에서 같은 일을 할 수 있으며(운영자의 호출은 속도 제한을 받지 않고 셀의 속도에도 산입되지 않음), 배치는 영구적이므로 그것이 가져간 org 이름은 다른 모든 셀에서 사용할 수 없게 됩니다. 이는 셀의 스토어 자격 증명에는 없는, 공유 디렉터리에 대한 권한입니다. 따라서 파드가 이를 보유하며, CLI는 첫 셀의 모드가 `recording`인 동안 이를 필요로 하는 읽기 하나에만 사용합니다. org를 선언하는 CLI 명령은 셀이 첫 셀이면서 동시에 그 모드가 `recording`으로 읽히는 경우가 아니면 이것이 설정된 채 실행되기를 거부하고 이를 명시합니다. org가 없는 명령은 이를 사용하지 않습니다. 유출된 자격 증명은 셀의 스토어를 필요로 하지 않는 `loom cell limit --closed`로 막고 `loom cell credential`(아래)로 교체합니다. `loom cell place --org <org>`(org 없음으로 선언됨: org의 배치와 테넌시 행을 쓰는 것이 org가 보유되는 방식)는 라우터의 운영자 자격 증명으로, 새 org를 쓰는 명령(봇, 가져오기)을 위해 org를 배치합니다. 이는 attach가 구성된 org를 배치하는 것과 같이 라우터의 배치 API를 통해 같은 순서로 진행됩니다. 배치를 삽입하고 승자를 다시 읽으며, 승자가 이 셀인 경우에만 셀의 테넌시 행을 쓰고(아니면 거부하고 아무것도 쓰지 않음), 행이 쓰인 뒤에만 성공을 보고하므로 다시 실행해도 멱등합니다. 디렉터리가 아직 배치하지 않은 org의 경우 배치 API의 게이트(아래)를 통과해야 합니다. 디렉터리를 사용할 수 없는 동안, 게이트가 받아들이지 않는 셀, 닫힌 셀, CLI 자신의 셀 구성(연결하는 스토어에서 읽은 배포 id 포함)의 지문이 셀 행의 두 값 중 어느 것과도 일치하지 않을 때, 또는 `placements_max`를 넘을 때 거부되며, 이는 거기에 산입됩니다.
- **검사 도입 이전의 쓰기 주체는 쓰기 대상 스토어가 거부합니다.** 테넌시 검사를 실행한 세션은 `loom.tenancy_checked = 'on'`으로 스스로 표시합니다. `LOOM_CELL`이 설정된 프로세스의 모든 세션이 이를 시작 매개변수로 보내므로(풀의 `RESET ALL`이 유지함), 마이그레이션 세션은 마이그레이션 잠금을 잡은 뒤 이를 설정합니다. 마이그레이션의 데이터 단계는 이미 저장된 행을 복사하거나 다시 쓸 뿐이기 때문입니다. `org` 컬럼이 있는 authority의 모든 일반 테이블(`loom.tenancy` 자체나, 호출자의 토큰 org를 키로 쓰는 `loom.idempotency`와 `loom.idempotency_fences`는 제외)에는 origin 트리거로 활성화된 행 단위 `AFTER INSERT` 및 `AFTER UPDATE` 트리거가 있으며, 표시된 세션은 그 `WHEN`에서 건너뜁니다(update 트리거는 행의 org를 바꾸지 않는 update도 건너뛰므로 기존 행을 건드리는 `ON CONFLICT DO UPDATE`는 거부되지 않음). 이 트리거는 하나의 함수를 호출합니다(마이그레이션 011). 이 함수는 상태 규칙(위)을 따릅니다. 상태가 open이거나 첫 셀이 recording인 동안에는 모든 행을 통과시키고, 그 외 모든 상태에서는 테넌시 행이 없는 org의 행을 SQLSTATE `LT001`(호출자에게는 503 `TENANCY_REFUSED`)로 거부합니다. 다만 센티널 org 값 `''`, `'-'`, `'*'`는 예외로, 테넌시 행이 없어도 이 거부 대상이 아니며 이 트리거를 항상 통과합니다. 이 값들이 금지된 org 값이라는 뜻은 아닙니다. 상태는 행이 쓰인 뒤 행 잠금 없이 읽으므로 어떤 쓰기도 attach 뒤에 대기하지 않으며, 4단계(아래)는 `recording`을 읽었을 수 있는 모든 트랜잭션이 끝나기를 기다립니다. 마이그레이션이 켜진 부팅은 카탈로그에서 찾은 해당 테이블 모두에, 완전히 준비된 `enforced` 셀에서만 트리거를 만들고, 거기서 origin이 아닌 상태로 있는 트리거는 origin으로 되돌립니다. 각 테이블의 DDL은 시도마다 잠금을 100ms 기다리며, 1초 간격으로 세 번 시도합니다(바쁜 테이블 하나당 약 2.3초이므로, 보호되는 모든 테이블이 바쁜 상태로 발견되면 부팅은 다른 부팅 중인 파드가 기다리는 마이그레이션 잠금을 쥔 채 각각을 차례로 그만큼 기다림). 잠금을 잡지 못한 테이블, 즉 잠금 보유자와 함께 기록된 경우나 역할이 변경할 수 없어 그렇게 기록된 경우는 건너뛰고 부팅이 서비스를 계속합니다(불변 조건의 세 번째 예외). 첫 셀은 attach가 실행되면서 `enforced`로 설정하기 전까지 `recording`이므로 어떤 부팅도 이를 만들 수 없었습니다. attach가 `enforced`를 설정한 뒤 같은 패스(`cell_triggers.ensure`)로 직접 만들며, 셀은 `cell_triggers.missing`이 결함을 지목하지 않을 때에만 `serving`이 됩니다. 이후 셀은 prepare 때부터 `enforced`이고 prepare 다음의 첫 마이그레이션 부팅에서 트리거를 얻으며, 그 attach도 같은 방식으로 이를 요구합니다. `loom doctor`는 어느 상태에서든 비활성화되거나 변경된 트리거를, `enforced` 셀에서는 없는 트리거를, 그리고 `org` 컬럼이 있는 파티션 테이블은 트리거를 받지 못하므로 지원되지 않는 것으로 알려 줍니다. origin 트리거는 논리 복제의 적용이나 `session_replication_role = replica` 아래에서는 실행되지 않으며, 셀의 스크립트는 이를 사용하지 않습니다. 표시는 권한 경계가 아닙니다. 의도적으로 표시를 설정하는 쓰기 주체는 통과하며, 트리거는 표시를 알지 못하는 쓰기 주체(오래된 CLI, 검사 이전으로 다운그레이드된 파드, 스크립트)가 셀이 보유하지 않은 org의 행을 추가하거나 행을 그런 org로 옮기는 것을 막습니다. 행의 org를 유지하는 update와 delete는 거부되지 않습니다. org 트리거의 비용은 표시된 행당 설정 조회 한 번, 표시되지 않은 행당 상태 읽기 한 번과 `loom.tenancy` 조회 한 번입니다. 출시 기준은 `enforced`에서 org를 보유한 상태로 `memory.set` p99 증가가 최대 10ms, `LOOM_PG_DELIVERY_BATCH_ROWS`에서 전달 패스의 초당 행 수 감소가 최대 10%입니다. 셀의 모든 Loom 쓰기는 표시되므로 설정 조회 비용만 부담하며, 트리거를 켠 경우와 끈 경우의 문장에서 측정했을 때 0과 구별되는 비용이 없고(여섯 라운드가 행당 −0.36~0.49µs 범위, [벤치마크 결과](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md)), 이는 기준이 넉넉한 여유로 충족됨을 예측합니다. 게이트 자체는 셀에서의 엔드투엔드 `memory.set` 및 전달 패스 측정이며, attach가 필요하고 이와 함께 확인됩니다. 그때까지 트리거(이후 셀은 prepare 다음의 마이그레이션 부팅에서 얻음)는 문장 수준의 측정을 근거로 출시됩니다. `loom.tenancy` 자체에도 보호 장치가 있는데, 테넌시 행이 org를 보유 상태로 만들기 때문입니다. `tenancy_record`는 같은 표시 `WHEN`을 가진 행 단위 `AFTER INSERT OR UPDATE OF org` origin 트리거로, `loom.tenancy_refuse_unmarked()`(마이그레이션 012)를 호출하여, 첫 셀이 아직 recording인 경우를 제외한 모든 상태(행 자체가 상태를 `partial`로 만들 것이므로 `open`도 포함)에서 표시되지 않은 세션의 테넌시 행이나 행을 다른 org로 옮기는 update를 `LT001`로 거부합니다. 따라서 스크립트가 디렉터리가 배치하지 않은 org를 보유 상태로 만들 수 없습니다. 부팅과 attach는 org 트리거와 마찬가지로 이를 만들고 복구합니다. attach와 함께 `loom doctor`는 디렉터리가 배치하지 않은 테넌시 행(보호 장치 이전에 쓰였거나 표시를 설정한 쓰기 주체가 쓴 것)과, 테넌시 행이 없는 org 키 Postgres 테이블의 org(org 트리거 이전에 쓰였거나, 표시를 설정한 쓰기 주체가 썼거나, 삭제된 테넌시 행으로 남은 행)도 나열합니다. 첫 attach 전에 운영자는 셀의 ClickHouse 쓰기 자격 증명을 교체하며(새 사용자를 만들고, 검사하는 빌드의 구성에 롤아웃하고, 이전 사용자를 삭제), attach는 `loom.*`에 대한 `INSERT` 권한을 가진 ClickHouse 사용자(`system.grants`, 데이터베이스·전역·역할 권한은 `system.role_grants`를 따라가며, 구성 파일의 사용자나 암묵적 `ALL`을 가진 사용자도 포함)가 검사하는 빌드의 라이브 프로세스나 CLI에 구성된 사용자가 보고한 사용자가 아닌 동안은 거부하므로, 교체된 자격 증명의 보유자만 ClickHouse에 씁니다. 그 자격 증명을 받은 오래된 CLI는 여전히 검사 없이 쓸 수 있으며, attach와 함께 `loom doctor`는 그것이 쓴 내용, 즉 attach 2단계와 같은 스키마 목록에서 테넌시 행이 없는 org 키 ClickHouse 테이블에서 발견된 모든 org를 나열합니다.
- **셀이 보유하지 않은 org는 그곳에 배치되거나 거부됩니다.** 해당 org로 범위가 정해진 검증된 주체(그 org의 토큰, 또는 해당 org에 속한 발급자나 봇의 주체)의 경우, 셀은 자신의 자격 증명(`LOOM_CELL_ROUTER_TOKEN`)으로 라우터의 배치 API(`LOOM_CELL_ROUTER_URL`의 `POST /cells/v1/placements`, 승리한 셀과 그 배포 id로 응답)를 호출하며, 호출이 지목하는 셀은 자격 증명이 기록된 해시와 일치하는 셀이어야 합니다(해시는 하나의 셀을 지목함). 라우터는 한 번에 하나의 org를 배치하며(org에 대한 트랜잭션 범위 잠금으로, 배치하는 모든 경로가 이를 취함), 이미 배치된 org에는 그 셀로 응답하고, 그렇지 않으면 잠긴 행을 기준으로 요청한 셀을 판정하여 배치를 삽입하고 승자를 다시 읽으며, 셀은 이를 이름과 기록된 배포 id로 비교합니다. 승자가 이 셀이면 셀은 테넌시 행을 쓰고 요청을 서비스합니다. 이 셀의 이름이 프로세스가 검증한 것과 다른 배포 id 아래에 있으면 503으로 응답하고 아무것도 쓰지 않으며, 다른 셀의 이름이면 요청은 409 `WRONG_CELL`로 응답하고 아무것도 쓰이지 않습니다. 이것이 org를 어떻게 생성했든(mint, 게이트웨이나 연합 발급자의 토큰, 최종 사용자 발급자의 `prefix*` org, 봇) 요청이 org를 셀로 가져오는 유일한 경로입니다. `*` org 또는 플랫폼 주체는 셀이 이미 보유한 org에서만 동작하며 org를 배치하지 않습니다(`serving` 이전의 첫 셀에 대해서는 [하트비트의 키](#the-heartbeats-keys) 참조). 디렉터리가 아직 배치하지 않은 org에 대해 라우터는 `serving` 셀(또는 디렉터리가 `enforced`를 기록한 뒤, attach 3단계가 셀의 모드를 설정하기 전에 쓰는 `attaching` 상태의 첫 셀)의 배치 호출만, 그리고 호출 프로세스의 구성 지문이 있고 그 필드가 셀의 디렉터리 행의 값과 일치할 때만 받아들이며, 준비된 셀의 행에는 attach가 쓰기 전까지 발급자나 org 패턴이 없습니다. 실패한 호출, `LOOM_CELL_ROUTER_TIMEOUT_S` 안에 응답이 없는 호출, 아직 attach되지 않았거나 새 org에 닫힌 셀, 어느 값과도 일치하지 않는 지문은 503으로 응답하고 아무것도 쓰지 않으며, 다시 읽기로 멱등하므로 재시도는 안전합니다. 디렉터리가 이미 배치한 org의 경우 셀의 호출은 자격 증명(라우터가 `LOOM_ROUTER_DIRECTORY_CACHE_S`, 기본 5초 동안 캐시하는 셀들의 해시와 대조)과 셀의 속도만 검사하고, `loom cell place`는 운영자 자격 증명만 검사하며, 둘 모두 셀의 상태, 쿼터, 지문과 무관하게 승자를 응답하고 배치를 추가하지 않습니다(승자는 조회를 통해 어차피 공개됨). 셀의 속도를 넘은 요청은 `Retry-After`(최대 1분)와 함께 503으로 응답하며, 재시도는 그 셀의 해당 레플리카에서의 호출이 속도 아래로 내려가면 그것을 응답하는 레플리카가 받아들입니다. 셀이 이미 보유한 org는 호출이 필요 없으므로, 그것을 서비스하는 일은 라우터에 의존하지 않습니다.
- **배치는 셀별로 제한됩니다.** 각 라우터 레플리카는 셀의 배치 호출을 분당 속도 제한(`LOOM_ROUTER_PLACEMENTS_PER_MINUTE`)하므로 그 속도에 레플리카 수를 곱한 값이 호출 속도의 상한이 되고, 셀의 디렉터리 행에는 배치 쿼터(`placements_max`, 기본값은 미설정)가 있을 수 있으며, 설정되면 총 개수를 제한하고 셀의 디렉터리 행에 대한 잠금 아래에서 세고 삽입하므로 라우터 레플리카 전반의 동시 호출도 이를 넘지 못합니다. 속도를 넘으면 셀의 모든 배치 호출이 `Retry-After`와 함께 503으로 응답하고, 쿼터를 넘으면 디렉터리가 아직 배치하지 않은 org에 대한 호출은 닫힌 셀처럼 503으로 응답합니다(운영자의 `loom cell place`는 위와 같이 속도 제한에서 면제됨). 각 셀의 배치는 `/v1/health?include=capacity`와 `loom doctor`가 보고하며, 후자는 쿼터가 없는 셀을 알려 줍니다. 첫 셀의 attach가 배치하는 모든 org(2단계의 스냅샷, 구성된 org 포함, 그리고 4단계의 것)는 센다는 점은 같지만 쿼터나 닫힌 셀 때문에 거부되는 일이 없는데, 셀이 이미 서비스하고 있어 거부하면 데이터가 고립되기 때문입니다(`ORG_MAX_BYTES`를 넘는 것은 디렉터리가 거부, 아래). 디렉터리가 아직 배치하지 않은 org에 대한 다른 모든 배치(attach에서의 이후 셀의 구성된 org와 `loom cell update`에서 바뀐 org 포함)는 닫힌 셀과 `placements_max`를 포함한 게이트를 통과해야 하므로, attach 전에 닫혔거나 가득 찬 이후 셀은 org를 명시하며 attach를 거부합니다.
- **첫 셀은 단일 배포와 마찬가지로 `enforced`가 될 때까지 기록합니다.** 셀의 모드에 3단계가 `enforced`를 쓸 때까지(그리고 3단계나 4단계가 셀을 되돌릴 때마다) 지속되는 `recording`에서는, 새 org에 대한 검증된 요청이 배치 호출 없이 테넌시 행을 쓰므로 라우터의 속도, `placements_max`, `loom cell limit --closed`는 적용되지 않습니다. 새 org는 단일 배포에서와 같이 자체 가입, 발급자, JIT 설정이 정한 범위 안에서 도착하며, 2단계나 4단계가 이를 거부 없이 배치합니다. `loom doctor`는 데이터가 없는 기록된 org를 나열하여 운영자가 attach가 무엇을 배치할지 볼 수 있게 합니다.
- **구성된 org는 attach 때 배치됩니다.** 셀의 `oidc_jit_org`, 가입이 켜진 셀의 `self_signup_org`, 코드 org(`LOOM_CODE_ORG`와 코드 구성이 유지하는 각 `LOOM_CODE_REPOS_JSON` 항목의 org), 트래커 org는 셀이 attach될 때 자신의 것으로 배치됩니다. 첫 셀의 것은 2단계의 스냅샷에서, 이후 셀의 것은 `serving`으로 표시되기 전에 배치됩니다. JIT와 자체 가입은 다른 요청과 마찬가지로 테넌시 검사를 통과하며, 부팅 시 거부되는 것은 없습니다. 첫 셀의 `recording`에서는 디렉터리가 `attaching`으로 응답하는 동안 org를 기록하고, 그 외에는 셀이 보유하지 않은 구성된 org가 배치될 때까지 503으로 응답하며(디렉터리가 거부하는 `ORG_MAX_BYTES` 초과 org는 422), 이는 `loom doctor`가 알려 줍니다. 첫 attach든 이후 attach든, 새것이든 재개된 것이든 모든 attach는 겹침 거부를 실행하고 `loom.cell_self`의 두 값의 구성된 org를 배치하므로, attach 전에 업데이트가 `next`에 넣은 org도 나머지와 함께 배치됩니다. attach가 셀의 디렉터리 행을 쓴 뒤에는, `loom cell update`가 바뀐 org를 `next`를 쓰는 디렉터리 트랜잭션에서, 디렉터리가 아직 배치하지 않은 org에 대한 배치 API의 게이트(닫힌 셀과 `placements_max` 포함)를 통해 배치하며, 다른 셀이 보유한 org이면 이를 명시하며 거부하고, 이어서 셀에 그 테넌시 행을 씁니다. 디렉터리 트랜잭션 후에도 여전히 `attaching`인 이후 셀의 경우, `loom cell update`는 셀이 `serving`이 될 때까지 구성된 org의 변경을 거부합니다. `enforced`에서 워커는 셀이 org를 보유한 뒤에만 그 org에 쓰므로(주체 없는 테넌시 검사), 이후 셀은 attach가 배치하기 전에는 구성된 org 아래에서 인덱싱, 가져오기, 스윕을 하지 않습니다. `recording`에서는 워커가 이전처럼 실행되며, 2단계의 스냅샷과 4단계의 두 번째 읽기가 워커가 쓰는 모든 org를 찾아냅니다.
- **행은 삭제되지 않습니다.** 테넌시 행과 배치는 org의 이름을 나타낼 뿐 그 메모리를 나타내지 않습니다. 둘 다 네임스페이스의 클레임처럼 메모리 콘텐츠를 담지 않는 것으로 삭제 대상으로 분류되며 어떤 삭제 후에도 남으므로, org 이름이 다른 셀에서 사용 가능해지는 일은 없습니다. 프로세스는 보유된 것으로 본 org를 계속 기억하며, 기억된 org를 서비스하는 것은 틀린 적이 없습니다.
- **org 이름의 길이 한도는 하나입니다.** 셀은 `ORG_MAX_BYTES`(UTF-8 2048바이트, `server/core/cell.py`, Postgres의 인덱스 항목 한도 아래)보다 긴 새 org를 기록하거나 배치하지 않습니다. 기록 중인 셀의 테넌시 검사는 이를 422로 거부하고 아무것도 쓰지 않으며, 디렉터리는 배치하는 모든 경로에 대해 배치를 쓰기 전에 400(`ORG_TOO_LONG`)으로 거부하고 셀의 배치는 이를 같은 422로 바꿉니다(MCP에서는 호출자의 잘못으로 센 도구 오류). 따라서 셀이 기록하는 모든 org는 배치될 수 있으며, 한도 이전에 보유되거나 배치된 org는 자신의 셀을 유지합니다.
- **행이 없는 배치된 org**(배치 이전으로의 복원)는 복원된 셀이 시작되기 전에 `loom cell restore`가 행을 되돌려 줍니다([각 셀이 실행하는 것](#what-each-cell-runs)).

<a id="attaching-a-cell"></a>

## 셀 연결하기

라우터를 대상으로 실행하는 `loom cell attach`는 셀을 한 번에 하나씩 등록하며, 어떤 항목이든 실패하면 해당 항목을 지목하고 거부합니다.

- 셀은 자신의 호스트에서 `probe_url`이 보고하는 배포 id로 응답하고, 실행 중인 모든 프로세스에는 `LOOM_CELL`이 자신의 이름으로 설정되어 있으며, 동기 대기(standby)를 둔 Postgres 권한 저장소(`LOOM_PG_DURABILITY=synchronous`)와 강제된 인증으로 동작하고, 다른 어떤 셀도 기록하지 않은 배포 id를 기록합니다.
- 첫 번째 셀에서는 attach의 Postgres 역할이 모든 백엔드의 트랜잭션 상태를 읽을 수 있고(`pg_read_all_stats`) 셀의 Postgres가 준비된 트랜잭션을 허용하지 않아야(`max_prepared_transactions = 0`) 하므로, 4단계에서 열려 있는 모든 트랜잭션을 볼 수 있습니다.
- 키는 셀 고유의 것이어야 합니다. 셀이 베어러 토큰에 대해 수락하는 어떤 발급자도 다른 셀에서 수락되지 않으며, 루트 시크릿 지문(`keys_fp`)도 다른 어떤 셀의 지문과 일치하지 않습니다. 셀이 업스트림 ID 공급자와 워크로드 발급자로부터 자체 토큰을 발급하므로 이들은 공유할 수 있습니다. 게이트웨이(`LOOM_IDENTITY_PROVIDER=gateway`)는 하나의 셀에 대해서만 발급하므로, 배포는 셀마다 게이트웨이를 하나씩 실행합니다.
- 다른 셀의 실행 중인 프로세스 중 디렉터리 행의 두 값 어느 쪽과도 일치하지 않는 지문을 보고하는 것이 없어야 하고, attach 대상 셀의 실행 중인 모든 프로세스는 `loom.cell_self`의 `current` 또는 `next`와 일치해야 합니다(일치하지 않는 프로세스는 attach가 지목합니다).
- 다른 어떤 셀도 동일한 (OIDC 발급자, 클라이언트 id) 쌍을 기록하지 않아야 합니다(디렉터리 행이 이를 기록하며, `loom cell update`는 겹침 거부에서 이를 셉니다).
- SCIM이 켜져 있으면, 셀이 가진 모든 SCIM 토큰이 셀을 이름으로 가리키거나(`lsc_<cell>_…`), 첫 번째 셀에 한해 어떤 셀도 가리키지 않아야 합니다. 이후의 셀은 SCIM 사용자 행이나 삭제 표시(tombstone)를 가지지 않습니다(구성원은 attach 이후에 `LOOM_CELL`, 이름이 지정된 토큰, 애플리케이션의 할당 순서로 프로비저닝됩니다).
- `LOOM_PUBLIC_BASE_URL`이 설정되어 있어야 하고(`LOOM_CELL`이 설정된 프로세스는 이것 없이는 부팅을 거부하므로, 셀이 내주는 어떤 URL도 요청의 Host에서 오지 않습니다), 이 URL과 `LOOM_OAUTH_ISSUER`(비어 있으면 공개 기본 URL로 해석됩니다)의 호스트가 셀에 등록된 호스트와 같아야 합니다. 등록된 호스트가 공유 호스트인 첫 번째 셀의 경우 이들은 공유 호스트이거나 그 기록된 별칭입니다. 이후 셀의 호스트는 공유 호스트나 별칭이 될 수 없으며, 이는 디렉터리의 `hosts` 테이블이 강제합니다(호스트가 기본 키이며, 하나의 함수 `normalise_host`로 정규화합니다: 소문자화, IDNA를 ASCII로 변환, 끝의 점과 기본 포트 제거, IPv6의 대괄호 유지. 이 함수는 `hosts`, 규칙 1, attach, 준비 상태 점검에서 사용되고, 각 호스트는 한 셀이 소유하며 별칭은 첫 번째 셀에 속합니다). 이 테이블은 각 점검과 같은 트랜잭션에서 기록되고 규칙 1이 여기에서 라우팅합니다. `LOOM_JWT_ISSUER`는 불투명한 문자열이며 고유하기만 하면 됩니다. prepare도 같은 점검을 수행합니다.
- 셀에 구성된 org는 다른 셀에 배치된 어떤 org와도 충돌하지 않아야 하고, 셀이 신뢰하는 org 패턴(최종 사용자 발급자의 `orgs`)은 다른 셀의 패턴이나 구성된 org와 겹치지 않아야 하며, 다른 셀의 패턴이 이 셀의 구성된 org와 일치해서도 안 됩니다. 이는 단일 배포가 자체 최종 사용자 발급자에 적용하는 겹침 규칙을 따릅니다.
- 셀의 저장소는 다른 셀의 것이 아니어야 합니다. `loom._migration_lock` KeeperMap의 예약된 이름에 기록한 프로브 키는 다른 어떤 셀에서도 보이지 않아야 하고 다른 모든 셀의 프로브도 이 셀에서 보이지 않아야 합니다(Keeper가 없는 ClickHouse는 거부됩니다). 버킷 접두사는 같은 이름의 버킷에서(엔드포인트와 무관하게) 다른 셀의 접두사의 경로 접두사가 아니어야 하고 그런 접두사를 가지지도 않아야 하며, 프로브 객체는 어느 방향으로도 목록에 나타나지 않아야 합니다.
- 모든 셀의 실행 중인 모든 프로세스는 직전 빌드도 테넌시 점검(아래 참조)을 실행하는 빌드를 실행하고, 자신의 테넌시 모드, 지문, 실행 중인 `LOOM_CELL`을 보고하는 하트비트를 보냅니다.
- SCIM이 켜져 있으면, 활성 SCIM 행이 없는 활성 계정이 연락처나 검증된 이메일을 가져서는 안 되며(비밀번호 계정, 유효한 리프레시 세션, 개인 서비스 계정 포함), 유효한 서비스 계정의 생성자 체인이 이메일 없는 계정으로 끝나서도 안 됩니다(SSO 이전에 만든 에이전트 가입 토큰). attach는 이들을 나열하고 거부하며, `--revoke-unprovisioned`가 주어지면 attach 이전에 발급된 이들의 토큰을 SCIM 자체의 해지 접두사로 종료합니다. 이렇게 하면 ID 공급자가 나중에 프로비저닝하는 사람이 허용됩니다. ID 공급자는 할당된 것으로 세지 않는 사람을 프로비저닝 해제하지 않기 때문입니다.

첫 번째 attach는 기존 배포를 첫 번째 셀로 바꾸며, 순서는 다음과 같습니다.

1. 모드가 prepare가 설정한 대로 `recording`인지 확인합니다. 디렉터리가 셀이 `attaching`이라고 답하는 동안, 검증된 모든 요청은 해당 org의 테넌시 행이 없으면 기록해 둔 상태입니다.
2. 하나의 디렉터리 트랜잭션에서 `attach_started_at`, 셀의 발급자, 패턴, 지문(`loom.cell_self`의 두 값 모두), 그리고 셀이 가진 모든 org의 배치와 이어서 테넌시 행을 하나의 스냅샷으로부터 디렉터리에 직접 기록합니다(아직 다른 셀이 없기 때문입니다). 대상은 구성된 org(두 값 모두), 두 스키마의 모든 테이블에 있는 고유한 `org`(삭제 처리의 테이블 분류와 마찬가지로 스키마에서 생성됨), 카탈로그에 등록된 버킷 객체의 org이며, `''`, `'-'`, `'*'`는 절대 포함하지 않습니다.
3. 위와 같이 `enforced`를 설정합니다. 이는 `--wait` 안에서 이루어지며 아래의 대기도 이 시간을 공유합니다. 남은 시간이 그 대기의 최소치(모드 캐시 수명과 가장 긴 요청 데드라인의 합)보다 적을 때는 모드를 커밋할 수 있는 시도를 시작하지 않습니다. 그러면 attach는 다시 읽어 온 모드(`recording`이며 재실행하면 1단계부터 재개됨)를 보고하며 거부하거나, 읽을 수 없으면 모드를 알 수 없다고 보고하며 거부하고, 이 경우 재실행은 읽어 온 모드에 따라 재개됩니다. 그다음 `--wait`(기본 10분, 초과 시 거부하고 `recording`으로 되돌림)의 남은 시간 안에서, 실행 중인 모든 프로세스가 `enforced`를 보고하고 모드 캐시 수명과 가장 긴 요청 데드라인이 지날 때까지 기다립니다. 이어서 `enforced`가 적용되기 전에 만들어진 계정을 위해 SCIM 전제 조건을 다시 실행합니다(주어졌다면 `--revoke-unprovisioned`도 다시). 이것이 거부되면 셀은 `enforced`이자 `attaching` 상태로 남고, attach를 다시 실행하면 재개된 attach(아래)처럼 대기 단계부터 재개됩니다.
4. `--wait`의 남은 시간 안에서, `recording`을 읽었을 수 있는 트랜잭션이 더 이상 열려 있지 않을 때까지 기다립니다. 판단은 시계가 아니라, 이번 실행에서 `enforced`를 다시 읽은 뒤 attach가 한 번 취하는 Postgres 스냅샷으로 합니다. 셀의 데이터베이스에서 그보다 먼저 시작한 트랜잭션은 어떤 클라이언트, 백그라운드 워커, 논리 복제 연결에서 온 것이든, 읽기 전용이든 열린 것으로 칩니다. 같은 서버의 다른 데이터베이스에서 먼저 시작한 쓰기 트랜잭션도 마찬가지입니다(모든 스냅샷의 호라이즌을 붙잡으며, 그렇게 지목됩니다). 준비된 트랜잭션(즉시 거부됨)이나 attach가 상태를 읽을 수 없는 트랜잭션도 열린 것으로 칩니다. Postgres 자체의 유지보수 프로세스, 물리 복제 연결(모든 standby와 베이스 백업의 연결로, SQL을 실행하지 않음), attach 자신의 연결은 포함하지 않습니다. `--wait`를 넘기면 attach는 무엇을 기다렸는지 지목하며 거부하고 셀을 `enforced`로 남기므로, 재실행은 3단계의 대기부터 재개됩니다. 정확한 쿼리는 attach 명령이 고정하며, 그 테스트가 각 종류의 트랜잭션을 다룹니다. 대기를 통과하면, 스냅샷 이후에 기록된 테넌시 행과 2단계의 소스를 다시 읽었을 때 나오는 모든 org를 배치합니다(두 스키마의 모든 테이블에 있는 고유한 `org`와 카탈로그에 등록된 버킷 객체의 org이며, 구형 CLI나 워커처럼 점검하지 않는 작성자가 `recording` 동안 스냅샷 이후에 기록한 행이나 객체도 함께 배치됩니다). 이어서 실행 중인 모든 프로세스가 `enforced`를 보고하는지 다시 확인하고(그렇지 않으면 3단계처럼 거부하고 `recording`으로 되돌립니다), 셀을 `serving`으로 표시합니다. 디렉터리는 attach가 올렸거나 올리려 한 가장 높은 모드를 기록하며, `loom cell restore`는 이를 위쪽으로만 되돌려 씁니다. 3단계가 락에서 거부된 셀은 `enforced`로 복원되고, 재개된 attach는 3단계의 대기부터 실행됩니다.

이후의 셀은 첫 번째 셀이 `serving`이 된 뒤에야 연결할 수 있습니다. 이 셀은 org 데이터를 가지고 있지 않아야 하며(그렇지 않으면 attach가 거부함) `enforced`로 시작합니다. attach는 다음을 순서대로 실행합니다. 거부 점검, 디렉터리 락 아래에서 겹침 거부를 안에서 다시 실행하는 하나의 디렉터리 트랜잭션(여기서 `attach_started_at`, 구성된 org의 배치, 발급자, 패턴, 지문(`loom.cell_self`의 두 값 모두)을 기록하며, 다시 읽었을 때 다른 셀이 지목되면 해당 org를 지목하고 아무것도 쓰지 않고 거부함), 셀 안에서의 구성된 org와 `loom.cell_self`의 테넌시 행 기록, SCIM 전제 조건(주어졌다면 `--revoke-unprovisioned`), 그리고 `serving`입니다. 재개된 이후 셀의 attach는 새 셀에만 해당하는 점검을 제외한 거부 점검을 다시 실행하고, 완료되지 않은 첫 단계부터 계속합니다. 배치는 다시 읽기를 통해 멱등적입니다. 구성원은 로그인하기 전에 셀 자신의 ID 공급자 애플리케이션이 프로비저닝합니다. org 자체의 서비스는 별도의 셀로 연결합니다. 사람으로 이루어진 새 org는 `loom cell place --org`로 시작하고, 이어서 그 셀의 애플리케이션에 구성원을 할당합니다. SCIM이 켜진 셀은 첫 프로비저닝 주기가 실행되기 전에는 아무도 허용하지 않습니다. 저장소 한계에 가까워진 셀은 새 org에 대해 닫히며, 배치 호출은 503으로 응답하므로 그 셀 발급자의 새 org는 다른 곳으로 넘어가지 않고 용량이 생길 때까지 기다립니다.

셀의 디렉터리 행에 `attach_started_at`이 있는 재개된 첫 번째 attach는, 위 목록에서 첫 번째 셀에 적용되는 모든 거부 점검을 다시 실행합니다. 그런 다음 셀의 모드에 따라 계속합니다. `recording`이면 1단계부터, `enforced`이면 3단계의 대기(실행 중인 모든 프로세스가 `enforced`를 보고하고, 이어서 캐시 수명과 가장 긴 요청 데드라인이 지남)와 그다음 SCIM 전제 조건부터 진행합니다. 따라서 `enforced`를 설정한 뒤 멈춘 attach를 끝내는 SCIM 점검은, 무엇이 attach를 멈추게 했든 항상 `enforced`가 적용된 뒤에 실행됩니다.

<a id="what-each-cell-runs"></a>

## 각 셀이 실행하는 것

배포가 실행하는 모든 것이 그대로 실행됩니다. 풀, 마이그레이션, 워커와 그 리스, 상태 및 준비 상태 확인(파드의 준비 상태는 해당 셀의 준비 상태입니다), 삭제와 그 집계, 감사 체크포인트, 백업과 복원이 여기에 해당합니다. 셀의 복원은 단일 배포의 복원과 같으며([백업 및 복구](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)), 한계도 같습니다. 백업이 담고 있는 것(키, 폐기 내역, 세션, 봇, SCIM 행)은 백업 당시 그대로 돌아옵니다. 셀은 스토어 복원 이후, 해당 페이지가 실행하는 다른 모든 작업보다 앞서 한 단계를 더합니다. `loom cell restore`는 셀을 중지한 상태에서, 운영자가 `loom cell place`와 attach를 실행하는 곳에서, 어떤 셀의 구성에도 들어 있지 않은 라우터의 운영자 자격 증명으로 실행합니다(org와 무관하게 선언된 CLI 명령으로, 셀 자체의 행을 씁니다). 이 명령은 복원이 되살릴 수 있는 행을 디렉터리에서 다시 써 넣습니다. 그래서 `loom reconcile`의 삭제와 개인정보 보호를 위한 민감 내용의 마스킹 및 제거(redaction)가 테넌시 검사를 통과하고, `loom reconcile`이 거부하는 두 스토어 모두의 복원에서도 해당 셀의 행을 받을 수 있습니다. 디렉터리를 사용할 수 없으면 거부하며, 다음을 씁니다.

- 디렉터리가 이 셀에 배치한 모든 org에 대한 테넌시 행
- `first` 행과 mode 행 중 없는 것을, 재개된 prepare와 마찬가지로 디렉터리에서 가져와 씁니다. 디렉터리의 것과 다른 `first` 행이 이미 있으면 거부하고, 일치하면 그대로 둡니다.
- 테넌시 행이 복원되면, mode 행 위에 디렉터리에 기록된 mode를 덮어씁니다. 위쪽 방향(`recording`에서 `enforced`)으로만 가며 아래로는 내리지 않습니다.
- 디렉터리 행이 셀의 핑거프린트를 가지고 있으면(attach가 씁니다), 그로부터 `loom.cell_self`(`current`와 `next`)를 씁니다. attach 이전에는 디렉터리에 핑거프린트가 없으므로, 복원된 `loom.cell_self`는 백업이 가진 상태 그대로 남습니다(없는 `current`는 셀이 시작된 뒤 `loom cell prepare`를 다시 실행하면 써지고, 잃어버린 `next`는 `loom cell update --config`를 다시 실행하면 써집니다).

prepare 이전으로 복원되었고 아직 attach되지 않은 첫 셀은, `LOOM_CELL`이 설정된 프로세스에서는 공유 호스트에서 아무것도 서비스하지 않습니다(설정되지 않은 프로세스는 롤아웃 이전처럼 단일 배포로 서비스합니다). 이는 셀이 시작된 직후 단계인 `loom cell prepare`를 다시 실행할 때까지 계속됩니다.

셀의 준비 상태는 디렉터리를 기다리지 않으므로, 디렉터리 장애가 어떤 셀의 롤아웃도 막지 않습니다. `recording`을 읽은 프로세스는 디렉터리가 해당 셀이 `attaching`이라고 응답하는 동안에만 새 org를 기록합니다([하트비트의 키](#the-heartbeats-keys)). 디렉터리를 읽을 수 없거나 셀이 `serving`으로 표시되어 있으면 새 org는 503으로 응답하고, 셀이 보유한 org는 계속 서비스됩니다. 따라서 첫 attach의 3단계 이전으로 복원되었고 `loom cell restore`를 건너뛴 셀은 자신이 보유하지 않은 org를 서비스하지 않습니다. `loom doctor`가 그런 셀을 알려 주며, `loom cell restore`가 해당 mode를 올립니다.

**디렉터리는 고가용성 스토어입니다.** 디렉터리의 Postgres는 셀의 Postgres와 마찬가지로 동기식 스탠바이와 마지막 커밋까지의 시점 복구와 함께 실행되므로, 페일오버나 손상이 있어도 커밋된 데이터는 손실되지 않습니다. 디렉터리를 완전히 잃으면 장애가 발생하며 이는 안전하게 실패하는(fail closed) 방식으로 처리됩니다. 모든 셀은 자신이 보유한 org를 계속 서비스하고, 라우팅은 각 라우터 레플리카가 마지막 캐시를 서명해 둔 스냅샷(디렉터리가 바뀔 때마다 공유 스토리지에 기록됨)으로 계속됩니다. 반면 배치, 캐시되지 않은 org의 조회, 디렉터리를 읽거나 쓰는 `loom cell` 명령, 기록 중인 셀의 상태 읽기는 디렉터리가 돌아올 때까지 503으로 응답하거나 거부됩니다. 이때 `loom doctor`는 디렉터리 검사를 실행하지 않은 것으로 보고하며, `LOOM_CELL`이 설정되어 있으면 0이 아닌 코드로 종료합니다. 잃어버린 디렉터리를 셀로부터 다시 구축하는 것은 별도의 설계 주제입니다.

각 셀은 자신의 Postgres에 디렉터리 행의 구성 핑거프린트 사본(`loom.cell_self`)을 보관합니다. 프로세스는 이를 자신의 구성과 비교하며, attach와 `loom cell update`가 이를 씁니다([셀 자체의 행](#the-cells-own-row)). `loom cell restore`는 디렉터리로부터 `loom.cell_self`를 다시 씁니다. 복원된 스토어에는 셀의 배포 ID가 담겨 있으므로, 새 엔드포인트로 복원할 때는 셀의 구성에 새 주소만 있으면 됩니다. 셀을 닫거나 `placements_max`를 설정하는 일은 다음 명령 하나로 합니다.
`loom cell limit --cell <cell> [--closed | --open] [--placements-max (<n> | none)]`
이 명령은 라우터의 운영자 자격 증명으로 디렉터리에만 쓰며 셀의 스토어는 건드리지 않으므로, 셀이 중단된 상태에서도 동작합니다. 라우터는 디렉터리 행을 보고 배치를 판단합니다.

<a id="operations"></a>

## 운영

- `loom cell restore`는 스토어를 복원한 뒤 `loom reconcile`을 실행하기 전에, 디렉터리에서 셀의 행을 다시 기록합니다 ([각 셀이 실행하는 것](#what-each-cell-runs)).
- `loom cell which --org <org>`는 조직의 셀을 알려 줍니다(삭제, 복원, 지원은 여기서 시작합니다). 배치가 없는 조직에는 첫 번째 셀을 알려 주며, 조회는 이 둘을 구분하지 못합니다.
- `loom cell limit --cell <cell> --closed`는 셀이 새 조직을 받지 않도록 닫고, `--open`은 다시 엽니다. `--placements-max <n>`은 셀의 배치 할당량을 설정합니다(`--placements-max none`은 할당량을 해제합니다).
- `loom cell remove --cell <cell>`은 배치가 없고 `attaching` 상태인 셀의 디렉터리 행을 제거합니다(`--cell`은 셀의 `LOOM_CELL`이며, 그 시점에는 설정되어 있지 않습니다). 첫 번째 셀의 경우 ClickHouse 없이 `LOOM_PG_DSN`의 세션 하나로 셀의 Postgres만 읽으며, 값이 `open`으로 읽히고 행의 배포 id가 기록되어 있는 경우가 아니면 거부합니다. 즉 두 조건을 모두 충족해야 제거되며, 그렇지 않은 상태는 모두 거부됩니다. 이는 되돌리는 순서를 강제합니다. 먼저 모든 프로세스에서 `LOOM_CELL`을 해제하고(각 프로세스는 `recording`일 때처럼 동작합니다), 그다음 전체 상태 정리를 수행한 뒤, 마지막으로 제거합니다
  ([문제 해결](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)).
  행을 먼저 제거하면 모든 새 조직에 503이 응답되고, 상태를 먼저 정리하면 `LOOM_CELL`이 설정된 모든 프로세스가 차단됩니다. 배치가 있는 첫 번째 셀은 앞으로만 진행하며 되돌릴 수 없습니다. 제거된 셀의 스토어에는 가지고 있던 상태 행이 그대로 남으므로, 다시 준비하기 전에 전체 상태 정리를 실행해야 합니다.
- 라우터의 운영자 자격 증명은 `lco_`와 소문자 16진수 128자로 이루어지며(`LOOM_ROUTER_OPERATOR_SHA256`이 없는 라우터는 운영자 API에 `NO_OPERATOR_CREDENTIAL`과 함께 503으로 응답합니다), `loom cell credential new --operator`로 만듭니다. 라우터는 그 SHA-256만 보관합니다. 운영자 API의 거부 응답에는 속도 제한이 없습니다. 주소별 제한을 두면 공유 인그레스 뒤의 낯선 사용자 한 명이 모든 운영자를 잠글 수 있고, 512비트는 온라인에서 추측할 수 없기 때문입니다. 운영자 명령이 결과를 확실히 아는 경우는 연결이 열리지 않았거나 라우터 자체가 응답한 경우뿐이며, `BACKEND_UNAVAILABLE`은 예외입니다(COMMIT이 제한 시간 이후에 반영될 수 있습니다). 시간 초과, 끊어진 연결, 게이트웨이의 페이지가 나타난 뒤에는 변경이 이미 적용되었을 수 있다는 점과 재시도 시 어떻게 보이는지를 알려 줍니다. 운영자 자격 증명은 새 해시를 `LOOM_ROUTER_OPERATOR_SHA256`에 설정하고 라우터를 재시작하여 교체합니다. 복제본이 순차적으로 교체되는 동안 일부는 여전히 새 자격 증명을 401로 거부하므로, 모든 복제본이 받아들일 때까지 운영자는 명령을 다시 실행합니다. 명령은 `--router`의 라우터를, 없으면 `LOOM_CELL_ROUTER_URL`의 라우터를 루트 경로로 호출하며(라우터는 경로를 셀로 전달하므로 경로가 있으면 거부됩니다), 운영자 자격 증명은 https로만(루프백에서는 http) 보냅니다. 따라서 네트워크 내부의 `http` 라우터 주소는 셀에는 쓸 수 있지만 이 명령에는 쓸 수 없습니다.
- `loom cell credential new`는 라우터 자격 증명을 오프라인으로 만들어 SHA-256과 함께 출력합니다. `loom cell credential --cell <cell> --next <sha256>`는 새 라우터 자격 증명의 SHA-256을 셀의 `next` 해시로 기록합니다. prepare와 마찬가지로 해시를 같은 형식의 인자로 받습니다. 이 명령은 라우터의 운영자 자격 증명을 사용하고, 디렉터리에만 쓰며, 디렉터리 잠금을 잡습니다. 어떤 셀이든 그 해시를 current 또는 next로 기록하고 있거나 `next`가 대기 중이면 거부됩니다. 라우터는 배치 호출과 상태 읽기에서 둘 다 받아들이며, 모든 복제본은 `--next`로부터 `LOOM_ROUTER_DIRECTORY_CACHE_S` 이내에 이를 반영하므로, 새 자격 증명은 그 이후에 파드에 넣어야 합니다. `loom router migrate`는 `next` 해시를 읽는 라우터보다 먼저 실행하며, 교체는 모든 라우터 복제본이 이를 읽게 된 뒤에 시작합니다. current 해시만 읽는 빌드로 롤백된 라우터는 다음 해시를 가진 파드를 거부합니다. 따라서 `next`가 대기 중이지 않을 때 롤백하고(먼저 `--revert`), `--finish`부터 이전 자격 증명이 파드에서 사라지기까지의 사이에는 롤백하지 마십시오. 새 자격 증명이 셀의 파드에 들어가 있고, 첫 번째 셀의 모드가 `recording`인 동안에는 CLI 설정에도 들어가 있다면, `loom cell credential --cell <cell> --finish`가 `next`를 current로 만들고 이전 것을 버립니다. 이 명령은 볼 수 없는 것을 검사하지 않으며(라우터는 어떤 파드가 어떤 자격 증명을 가졌는지 알지 못합니다), 너무 일찍 완료한 셀은 안전하게 실패합니다. 늦어도 라우터의 셀 해시 캐시가 만료되는 시점(`LOOM_ROUTER_DIRECTORY_CACHE_S`)에는 배치 호출과 상태 읽기가 401로 응답하며, 파드가 새 자격 증명을 가지거나 이전 해시를 `--next`로 다시 기록해 완료할 때까지 계속됩니다. `loom cell credential --cell <cell> --revert`는 대기 중인 `next`를 버리므로, 잘못되었거나 유출된 것을 완료할 필요가 없습니다. `next`가 대기 중이지 않으면 `--finish`와 `--revert`는 거부됩니다.
- 새 셀의 설정에는 `LOOM_CELL`, 공개 호스트(`LOOM_PUBLIC_BASE_URL`, `LOOM_OAUTH_ISSUER`, `LOOM_JWT_ISSUER`), 키, 버킷 접두사, 구성된 조직, ID 공급자의 OIDC 클라이언트와 SCIM 토큰, 그리고 라우터 자격 증명(`LOOM_CELL_ROUTER_URL`, 파드가 보유하는 `LOOM_CELL_ROUTER_TOKEN`, `LOOM_CELL_ROUTER_TIMEOUT_S`)을 명시합니다.
- 각 셀은 `/v1/health?include=capacity`에서 초당 쓰기 수, 네임스페이스별 행 수, 키별 바이트를 보고하며, 기준은 키당 ClickHouse에서 약 13.6 KB, Postgres에서 약 6.8 KB입니다 ([대규모 메모리](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md#memory-at-scale)).
- **조직은 자신의 셀에 머뭅니다.** 셀 간에 조직을 옮기는 것은 별도의 설계가 필요한 문제입니다. 셀의 모든 프로세스에서 조직의 쓰기를 차단하고, 아무것도 이중으로 세지 않는 모든 스토어의 복사본을 만들고, 검증된 제거를 수행해야 합니다.
- **셀의 데이터는 셀의 스토어에 머뭅니다.** 다른 스토어(다른 배포 id, 버킷 이름 또는 접두사)로 옮기거나, 버킷 없이 준비된 셀에 버킷을 추가하는 것은 별도의 설계가 필요한 문제입니다. 롤아웃 중에 기존 프로세스와 새 프로세스가 서로 다른 스토어에 쓰게 되므로, 조직 이동과 마찬가지로 셀의 쓰기를 차단해야 합니다.
- **셀은 연결된 상태로 유지됩니다.** 셀을 폐기하는 것은 별도의 설계가 필요한 문제입니다. 해당 조직 데이터의 모든 사본이 사라졌다는 증거를 스토어 자체에서 확보해야 하며, 그전에는 폐기되었다고 응답해서는 안 됩니다. 그때까지 중단된 셀도 셀로 남아 있으며, 그 조직은 503으로 응답하고 이름, 발급자, 호스트, 배치는 계속 예약된 상태로 유지됩니다.

<a id="failure-modes"></a>

## 장애 유형

| 장애                                                                     | 동작                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 디렉터리가 중단됨                                                        | 호스트별, 발급자별, 첫 번째 셀로 가는 요청은 라우팅되고, 새 조직과 캐시되지 않은 조회는 503으로 응답합니다                                                                                                                                                                                                                                                                                                                           |
| 라우터의 배치 호출이 실패함                                              | 요청은 503으로 응답하고 아무것도 기록되지 않으며, 셀이 보유한 조직은 계속 처리됩니다                                                                                                                                                                                                                                                                                                                                                 |
| 셀의 발급자가 조직을 대량으로 배치함                                      | `enforced`부터 해당 셀의 배치 호출은 허용 속도를 넘으면 `Retry-After`와 함께 503으로 응답하고, 할당량이 설정된 경우 새 조직에 대한 호출은 할당량을 넘으면 503으로 응답합니다. 다른 셀은 이전처럼 배치합니다                                                                                                                                                                                                                         |
| 다른 셀의 SCIM 토큰, 또는 잘못된 셀의 호스트에 있는 애플리케이션         | 프로세스가 부팅되지 않거나 `/scim/v2`가 401로 응답하고 아무것도 기록하지 않습니다                                                                                                                                                                                                                                                                                                                                                    |
| 셀의 Postgres 또는 ClickHouse                                            | 해당 셀은 단일 배포와 같은 방식으로 실패합니다([스토리지 권한](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#failure)). 다른 셀은 계속 처리합니다                                                                                                                                                                                                                                              |
| 셀 자체의 행 또는 테넌시 모드를 읽을 수 없음                             | `LOOM_CELL`이 설정되어 있으면 프로세스는 마지막으로 읽은 행과 모드를 유효 기간 한도 내에서 유지하다가 차단됩니다. 첫 읽기가 실패한 server 프로세스는 부팅되지 않고(Postgres 마이그레이션이 대기 중이면 차단되고 준비되지 않은 상태가 됨), 읽은 적 없는 workers 자식 프로세스는 차단됩니다. 설정되어 있지 않으면 server 프로세스는 판정을 기한 없이 유지하고, 첫 읽기 실패는 부팅 실패가 됩니다(Postgres 마이그레이션이 대기 중이면 읽기가 성공할 때까지 차단됨) |
| `first` 또는 모드 행이 제거됨, 또는 테넌시 행이나 자체 행과 함께 둘 다 제거됨 | 해당 트리거가 있는 셀에서는 조직 트리거가 `enforced`처럼 동작하고 모든 프로세스가 차단됩니다. `loom doctor`가 이를 알려 주며, prepare를 다시 실행하면 행이 복구됩니다                                                                                                                                                                                                                                                              |
| 디렉터리가 등록한 셀에 상태, 테넌시 또는 자체 행이 없음                  | 열린 상태가 됩니다. `loom doctor`가 이를 알려 주며, 복원 후에는 `loom cell restore`로, 중단된 prepare 후에는 prepare 재실행으로 닫습니다                                                                                                                                                                                                                                                                                              |
| 셀의 `first` 값을 아직 읽지 못함                                         | 상태 확인 프로브와 프로브 경로를 제외한 모든 요청이 503으로 응답합니다(SCIM은 `Retry-After` 포함). 프로세스는 준비되지 않은 상태가 되며 워커를 실행하지 않습니다(workers 자식 프로세스, 또는 Postgres 마이그레이션이 대기 중인 server 프로세스이며, 그 외의 server 프로세스는 부팅에 실패합니다)                                                                                                                                  |
| 다른 셀의 조직에 대한 요청                                               | 검증 후 409 `WRONG_CELL`, 아무것도 기록되지 않습니다                                                                                                                                                                                                                                                                                                                                                                                 |
| 보유하지 않은 조직에 대한 플랫폼, `*` 조직 또는 principal 없는 호출      | 첫 번째 셀에서는 디렉터리가 `attaching`으로 응답하거나 `serving` 응답 전에 읽을 수 없으면 503, `serving`이 된 후와 이후 셀에서는 409 `WRONG_CELL`입니다                                                                                                                                                                                                                                                                              |
| 풀러가 셀 세션에서 테넌시 마커를 제거함                                  | `cell_marker` 준비 상태 검사가 `enforced`와 `partial`에서는 실패하고 `recording`에서는 경고합니다. 하트비트는 `marked`를 false로 보고하며 attach는 해당 프로세스를 거부합니다                                                                                                                                                                                                                                                        |
| 셀이 이전 시점으로 복원됨                                                | `loom cell restore`가 시작하기 전에 배치된 조직의 행을 다시 기록합니다                                                                                                                                                                                                                                                                                                                                                               |
| 첫 번째 셀이 prepare 이전으로 복원되었고 아직 attach되지 않음            | `LOOM_CELL`이 설정된 프로세스에서는 prepare를 다시 실행할 때까지 상태 확인 프로브와 프로브 경로를 제외한 모든 요청이 503으로 응답합니다                                                                                                                                                                                                                                                                                              |
| 디렉터리를 잃음                                                          | 모든 셀은 보유한 조직을 계속 처리합니다. 디렉터리가 복구될 때까지 배치와 캐시되지 않은 조회는 503으로 응답하고 디렉터리 명령은 거부됩니다                                                                                                                                                                                                                                                                                             |
| 셀이 `recording` 상태이고 디렉터리를 읽을 수 없음                        | 새 조직은 503으로 응답하고, 보유한 조직은 계속 처리됩니다                                                                                                                                                                                                                                                                                                                                                                            |
| 첫 attach 중 프로세스가 멈춤                                             | `--wait` 이후 attach가 거부되고 셀은 `recording`으로 돌아갑니다                                                                                                                                                                                                                                                                                                                                                                      |
| 첫 attach 중 기록 insert가 열린 채 유지됨                                | 대기에 쓸 `--wait`가 너무 적게 남으면 attach는 시도를 중단하고 다시 읽은 모드를 보고합니다. 다시 실행하면 이어서 진행합니다                                                                                                                                                                                                                                                                                                          |
| attach가 모드 테이블의 잠금을 쥔 채 멈춤                                 | Postgres가 수 초 내에 세션을 종료하고 잠금을 해제하며, 새 조직은 기한 내에 응답합니다                                                                                                                                                                                                                                                                                                                                               |
| 4단계의 스냅샷 이전부터 열려 있던 트랜잭션                               | `--wait`가 소진되면(준비된 트랜잭션은 즉시) attach는 기다린 대상을 알리며 거부하고 셀을 `enforced`에 둡니다                                                                                                                                                                                                                                                                                                                          |
| `LOOM_CELL`이 설정되지 않은 CLI 명령이 attach의 3단계 이전에 시작됨      | 첫 번째 셀이 `recording`일 때 상태를 읽었으므로 `serving` 이후에도 ClickHouse에 계속 기록합니다. 런북은 attach 전에 모든 CLI에 `LOOM_CELL`을 설정합니다                                                                                                                                                                                                                                                                              |
| 상태 읽기 기능이 없는 빌드의 CLI                                         | `enforced` 셀에서도 거부되지 않습니다. 모든 CLI와 CI 이미지는 attach 전에 해당 읽기 기능이 있는 빌드를 실행해야 합니다([업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#upgrade-procedure))                                                                                                                                                                                                      |

<a id="rolling-upgrades"></a>

## 롤링 업그레이드

테넌시 검사, 배치 호출, 셀의 상태 읽기, CLI의 org 선언, `LOOM_CELL`, `loom cell prepare`, `scim.refuses_subject`, grant가 저장하는 이메일, `loom.cell_self`, 프로세스의 핑거프린트를 자기 행과 대조하는 요청 게이트와 준비 상태 검사, 다른 셀의 SCIM 토큰 거부, SCIM 요구 사항, 그리고 하트비트의 모드, 핑거프린트, `LOOM_CELL`은 한 릴리스에 함께 배포됩니다. `LOOM_CELL`이 설정되지 않은 프로세스의 게이트, 세션 마커, org 트리거도 한 릴리스에 함께 배포됩니다. 첫 번째 셀의 prepare는 그 이전 릴리스의 프로세스를 받아들이며, 이 프로세스는 셀이 `recording` 상태인 동안 서비스합니다. 그 이후 릴리스에 포함되어 자체 하트비트 키를 읽는 `loom cell attach`는 살아 있는 모든 프로세스가 그 릴리스를 실행할 때까지 거부합니다. 따라서 연결된 셀에서 지원되는 유일한 롤백은 마커를 보내는 빌드로 이어집니다. org 트리거의 마이그레이션은 추가 방식이며, 한 번도 prepare하지 않은 배포에서는 트리거가 아무 일도 하지 않습니다(상태 행이 없고, `first` 행의 규칙이 적용됩니다). `LOOM_CELL`이 설정되지 않은 프로세스는 모드 행과 `first` 행, 그리고 테넌시 행이나 자체 행이 존재하는지만 읽습니다. 이는 Postgres 권한 아래에서만 이루어지며, 한 번도 prepare하지 않은 배포에는 이 행들이 없습니다(테이블은 빈 상태로 생성됩니다). 따라서 N-1 빌드와 N 빌드는 변경 없이 나란히 서비스합니다. 라우터는 호스트, 발급자, 첫 번째 셀을 기준으로 라우팅하며 셀의 op를 기준으로 하지 않습니다. 따라서 셀의 릴리스는 라우터의 릴리스를 기다리지 않지만, 다음 문단에서 설명하는 한 가지 경우는 예외입니다.

하트비트의 핑거프린트 옆에 있는 키들([하트비트의 키](#the-heartbeats-keys))은 attach 릴리스 고유의 하트비트 키입니다. 이 키들보다 이전 빌드는 핑거프린트의 버전과 필드만 읽으므로 더 새로운 빌드의 하트비트를 그대로 받아들이며, attach는 이 키를 보고하지 않는 프로세스를 거부합니다. 이 릴리스는 라우터의 릴리스를 기다려야 합니다. 준비된 첫 번째 셀은 첫 셀 상태를 읽을 때부터 `serving`을 읽을 때까지 상태 경로를 요청하는데, 이 요청에 캐시로 응답하는 것은 이 릴리스의 라우터뿐이므로, 모든 라우터 레플리카가 어떤 셀의 프로세스보다 먼저 이 릴리스를 실행해야 합니다([업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#upgrade-procedure)).

<a id="invariants"></a>

## 불변 조건

- org는 배치(placement)에 지정된 셀 정확히 하나가 서비스하며, 그 배치는 삭제되거나 변경되지 않습니다.
- `LOOM_CELL`이 설정된 프로세스는 구성이 자신이 속한 셀의 own row 값과 일치하지 않는 한(디렉터리의 중복 거부가 이를 확인했습니다) 헬스 프로브와 프로브 라우트에만 응답하고 워커를 실행하지 않습니다. 상태 row가 `enforced`로 집계되거나 `partial` 상태(`first` row의 규칙)에 있는 셀에서 `LOOM_CELL`이 설정되지 않은 프로세스도 헬스 프로브와 프로브 라우트에만 응답하고 워커를 실행하지 않습니다.
- 어떤 bearer 토큰 발급자, 호스트, OIDC 클라이언트, org 패턴, 버킷 접두사도 두 셀이 동시에 허용하지 않으며, 어떤 배포 id나 라우터 자격 증명도 두 셀이 보유하지 않습니다.
- 모든 보안 경로는 실패 시 차단(fail closed)되며, 예외는 네 가지입니다. 첫째, `LOOM_CELL`이 설정되지 않은 서버 프로세스는 상태 row 읽기가 실패해도 오래됨 한도 없이 기존 판정을 유지합니다. 즉 `open`과 `recording` 상태에서는 단일 배포의 부분 장애와 마찬가지로 열린 상태를 유지하고, 그 밖의 모든 상태에서는 차단합니다. 첫 읽기가 실패하면 부팅이 실패하며, Postgres 마이그레이션이 보류 중이면 읽기가 성공할 때까지 차단 상태로 남습니다. 둘째, 상태, 테넌시 또는 own row가 없는 등록된 셀(Postgres가 prepare 이전으로 복원되었거나 prepare가 row 기록 전에 중단된 경우)은 `loom cell restore`(복원 후) 또는 prepare 재실행(중단된 prepare 후)까지 열려 있으며, 그동안 `loom doctor`가 이를 알려 줍니다. 읽을 수 없는 row, 모드 또는 `first` 값은 거부됩니다. 디렉터리에 접근할 수 없으면 배치, 캐시되지 않은 조회, 디렉터리를 읽거나 쓰는 `loom cell` 명령, 기록 셀의 상태 읽기는 거부되지만, 각 셀은 이미 보유한 org를 계속 서비스합니다. 셋째, org 트리거나 테이블의 `loom.tenancy` 가드를 만들거나 활성화하지 못하거나, `loom.cell_first`의 트리거를 always로 되돌리지 못하는 마이그레이션 부팅(세 번의 시도 각각이 잠금을 최대 100 ms 동안 기다렸는데도 잠금을 얻지 못했거나, 역할이 변경할 수 없는 테이블이 있는 경우)은 이를 로그로 남기고 서비스를 계속하며, 이후 부팅이 성공할 때까지 해당 테이블을 보호하지 않은 채로 둡니다. 트리거는 마커를 보내지 않는 기록자에 대한 보조 장치일 뿐이고, 보조 장치 때문에 부팅을 거부하면 셀이 중단되며, attach는 누락된 트리거를 거부합니다. 넷째, 접근을 되돌려 줄 수 없는 org 비종속 폐기 명령(범위를 좁히거나 만료시키는 경우가 아닌 일반 `loom revoke-token`, SQL 사용자 폐기, `loom signing-key retire`, `loom bot disable`, `loom sso unlink`)은 `LOOM_CELL`이 설정되어 있고 Postgres가 응답하지 않아 셀의 `first` row 읽기가 실패하면, 폐기는 장애 중에도 동작해야 하므로 셀을 확인하지 않았다고 출력하고 실행됩니다. 권한 누락을 포함한 그 밖의 읽기 실패는 거부됩니다.

<a id="source-entry-points"></a>

## 소스 진입점

- `server/core/cell_probe.py`: 프로브 라우트와 프로브 리스너입니다. 모든 웹 프로세스가 이 리스너로 연결을 받고, 워커 자식 프로세스는 이를 열지 않습니다.
- `server/core/cell.py`: 셀 자체의 상태(`loom.cell_first`, `loom.tenancy_mode`, `loom.cell_self`), 배포의 상태 규칙(`state`, `refresh`가 읽는 행을 대상으로 하며, 그중에 `loom.tenancy`의 행이 있는지 여부), 지문(fingerprint)과 `gate_reason`, 그리고 `LOOM_CELL`이 설정되었거나 설정되지 않은 프로세스에 대한 게이트를 담고 있습니다. 이 게이트는 요청 미들웨어(`server/transport/model_maintenance.py`), `verify_token`, 준비 상태 확인, 워커의 리스, 하트비트 읽기에서 사용됩니다. `server/boot.py`의 `start_cell_gate`는 서버 프로세스가 부팅할 때 수행하는 읽기입니다.
- `server/core/cell_triggers.py`: 조직 트리거의 마커, `ensure`(마이그레이션을 수행하는 부팅에서 트리거와 `loom.tenancy` 가드를 생성하고 복구함), `missing`(`loom doctor`가 알려 주는 항목)을 담고 있으며, 해당 함수는 `schemas/pg_migrations/011_tenancy_triggers.sql`과 `012_tenancy_guard.sql`에 있습니다. `server/cli/doctor_cell.py`: `loom doctor`의 셀 점검입니다.
- `server/cli/cell_scan.py`: 첫 번째 연결 시의 조직 스캔이며, 어떤 명령도 호출하지 않는 라이브러리입니다. 두 저장소에서 `org` 컬럼을 가진 테이블을 엔진별로, 그리고 삭제(erasure)의 분류에 비추어 판단하고, 클러스터의 모든 호스트가 같은 목록을 보이게 하며, `LOG_TABLES` 밖에 있는 각 테이블의 고유 조직을 모읍니다. `server/cli/cell_writers.py`: ClickHouse 작성자 점검입니다(운영자의 허용 목록에 없는 사용자, 사용자 디렉터리, 오브젝트, 레플리카). `server/cli/cell_ch.py`: 두 모듈이 공유하는 부분입니다(클러스터의 호스트, 호스트별 읽기).
- `schemas/pg_migrations/008_cells.sql`, `schemas/pg_migrations/009_cell_probe.sql`, `schemas/migrations/094_cell_heartbeats.sql`: 셀의 테이블입니다.
- `server/auth/tenancy.py`(`ensure_held`): 테넌시 확인과 배치 호출이며, op 게이트(`server/transport/gates.py`), `check_authorized`, `admit_org`, 그리고 조직을 지정하는 라우트에서 실행됩니다. `server/transport/tenancy_gate.py`는 레지스트리 밖에서 해당 조직 안에서 동작하는 라우트에 대해 토큰 자체의 조직을 확인하며, `tests/unit/test_cell_tenancy.py`에는 모든 라우트의 목록이 있습니다.
- `server/router/app.py`(`loom router serve`): 배치 API, 첫 번째 셀의 상태 읽기(첫 번째 셀에서 `server/core/cell_router.py`가 수행함), 규칙 1~4에 따른 라우팅(결정하는 `server/router/routing.py`와 포워딩), 배치된 조직의 캐시를 가진 조직 조회(`loom login --org`, `loom.credentials.org_server`가 요청함), 그 속도 제한(`server/router/limits.py`), 배치가 통과하는 점검을 담고 있습니다. 또한 첫 번째 셀의 연결 라우트를 포함한 운영자 API가 있으며, `loom cell limit`, `loom cell credential`, `loom cell remove`(`server/cli/cell.py`, `loom cell which` 포함)가 라우터의 운영자 자격 증명(`LOOM_ROUTER_OPERATOR_TOKEN`, 라우터는 `LOOM_ROUTER_OPERATOR_SHA256`만 보관함)으로 이를 호출합니다. `server/router/directory.py`와 `schemas/router_migrations/`: 라우터 자체의 Postgres 데이터베이스(`LOOM_ROUTER_PG_DSN`, `loom router migrate`)에 있는 디렉터리입니다.

셀 코드의 나머지는 이 페이지를 구현하는 풀 리퀘스트에서 추가됩니다. 이 코드는 다음을 기반으로 합니다.

- `server/auth/jwt.py`(`verify_token`, `AuthUnavailable`): 지문 게이트가 가장 먼저 실행되는 곳입니다.
- `server/auth/scim.py`(`tokens`)와 `server/auth/scim_routes.py`(`scim_settings_problem`, `_authorized`): SCIM 토큰 파서와 점검입니다.
- `server/core/instances.py`: 모드, 지문, `LOOM_CELL`, 그리고 지문과 함께 있는 키를 보고하는 하트비트입니다.
- `server/workers/leader.py`: 게이트된 프로세스가 물러나 있는 리스입니다.
- `server/core/pg.py`(`same_deployment`): 두 저장소가 모두 가지고 있는 배포 id입니다.
- `server/transport/gates.py`(`resolve_org`, `authorize`): 테넌시 확인이 실행되는 곳입니다.
- `server/cli/_ch.py`(`run_connected`, `connect_checked`, `connect_declared`): CLI의 조직 선언이며, `tests/unit/test_cell_cli_orgs.py`가 모든 connect에 이를 요구합니다.
- `server/auth/authz.py`(`check_acted_for`, `_check_creator`)와 `server/auth/oauth.py`(`_refresh_session`): 대리 수행과 갱신에 대한 SCIM 점검입니다.
- `server/identity/app/scim_groups.py`(`_caller`): 두 번째 SCIM 라우트입니다.

<a id="rejected"></a>

## 기각된 안

- **셀들이 공유하는 컨트롤 플레인** (키, 권한 부여, 워커를 하나의 세트로 두고 데이터만 org별로 분할): 보안 검사, 워커 리스, 삭제, 정책 세대, 감사 체인이 각각 여러 저장소에 걸치게 되며, 분할마다 별도의 프로토콜이 필요합니다.
- **검증 이전, 첫 요청 시점에 org를 배치하는 방식**: 누구나 org의 셀을 선택할 수 있고, 한 셀에서 발급된 토큰이 다른 셀에 배치된 org를 대상으로 사용될 수 있습니다.
- **org를 생성하는 각 경로가 직접 배치하도록 경로 목록을 두는 방식**: org는 목록으로 따라잡을 수 없을 만큼 다양한 경로(게이트웨이 및 연합 토큰, 봇, 가져오기)로 생겨납니다. 검증된 확인 단계는 모든 요청이 거치는 유일한 지점입니다.
- **진행 중인 플로우를 한 셀에서 다른 셀로 리디렉션하는 방식**: 플로우의 클라이언트, 코드, 리프레시 토큰은 해당 플로우를 시작한 셀에 존재합니다.
- **라우터가 모든 셀을 위해 아이덴티티 제공자의 사용자를 보유하는 방식**: 각 이메일이 각 셀에 미치는 범위, 디렉터리를 잃어도 유지되는 버전, 푸시와 풀이 각각 별도의 프로토콜이 되는데, 아이덴티티 제공자는 이미 사용자가 할당된 모든 애플리케이션의 프로비저닝을 해제합니다.
- **모든 레플리카가 모든 셀의 저장소에 접근하는 방식**: 레플리카당 셀마다 풀이 하나씩 필요하며, 이는 [테넌트별 데이터베이스](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#a-database-per-tenant)가 기각하는 비용입니다.
- **org 내에서 네임스페이스로 라우팅하는 방식**: org 전체에 걸친 작업(삭제, 네임스페이스 간 ID 해석, 공유)이 여러 셀에 걸치게 됩니다. 규모가 큰 org에는 전용 셀을 할당합니다.

<a id="tests"></a>

## 테스트

CI의 Postgres 잡에서 셀 두 개와 라우터로 수행하는 통합 테스트:

- 각 셀에 대한 신규 org의 검증된 요청은 동시 요청에서도 org를 한 번만 배치하고, 다른 셀은 `WRONG_CELL`로 응답한다. 게이트웨이가 발급한 org, 최종 사용자 발급자의 `prefix*` org, 봇의 org는 `enforced` 이후에도 같은 방식으로 배치되며, 플랫폼 principal이 보유하지 않은 org를 요청하면 아무것도 배치되지 않는다.
- MCP의 배치 항목과 모든 CLI 명령을 포함한 모든 라우트는 다른 셀의 org를 거부하고, 해당 셀의 Postgres나 ClickHouse에 아무것도 쓰지 않는다(라우트, op 필드, CLI 전수 조사가 나머지를 다룬다).
- 첫 attach는 어떤 테이블에든 행이 있는 모든 org를 배치한다. attach 도중 처음 발견된 org는 4단계에서 배치된다. 2단계의 스냅샷과 `enforced` 사이에 Postgres 직접 insert가 쓴 org, 그 사이에 이전 CLI가 쓴 ClickHouse 행, 그 사이에 카탈로그에 등록된 버킷 객체도 마찬가지로 4단계에서 배치된다. 자신의 행이나 모드를 읽는 데 실패한 시간이 `LOOM_JWT_REVOCATION_MAX_STALE_SECONDS`를 넘은 프로세스는 게이트되며, 읽기가 성공하면 다시 서비스한다. `LOOM_CELL`이 설정되지 않은 파드는 attach된 셀과, prepare와 attach 사이의 이후 셀에서는 준비되지 않은 상태가 되어 해당 설정을 이름으로 알리고, bearer 요청에 503으로 응답하며, 헬스 프로브는 통과하고, 프로브 라우트에 응답하고, 워커를 실행하지 않는다. `recording` 상태의 첫 셀에서는 계속 서비스하며, 읽기에 실패해도 마지막으로 읽은 모드를 유지한다. 3단계나 4단계가 셀을 그 모드로 되돌린 뒤의 `recording`도 포함한다. org를 선언하는 CLI 명령은 이것이 설정되지 않은 상태에서 `enforced` 또는 `partial` 셀에서는 거부되고, org와 무관한 명령(토큰 폐기)은 실행되며, 한 번도 prepare되지 않은 배포에서 Postgres가 내려가 있어도 실행된다. `loom cell` 저장소 명령은 거부된다. `loom cell limit --closed`는 셀의 Postgres가 내려가 있어도 성공한다. `loom cell credential --cell <cell> --next` 이후에는 두 자격 증명 모두 배치하고 상태를 읽을 수 있으며, `--finish`는 이전 자격 증명을 거부한다. 파드가 새 자격 증명을 갖기 전에 finish된 셀의 경우 라우터는 그 호출을 401로 거부하고, 그 셀의 요청은 아무것도 쓰지 않고 503으로 응답하며, 이전 해시를 다시 기록하면 복구된다. `--revert`는 대기 중인 `next`를 버리며 이후 그것은 거부되고 이전 자격 증명은 계속 배치한다. 대기 중인 상태에서의 두 번째 `--next`와, 다른 셀이 current 또는 next로 기록한 해시는 거부된다. 디렉터리를 사용할 수 없는 동안 `loom cell limit`과 `loom cell credential --next`, `--finish`, `--revert`는 거부된다. 라우터 레플리카 두 개에 걸쳐 `placements_max`보다 하나 적은 상태에서 동시에 배치하면 하나만 기록된다. `LOOM_CELL_ROUTER_TOKEN`이 설정된 상태에서 org를 선언하는 CLI 명령은 `enforced`(`attaching` 포함)가 된 첫 셀과 이후 셀에서는 해당 토큰을 이름으로 알리며 거부되고, `recording` 상태의 첫 셀에서는 실행되어 org를 기록한다. 첫 셀이 가진 org 수보다 작은 `placements_max`로 attach하면 모두 배치되며, 이후 셀의 attach가 쿼터를 넘거나 닫혀 있으면 org를 이름으로 알리며 거부된다. 2단계 전에 `--closed`와 `placements_max`를 설정한 첫 셀은 attach되고, 2단계와 `enforced` 사이에 요청이 기록한 org는 503 없이 4단계에서 배치된다. 3단계가 셀의 모드를 기록한 뒤에도 캐시가 여전히 `recording`인 프로세스는 신규 org의 요청을 배치 호출로 보내며, 닫힌 셀은 이를 503으로 응답한다. insert가 `enforced`를 발견한 CLI 명령은 org를 이름으로 알리며 거부하고 배치 호출을 하지 않는다. 3단계의 거부된 대기나 4단계의 재확인이 셀을 `recording`으로 되돌린 뒤에는 신규 org가 배치 호출 없이 기록되며, 캐시가 여전히 `enforced`인 프로세스에서는 캐시가 만료될 때까지 게이트를 통해 배치된다. attach의 모드 기록과 기록 insert의 각 순서는 위에서 설명한 대로 유지된다(실행 중, 기록 도중 시작, 각각 한 번의 시도보다 짧은 겹치는 insert의 연속과 한두 번의 시도 안에 `enforced`를 설정하는 attach, 여러 번의 시도에 걸쳐 유지, `--wait`이 거의 남지 않을 때까지 유지, 멈춘 attach, 타임아웃으로 끊긴 커밋, 스탠바이를 기다리는 동안 연결이 끊긴 커밋, 해당 백엔드가 사라진 뒤에야 읽고 `enforced`로 읽히면 다시 내구적으로 기록). `enforced`가 되기 전에 첫 문장을 실행한 `REPEATABLE READ` 트랜잭션은 attach의 role이든 두 번째 role이든 끝날 때까지 4단계를 붙잡으며 보유하지 않은 org에 대한 쓰기는 이후 배치된다. 그 뒤에 첫 문장을 실행한 것은 트리거가 거부한다. attach가 락을 잡은 뒤 커밋이 보이기 전에 시작한 트랜잭션은 4단계를 붙잡는다. `recording`에서 열려 한 번의 `--wait`보다 오래 지속되는 트랜잭션은 거부 이후와 `loom cell restore`가 모드를 올린 이후에도 재실행의 4단계를 붙잡는다. loom 테이블의 autovacuum 워커는 4단계를 붙잡지 않고, `recording` 이후 트랜잭션이 열려 있는 백그라운드 워커는 붙잡는다. 준비된 트랜잭션(대기 중에 `max_prepared_transactions`를 올려 재시작한 뒤)은 4단계가 즉시 이를 이름으로 알리며 거부하게 하고 모드는 여전히 `enforced`이며, 해결되고 설정이 0으로 돌아올 때까지 재실행은 거부된다. 같은 서버의 두 번째 데이터베이스에서 열린 쓰기 트랜잭션은 4단계를 붙잡고 이름이 알려진다. `hot_standby_feedback`이 켜진 동기 스탠바이나 두 번째 스탠바이의 긴 읽기는 이를 붙잡지 않으며, 그 사이에 실행되는 베이스 백업도 마찬가지다. `replication=database` 연결에서 열려 있는 쓰기는 4단계를 붙잡고, `recording`에서 열려 `enforced` 전에는 아무것도 쓰지 않은 해당 연결의 `REPEATABLE READ` 트랜잭션도 마찬가지다. 셀의 데이터베이스에서 `--wait`을 넘기는 긴 논리 덤프(`REPEATABLE READ` 읽기 전용 트랜잭션)는 4단계를 이를 이름으로 알리며 거부하게 하고 셀은 `enforced`로 남는다. `pg_read_all_stats`가 없거나 `max_prepared_transactions`가 0보다 큰 첫 셀의 attach는 1단계 전에 거부되고 모드는 `recording`으로 남으며, 이후 셀의 attach는 어느 쪽도 요구하지 않는다. org 트리거가 없거나 비활성화된 경우 attach가 거부하고 `loom doctor`가 이를 알린다. 모드 행이 삭제된 `enforced` 셀에서 보유하지 않은 org에 대한 쓰기는 거부되고 `loom doctor`가 상태를 알린다. 그 셀에서 `LOOM_CELL`이 설정되지 않은 파드는 준비되지 않은 상태로 워커를 실행하지 않으며, org를 선언하는 CLI 명령은 파드와 마찬가지로 거부된다. `enforced` 셀의 `first` 행을 갱신, 삭제, truncate하는 것은 `session_replication_role = replica`에서도 거부되며, `first` 행 트리거가 없거나 비활성화된 경우 attach가 거부하고 `loom doctor`가 이를 알린다. 모드 행이 제거된 셀에서 `LOOM_CELL`이 설정된 실행 중 프로세스는 bearer 요청에 503으로 응답하고 워커 패스를 실행하지 않으며, 실행 중에 `loom cell prepare` 재실행이 행을 다시 기록하면 다시 서비스한다. 디렉터리에 등록되었지만 state, tenancy, 자체 행이 없는 셀은 `loom doctor`가 이름으로 알리고, `LOOM_CELL`이 설정된 그 프로세스는 준비되지 않은 상태로 남으며, 설정되지 않은 프로세스는 단일 배포로 서비스한다. `loom cell restore`는 두 행을 모두 다시 기록하고, attach된 셀은 다시 서비스하며 attach되지 않은 셀은 prepare 재실행 이후 서비스한다. 두 행이 모두 없고 tenancy 행만 있는 셀과 자체 행만 있는 셀에서는 함수가 보유하지 않은 org를 거부하고(그곳에서는 부팅이 트리거를 만들지 않는다), 모든 프로세스가 게이트되며 `loom doctor`가 이를 알리고, prepare 재실행이 행을 다시 기록한다. prepare 이전으로의 attach된 첫 셀의 Postgres 전용 복원은 `loom doctor`가 알리고 `loom cell restore`가 닫는다. attach된 셀에서 `loom cell update`가 대기 중일 때 두 값의 프로세스가 공존하고 `loom.cell_self`가 사라진 상태에서 prepare를 재실행하면 두 값을 모두 다시 기록하고 두 프로세스 집합이 계속 서비스하며, attach 전에는 두 구성을 거부한다. `current`가 없고 파드의 구성이 디렉터리 행과 다른 attach된 셀에서의 prepare 재실행은 거부되며, 하트비트가 다른 버킷 접두사를 보고하는 attach 이전의 prepare 재실행도 거부된다. 행의 `current`도 `next`도 아닌 자격 증명 해시를 준 prepare 재실행은 거부된다. 접두사에 데이터가 있는 `serving` 상태의 이후 셀에서의 prepare 재실행은 제거된 모드 행을 다시 기록한다. 모드 행은 있고 `first` 행이 없는 셀에서는 함수가 보유하지 않은 org를 거부하고(그곳에서는 부팅이 트리거를 만들지 않는다), 모든 프로세스가 게이트되며 `loom doctor`가 이를 알리고, prepare 재실행이 행을 다시 기록한다. 모드 행이 `recording`으로 설정된 이후 셀은 아무것도 기록하지 않고, 트리거가 보유하지 않은 org를 거부하며, `LOOM_CELL`이 설정된 프로세스는 `enforced`처럼 서비스하고, `LOOM_CELL`이 설정되지 않은 파드는 준비되지 않은 상태로 워커를 실행하지 않으며, `loom cell prepare`가 그 행을 이름으로 알리고, `LOOM_CELL_ROUTER_TOKEN`이 설정된 상태에서 org를 선언하는 CLI 명령은 이를 이름으로 알리며 거부되고, 라우터는 그 상태 읽기를 거부한다. 한 번도 prepare되지 않은 배포에서 N의 마이그레이션 이후 빌드 N-1 프로세스의 `memory.set`과 전달 패스는 성공하며 tenancy 행을 쓰지 않는다. `recording` 상태의 첫 셀에서는 부팅이 org 트리거를 만들지 않고, 수동으로 만든 트리거는 상태를 읽되 아무것도 조회하지 않는다. 보유하지 않은 org에 대해 `session_replication_role = replica`에서 수행한 쓰기는 건너뛰어진다(origin 트리거). 보유하지 않은 org의 행을 삽입하는 `INSERT ... ON CONFLICT DO UPDATE`는 거부되고 그 org의 기존 행에 충돌하는 경우는 거부되지 않으며, 표시된 세션의 모든 쓰기는 통과한다. `enforced` 셀의 트리거는 erasure가 `org` 컬럼으로 분류하는 모든 테이블을 세 가지 제외 항목을 빼고 모두 포괄한다. attach가 모드 테이블의 락을 잡고 있는 동안 org 키 쓰기는 즉시 반환되며, 신규 org 요청은 데드라인 안에 응답하고 모드 캐시 읽기는 내내 즉시 반환된다. 3단계의 락 거부 이후 `loom cell restore`는 셀을 `enforced`로 두고, 재개된 attach는 3단계의 대기부터 실행된다. `lcr_` 형식이 아닌 `LOOM_CELL_ROUTER_TOKEN`은 부팅 시 거부되고 `loom doctor`가 이를 알린다. `loom cell credential new`는 디렉터리와 저장소에 접근할 수 없어도 그 형식의 자격 증명과 그 SHA-256을 출력한다. prepare와 `--next`는 소문자 16진수 64자가 아닌 인자를 거부하며, 자격 증명과 128자 비밀 값 자체도 포함하여 아무것도 저장하지 않는다. 첫 셀이 `recording`에서 기록했으나 데이터가 없는 org는 `loom doctor`가 나열한다. 쿼터가 설정되지 않은 배치 폭주는 각 라우터 레플리카에서 속도 제한에 묶이고, `loom doctor`는 그 셀을 쿼터가 없는 셀로 알리며, 한 레플리카에서 그 제한을 넘겨 거부된 호출은 최대 60초의 `Retry-After`와 함께 503으로 응답하고, 그 사이에 그 셀의 다른 호출이 허용되지 않았다면 해당 레플리카에서의 재시도는 허용된다. 디렉터리 행이 아직 없는 셀의 첫 prepare는 deployment-id 확인을 통과한다. 셀에서 `LOOM_PG_DSN`이나 `LOOM_STORAGE_AUTHORITY`를 잃은 파드나 CLI는 authority 확인에서 거부된다. 첫 셀의 기존 토큰, 리프레시 토큰, OAuth 클라이언트는 전환 내내 계속 동작하며, 공유 호스트를 통한 로그아웃은 그 리프레시 토큰을 폐기한다.
- attach는 공유 발급자, 루트 시크릿, Keeper 경로, 중첩된 버킷 접두사, 구성된 org, 데이터를 가진 두 번째 셀, 실행 중에 시작된 두 번째 attach를 거부한다.
- 두 번째 셀에 있는 org에 대한 OIDC 로그인, MCP 클라이언트의 인증, 디바이스 플로우는 조회 이후 해당 셀의 호스트에서 완료된다. `loom login --org`는 `NO_CELL`과 라우터가 없는 배포에서는 호스트를 유지하고, 429의 `Retry-After` 이후 `--wait`이 소진될 때까지 재시도한 다음 속도 거부로 거부하며, 디렉터리가 내려간 동안에는 라우터가 캐시한 org의 셀 호스트에서 플로우를 시작하고 캐시하지 않은 org에 대해서는 플로우를 시작하지 않고 거부한다.
- SCIM이 켜져 있으면 아이덴티티 공급자가 셀에 할당하지 않은 사람은 그곳에서 로그인, 리프레시를 할 수 없고, 대리 행위의 대상이 될 수 없으며, 게이트웨이 토큰을 사용할 수 없다. 셀의 애플리케이션으로 푸시된 비활성화는 그곳에서 해당 사람을 종료시킨다. 플랫폼 관리자 봇은 SCIM이 모두를 비활성화한 셀에도 여전히 접근할 수 있으며, attach는 프로비저닝되지 않은 활성 subject가 있거나 다른 셀의 OIDC 클라이언트를 공유하는 셀을 거부한다.
- `enforced`를 설정한 뒤 대기가 지나기 전에 3단계에서 멈춘 attach는 SCIM 선행 조건 이전의 대기부터 재개되며, SCIM 선행 조건에 의해 거부된 attach도 대기부터 재개되고 모드는 여전히 `enforced`이다. 디렉터리 트랜잭션 전에 거부된 이후의 attach는 `attach_started_at`을 비워 두므로, 재실행은 새 셀의 거부 조건을 다시 확인하고, 재개된 첫 attach는 구성된 org가 이 셀에 이미 배치된 것을 발견하고 계속 진행한다.
- 첫 attach의 `enforced` 이전으로 복원된 셀은 `loom cell restore`로 모드를 되돌려 받는다. `loom cell restore`를 건너뛴 셀은 보유하지 않은 org에 대해 503으로 응답하며(다른 셀의 org 포함), 그 org의 tenancy 행을 쓰지 않고, `loom doctor`가 이를 알린다. `LOOM_CELL` 롤아웃 중과 prepare와 attach 사이에 디렉터리가 중단되어도 첫 셀은 보유한 org를 계속 서비스하며, 신규 org는 `LOOM_CELL`이 설정된 모든 프로세스에서 503으로 응답한다. 상태 읽기는 attach의 2단계 전에 `attaching` 상태인 첫 셀에서 허용되며 지명된 셀 자신의 자격 증명으로만 허용되고, 거부되거나 늦은 응답은 읽을 수 없음으로 센다.
- N-1에서 기록되어 N에서 갱신된 grant는 그 사람의 행과 대조하여 확인되며, SCIM을 읽을 수 없는 동안의 갱신은 503으로 응답하고 세션을 유지하며, `loom cell prepare` 이전에 `LOOM_CELL`이 설정된 프로세스는 준비되지 않은 상태로 남는다.
- 첫 attach 중에 프로비저닝된 적 없는 사람이 위임한 토큰은 `enforced` 이후 거부된다. 봇을 대신하는 게이트웨이는 서비스되고 단순 핸들은 거부된다.
- 디렉터리를 사용할 수 없으면 모든 셀은 보유한 org를 서비스하고, 배치는 503으로 응답하며, 셀의 `loom doctor`는 디렉터리 검사를 실행하지 않음으로 보고하고 0이 아닌 값으로 종료한다.
- `LOOM_CELL`은 모든 파드가 준비된 상태에서 `loom cell prepare` 이후, attach 이전에 롤아웃된다.
- 공유 호스트의 배포 이전에 빈 셀을 prepare하는 것은 거부되며, 다른 셀의 스냅샷에서 복원된 셀은 prepare에서 거부된다.
- 디렉터리 기록과 셀 기록 사이에서 중단된 prepare는 `LOOM_CELL`이 롤아웃된 상태에서 게이트된 프로세스에 대해 `probe_url`을 통해 재실행된다. 하트비트가 현재 `current`도 `next`도 아닌 값과 일치하는 attach 이전의 prepare 재실행은 거부된다. `next`만 잃은 attach된 prepare 재실행은 이를 다시 기록하고, 현재 `current`가 디렉터리와 다른 경우에는 이를 덮어쓴다. attach된 첫 셀을 prepare 이전으로 Postgres만 복원한 뒤 prepare만 재실행하면 `loom doctor`가 누락된 tenancy 행을 알리며, `LOOM_CELL`이 설정되지 않은 파드는 재실행까지 그곳의 모든 org를 서비스하고 이후에는 게이트되지만, `LOOM_CELL`이 설정된 경우 org는 배치 호출을 통해 tenancy 행을 되찾는다. `partial` 상태에서 `LOOM_CELL`이 설정되지 않은 파드에 대한 prepare 재실행은 그 프로브 라우트에 도달하여 누락된 행을 다시 기록한다. prepare는 자신의 저장소와 다른 id를 보고하는 이후 셀의 `probe_url`을 거부하고, attach는 호스트가 `probe_url`의 것과 다른 id를 보고하는 셀을 거부하며, prepare는 첫 셀에 대한 프로브 주소 인자를 거부하고, 라우터는 `LOOM_ROUTER_UPSTREAM_PROBE_URL`만 프로브한다. 이후 셀의 첫 prepare는 성공한다. `loom cell update --probe-url`은 다른 배포 id를 보고하거나 nonce 에코에 실패하는 주소를 거부하며 첫 셀도 거부한다. `loom cell update`는 모든 라우터 레플리카가 새 값으로 실행 중이고 그들의 프로브와 업스트림의 id 확인이 끝난 뒤에만 첫 셀의 프로브와 업스트림 주소를 옮기며, 이전 값의 레플리카(또는 이동 전의 새 값)를 통한 prepare 재실행은 행의 주소를 이름으로 알리며 거부된다. userinfo가 있거나 다른 스킴인 `probe_url`은 거부된다. 메인 포트는 어떤 Host로든 저장소를 읽지 않고 메모리 내 id로만 응답한다. 라우터는 `SSL_CERT_FILE`의 CA가 서명한 인증서를 가진 https `probe_url`을 프로브한다. 프로브 리스너는 속도를 넘으면 429로 응답한다. 첫 셀의 저장소를 복사한 셀에 대한 prepare는 nonce에 의해 거부된다.
- 기본 첫 셀(`LOOM_JWT_ISSUER=loom`, 빈 `LOOM_OAUTH_ISSUER`)은 attach된다. 공유 호스트를 공개 URL로 하여 재배포된 셀은 준비되지 않은 상태가 된다.
- 셀의 쿼터에서 삽입되었으나 호출이 타임아웃된 배치는 재시도되어 그 승자에게 응답하고, 셀은 tenancy 행을 쓴다. 그 사이에 닫힌 셀과 `loom cell place` 재실행에서도 같다.
- `loom.cell_self`에 쓰기 전, 디렉터리 쓰기 이후에 중단된 attach는 `serving`으로 재개되며, 그동안 해당 attach의 issuer는 예약된 상태로 남습니다. 다른 셀이 보유한 조직에 대한 `loom cell place`는 행을 쓰지 않습니다. 디렉터리가 배치하지 않은 조직에 대한 같은 요청은 다음의 경우 행을 쓰지 않고 거부됩니다. 닫힌 셀인 경우, `placements_max`를 넘은 경우, 이후 셀이 아직 `attaching`인 경우, 첫 번째 셀에서 디렉터리가 `enforced`를 기록하기 전인 경우, 지문이 셀 행의 두 값 어느 쪽과도 일치하지 않는 구성인 경우, 디렉터리를 사용할 수 없는 경우입니다. 또한 셀의 속도 한도를 모두 소진했다고 해서 거부되지도 않고, 그 한도에 산입되지도 않습니다(운영자의 place가 연속된 뒤에도 셀 자체의 배치 호출은 계속 허용됩니다). 디렉터리가 이 셀에 배치하는 조직에 대한 호출은 닫혔거나 가득 찬 셀에서도 해당 조직의 테넌시 행을 씁니다. `recording` 상태인 첫 번째 셀에서 새 조직을 위한 `loom bot create`는 디렉터리가 `attaching`으로 응답하는 동안 해당 조직을 기록하고, `serving`으로 응답하거나 읽을 수 없는 동안에는 거부됩니다.
- 셀의 공개 호스트와 다른 OAuth issuer 호스트는 prepare에서 거부되며, 어떤 셀이 attach되기 전에도 공유 호스트가 라우팅합니다. 다른 쓰기가 없는 `loom cell place`는 조직을 해당 셀에 그대로 둡니다.
- attach 1단계와 3단계 사이로 복원된 첫 번째 셀은 `serving`이 된 뒤 `loom cell restore`를 실행하면 `enforced` 상태로 준비됩니다.
- `loom cell update --finish` 이전 시점으로 복원된 셀은 `loom cell restore`가 자신의 행을 다시 쓰면 다시 서비스합니다. 두 저장소가 모두 복원된 셀은 `loom cell restore`만으로 행을 되찾으며, prepare는 했지만 attach하지 않은 셀은 복원된 자신의 행을 유지합니다.
- prepare 이전 시점으로 복원된 첫 번째 셀은 행을 되찾습니다. 이 셀은 `LOOM_CELL`이 설정된 프로세스의 공유 호스트에서 `loom cell prepare`를 다시 실행할 때까지 503으로 응답하고, 그 뒤에 서비스합니다. `LOOM_CELL`이 설정되지 않은 배포의 SCIM은 N에서, prepare, `LOOM_CELL` 롤아웃, attach를 거치는 동안 이전과 같이 동작합니다.
- 첫 번째 셀의 SCIM은 전환 내내 이름 없는 토큰에 계속 응답합니다. 이후 셀은 이름 없는 토큰을 거부하고, 어떤 셀도 다른 셀의 토큰을 받아들이지 않습니다. 첫 번째 셀에서는 `lsc_b_…`와 형식이 잘못된 `lsc_` 토큰이 거부됩니다. `LOOM_CELL` 이전에 쓰인 SCIM 행이 있는 이후 셀은 attach에서 거부됩니다. 셀 `a-b`의 토큰은 셀 `a`에서 거부되며, `_`가 들어간 셀 이름은 거부됩니다.
- `oidc_jit_org`가 설정된 이후 셀은 prepare와 attach 사이에 부팅하고 파드를 재시작하며, 해당 조직에 대한 JIT는 attach가 그 조직을 배치할 때까지 503으로 응답합니다. prepare와 attach 사이에 어떤 요청도 기록하지 않은 조직으로의 첫 번째 셀 셀프 가입은 그 조직을 기록하고 가입시킵니다. 인덱싱된 저장소가 있는 이후 셀은 attach 전에는 코드 행을 쓰지 않다가 이후 attach됩니다. `recording` 상태인 첫 번째 셀은 롤아웃 이후 어떤 요청도 닿지 않은 조직에 대한 워커 패스를 유지합니다. `attach_started_at` 이후 중단된 이후 셀의 attach는 구성된 조직을 배치하고 보유한 채로 재개됩니다. prepare와 attach 사이에 코드 조직을 바꾸는 update는 attach가 그 조직을 배치하게 하며, `--finish` 후에는 인덱싱합니다. attach 이후의 update는 다른 셀이 보유한 구성 조직의 변경을 해당 조직을 지목하며 거부하고, 디렉터리가 아직 배치하지 않은 조직의 경우 닫힌 셀과 `placements_max` 초과 시 거부됩니다. 디렉터리 트랜잭션 이후에도 아직 `attaching`인 이후 셀의 구성 조직을 바꾸는 update는 그 셀이 `serving`이 될 때까지 거부됩니다. `--revert`는 update가 배치한 구성 조직을 유지합니다. 이후 셀의 코드 및 트래커 조직은 `serving`이 되면 서비스하고 인덱싱하며, 다른 조직 구성원의 `code.*` 연산도 포함됩니다. `loom cell update`가 바꾼 구성 조직도 마찬가지입니다. 다른 셀의 issuer를 넓히는 update와 경합하는 이후 셀의 attach는 둘 중 하나를 거부합니다. attach의 거부 시점과 배치 시점 사이에 다른 셀이 배치한 구성 조직은 그 조직을 지목하며 attach를 거부하고 아무것도 쓰지 않습니다. prepare는 다른 셀이 기록한 라우터 자격 증명을 거부합니다. 이 셀의 유효한 자격 증명으로 다른 셀을 지목한 배치 호출은 다른 셀에 아무것도 배치하지 않습니다.
- prepare는 했지만 attach하지 않은 셀에서 디렉터리가 배치하지 않은 조직에 대한 배치 호출은 503으로 응답합니다. 디렉터리가 배치한 조직에 대한 호출은 `loom cell credential --finish` 이후에도 이전 자격 증명이 캐시되어 있거나 지문이 두 값 어느 쪽과도 일치하지 않는 경우에도 승자를 응답합니다. 다른 배포 id 아래에 이 셀 이름의 승자가 있으면 503으로 응답하고 테넌시 행을 쓰지 않습니다. 구성이 셀의 행과 다른 프로세스는 아무것도 배치하지 않습니다.
- SCIM을 끈 채 attach되었다가 `loom cell update`로 켜는 셀은 agent-signup 토큰이 유효한 동안 거부되며, update가 롤아웃되는 중에 발급된 토큰도 포함됩니다. 다른 셀의 issuer로 구성된 프로세스는 라우터를 거쳤든 직접 접근했든 모든 bearer 요청에 503으로 응답합니다.
- `loom cell update` 중에는 이전 구성과 새 구성의 프로세스가 모두 서비스합니다. `--finish`는 어떤 프로세스도 더 이상 받아들이지 않을 때에만 좁혀진 issuer를 해제합니다. 디렉터리 쓰기 이후 중단된 update는 넓혀진 issuer를 예약된 상태로 유지하며, 같은 구성의 빌드 N과 N+1은 같은 행과 일치합니다.
- SCIM 토큰을 교체해도 지문은 바뀌지 않습니다. 프로세스는 다른 셀의 SCIM 토큰으로는 부팅을 거부합니다. 잘못된 셀의 호스트를 가리키는 아이덴티티 제공자는 401을 받고 아무것도 쓰지 못합니다. N으로 롤백된 셀도 여전히 자신의 행으로 게이트하며 다른 셀의 SCIM 토큰을 거부합니다. 한 셀의 issuer에서 오는 배치 폭주는 할당량을 넘으면 거부됩니다.
- 프로비저닝된 적 없는 사람의 개인 서비스 계정을 대행하는 게이트웨이는 거부되며, 다른 셀의 issuer를 받아들이기 시작한 셀은 배치를 받지 않습니다.
- 행의 두 값 어느 쪽과도 일치하지 않는 프로세스는 로그인, refresh, OAuth 토큰 및 디바이스 엔드포인트, 로그인 콜백, 가입에 503으로 응답하며, 프로브 경로는 여전히 prepare의 nonce를 그대로 돌려줍니다. `--revert`는 `next`와만 일치하는 프로세스를 기다립니다. 다른 `next`가 대기 중일 때 `update --config`는 거부되며, `loom.cell_self` 쓰기 전에 중단된 update는 앞으로 재개됩니다. pre-N 프로세스가 살아 있는 동안 prepare는 거부됩니다. `attaching` 중의 구성 변경은 `loom cell update`를 거치며, 재개된 attach는 두 값을 모두 예약합니다. 구성된 저장소가 셀의 행과 다른 프로세스는 503으로 응답하고 워커에서 물러나므로, 게이트가 적용된 새 빌드가 게이트 없는 이전 빌드 옆에 있어도 워커는 계속 실행되고 삭제를 수행합니다. `loom cell update`는 버킷 추가를 포함해 배포 id, 버킷 이름, 프리픽스의 변경을 거부합니다. `on` 모드의 게이트가 적용된 프로세스는 워커 패스를 실행하지 않습니다. 첫 번째 셀의 버킷 이름과 프리픽스를 가진 클론의 prepare는 엔드포인트가 같든 다르든 거부됩니다. 프리픽스에 다른 배포의 객체가 있는 이후 셀은 prepare에서 거부됩니다. 중첩된 프리픽스에 대한 두 동시 prepare가 둘 다 통과하지는 않습니다. 버킷이 없는 두 셀은 모두 prepare할 수 있습니다. prepare는 다른 셀의 `LOOM_CELL`을 가진 프로세스가 있는 이후 셀을 거부하며, `first` 행이 다른 셀을 지목하는 프로세스는 503으로 응답하고 워커를 실행하지 않습니다. 메인 포트의 id 경로에 대한 폭주는 attach를 멈추게 하지 않습니다. 새로운 Postgres, ClickHouse 또는 버킷 엔드포인트로 복원된 셀은 구성이 해당 엔드포인트를 지정하면 서비스합니다. 공유 호스트의 bearer 요청은 prepare 전, prepare와 attach 사이, attach 중에도 서비스됩니다.
- 차트는 기본적으로 프로브 리스너를 렌더링하지 않으며, 켜면 프로브 Service를 렌더링하고 NetworkPolicy는 바꾸지 않으므로, 차트의 정책을 켠 경우 차트 자체의 어떤 규칙도 프로브 포트를 허용하지 않습니다. `--wait`가 끝나면 prepare는 라우터의 `PROBE_UNREACHABLE`과 `PROBE_BUSY`를 알려 줍니다. 메인 포트의 폭주는 프로브 리스너의 속도에 영향을 주지 않습니다.
- 버킷과 프리픽스를 포함해 첫 번째 셀의 환경에서 시작한 이후 셀은 첫 부팅부터 게이트가 적용된 채 실행되며 원본을 삭제하지 않습니다. 살아 있는 프로세스에 `LOOM_CELL`이 없으면 prepare는 이후 셀을 거부합니다.
- `loom cell limit --closed`는 셀이 보유한 조직을 계속 서비스하면서도 셀의 배치 호출이 503으로 응답하게 하고, `--open`은 이를 복원하며, `--placements-max`는 다음 배치 호출부터 적용됩니다.
- 어떤 조직의 배치 이전 시점으로 `enforced` 셀의 Postgres를 복원하고 그 시점 이후 해당 조직이 삭제된 경우, `loom cell restore` 이후 종료 코드 0으로 조정되고 이후 그 조직을 서비스합니다.
- 어떤 조직의 배치 이전 시점에서 복원된 셀은 준비되면 그 조직을 서비스하고, 삭제는 조직의 배치를 남기며, 디렉터리를 잃어도 모든 셀은 자신이 보유한 조직을 서비스합니다.
