Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

O original em inglês mudou desde esta tradução automática. Consulte a página em inglês para ver as instruções atuais.

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

Células

A memória de um deployment pode crescer além de um primary Postgres e de um serviço ClickHouse, e uma organização pode querer sua memória em serviços próprios. Uma célula é um deployment completo do Loom, como esta documentação o descreve: suas réplicas e workers, uma unidade Postgres (um primary com seus standbys), um serviço ClickHouse, um prefixo de bucket de documentos, seu próprio host público, e suas próprias chaves de assinatura, concessões, workers e exclusão. Um router no host compartilhado do deployment envia uma requisição para a célula que contém o que ela endereça. Uma organização vive em exatamente uma célula, a que a alocou, e nunca sai dela. Uma organização é alocada no attach (as organizações que a célula continha e suas organizações configuradas), por loom cell update (uma organização configurada que mudou) ou por loom cell place, ou na primeira requisição verificada de um principal com escopo nela. Um deployment com uma célula e sem router funciona como um deployment único.

As células exigem a autoridade Postgres (LOOM_STORAGE_AUTHORITY=postgres) e uma autenticação que todos os transportes imponham (auth_actually_required(), e LOOM_MCP_AUTH_MODE diferente de open): loom cell attach se recusa a executar sem elas, e um processo com LOOM_CELL definido se recusa a iniciar sem elas. Autoridade de armazenamento descreve o que uma célula contém e como seus dois armazenamentos concordam.

Por que implantações inteiras

Uma célula não compartilha armazenamento, chave, lease nem worker com outra. Toda garantia que uma implantação única oferece (isolamento de tenants, uma revogação que vale imediatamente, cobertura de apagamento, um lease de worker, uma cadeia de auditoria, uma restauração) vale por célula, sem alterações, e os dados, as concessões e o apagamento de uma organização nunca abrangem várias células. O roteador adiciona o diretório e as regras de roteamento abaixo; cada célula adiciona uma verificação de que contém a organização à qual uma requisição se dirige.

O que abrange várias organizações passa a ser por célula:

  • um token é válido na célula que o emitiu e em nenhuma outra;
  • as linhas de escopo global da implantação são por célula: a lista de bloqueio global (org='*'), as configurações e os overrides de runtime, as regras de política, os overrides de limite de taxa e de orçamento, a rotação de chaves de assinatura e a revogação de um subject. loom cell each -- <command> executa um comando administrativo sem organização em todas as células, com uma credencial de curta duração por célula, registra o resultado de cada célula, retoma as células que falharam e falha até que todas tenham êxito; loom doctor compara as configurações e os fingerprints de configuração das células e indica o que difere;
  • as organizações de código e de tracker (LOOM_CODE_ORG, LOOM_TRACKER_ORG) são próprias de cada célula: cada célula indexa seus próprios repositórios, com o custo de ingestão de cada um;
  • a visão de plataforma de um operador e o painel são por célula, no host da célula.

O router

O router é um proxy HTTP sem estado, executado como várias réplicas atrás do host compartilhado do deployment, lançado de forma independente e compatível com cells das builds N-1 e N. Ele mantém o diretório em seu próprio banco Postgres:

  • cells: a cell, o host público, os emissores de bearer token que ela aceita exclusivamente (seu próprio LOOM_JWT_ISSUER, seu LOOM_JWT_TRUSTED_ISSUERS, seus emissores de usuário final), seus stores (o id do deployment e o nome e o prefixo do bucket), seu estado (attaching, serving), quando o attach começou (attach_started_at, que o attach grava sob o lock do diretório somente depois de todas as suas recusas terem passado, antes de gravar qualquer linha na cell além de suas probes e das revogações de --revoke-unprovisioned, e que um attach retomado lê), seu modo de tenancy e quando foi definido (o prepare grava o primeiro, e o attach registra cada um que ele eleva ou tenta elevar), se está fechada para novas orgs e sua cota de placement (placements_max), o SHA-256 da credencial com a qual ela chama o router (current e, durante uma rotação, next), a impressão digital de seu segredo raiz (keys_fp), seu probe_url (o do próprio router para a primeira cell), os nomes e as impressões digitais de chave de seus bots break-glass e a impressão digital de sua configuração (current e, durante uma mudança, next; os campos citados em "Verificação contínua"), que o attach e loom cell update gravam junto com a cópia da própria cell dessa impressão digital (loom.cell_self);
  • placements: org, cell. Uma linha por org, gravada uma vez e nunca excluída;
  • hosts: o host de cada cell e os aliases do host compartilhado (abaixo).

O router tem sua própria credencial de operador, definida em sua configuração e nunca no diretório; toda alteração do diretório feita pelo operador usa essa credencial, e toda alteração, placements incluídos, é gravada no log de auditoria do router. Anexar uma cell também exige uma credencial de administrador da plataforma da cell que está sendo anexada. O router informa sua própria liveness e readiness, independentes as de qualquer cell.

O router é colocado primeiro na frente do deployment existente, repassando todas as requisições a ele; esse deployment se torna a primeira cell quando é anexado e mantém o host compartilhado como seu próprio host, de modo que seus clientes, tokens, refresh tokens, clientes OAuth e callbacks registrados continuam funcionando. O router responde por conta própria seus próprios caminhos (/cells/, /livez, /readyz) e roteia todo o resto, inclusive os caminhos /v1/health de uma cell, tanto para cells attaching quanto serving, nesta ordem:

  1. Por host. Uma requisição ao host próprio de outra cell vai para essa cell. O host compartilhado, e qualquer alias dele registrado em hosts, são configuração própria do router e são tratados pelas regras 2 a 4 (a cell da regra 4 é o upstream de pass-through, antes e depois de a primeira cell ser registrada, já que o prepare a registra nesse endereço), nunca respondidos com 421; qualquer outro host que nenhuma linha de cells nomeie responde 421. Toda URL que uma cell fornece nomeia seu próprio host: seus endpoints OAuth e OIDC, a URI de verificação do device flow, o callback de login (LOOM_OAUTH_ISSUER, registrado no provedor de identidade por cell), seu JWKS, as páginas e os assets do painel e os metadados de recurso MCP. Clientes MCP de uma cell que não seja a primeira usam o host da cell, que as linhas de setup da cell exibem.
  2. SCIM segue o host, como a regra 1: o aplicativo do provedor de identidade de cada cell faz o provisionamento em seu próprio host (abaixo); o SCIM no host compartilhado é o da primeira cell, exceto uma requisição /scim/v2/Groups com um JWT, que vai pelo emissor como na regra 3. As rotas Groups têm verificação de tenancy (elas gravam loom.principal_groups da org).
  3. Por emissor. Uma requisição com token ao host compartilhado vai para a única cell que aceita seu claim iss, lido sem verificação; a cell verifica. Um emissor que nenhuma cell aceita responde 401. Até a primeira cell estar serving, as regras 2 a 4 enviam toda requisição do host compartilhado para a cell da regra 4, que a verifica, de modo que o deployment atrás do router atende as orgs que possui como antes durante o prepare, o rollout de LOOM_CELL e o attach; do rollout até serving, uma nova org também precisa do diretório em todo processo com LOOM_CELL definido (ele responde 503 ali enquanto o diretório estiver ilegível). Isso abrange MCP e toda op, qualquer que seja a org que um corpo nomeie, e os tokens de emissores federados e de usuário final de integrações.
  4. Todo o resto no host compartilhado vai para a primeira cell: seus fluxos OAuth e device, refreshes, callbacks, requisições de senha e autocadastro, probes de saúde e a página de login; uma revogação de token (/oauth/revoke) de um JWT segue o emissor, como na regra 3, e a de um refresh token opaco vai para a primeira cell, já que apenas os clientes da primeira cell usam o host compartilhado (loom logout revoga no host em que fez login). Os documentos de descoberta do host compartilhado são os da primeira cell.

O router alcança uma cell no upstream_url que a linha do diretório registra, um endereço dentro da rede do deployment (o da primeira cell é LOOM_ROUTER_UPSTREAM_URL, gravado pelo prepare, de modo que registrá-la não muda nenhuma rota; o de uma cell posterior é gravado pelo attach), nunca no host público da cell, que nomeia o próprio router; antes de a primeira cell ser registrada, a cell da regra 4 é o deployment diante do qual o router foi colocado (LOOM_ROUTER_UPSTREAM_URL). O host compartilhado é LOOM_ROUTER_SHARED_HOST, o host próprio da primeira cell e os aliases dessa cell em hosts. Ele encaminha cada requisição como o cliente a enviou (seu caminho e query brutos, seu próprio Host) com a visão do próprio router sobre endereço, esquema e host do cliente em X-Forwarded-For, -Proto e -Host, substituindo o que o cliente declara ali (por isso cada cell lista os endereços do router em LOOM_TRUSTED_PROXIES, ou então conta todo cliente como o router nos limites de login e lê o esquema como o do router), descarta os cabeçalhos que descrevem uma única conexão (e os que Connection nomeia), mantém toda linha de cabeçalho da resposta (um segundo Set-Cookie incluído), faz streaming de ambos os corpos (um stream de server-sent events incluído), responde 502 quando a cell não pode ser alcançada e nunca encaminha um caminho sob /cells/ (um que ele não serve responde 404). Uma primeira cell registrada sem endereço de upstream responde 503, como a de qualquer cell. Ele lê as cells, seus emissores e hosts uma vez a cada LOOM_ROUTER_DIRECTORY_CACHE_S, respondendo pela última tabela enquanto uma desatualizada é lida de novo em segundo plano, de modo que um diretório que trava ou não pode ser lido não atrasa nenhuma requisição; antes de sua primeira leitura, ele responde 503. Um emissor que duas cells listam (o que o attach recusa) não roteia para nenhuma.

Um cliente encontra a cell de uma org com GET /cells/lookup?org=<org>, sem autenticação e com limite de taxa; uma org sem placement responde a primeira cell com o mesmo corpo de uma org colocada ali (apenas a resposta de uma org colocada é armazenada em cache, então o tempo de resposta e uma indisponibilidade ainda podem distingui-las: o nome de uma org não é segredo), e antes de qualquer cell ser registrada o lookup responde 503 com o código NO_CELL; um diretório que ele não consegue ler para uma org que não está em cache responde 503 com BACKEND_UNAVAILABLE. Um cliente confere o código, nunca a mensagem: em NO_CELL, e em um 404 de um deployment sem router, loom login --org mantém o host que recebeu (o host compartilhado, servido como antes pela regra 4, ou o deployment único); em um 429 ele espera o Retry-After e pergunta de novo, por no máximo --wait (padrão 2 minutos), depois recusa como recusa por limite de taxa; em qualquer outra resposta ele recusa, nomeando o router, de modo que nenhum fluxo comece em uma cell que pode não conter a org. A cell de uma org é pública, como a URL de um workspace: o lookup revela que uma org fora da primeira cell existe. loom login --org, a página de login da primeira cell (que pergunta a org primeiro) e as linhas de setup iniciam todo fluxo OAuth, device e de login no host da cell da org, de modo que nenhum fluxo cruza cells; um navegador é redirecionado apenas para o início de um fluxo novo.

Somente a primeira cell chega a estar em recording: uma cell cuja linha first é (false, …) trata qualquer modo diferente de enforced como enforced em seus triggers de org, em seu cache de modo e em sua CLI, de modo que a linha de modo de uma cell posterior definida como recording não registra nada. Uma cell em recording lê seu próprio estado com GET /cells/v1/cells/<cell>, com sua credencial do router, respondido apenas para a cell que o índice único do diretório nomeia primeiro e aceito apenas quando o SHA-256 da credencial é um dos hashes que o diretório registra para <cell>, dentro de LOOM_CELL_ROUTER_TIMEOUT_S (padrão 5 s, o timeout da chamada de placement); uma resposta recusada, falha ou tardia conta como ilegível.

Com o diretório inacessível, as regras 1 a 4 roteiam a partir das cells em cache do router; um lookup de uma org que ele não tem em cache e um placement respondem 503.

As rotas do operador, cada uma com a credencial de operador do router, ficam em /cells/v1/operator/cells/<cell>: limit, credential e register (o do prepare), a própria linha (GET, com o nome de qualquer outra linha, que o attach lê para suas recusas, sua verificação de conclusão e sua retomada), o attach da primeira cell (attach/begin, attach/place, attach/enforced e attach/serving, nessa ordem) e DELETE. Cada uma, exceto register, responde a uma cell que o diretório não possui com 404 e o código NO_SUCH_CELL, de modo que um 404 sem ele indica uma réplica do router de uma build anterior. Toda chamada bem-sucedida, a leitura incluída, é gravada no log de auditoria (uma repetição de registro, que não muda nada, não grava nenhuma), e toda chamada executa um número fixo de instruções, cada uma limitada pelo statement timeout do diretório (aplicado também no servidor do diretório); a leitura e a remoção carregam os limites derivados que loom cell aguarda. Toda alteração toma o lock do diretório e depois o lock da linha da cell (a ordem que o registro, as alterações do operador e a remoção seguem). Toda réplica do router executa uma build com essas rotas antes de o attach da primeira cell começar: o placement de uma build anterior colide com o de um lote de attach como um 503 transitório, e seu registro pode adicionar uma cell posterior durante o attach, o que faz toda chamada de attach recusar até que ela seja removida. Cada chamada de attach recusa, a menos que a linha seja a da primeira cell, esteja attaching e registre o id de deployment que a chamada nomeia, e enquanto existir qualquer outra linha (o registro recusa uma cell posterior até a primeira estar serving, e uma réplica do router de uma build anterior ainda poderia registrar uma):

  • attach/begin traz as impressões digitais da cell exatamente como loom.cell_self as armazena, a impressão digital de seu segredo raiz, as listas de permissão pelas quais o attach julgou os stores e nonces novos. Ele recusa uma impressão digital cujo id de deployment, bucket, prefixo, host público ou host do emissor difiram dos da linha (um host de emissor diferente do próprio da cell é recusado), e uma cujo corpo de placement real, com um nome de org no comprimento máximo, ultrapassaria o limite de corpo do router, nomeando os maiores campos. Fora de qualquer transação do diretório, ele executa a probe do registro no probe_url da linha e pergunta ao upstream_url da linha o id de deployment, de modo que os stores que o attach lê sejam aqueles de que a cell em operação serve. Depois, sob os locks, grava attach_started_at uma vez, as impressões digitais somente enquanto a linha não tem nenhuma (outras impressões digitais ali respondem 409: elas mudam com loom cell update) e keys_fp em toda chamada, e audita as listas de permissão. É idempotente. Seu corpo tem limite próprio, 256 KiB, acima do qual responde 413.
  • attach/place coloca um lote de no máximo 500 orgs (dentro do limite de corpo de 64 KiB) depois que begin foi executado e o modo do diretório é enforced, além da marca de fechamento e da cota da cell. Ele executa um número fixo de instruções: um insert do lote que ignora uma org já colocada, uma leitura que recusa o lote (com rollback, nomeando a org) quando uma org está colocada em outra cell, uma contagem e uma linha de auditoria por org que colocou e uma para a chamada. Um placement real da mesma org corre ao lado dele quando o modo é enforced; ambos seguram o lock da linha da cell, um placement real lê o vencedor de novo quando o obtém, e todo insert ignora uma org já colocada e conta apenas o que gravou, de modo que a org é colocada e contada uma vez.
  • attach/enforced registra o modo do diretório enforced, depois do qual a primeira cell coloca novas orgs em tempo real; é idempotente.
  • attach/serving executa a probe e a verificação de upstream de novo, depois, sob os locks, calcula os emissores da linha a partir de suas impressões digitais (bearer_issuers de current e next) e marca a cell como serving; em uma cell serving, responde na hora, com auditoria. begin, place e enforced em uma cell serving respondem 409.

DELETE remove a linha de uma cell que está attaching sem nenhum placement, qualquer que seja o modo do diretório, com suas linhas de host, com auditoria: uma primeira cell é desfeita até seu primeiro placement, e uma cell posterior registrada por uma build anterior deixa de bloquear o primeiro attach. Um placement em andamento ou é confirmado primeiro, e a remoção recusa, ou não encontra linha. O router não consegue ler os stores da cell, então loom cell remove, que o chama, verifica antes o Postgres de uma primeira cell (Operações).

SCIM e login entre células

Cada célula é uma aplicação própria no provedor de identidade: um cliente OIDC para o login em seu host e uma aplicação SCIM que provisiona o seu /scim/v2, ambos atribuídos ao mesmo grupo de pessoas, as pessoas das orgs dessa célula. Uma pessoa que o provedor de identidade desativa, exclui ou remove da atribuição é desprovisionada em todas as células cuja aplicação lhe estava atribuída; o Loom não consegue ver uma aplicação configurada para admitir pessoas não atribuídas ou para não desativar ao remover a atribuição, então o operador configura cada aplicação para exigir atribuição e para desativar ao remover a atribuição. Cada célula mantém seus usuários SCIM, desativações e tombstones exatamente como uma implantação única (SSO e SCIM); o roteador não guarda nenhuma identidade.

Uma célula em enforced com SCIM ativado exige SCIM: uma pessoa só age na célula enquanto o SCIM dela mantiver uma linha ativa para ela. A verificação é feita na conta da pessoa, não na forma como um subject é escrito: scim.refuses_subject(subject) considera as grafias de email do próprio subject e os emails de contato e verificados das contas ativas que ele possui, incluindo contas de senha, e recusa se qualquer um deles não tiver linha ativa (a linha cujo id é scim.user_id(email); uma linha inativa ou excluída com esse id sempre recusa, e um email sem linha própria só passa como endereço de trabalho de uma linha ativa cujo email principal seja uma das grafias do próprio subject). Um principal fora do SCIM pertence a uma lista fechada: um bot (um subject cujo sa:<name>, antes de qualquer : adicional, nomeia uma linha de loom.machine_identities: o bot e seus agentes, como check_acted_for o interpreta), um subject de máquina ou workload, um usuário final (user:). Qualquer outro subject sa:, uma conta de serviço pessoal, é verificado por meio de seu criador (service_accounts.sa_creator) e de todo subject que o lineage de sua linha lista, de modo que agir em nome dela é agir em nome da pessoa que a criou; todo outro subject nesses caminhos é uma pessoa e é recusado, a menos que tenha uma grafia de email ou possua uma conta com uma. Uma leitura SCIM que falha gera SignInUnavailable, como faz scim.deactivated, nunca um OAuthError, de modo que um refresh devolve seu token e nenhuma sessão termina por causa de uma indisponibilidade. Todo caminho que admite uma pessoa o utiliza:

  • um login SSO, antes de a conta ser encontrada ou criada (JIT), com o email que o provedor de identidade verificou;
  • todo refresh de uma sessão (_refresh_session), com o email verificado que o grant armazena ou, para um grant sem email, as contas do subject;
  • um ato em nome de uma pessoa (authz.check_acted_for), qualquer que seja a grafia do subject;
  • o subject de um token de gateway, verificado no momento da verificação e lembrado como as outras respostas da verificação;
  • o criador de um token delegado ou de uma conta de serviço pessoal (authz._check_creator), em cache como a verificação de atuação em nome de alguém, de modo que um token criado por uma pessoa nunca provisionada é recusado quando a célula está enforced.

Com SCIM ativado, o login por senha e o autocadastro já ficam fechados (oauth_login_provider=oidc), e o fluxo de dispositivo faz login por SSO, portanto passa pela mesma verificação. Principais sem email estão fora do SCIM e são desprovisionados por quem os criou: bots e tokens emitidos por um operador, usuários de emissores de usuário final pelo serviço que assina por eles, a confiança de workload por sua regra.

Break-glass. Cada célula possui um bot administrador de plataforma com prova por chave (loom bot create --platform-admin), que não tem email e que o SCIM nunca revoga, e um segundo, separado, para attach e loom cell each. As chaves ficam no cofre de segredos do operador, lidas a cada uso; o diretório registra apenas o nome e a impressão digital da chave de cada bot, de modo que o roteador não guarda credencial de nenhuma célula, e todo uso do bot break-glass consta no log de auditoria da célula e é apontado por loom doctor. Os operadores são atribuídos às aplicações de todas as células para usar o painel e acessam uma célula cuja aplicação no provedor de identidade esteja com defeito por meio do bot dela.

Os tokens SCIM de uma célula são só dela por construção. O nome de uma célula corresponde a [a-z0-9-]{1,32} (sem _, comparado exatamente; verificado em prepare, attach e boot, e único no diretório). Um token que começa com lsc_ nomeia uma célula e deve corresponder por inteiro a lsc_[a-z0-9-]{1,32}_[0-9a-f]{32,}, ou toda célula o recusa; somente um token sem esse prefixo não nomeia nenhuma célula. Com LOOM_CELL definido, um token SCIM tem a forma lsc_<cell>_<secret>, como loom cell scim-token new --cell <name> o gera (roda offline): exatamente três campos separados por _, o do meio igual a LOOM_CELL, e um segredo de pelo menos 32 caracteres hexadecimais minúsculos (128 bits).

Um parser ao lado de scim.tokens() devolve o nome da célula de um token ou nada, e quem o chama compara o resultado com LOOM_CELL e com a linha first da célula (abaixo). scim_settings_problem recebe ambos, de modo que o boot e loom doctor recusam por meio de uma única função, e com LOOM_CELL definido recusam um terceiro token configurado (dois permitem uma rotação). Uma função, scim.authorized(presented), concentra a comparação em tempo constante para as duas rotas SCIM (_authorized, scim_groups._caller). Com LOOM_CELL indefinido, compara com os tokens configurados como uma implantação única faz e não lê nada. Com ele definido, compara com os tokens que o parser admite para LOOM_CELL e com a linha first; enquanto essa linha não foi lida, gera erro como AuthUnavailable faz, de modo que as rotas respondem 503 com Retry-After e o provedor de identidade tenta de novo.

  • Um processo se recusa a iniciar com um token SCIM que nomeia outra célula, e /scim/v2 responde 401 a um token assim.
  • Uma célula posterior recusa um token que não nomeia nenhuma célula. A primeira célula, que mantém o host compartilhado, também aceita seus tokens existentes sem nome, somente enquanto sua linha first for (true, LOOM_CELL), de modo que seu SCIM continue funcionando durante a transição sem rotação.
  • Um token copiado para as configurações de outra célula, ou uma aplicação do provedor de identidade apontada para o host da célula errada, portanto falha de forma fechada, e nenhuma célula jamais compara seus tokens com os de outra.

Preparando uma célula

loom cell prepare registra uma célula no diretório e grava as linhas que os processos da célula leem. A verificação de tenancy (abaixo) diz o que ele grava e como retoma; esta seção diz como ele prova que recebeu a célula certa.

Qual célula é a primeira nunca é uma configuração nem a ordem de preparação. O prepare só concede isso à célula cujo host é o host compartilhado do roteador e cujo id de deployment é o que o upstream de pass-through do roteador informa no endereço de probe do upstream. Esse endereço é a configuração do próprio roteador (LOOM_ROUTER_UPSTREAM_PROBE_URL) e o probe_url da primeira célula, nunca um dos argumentos do prepare: o roteador o lê ali a cada prepare e a cada nova execução, e recusa uma resposta com outro id de deployment ou sem id. O roteador também consulta a porta principal do seu upstream de pass-through (LOOM_ROUTER_UPSTREAM_URL, que o registro copia para a linha) e recusa uma que informe outro id de deployment, de modo que a linha nunca nomeia dois deployments. O prepare recusa toda outra célula até que a primeira esteja registrada e serving, sob o lock do diretório, de modo que nenhuma célula posterior apareça enquanto a primeira é anexada.

Os stores são os ativos. Antes de gravar qualquer coisa, o prepare grava um nonce aleatório no Postgres de destino, sob uma chave reservada do loom._migration_lock do ClickHouse de destino, e como um objeto de probe sob o prefixo do bucket de destino. A rota de probe da célula deve devolver cada um deles conforme o lê da sua própria conexão com o primário naquela requisição. Os nonces são então apagados; suas linhas não guardam memória nem org e são classificadas assim. Uma cópia com o mesmo id de deployment é recusada. O prepare envia ao roteador os três nonces junto com o registro (POST /cells/v1/operator/cells/<cell>/register, com a credencial de operador); o roteador lê ele mesmo o listener de probe e só registra a célula quando este responde o id de deployment da célula, esses nonces, e o bucket e o prefixo que o registro nomeia (assim, um registro que não nomeia bucket não pode passar por uma célula que tem um). O roteador responde como PROBE_BUSY um listener acima da sua taxa (429), e como PROBE_UNREACHABLE um que ele não consegue alcançar ou que não consegue ler um store, ou a porta principal do upstream de uma primeira célula que ele ainda não alcança, ambos com 503, e o prepare espera por eles dentro de --wait. Uma nova execução cujos endereços diferem dos da linha é recusada antes do probe.

A rota de probe, GET /v1/health/deployment, não recebe credencial e fica fora do gate de fingerprint:

  • Na porta principal, ela responde apenas o id de deployment que cada processo verificou na inicialização, mantido em memória, seja qual for o Host da requisição. Não lê nenhum store e não tem limite de taxa, então nenhuma enxurrada na porta principal trava a verificação de host do attach.
  • Completa, com os valores sob as chaves de nonce reservadas do prepare, ela é servida apenas em uma porta separada de listener de probe (LOOM_CELL_PROBE_PORT, 0 para desligado; exige a autoridade do Postgres e a autenticação ligadas, e escuta em todos os endereços do host): a linha do Postgres loom.cell_probe e a chave do KeeperMap, ambas chamadas cell-probe, e o objeto <prefix>/_cell_probe; ela também nomeia o bucket e o prefixo onde armazena. Nenhum desses valores é secreto. Responde 429 acima de uma taxa fixa por processo nesse listener.
  • Somente o endereço de probe da célula (probe_url) aponta para o listener: um endereço interno que nenhum ingress expõe e para o qual o roteador nunca roteia, que o deployment envia a todo processo vivo, pronto ou não, de modo que o prepare e o attach alcançam um processo que o gate mantém como não pronto.
  • O listener de probe do chart vem desligado por padrão e é ligado, inclusive no deployment existente, antes do primeiro loom cell prepare. Ele renderiza um Service nessa porta que publica endereços não prontos e não altera nenhuma NetworkPolicy. Quem pode alcançar a porta é decisão da network policy do operador, como ocorre com a do ClickHouse: com a policy própria do chart ligada, que admite apenas a porta http, o operador adiciona uma policy que admita a porta de probe a partir dos pods do roteador (o registro do prepare é sondado pelo roteador) e de onde a CLI roda (as policies se somam), e sem ela qualquer pod pode alcançá-la. Do mesmo modo, o egress da célula para o endereço de placement do roteador e para o Postgres é responsabilidade do operador, por meio de networkPolicy.extraEgress quando a policy do chart está ligada.
  • O prepare tenta de novo os PROBE_BUSY e PROBE_UNREACHABLE do roteador (um listener em inicialização fica inalcançável por um tempo), e o attach e o loom cell update --probe-url tentam de novo um 429 do listener que sondam, por no máximo --wait (padrão 10 minutos), e então o nomeiam.

O probe_url de uma célula posterior é entregue ao prepare, normalizado (http ou https, sem userinfo), e aceito apenas quando informa o id de deployment que o prepare lê dos stores de destino; o attach então verifica que o host da própria célula informa o mesmo id. O prepare recusa um argumento de endereço de probe para a primeira célula. loom cell update --probe-url substitui o de uma célula posterior sob o lock do diretório, após a mesma verificação e um novo eco de nonce. Os endereços de probe e de upstream da primeira célula são copiados da configuração do roteador no registro, e loom cell update os substitui a partir dela, depois que toda réplica do roteador roda os novos valores, após o mesmo probe e uma verificação de que o novo upstream informa o id de deployment da célula. Uma nova execução do prepare nunca move um endereço: ela recusa enquanto a réplica do roteador que alcança estiver configurada com outros.

A linha first. O prepare grava uma linha first explícita e imutável no Postgres de cada célula (loom.cell_first: um trigger de linha recusa seu update e delete e um trigger de statement seu truncate, ambos criados ENABLE ALWAYS e verificados pelo attach e pelo loom doctor como os triggers de org), (true, <cell>) para a primeira célula e (false, <cell>) para qualquer outra, na mesma transação do modo de tenancy, de modo que nenhuma exista sem a outra. Lidas em conjunto, as duas linhas dão um de quatro estados. Ambas ausentes, sem linha de tenancy nem própria: aberto, de um deployment único, sem verificação; um processo com LOOM_CELL definido permanece não pronto ali (sem linha de modo). Em uma célula que o diretório registra, isso só acontece quando o Postgres dela é restaurado para antes do seu prepare (fechado por loom cell restore) ou quando um prepare para entre o registro e a gravação da linha (fechado por uma nova execução do prepare), e os triggers e os processos com LOOM_CELL não definido permanecem abertos nesse meio tempo, como em um deployment nunca preparado, já que o Postgres da célula, que guarda o seu estado, não distingue os dois casos (o ClickHouse não carrega estado da célula: adicioná-lo faria o caminho de escrita ler um segundo store para tenancy) e tal processo nunca lê o diretório; onde todo processo tem LOOM_CELL não definido, o apontamento do loom doctor (que lê o diretório e vem com o attach) é o único sinal. Uma linha (true, …) com recording e a linha própria: a primeira célula em gravação. Ambas presentes com a linha própria de outro modo: enforced, com o modo de uma célula posterior lido como enforced seja o que disser sua linha (seus triggers, cache de modo e CLI o tratam assim, e loom cell prepare nomeia uma linha que não é). Qualquer das linhas sozinha, ambas sem a linha própria, ou ambas ausentes ao lado de uma linha de tenancy ou própria (os estados partial: alguma linha de estado presente, mas não todas entre first, modo e própria), que o prepare nunca deixa: os triggers de org, onde a célula os tem, agem como em enforced (uma inicialização não cria nenhum nela), todo processo fica sob gate como por uma linha não lida, o loom doctor o nomeia, e uma nova execução de loom cell prepare grava de volta as linhas ausentes a partir do diretório enquanto a célula roda. Um índice único no diretório permite uma só primeira célula, e o valor não guarda conteúdo de memória e é classificado assim. O attach reverifica o host e o id de deployment. Um processo lê o valor junto com o modo, e "ainda não lido", "ausente" e "falso" são distintos: só uma linha que foi lida deixa um processo pronto, e uma linha cuja célula não é LOOM_CELL o mantém sob gate (abaixo) e é reportada por scim_settings_problem. A inicialização recusa apenas pelas configurações (scim_settings_problem com a linha não lida verifica só a forma do token contra LOOM_CELL); a comparação com a linha first roda por requisição depois que a linha é lida, e o loom doctor lê o valor do Postgres da célula ou o reporta como desconhecido.

A linha própria da célula

Verificada continuamente, não apenas no attach. Cada processo calcula o fingerprint de sua configuração: campos nomeados sob uma versão de schema (os hosts de seu LOOM_PUBLIC_BASE_URL e do LOOM_OAUTH_ISSUER resolvido, seu emissor OIDC e client id, se o SCIM está ativado, os emissores de bearer que ele aceita (trusted_issuers() e seus emissores de usuário final), suas orgs configuradas, as orgs de seu jwt_end_user_issuers_json, o deployment id que ele verificou no boot, e o nome e o prefixo do bucket). Seu Postgres e seu ClickHouse carregam ambos o deployment id (a verificação de pareamento que um deployment único já executa). O bucket, quando há um configurado, é identificado por seu nome e prefixo (uma célula sem bucket não participa de nenhuma verificação de bucket), que duas células não compartilham em nenhum endpoint: o prefixo de nenhuma célula em um bucket de mesmo nome fica aninhado dentro do de outra nem o contém, de modo que um endpoint tomado do ambiente não pode cair no prefixo de outra célula. Nenhum store é identificado por seu endereço, então a troca de um standby, um failover, um endereço tomado do ambiente ou uma restauração para um novo endpoint não altera nada do que a célula verifica. O deployment id, o nome do bucket e o prefixo nunca mudam após o prepare: loom cell update recusa a mudança de qualquer um deles, inclusive adicionar um bucket a uma célula preparada sem um, e mover os dados de uma célula para outros stores, ou adicionar um, é um desenho à parte (Operações). Os bots não entram nele: loom bot create os adiciona em tempo de execução, cada um com uma org, e a colocação já os limita. A linha própria da célula em loom.cell_self contém um fingerprint aceito, current, e, durante uma mudança, um segundo, next. Suas linhas, e o heartbeat da célula (loom.cell_heartbeats, indexado pela linha do processo em loom.instances e escrito junto com ela, já que uma tabela KeeperMap não aceita nova coluna: o LOOM_CELL com que ele executa, o estado que sua última leitura produz, seu fingerprint e as chaves ao lado dele), não contêm conteúdo de memória e são classificadas assim para fins de exclusão. Um processo corresponde a um valor quando todos os campos que ambos conhecem são iguais, e um campo que o valor não tem conta como igual apenas no seu padrão, de modo que os builds N e N+1 com a mesma configuração correspondem a uma única linha. Com LOOM_CELL definido, enquanto a linha própria de sua célula, a linha first ou a linha de modo não foi lida, as linhas de estado estão em estado partial (a regra da linha first, acima), a linha própria da célula está ausente ou não corresponde a nenhum dos dois valores, ou a linha first nomeia outra célula, toda requisição que ele recebe, exceto seus health probes e a rota de probe, responde 503 AuthUnavailable: requisições bearer (a primeira verificação em verify_token, antes do ramo de emissor de usuário final), SCIM, e toda rota que faz login, emite, renova ou troca um token, incluindo signup, os endpoints OAuth e de dispositivo e o callback de login. Ele também se reporta como não pronto e se afasta dos workers como faz um processo com drift: interrompe suas passagens, devolve o lease e não nomeia nenhum lease em sua linha de instância, em todos os modos de LOOM_BACKGROUND_WORKERS (inclusive on: sem lease para manter, o processo on de uma célula executa o loop de lease, que inicia e para o supervisor no gate dentro de LOOM_TENANCY_MODE_CACHE_S e um período do loop), e sua linha de instância não o conta como servindo, de modo que um build mais antigo ao lado dele mantém os workers em execução. Uma leitura com falha mantém as últimas linhas por no máximo LOOM_JWT_REVOCATION_MAX_STALE_SECONDS, como fazem o keyring de assinatura e o snapshot de revogação; passado esse tempo, o processo fica bloqueado até que uma leitura seja concluída. O modo (abaixo) tem o mesmo limite. Uma célula configurada para aceitar o emissor de outra célula, um host com o qual não foi anexada ou um padrão de org que não lhe foi concedido, portanto, não serve nada com isso, onde quer que a requisição chegue a ela. Seu heartbeat reporta o fingerprint, o router recusa uma chamada de colocação cujos campos não correspondem a nenhum dos dois valores da linha do diretório, e loom doctor nomeia uma divergência, uma célula cujo cliente OIDC outra célula compartilha, e uma célula com SCIM desativado ao lado de células com ele ativado.

loom cell prepare escreve current em loom.cell_self junto com as linhas first e de modo. Até que a linha do diretório contenha um fingerprint (antes do attach), ele escreve, quando a linha própria está ausente, o fingerprint que todo processo vivo reporta em seu heartbeat, recusando enquanto algum processo vivo executar um build anterior ao N, que não reporta nenhum, ou enquanto os fingerprints reportados forem diferentes; uma linha própria presente permanece, e um processo vivo que executa nem seu current nem seu next recusa; a cada execução, antes de se registrar, ele recusa um processo vivo cujo deployment id, nome de bucket ou prefixo difira da configuração do próprio prepare (um campo que ele não reporta é lido em seu padrão). Quando a linha do diretório já contém um fingerprint, uma nova execução escreve current e next a partir dele, como faz loom cell restore, recusando apenas enquanto o fingerprint de um processo vivo não corresponder a nenhum dos dois. De qualquer forma, a célula permanece pronta durante o rollout de LOOM_CELL. Uma mudança posterior de configuração, enquanto a célula está attaching ou serving, passa por loom cell update; antes que o attach tenha escrito o fingerprint da célula na linha do diretório, ele escreve next somente em loom.cell_self, sem reservar nada (e --finish e --revert então tocam apenas loom.cell_self), e um attach retomado executa suas recusas de sobreposição com, e escreve no diretório, ambos os valores de loom.cell_self. Os emissores e padrões de org de uma célula preparada não são reservados em lugar nenhum: o router não roteia nenhum emissor para ela e não aceita nenhuma colocação dela até que o attach tenha executado suas recusas de sobreposição e escrito sua linha no diretório.

Uma mudança no que uma célula aceita passa por loom cell update --config <file>, sob o mesmo lock do diretório que o attach; ele calcula next a partir dessa configuração com a mesma função que os processos usam, e recusa enquanto um next diferente estiver pendente; uma nova execução com a mesma configuração, ou --finish, primeiro escreve next onde ele estiver ausente. Ele executa novamente as recusas de sobreposição do attach contra a linha de diretório de toda outra célula, contando ambos os valores de cada uma, escreve o novo fingerprint como next no diretório e depois em loom.cell_self, de modo que processos antigos e novos servem ambos enquanto a nova configuração é distribuída. loom cell update --finish espera, no máximo --wait (padrão 10 minutos), até que todo processo vivo reporte next e o maior prazo de requisição tenha passado; quando a mudança ativa o SCIM ou altera o cliente OIDC da célula, ele então executa a precondição de SCIM do attach (recusando, ou --revoke-unprovisioned); só então torna next o único valor, primeiro em loom.cell_self e por último no diretório. Um emissor ou padrão ampliado é reservado no diretório antes que qualquer processo o aceite, e um reduzido só é liberado depois que nenhum o aceita. Uma recusa ou uma espera que se esgota mantém ambos os valores e imprime os processos que ainda não reportam next; executar novamente retoma, e loom cell update --revert espera da mesma forma até que nenhum processo vivo corresponda apenas a next (recusando quando --wait se esgota), depois descarta next, primeiro em loom.cell_self, sob o mesmo lock; uma org configurada que a atualização colocou permanece colocada na célula (uma colocação nunca é excluída).

Um novo token SCIM não altera nenhum fingerprint e não precisa de loom cell update. Uma célula muda a aplicação de seu provedor de identidade como um deployment único (SSO e SCIM), com os mesmos limites; nada nisso é particular às células.

As chaves do heartbeat

O heartbeat de célula de um processo reporta, ao lado do LOOM_CELL com que ele executa, seu modo de tenancy: o estado que sua última leitura das linhas de estado produz (open, recording, enforced ou partial, com o recording de uma célula posterior lido como enforced), e '' somente antes de uma leitura ser concluída ou em um processo que nunca as lê. Seu JSON fingerprint contém a versão e os campos do fingerprint, e ao lado deles chaves que nenhum fingerprint compara: elas nunca estão em loom.cell_self, nos fingerprints do diretório nem no corpo de uma colocação, e uma linha KeeperMap não precisa de coluna para elas (server.core.instances.cell_row). Sua presença prova o build que as reporta; não há chave de geração.

  • serves: LOOM_SERVES_TRAFFIC.
  • marked: se as sessões Postgres em pool deste processo mantêm o marcador de tenancy (loom.tenancy_checked). O refresh da célula o lê junto com as linhas de estado, após RESET ALL na mesma transação: um valor de startup sobrevive ao reset, um SET não, de modo que um pooler, que uma célula não deve ter (Postgres), é lido como não marcado, quer remova os parâmetros de startup, quer os envie de novo com SET, e a leitura é executada na conexão de servidor em que o reset foi executado. Custa três idas e vindas a mais por refresh (BEGIN, RESET ALL e COMMIT), e todo processo reporta um valor novo sem prober. Uma sessão que o pooler removeu, ou um processo com LOOM_CELL não definido sob a autoridade Postgres, lê false; null significa apenas que nenhuma leitura foi concluída (um boot com migrações Postgres ignoradas cuja primeira leitura falhou, ou a autoridade ClickHouse, em que nada é lido). A verificação de readiness cell_marker de um processo com LOOM_CELL definido lê o mesmo valor: ela falha em enforced e partial, onde os triggers recusam as escritas de uma sessão não marcada para uma org que a célula não possui e a linha de tenancy de cada org recém-colocada, e passa com um aviso em recording, de modo que uma primeira célula atrás de tal pooler não trava seu rollout antes do attach, que recusa o processo (solução de problemas).
  • router e router_why: com LOOM_CELL definido, router é null e router_why diz por quê até que a linha first seja lida, e depois ambos estão presentes somente em uma primeira célula (a rota de estado de uma célula posterior responde 404, então ela nem pergunta nem os reporta). router indica se a última leitura deste processo de GET /cells/v1/cells/<cell> com sua própria credencial respondeu 200 nomeando a célula: null até que a primeira leitura responda (ainda em boot), true com tal resposta, e false para uma configuração que nunca funciona: uma configuração do router não definida (o processo nunca pergunta), uma URL que não pode ser requisitada, um 404, uma resposta para outra célula, ou um 401 que persiste além de um LOOM_ROUTER_DIRECTORY_CACHE_S. Essa é a configuração do router, que os processos da célula também carregam: os hashes de credencial em cache de uma réplica do router respondem 401 para um token rotacionado há pouco, então até lá o último valor permanece e router_why diz "401, possibly a rotation" (um router executado com um cache maior pode fazer o attach recusar durante uma rotação; uma nova execução resolve). Uma falha transitória (um timeout, um erro de conexão, um 503, um 200 que não é um objeto JSON nomeando a célula) mantém o último valor, e enquanto router é null, router_why nomeia a última causa desse tipo.

Um leitor em segundo plano por processo de servidor consulta a rota a cada min(LOOM_INSTANCE_HEARTBEAT_SECONDS, LOOM_TENANCY_MODE_CACHE_S) em uma primeira célula até ler serving (server/core/cell_router.py); nada espera por ele, então um router lento não atrasa nenhum beat nem nenhuma requisição, e o beat reporta o que leu por último, com no máximo um período mais LOOM_CELL_ROUTER_TIMEOUT_S de idade quando um beat o escreve. Todo processo uvicorn executa um, de modo que mil pods de oito workers consultam até 1,600 vezes por segundo. Cada réplica do router responde a rota a partir de sua própria leitura da linha da célula, feita no máximo uma vez por LOOM_ROUTER_DIRECTORY_CACHE_S, então o diretório vê uma leitura por réplica por janela; uma leitura com falha responde 503 durante sua janela, de modo que um diretório fora do ar não é consultado com mais frequência e continua respondendo 503. Um processo sem heartbeat (uma CLI, o filho dos workers) consulta sob demanda, no máximo uma vez a cada LOOM_TENANCY_MODE_CACHE_S.

O leitor também mantém a última resposta do diretório para a verificação de tenancy, como uma de quatro: attaching, serving, outro estado, ou desconhecido enquanto nenhuma leitura foi concluída, a última falhou, respondeu sem nenhum estado desta célula (um 401, um 404 ou uma resposta para outra célula), ou está atrasada (mais antiga que o período em que este processo lê, o do leitor em segundo plano ou a janela sob demanda, mais LOOM_CELL_ROUTER_TIMEOUT_S). Quando um processo leu serving, ele mantém isso durante toda a sua vida e não pergunta mais: apenas loom cell restore o rebaixa, e isso reinicia os processos. Uma primeira célula em recording registra uma nova org somente em attaching. Um principal de plataforma ou de org *, ou uma chamada sem principal, não coloca nenhuma org: em uma primeira célula cujo diretório responde attaching, ou não pode ser lido antes de ela ter lido serving, tal chamada para uma org que a célula não possui responde 503 ("attach in progress" ou diretório ilegível), já que os dados da org podem estar nesta célula até que o attach a coloque; uma vez serving, e em uma célula posterior, ela responde 409 WRONG_CELL. Um processo que inicia após serving com o router fora do ar responde essas chamadas com 503 até que sua primeira leitura seja concluída.

Com LOOM_CELL definido, um LOOM_CELL_ROUTER_URL não vazio que não seja uma URL http(s) com host, porta de no máximo 65535 e sem ? nem # recusa o boot (cell.settings_problem); um vazio é permitido, para pods somente de workers (LOOM_SERVES_TRAFFIC=false), cujo heartbeat então reporta router como false com as configurações não definidas em router_why, sem registrar nada em log.

A verificação de tenancy e o posicionamento

Um processo com LOOM_CELL não definido não executa nenhuma verificação de tenancy. Sob a autoridade Postgres (LOOM_STORAGE_AUTHORITY=postgres, a única que uma célula executa), um processo de servidor ainda lê, em uma única instrução, a linha de modo, a linha first e se existe alguma linha em loom.tenancy ou loom.cell_self, com as regras do cache de modo (abaixo). Um comando da CLI que declara uma org lê o mesmo em uma sessão limitada própria: toda tabela de estado ausente (julgada por to_regclass, de modo que um papel sem um grant ainda assim recusa) é lida como open, e uma leitura que falha recusa. Um comando sem org, como a revogação de um token, loom migrate ou loom doctor, não é controlado pelo modo e executa, inclusive durante uma indisponibilidade do Postgres. Com as duas linhas ausentes e sem linha de tenancy nem própria, como em um deployment nunca preparado, ou na primeira célula em recording, o processo continua servindo como um deployment único; todo estado que a regra da linha first (acima) conta como enforced, ou como um estado partial, o controla como enforced controla. enforced (que o attach define na primeira célula quando todo processo ativo tem LOOM_CELL definido, e o prepare em uma célula posterior, cujos processos executam com ele desde o primeiro boot) faz um processo de servidor ficar não pronto, não executar nenhum worker e não responder nada além de suas sondas de saúde e da rota de sonda (para que uma nova execução do prepare consiga alcançá-lo), e faz o comando da CLI recusar; o motivo de prontidão e a recusa citam LOOM_CELL. Assim, um pod ou uma CLI de operador que perde LOOM_CELL em uma célula enforced não escreve para nenhuma org; um que também perde LOOM_PG_DSN ou LOOM_STORAGE_AUTHORITY é recusado pela verificação de autoridade que o deployment já executa (o registro loom.storage_authority do ClickHouse). Os comandos loom cell que se conectam aos stores de uma célula (prepare, attach, place, restore, update) recusam sem LOOM_CELL e, quando o diretório já tem uma linha para LOOM_CELL, recusam stores cujo id de deployment não seja o registrado nessa linha. Um deployment iniciado com LOOM_CELL não definido é um deployment único até ser preparado, e apontá-lo para o prefixo de bucket de outro deployment é a má configuração que é para qualquer deployment. Na primeira célula, loom cell prepare executa antes de LOOM_CELL ser distribuído; uma célula posterior executa com LOOM_CELL definido desde o primeiro boot, então seus processos ficam controlados e se mantêm à parte dos workers (inclusive da varredura de blobs) até o prepare gravar sua linha, e o prepare recusa uma célula posterior enquanto o heartbeat de qualquer processo ativo não tiver LOOM_CELL ou nomear outra célula. O prepare faz três coisas, em ordem:

  1. Ele recusa uma célula cujos stores já carregam a identidade de outra célula: um id de deployment que o diretório registra, ou estado que o diretório não posicionou ali. Isso é verificado pelo roteador, na própria transação do registro, a partir de contagens que o prepare envia: uma célula para a qual o diretório não tem linha não pode ter linha de tenancy, first, modo ou própria, e uma célula posterior não pode ter nenhum objeto sob seu prefixo além da sonda do prepare e nenhum processo ativo sem seu LOOM_CELL. Uma nova execução conta as linhas de tenancy e de estado e os objetos do prefixo como seus; os processos de uma célula posterior executam com seu LOOM_CELL em toda execução, o que o prepare verifica por conta própria.
  2. Ele registra a célula no diretório como attaching, sob o lock do diretório: seu host, o id de deployment lido da célula, o SHA-256 da credencial com a qual ela chama o roteador, e o nome e o prefixo de seu bucket, verificados contra os de todas as outras células, preparadas ou anexadas. A credencial é lcr_ e 128 caracteres hexadecimais minúsculos (512 bits), como loom cell credential new a gera offline, imprimindo a credencial e seu hash; o boot e loom doctor recusam um LOOM_CELL_ROUTER_TOKEN de qualquer outra forma. O prepare recebe o hash como argumento, 64 caracteres hexadecimais minúsculos, de modo que nenhuma CLI precisa do segredo; qualquer outro valor, inclusive a credencial ou seu segredo de 128 caracteres, é recusado, citando loom cell credential new, e não é armazenado em lugar nenhum. Nenhuma outra linha de célula pode conter o hash, nem como atual nem como próximo.
  3. Ele grava as linhas da célula: o modo (recording na primeira célula, enforced em uma célula posterior), a linha first e current.

O prepare é retomável. Uma nova execução para a linha do diretório de mesmo nome, id de deployment e host grava a que estiver faltando entre a linha first e a linha de modo, a partir do estado do diretório, e loom.cell_self como acima (antes do attach a partir dos heartbeats quando ela falta; depois que o diretório guarda a impressão digital, current e next a partir dele, sobrescrevendo um valor presente que difira); antes do attach, uma linha própria presente permanece, e um processo ativo que não executa nem seu current nem seu next recusa. O estado do diretório é o valor de first que o índice único nomeia e o maior modo que ele registra para a célula: recording para a primeira célula ou enforced para uma posterior no registro, na mesma transação da linha, e depois cada modo que o attach eleva, registrado no diretório antes de o attach defini-lo na linha de modo da célula (uma recusa informa a linha de modo como o attach a lê de volta após qualquer retorno a recording, e nunca reduz o registro do diretório). Uma nova execução recusa uma linha de modo acima do estado do diretório e a linha recording de uma célula posterior, sendo nenhuma delas desta célula, e deixa a linha de uma primeira célula abaixo dele para o attach concluir. Uma nova execução recusa um hash de credencial que não seja nem o current nem o next da linha (a rotação cabe a loom cell credential), conta as linhas de tenancy posicionadas ou registradas desde seu próprio registro como suas, e pula as verificações do registro que já passou (o prefixo vazio e a sobreposição de prefixos), de modo que executa em uma célula serving cujo prefixo contém dados.

Um processo com LOOM_CELL definido e sem linha de modo não fica pronto. Com ele definido, o Postgres de cada célula contém loom.tenancy (org, since) e loom.tenancy_mode (recording, enforced); um processo lê o modo por um cache de no máximo LOOM_TENANCY_MODE_CACHE_S (padrão 5 s), mantém o último modo que leu quando não consegue lê-lo, e continua servindo as orgs que possui, por no máximo LOOM_JWT_REVOCATION_MAX_STALE_SECONDS, depois do que fica controlado até que uma leitura se conclua. Todo processo de servidor sob a autoridade Postgres, com LOOM_CELL definido ou não, lê as linhas logo após seus stores abrirem e migrarem, antes de seu primeiro heartbeat e de sua decisão de lease; uma primeira leitura que falha faz o boot falhar (com migrações do Postgres pendentes ele inicia controlado e não pronto até que uma leitura se conclua). Depois disso, um processo com LOOM_CELL definido mantém o limite de obsolescência acima, e um com ele não definido mantém seu veredito através de leituras que falham sem limite de obsolescência, como um deployment único atravessa uma indisponibilidade do Postgres (a primeira exceção em Invariantes). O processo filho de workers de uma célula lê suas próprias linhas e fica controlado até que uma leitura se conclua. Com LOOM_CELL não definido, linhas de modo e first ausentes e sem linha de tenancy nem própria indicam um deployment nunca preparado, e uma leitura que falha nunca é tomada por uma linha ausente; um processo que não lê nenhum estado (o filho de workers e uma CLI com LOOM_CELL não definido, e todo processo sob a autoridade ClickHouse) não é controlado por ele. Em enforced, uma célula serve exatamente as orgs para as quais tem uma linha; uma org que um processo leu como não possuída, para um chamador agindo em outra org, é lida novamente após LOOM_TENANCY_MODE_CACHE_S. Uma linha recording é gravada por uma instrução que a insere somente enquanto o modo é recording, lendo a linha de modo FOR SHARE; ela executa em READ COMMITTED em sua própria transação e confirma antes de a requisição prosseguir. A gravação de enforced pelo attach e esses inserts nunca se cruzam: um insert já em execução quando o attach grava o modo é posicionado pelo passo 4, um que começa depois lê enforced, um fluxo de inserts não consegue segurar a gravação, uma requisição de org nova espera o attach por poucos segundos no máximo, e um attach que trava segurando o lock da gravação o libera em segundos. O attach toma LOCK TABLE loom.tenancy_mode IN EXCLUSIVE MODE (que espera os inserts em execução e enfileira os posteriores atrás dele) em tentativas curtas, em uma transação com timeouts do lado do servidor, depois grava o modo e confirma; após qualquer erro nessa transação ele encerra o backend dessa sessão (pg_terminate_backend, o backend nomeado pelo pid e pelo backend_start que o attach capturou ao conectar) e espera até que tenha saído de pg_stat_activity, depois lê o modo de volta antes de tentar de novo ou informar; um modo lido de volta como enforced é gravado novamente em uma transação nova, cujo commit espera o standby, antes de o attach prosseguir, já que um commit encerrado enquanto ele esperava está apenas no primário. O comando attach fixa esses timeouts, e seus testes cobrem cada um desses casos. O cache de modo lê o modo com um SELECT simples, que não toma lock de linha e nunca espera o attach. Um insert que encontra enforced (um processo cujo cache ainda lê recording) não grava nada: a requisição segue para a chamada de posicionamento como em enforced, e um comando da CLI recusa como em enforced, citando a org. Um processo cujo cache ainda lê enforced depois que o passo 3 ou o passo 4 devolve a célula a recording posiciona pelo gate do roteador até seu cache expirar. loom doctor lista qualquer linha de tenancy que o diretório não posicionou.

  • Executa após a verificação, antes de qualquer coisa ser gravada para a org. O gate de op (gates.authorize) verifica primeiro a org que o transporte resolve (gates.resolve_org, com seus padrões do chamador e orgs de plano), antes de check_acted_for e do provisionamento do namespace pessoal, tanto para HTTP quanto para MCP (via MCP, uma chamada para a org de outra célula responde isError, de modo que um lote mantém suas outras respostas, e uma chamada na própria org do token, como gates.resolve_org a resolve, é verificada antes de os padrões do chamador serem lidos, já que eles vivem nessa org). As rotas fora do registro verificam por check_authorized, admit_org ou pela própria verificação, e um middleware verifica a própria org do bearer verificado nas que agem nela (as rotas que o censo marca token; para um token de org inteira ou sem org nas rotas do chamador que recorrem a ela, a org de cadastro, verificada sem principal, de modo que é registrada ou recusada, nunca posicionada). Um principal que não pode agir na org (um token de outra org) é recusado primeiro, com o 403 do gate, de modo que não registra, não posiciona e não descobre nada: nem se a célula possui a org, nem onde ela está posicionada. Uma op cujo campo de org tem outro nome (from_org) chega à mesma verificação por check_authorized, e um teste de censo lista cada um desses campos. Uma recusa gravada antes da verificação (JSON malformado, um argumento desconhecido, uma falha de validação) não cita, em sua telemetria nem em seu rastro de código, nenhuma org que a célula não possua. Um teste unitário lista cada rota do app e falha a menos que ela esteja marcada como verificada quanto a tenancy ou sem org.
  • A CLI declara suas orgs. Todo comando da CLI que se conecta passa por run_connected, connect_checked ou connect_declared (server/cli/_ch.py), que recebem as orgs que o comando grava, ou o motivo de ele não gravar para nenhuma. Um comando que declara uma org primeiro verifica seu deployment (check_configured), de modo que sob a autoridade Postgres ele precisa de LOOM_PG_DSN. Em uma célula, antes de verificar uma org declarada, eles leem as linhas da célula e recusam o comando a menos que a linha first nomeie sua célula e seus stores (deployment_id, bucket, bucket_prefix) coincidam com um valor da linha própria da célula: uma CLI não verifica nenhum token e sua impressão digital nunca chega ao roteador, de modo que ela pode executar onde os transportes recusam por outro campo da impressão digital. Com LOOM_CELL não definido, o comando é recusado em uma célula além de recording (acima). Uma org que a célula não possui é registrada na primeira célula em recording, como a org de uma requisição é (lendo o estado da célula com a credencial de roteador da célula, LOOM_CELL_ROUTER_TOKEN, na configuração da CLI da primeira célula enquanto seu modo é recording, e somente enquanto o diretório responde attaching), e recusada em enforced; nunca é posicionada. Um comando do índice de código declara a org que grava: seu --org, senão LOOM_CODE_ORG. Uma passagem por todo repositório configurado não declara nenhuma, já que o attach, ou o loom cell update que altera um, posiciona as orgs configuradas, e um comando somente leitura ou uma simulação (dry run) não declara nenhuma, já que uma leitura não registra nada. Um comando sem org diz o que faz aos stores: ele lê, grava (loom ch-setup, secrets, uma alteração de configuração, prepare e os demais; uma simulação lê) ou revoga (loom revoke-token, a revogação de um usuário SQL, loom signing-key retire, loom bot disable, loom sso unlink; um que pode devolver acesso é uma gravação), por subcomando onde uma conexão atende vários (loom signing-key: list lê, retire revoga, rotate e record-root gravam). Com LOOM_CELL definido, uma gravação ou revogação verifica seu ClickHouse contra seu Postgres (check_configured), lê a linha first em uma sessão limitada própria e recusa quando ela nomeia outra célula, o que uma CLI apontada para os stores de outra célula sempre encontra, ou quando a leitura falha; uma linha ausente, ou tabelas de estado ainda não migradas, passa, de modo que uma célula posterior executa esses comandos antes de ser preparada. Uma revogação executa durante uma indisponibilidade (a quarta exceção em Invariantes); uma gravação recusa durante uma; uma leitura não é controlada. loom ch-setup, que configura o ClickHouse em um cliente próprio, executa o mesmo gate antes de gravar, passando um ClickHouse ainda sem registro; loom migrate e loom provider-lock clear gravam pelo cliente do próprio executor de esquema e não são controlados. Um teste de censo falha em uma conexão que não declara nenhuma das duas coisas, em uma sem org que não diz de que tipo é, em uma conexão sob server/cli/ fora de _ch.py, e em um comando loom code que resolve sua org sem se conectar para isso. Quem detém a credencial de roteador da célula pode posicionar orgs para a célula, dentro da taxa da célula e de placements_max, como a credencial de operador que loom cell place usa pode para qualquer célula dentro de seu placements_max (uma chamada de operador não tem limite de taxa nem conta para a taxa da célula), e um posicionamento é permanente, de modo que um nome de org que ele toma é perdido para todas as outras células: um poder sobre o diretório compartilhado que as credenciais de store da célula não têm. Por isso os pods a detêm, e uma CLI apenas para a única leitura que precisa dela, enquanto o modo da primeira célula é recording: um comando da CLI que declara uma org recusa executar com ela definida, citando-a, a menos que a célula seja a primeira e seu modo leia recording, e um comando sem org nunca a usa; uma credencial vazada é contida por loom cell limit --closed, que não precisa de nenhum dos stores da célula, e substituída por loom cell credential (abaixo). loom cell place --org <org> (declarado sem org: ele grava o posicionamento da org e a linha de tenancy, que é como uma org passa a ser possuída), com a credencial de operador do roteador, posiciona uma org para um comando que grava uma nova (um bot, uma importação), pela API de posicionamento do roteador e em sua ordem, como o posicionamento de orgs configuradas pelo attach: ele insere o posicionamento e lê de volta o vencedor, grava a linha de tenancy da célula somente se o vencedor for esta célula (caso contrário recusa e não grava nada), e informa sucesso somente depois que a linha é gravada, de modo que uma nova execução é idempotente. Para uma org que o diretório ainda não posicionou ele passa pelo gate da API de posicionamento (abaixo): recusado enquanto o diretório está indisponível, para uma célula que o gate não aceita, fechada, ou quando a impressão digital da configuração da própria CLI da célula (com o id de deployment lido dos stores aos quais ela se conecta) não coincide com nenhum dos dois valores da linha da célula, ou além de placements_max, e contado para ele.
  • Escritores mais antigos que a verificação são recusados pelos stores em que gravam. Uma sessão que executou a verificação de tenancy se marca com loom.tenancy_checked = 'on': toda sessão de um processo com LOOM_CELL definido a envia como parâmetro de inicialização (de modo que o RESET ALL do pool a mantém), e a sessão de migração a define depois de tomar o lock de migração, já que os passos de dados de uma migração apenas copiam ou reescrevem linhas já armazenadas. Em cada tabela ordinária da autoridade com uma coluna org (não a própria loom.tenancy, nem loom.idempotency e loom.idempotency_fences, indexadas pela org do token do chamador) um trigger de linha AFTER INSERT e AFTER UPDATE, habilitado como triggers de origem, ignora uma sessão marcada em seu WHEN (o de update também ignora um update que deixa a org da linha intacta, de modo que um ON CONFLICT DO UPDATE que atinge uma linha existente não é recusado) e chama uma função (migração 011). A função segue a regra de estado (acima): ela passa toda linha enquanto o estado é open ou uma primeira célula está em recording, e em todo outro estado recusa, SQLSTATE LT001 (503 TENANCY_REFUSED para um chamador), uma linha de uma org sem linha de tenancy (nunca '', '-' ou '*'); ela lê o estado depois que a linha é gravada, sem lock de linha, de modo que nenhuma gravação fica na fila atrás do attach, e o passo 4 (abaixo) espera cada transação que poderia ter lido recording. Um boot com migrações ligadas cria os triggers, em toda tabela assim que encontra no catálogo, somente em uma célula totalmente preparada em enforced e, ali, volta para origem qualquer um que encontre fora dela; o DDL de cada tabela espera 100 ms por tentativa pelo seu lock, três tentativas com um segundo de intervalo (cerca de 2.3 s para uma tabela ocupada, de modo que um boot que encontra toda tabela protegida ocupada espera esse tempo em cada uma em sequência, segurando o lock de migração em que os outros pods em boot esperam), e o boot segue servindo além de uma tabela cujo lock não consegue tomar, registrado em log com os detentores de seus locks, ou uma que o papel não pode alterar, registrada como tal (a terceira exceção em Invariantes). Uma primeira célula fica em recording até o attach definir enforced enquanto executa, de modo que nenhum boot pode tê-los criado: o attach os cria por conta própria com a mesma passagem (cell_triggers.ensure) depois de definir enforced, e a célula passa a serving somente quando cell_triggers.missing não nomeia nenhum defeito. Uma célula posterior é enforced desde o prepare e os recebe em seu primeiro boot com migração após o prepare, o que seu attach exige da mesma forma. loom doctor nomeia um desabilitado ou alterado em qualquer estado, um ausente em uma célula enforced, e uma tabela particionada com coluna org como não suportada, já que ela não recebe trigger. Triggers de origem não disparam na aplicação da replicação lógica nem sob session_replication_role = replica, que os scripts de uma célula não usam. O marcador não é uma fronteira de privilégio: um escritor que o define de propósito passa; os triggers param escritores que não o conhecem, uma CLI mais antiga, um pod rebaixado para antes da verificação, ou um script, de adicionar uma linha para uma org que a célula não possui ou mover uma linha para uma; um update que mantém a org de uma linha, e um delete, não são recusados. O custo dos triggers de org é uma consulta de configuração por linha marcada, e uma leitura do estado e uma consulta a loom.tenancy por linha não marcada; o gate sob o qual eles são lançados é um aumento de p99 de memory.set de no máximo 10 ms e uma taxa de linhas por segundo de uma passagem de entrega em LOOM_PG_DELIVERY_BATCH_ROWS no máximo 10% menor, em enforced com as orgs possuídas. Toda gravação do Loom em uma célula é marcada, de modo que paga apenas a consulta de configuração, medida nas instruções com os triggers ligados e desligados (nenhum custo distinguível de zero: seis rodadas variam de −0.36 a 0.49 µs por linha, resultados de benchmark), o que prevê que o gate se sustenta com ampla margem. O gate em si é uma medição de ponta a ponta de memory.set e de passagem de entrega em uma célula, que precisa do attach e é verificada com ele; até lá os triggers, que uma célula posterior recebe no próximo boot com migração do prepare, são lançados com a medição no nível da instrução. loom.tenancy tem sua própria proteção, já que uma linha de tenancy torna uma org possuída: tenancy_record, um trigger de origem de linha AFTER INSERT OR UPDATE OF org com o mesmo WHEN do marcador, chama loom.tenancy_refuse_unmarked() (migração 012), que recusa, LT001, a linha de tenancy de uma sessão não marcada, ou um update que a move para outra org, em todo estado exceto o de uma primeira célula ainda em recording (open também, já que a própria linha tornaria o estado partial), de modo que um script não pode tornar possuída uma org que o diretório não posiciona. Boots e o attach o criam e reparam como fazem com os triggers de org. Com o attach, loom doctor também lista qualquer linha de tenancy que o diretório não posiciona, o que nomeia uma gravada antes da proteção ou por um escritor que definiu o marcador, e qualquer org em uma tabela do Postgres indexada por org sem linha de tenancy, o que nomeia linhas gravadas antes dos triggers de org, por um escritor que definiu o marcador, ou deixadas por uma linha de tenancy excluída. Antes do primeiro attach o operador rotaciona as credenciais de escrita do ClickHouse da célula (cria o novo usuário, distribui-o para as configurações das builds que verificam, remove o antigo), e o attach recusa enquanto qualquer usuário do ClickHouse com INSERT em loom.* (system.grants, com grants de banco de dados, globais e de papel seguidos por system.role_grants, e usuários de arquivos de configuração ou com ALL implícito contados) não for um que um processo ativo de uma build que verifica ou o usuário configurado da CLI informe, de modo que apenas os detentores da credencial rotacionada gravem no ClickHouse; uma CLI mais antiga que receba essa credencial ainda grava sem verificação, e com o attach loom doctor lista o que ela gravou: qualquer org encontrada em uma tabela do ClickHouse indexada por org sem linha de tenancy, a partir da mesma lista de esquemas do passo 2 do attach.
  • Uma org que a célula não possui é posicionada ali ou recusada. Para um principal verificado com escopo na org (um token dessa org, ou um principal de um emissor ou bot cuja org é ela), a célula chama a API de posicionamento do roteador (POST /cells/v1/placements em LOOM_CELL_ROUTER_URL, respondida com a célula vencedora e seu id de deployment) com sua própria credencial (LOOM_CELL_ROUTER_TOKEN), e a célula que a chamada nomeia deve ser aquela cujo hash registrado a credencial coincide (um hash nomeia uma célula): o roteador posiciona uma org por vez (um lock com escopo de transação na org, que todo caminho que posiciona toma), responde uma org já posicionada com sua célula e, caso contrário, julga a célula solicitante em sua linha travada, insere o posicionamento e lê o vencedor de volta, o que a célula compara por seu nome e id de deployment registrado. Se o vencedor é esta célula, a célula grava a linha de tenancy e serve a requisição; o nome desta célula sob outro id de deployment que o do processo verificado responde 503 e não grava nada; se for o nome de outra célula, a requisição responde 409 WRONG_CELL e nada é gravado. Este é o único caminho pelo qual uma requisição traz uma org a uma célula, seja o que for que a criou: uma emissão (mint), um token de um gateway ou de um emissor federado, uma org prefix* de um emissor de usuário final, um bot. Um principal de org * ou de plataforma age apenas em orgs que a célula já possui e nunca posiciona uma (em uma primeira célula antes de serving, veja as chaves do heartbeat). Para uma org que o diretório ainda não posicionou, o roteador aceita uma chamada de posicionamento somente de uma célula serving (ou da primeira célula enquanto attaching depois que o diretório registra enforced, o que o passo 3 do attach grava antes de definir o modo da célula), e somente com a impressão digital de configuração do processo chamador, cujos campos devem coincidir com um valor da linha do diretório da célula; a linha de uma célula preparada não contém emissores nem padrões de org até o attach gravá-los. Uma chamada que falha, uma sem resposta dentro de LOOM_CELL_ROUTER_TIMEOUT_S, uma célula ainda não anexada ou fechada para novas orgs, ou uma impressão digital que não coincide com nenhum valor responde 503 e não grava nada; uma nova tentativa é segura, já que a leitura de volta a torna idempotente. Para uma org que o diretório já posiciona, a chamada de uma célula é verificada apenas quanto à sua credencial (contra os hashes das células que o roteador mantém em cache por LOOM_ROUTER_DIRECTORY_CACHE_S, padrão 5 s) e à taxa da célula, e um loom cell place apenas quanto à credencial de operador; ambos respondem o vencedor qualquer que seja o estado, a cota ou a impressão digital da célula, sem adicionar posicionamento (o vencedor é público pela consulta de qualquer forma); uma requisição recusada além da taxa de sua célula responde 503 com Retry-After (no máximo um minuto), e sua nova tentativa é admitida pela réplica que a responde quando as chamadas da célula ali estiverem abaixo da taxa. Uma org que a célula já possui não precisa de chamada, de modo que servi-la nunca depende do roteador.
  • Os posicionamentos são limitados por célula. Cada réplica do roteador limita a taxa das chamadas de posicionamento de cada célula por minuto (LOOM_ROUTER_PLACEMENTS_PER_MINUTE), o que limita seu ritmo a essa taxa vezes as réplicas, e a linha de diretório de uma célula pode carregar uma cota de posicionamentos (placements_max, não definida por padrão), que, uma vez definida, limita o total deles, contado e inserido sob um lock na linha de diretório da célula, de modo que chamadas concorrentes entre réplicas do roteador nunca a ultrapassam; além da taxa, toda chamada de posicionamento da célula responde 503 com Retry-After; além da cota, uma chamada para uma org que o diretório ainda não posiciona responde 503 como para uma célula fechada (um loom cell place de operador é isento da taxa, como acima); e os posicionamentos de cada célula são informados em /v1/health?include=capacity e por loom doctor, que nomeia uma célula sem cota. Toda org que o attach da primeira célula posiciona (o snapshot do passo 2, suas orgs configuradas incluídas, e o do passo 4) é contada mas nunca recusada por cota ou célula fechada, já que a célula já a serve e recusá-la deixaria seus dados órfãos (uma além de ORG_MAX_BYTES o diretório recusa, abaixo); todo outro posicionamento de uma org que o diretório ainda não posiciona, incluídas as orgs configuradas de uma célula posterior no attach e uma alterada em loom cell update, passa pelo gate, célula fechada e placements_max incluídos, de modo que uma célula posterior fechada ou cheia antes do attach recusa o attach, citando a org.
  • A primeira célula registra até enforced, como um deployment único. Em recording, que dura até o passo 3 gravar enforced no modo da célula (e de novo sempre que o passo 3 ou o passo 4 a devolve a esse modo), uma requisição verificada para uma org nova grava uma linha de tenancy sem chamada de posicionamento, de modo que a taxa do roteador, placements_max e loom cell limit --closed não se aplicam: novas orgs chegam como em um deployment único, limitadas por suas próprias configurações de cadastro, emissor e JIT, e o passo 2 ou o passo 4 as posiciona sem recusa. loom doctor lista as orgs registradas que não contêm dados, para que o operador veja o que o attach vai posicionar.
  • As orgs configuradas são posicionadas no attach. O oidc_jit_org da célula, o self_signup_org de uma célula com cadastro ligado, e suas orgs de código (LOOM_CODE_ORG e a org de cada entrada de LOOM_CODE_REPOS_JSON que a configuração de código mantém) e a org do tracker são posicionadas como suas quando ela é anexada: as da primeira célula no snapshot do passo 2, as de uma célula posterior antes de ela ser marcada serving. JIT e cadastro próprio passam pela verificação de tenancy como qualquer requisição, e nada recusa no boot: na recording da primeira célula eles registram sua org enquanto o diretório responde attaching, e nos demais casos uma org configurada que a célula não possui responde 503 até ser posicionada (422 para uma além de ORG_MAX_BYTES, que o diretório recusa), o que loom doctor nomeia; todo attach, primeiro ou posterior, novo ou retomado, executa as recusas de sobreposição e posiciona as orgs configuradas dos dois valores de loom.cell_self, de modo que uma que um update colocou em next antes do attach é posicionada com as demais; depois que o attach grava a linha de diretório da célula, loom cell update posiciona uma alterada na transação do diretório que grava next, pelo gate da API de posicionamento para uma org que o diretório ainda não posiciona (células fechadas e placements_max incluídos), recusando, citando-a, quando outra célula a possui, e então grava sua linha de tenancy na célula; para uma célula posterior ainda attaching depois de sua transação de diretório, loom cell update recusa uma alteração de org configurada até a célula estar serving. Em enforced, um worker grava para uma org somente depois que a célula a possui (a verificação de tenancy sem principal), de modo que uma célula posterior não indexa, importa nem varre nada sob suas orgs configuradas antes de o attach posicioná-las; em recording, os workers executam como antes, e o snapshot do passo 2 e a segunda leitura do passo 4 encontram toda org sob a qual eles gravam.
  • As linhas nunca são excluídas. Uma linha de tenancy e um posicionamento nomeiam uma org, não sua memória: ambos são classificados para apagamento como não contendo conteúdo de memória, como a reivindicação de um namespace, e permanecem após qualquer apagamento, de modo que um nome de org nunca fica livre para outra célula. Um processo mantém as orgs que viu como possuídas, e uma org mantida nunca é errada de servir.
  • Um limite de nome de org. Uma célula não registra nem posiciona nenhuma org nova com mais de ORG_MAX_BYTES (2048 bytes UTF-8, server/core/cell.py, abaixo do limite de entrada de índice do Postgres): a verificação de tenancy de uma célula em recording recusa uma com 422 e não grava nada, e o diretório recusa uma com 400 (ORG_TOO_LONG) antes de gravar um posicionamento, para toda rota que posiciona, o que o posicionamento de uma célula transforma no mesmo 422 (via MCP, um erro de ferramenta contado como do chamador). Assim, toda org que uma célula registra pode ser posicionada, e uma org possuída ou posicionada antes do limite mantém sua célula.
  • Uma org posicionada sem linha (uma restauração para antes de seu posicionamento) tem sua linha de volta por loom cell restore, antes de a célula restaurada iniciar (O que cada célula executa).

Anexando uma célula

loom cell attach, executado contra o router, registra uma célula, um attach por vez, e recusa em qualquer falha, nomeando-a:

  • a célula responde em seu próprio host com o deployment id que seu probe_url informa, todo processo ativo tem LOOM_CELL definido com o nome dela, ela executa a autoridade Postgres com um standby síncrono (LOOM_PG_DURABILITY=synchronous) e autenticação imposta, e registra um deployment id que nenhuma outra célula registra;
  • na primeira célula, o papel Postgres do attach consegue ler o estado de transação de todos os backends (pg_read_all_stats) e o Postgres da célula não permite transações preparadas (max_prepared_transactions = 0), de modo que o passo 4 vê todas as transações abertas;
  • suas chaves são só dela: nenhum emissor que ela aceita para bearer tokens é aceito por outra célula, e a impressão digital do segredo raiz (keys_fp) não coincide com a de nenhuma outra célula. Provedores de identidade upstream e emissores de workload podem ser compartilhados, pois a célula emite seu próprio token a partir deles; um gateway (LOOM_IDENTITY_PROVIDER=gateway) emite para uma célula, então um deployment executa um gateway por célula;
  • nenhum processo ativo de qualquer outra célula informa uma impressão digital que não coincide com nenhum dos dois valores da linha do seu diretório, e todo processo ativo da célula que está sendo anexada coincide com o current ou o next de seu loom.cell_self (o attach nomeia qualquer um que não coincida);
  • nenhuma outra célula registra o mesmo par (emissor OIDC, client id) (a linha do diretório os registra, e loom cell update os conta em suas recusas por sobreposição);
  • com SCIM ativado, todo token SCIM que ela possui a nomeia (lsc_<cell>_…) ou, apenas na primeira célula, não nomeia nenhuma célula; uma célula posterior não possui linha de usuário SCIM nem tombstone (suas pessoas são provisionadas após o attach, na ordem LOOM_CELL, um token nomeado e depois a atribuição da aplicação);
  • seu LOOM_PUBLIC_BASE_URL está definido (um processo com LOOM_CELL definido se recusa a iniciar sem ele, de modo que nenhuma URL que ele entrega venha do Host de uma requisição), e os hosts dele e de LOOM_OAUTH_ISSUER (um vazio resolve para a URL base pública) são iguais ao seu host registrado: para a primeira célula, cujo host registrado é o host compartilhado, são o host compartilhado ou um alias registrado dele; o host de nenhuma célula posterior é o host compartilhado ou um alias, o que a tabela hosts do diretório impõe (host como chave primária, normalizado por uma única função, normalise_host: minúsculas, IDNA para ASCII, sem ponto final nem porta padrão, colchetes mantidos em IPv6, usada por hosts, pela regra 1, pelo attach e pela verificação de prontidão; pertencente a uma célula, com um alias pertencendo à primeira célula), escrita na mesma transação de cada verificação, e a partir da qual a regra 1 roteia; LOOM_JWT_ISSUER é uma string opaca, que só precisa ser única; o prepare verifica o mesmo;
  • suas orgs configuradas não colidem com nenhuma org colocada em outra célula, e nenhum padrão de org em que ela confia (os orgs de seus emissores de usuário final) se sobrepõe aos padrões ou às orgs configuradas de outra célula, nem o padrão de outra célula corresponde às suas orgs configuradas, pela regra de sobreposição que um deployment único aplica aos seus próprios emissores de usuário final;
  • seus stores não são os de outra célula: uma chave de sonda escrita em um nome reservado de seu KeeperMap loom._migration_lock não é visível a nenhuma outra célula e a sonda de toda outra célula é invisível a ela (um ClickHouse sem Keeper recusa); seu prefixo de bucket não é prefixo de caminho do de outra célula em um bucket de mesmo nome, em qualquer endpoint, nem tem um, e objetos de sonda não são listados em nenhuma das direções;
  • todo processo ativo de toda célula executa um build cujo predecessor também executa a verificação de tenancy (abaixo), e um heartbeat que informa seu modo de tenancy, a impressão digital e o LOOM_CELL com o qual executa;
  • com SCIM ativado, nenhuma conta ativa tem um e-mail de contato ou verificado sem uma linha SCIM ativa (contas com senha, sessões de refresh ativas e contas de serviço pessoais incluídas), e nenhuma conta de serviço ativa tem uma cadeia de criadores que termina em uma conta sem e-mail (tokens de agent-signup feitos antes do SSO): o attach as lista e recusa, ou, com --revoke-unprovisioned, encerra seus tokens emitidos antes do attach sob o próprio prefixo de revogação do SCIM, de modo que uma pessoa que o provedor de identidade provisionar depois seja admitida, já que ele nunca desprovisionará uma pessoa que não conta como atribuída.

O primeiro attach transforma o deployment existente na primeira célula, em ordem:

  1. verificar se o modo é recording, como o prepare definiu: toda requisição verificada escreveu a linha de tenancy de sua org, se ausente, enquanto o diretório respondia que a célula está attaching;
  2. em uma transação do diretório, escrever attach_started_at, os emissores, padrões e impressão digital da célula (ambos os valores de loom.cell_self) e as colocações, depois as linhas de tenancy, de toda org que a célula mantém, a partir de um snapshot, direto no diretório (nenhuma outra célula existe ainda): suas orgs configuradas (de ambos os valores), o org distinto de toda tabela dos dois schemas (gerado a partir do schema, como a classificação de tabelas do erasure) e as orgs de objetos de bucket catalogados; nunca '', '-' ou '*';
  3. definir enforced como acima, dentro de --wait, que a espera abaixo então compartilha, sem iniciar nenhuma tentativa que possa confirmar o modo com menos tempo restante que o mínimo dessa espera (a vida útil do cache de modo mais o maior prazo de requisição): o attach então recusa, informando o modo que lê de volta (recording, e uma nova execução retoma do passo 1), ou o modo como desconhecido quando não consegue lê-lo, e uma nova execução então retoma pelo modo que ler; depois esperar, dentro do que resta de --wait (padrão 10 minutos, depois recusar e definir recording de volta), até que todo processo ativo informe enforced e então a vida útil do cache de modo mais o maior prazo de requisição tenham passado; depois executar a precondição SCIM novamente (--revoke-unprovisioned de novo, se informado), para contas feitas antes de enforced entrar em vigor; se ela recusar, a célula permanece enforced e attaching, e executar o attach novamente retoma a partir da espera, como faz um attach retomado (abaixo);
  4. esperar, dentro do que resta de --wait, até que nenhuma transação que possa ter lido recording ainda esteja aberta, julgado a partir de um snapshot do Postgres que o attach toma depois de ter lido enforced de volta nesta execução (não de um relógio): conta como aberta uma transação no banco da célula que começou antes dele, de qualquer cliente, worker em segundo plano ou conexão de replicação lógica, inclusive as somente leitura, uma transação de escrita em outro banco do mesmo servidor que começou antes dele (ela segura o horizonte de todo snapshot, e é nomeada como tal), uma transação preparada (que recusa de imediato), ou uma cujo estado o attach não consegue ler; não contam os processos de manutenção do próprio Postgres, as conexões de replicação física (as de todo standby e de um base backup, que não executam SQL) e as conexões do próprio attach. Passado --wait, o attach recusa, nomeando o que esperou, e deixa a célula enforced, de modo que uma nova execução retoma da espera do passo 3. O comando attach fixa a consulta exata, e seus testes cobrem cada tipo de transação. Quando a espera termina, colocar as linhas de tenancy escritas desde o snapshot e toda org que as fontes do passo 2 fornecem quando lidas novamente (o org distinto de toda tabela dos dois schemas e as orgs de objetos de bucket catalogados; uma linha ou um objeto que um escritor não verificado, como uma CLI mais antiga ou um worker, escreveu em recording depois do snapshot também é colocado), verificar de novo que todo processo ativo informa enforced (recusando e voltando a recording como o passo 3 faz, se algum não informar) e marcar a célula como serving. O diretório registra o modo mais alto que o attach elevou ou tentou elevar, que loom cell restore só escreve de volta para cima: uma célula cujo passo 3 foi recusado no lock é restaurada como enforced, e seu attach retomado então executa a partir da espera do passo 3.

Uma célula posterior só é anexada quando a primeira está serving. Ela não deve conter dados de org (o attach recusa caso contrário) e começa em enforced. Seu attach executa, em ordem: as recusas; uma transação do diretório, sob o lock do diretório e com as recusas por sobreposição executadas novamente dentro dela, que escreve attach_started_at, as colocações de suas orgs configuradas e seus emissores, padrões e impressão digital (ambos os valores de loom.cell_self), recusando e não escrevendo nada quando uma leitura de volta nomeia outra célula (ela nomeia a org); as linhas de tenancy de suas orgs configuradas e de seu loom.cell_self, na célula; a precondição SCIM (--revoke-unprovisioned, se informado); e serving. Um attach posterior retomado executa novamente as recusas, exceto as de uma célula nova, e continua a partir do primeiro destes passos não concluído; as colocações são idempotentes por meio da leitura de volta. Suas pessoas são provisionadas pela aplicação do próprio provedor de identidade antes de entrarem. Os serviços próprios de uma org são anexados como uma célula à parte. Uma nova org de pessoas começa com loom cell place --org, depois a atribuição de suas pessoas às aplicações dessa célula; uma célula com SCIM ativado não admite ninguém até que seu primeiro ciclo de provisionamento tenha sido executado. Uma célula que se aproxima dos limites de seus stores é fechada para novas orgs: suas chamadas de placement respondem 503, de modo que as novas orgs de seus emissores esperam por capacidade em vez de se espalharem para outro lugar.

Um primeiro attach retomado, para uma célula cuja linha do diretório tem attach_started_at, executa novamente toda recusa da lista acima que se aplica à primeira célula. Em seguida continua pelo modo da célula: em recording, a partir do passo 1; em enforced, a partir da espera do passo 3 (todo processo ativo informa enforced, depois passam a vida útil do cache e o maior prazo de requisição) e então sua precondição SCIM, de modo que a verificação SCIM que encerra um attach interrompido após definir enforced, seja qual for o motivo, sempre execute depois que enforced tenha entrado em vigor.

O que cada cell executa

Tudo o que um deployment executa, sem alterações: seus pools, migrations, workers e seus leases, health e readiness (a readiness de um pod é a da sua cell), erasure e seu census, audit checkpoints, backups e restores. O restore de uma cell é o de um único deployment (backup e recuperação), com os mesmos limites: o que o backup contém (suas chaves, revogações, sessões, bots e linhas de SCIM) volta como estava. Uma cell acrescenta um passo depois do restore do store e antes de qualquer outro passo que essa página execute: loom cell restore, com a cell parada, executado onde o operador executa loom cell place e attach, com a credencial de operador do router, que nenhuma configuração de cell contém (um comando de CLI declarado sem org: ele grava as linhas da própria cell), grava de volta, a partir do directory, as linhas que um restore pode recuperar, de modo que as erasures e redactions do loom reconcile passem na verificação de tenancy, e um restore de ambos os stores, que o loom reconcile recusa, ainda recupera as linhas da sua cell. Ele recusa enquanto o directory estiver indisponível, e grava:

  • uma linha de tenancy para cada org que o directory coloca nela;
  • a linha first e a linha de mode, o que estiver ausente, a partir do directory, como faz um prepare retomado; uma linha first presente que difere da do directory é recusada, e uma que coincide é mantida;
  • depois que as linhas de tenancy voltam, o mode registrado no directory sobre a linha de mode, somente para cima (recording para enforced), nunca para baixo;
  • depois que a linha do directory contém o fingerprint da cell (o attach o grava), o loom.cell_self dela a partir dele (current e next); antes do attach o directory não contém nenhum, e o loom.cell_self restaurado permanece como o backup o contém (um current ausente é gravado por uma nova execução de loom cell prepare assim que a cell inicia, um next perdido por outro loom cell update --config).

Uma primeira cell restaurada para antes do seu prepare, e ainda não anexada, não serve nada no host compartilhado em seus processos com LOOM_CELL definido (um com ele indefinido serve como um deployment único, como antes do rollout) até essa nova execução de loom cell prepare, que é o passo logo após ela iniciar.

A readiness de uma cell nunca espera pelo directory, então uma indisponibilidade dele não trava o rollout de nenhuma cell. Um processo que lê recording registra uma nova org somente enquanto o directory responde que sua cell está attaching (as chaves do heartbeat); enquanto o directory está ilegível ou marca a cell como serving, uma nova org responde 503 e as orgs que a cell contém continuam sendo servidas. Um restore para antes do passo 3 do primeiro attach cujo loom cell restore foi pulado, portanto, não serve nenhuma org que não contenha; o loom doctor aponta tal cell, e o loom cell restore eleva o seu mode.

O directory é um store de alta disponibilidade. Seu Postgres roda com um standby síncrono e point-in-time recovery até o seu último commit, como o de uma cell, de modo que um failover ou uma corrupção não perde nada que tenha sido confirmado. Perdê-lo por completo é uma indisponibilidade que falha de forma fechada: toda cell continua servindo as orgs que contém, o roteamento continua a partir do snapshot assinado de cada réplica do router com o seu último cache (gravado em armazenamento compartilhado a cada mudança do directory), e os placements, as consultas de orgs fora do cache, os comandos loom cell que leem ou gravam no directory e as leituras de estado das cells em recording respondem 503 ou recusam até o directory voltar, enquanto o loom doctor informa suas verificações do directory como não executadas e, com LOOM_CELL definido, sai com código diferente de zero; reconstruir um directory perdido a partir das cells é um design à parte.

Cada cell mantém, em seu próprio Postgres, uma cópia do fingerprint de configuração da linha do seu directory (loom.cell_self), com o qual seus processos comparam a sua configuração e que o attach e o loom cell update gravam (A linha própria da cell). O loom cell restore regrava o loom.cell_self a partir do directory; os stores restaurados carregam o deployment id da cell, então um restore para um novo endpoint precisa apenas do novo endereço na configuração da cell. Fechar uma cell ou definir seu placements_max é um único comando, loom cell limit --cell <cell> [--closed | --open] [--placements-max (<n> | none)], que grava somente no directory, com a credencial de operador do router e sem nenhum dos stores da cell, de modo que funciona enquanto a cell está fora do ar; o router avalia um placement a partir da linha do directory.

Operações

  • loom cell restore, após qualquer restauração de store e antes de loom reconcile, grava de volta as linhas da célula a partir do diretório (O que cada célula executa).
  • loom cell which --org <org> indica a célula de uma org (apagamento, restauração e suporte começam por aí); para uma org sem placement, indica a primeira célula, e a consulta não distingue os dois casos.
  • loom cell limit --cell <cell> --closed fecha uma célula para novas orgs, --open a reabre e --placements-max <n> define sua cota de placements (--placements-max none remove a cota).
  • loom cell remove --cell <cell> remove a linha do diretório de uma célula que está attaching sem nenhum placement (--cell é o LOOM_CELL da célula, já sem valor definido nesse ponto). Para a primeira célula, lê apenas o Postgres da célula, em uma sessão a partir de LOOM_PG_DSN, sem ClickHouse, e recusa a operação a menos que leia open e registre o deployment id da linha, o que impõe a ordem de reversão: remover LOOM_CELL de todos os processos (cada um passa a servir como em recording), depois a limpeza completa do estado e, por fim, a remoção (solução de problemas). Remover a linha primeiro faz toda nova org receber 503; limpar o estado primeiro bloqueia todos os processos que têm LOOM_CELL definido. Uma primeira célula com placement só avança, nunca volta. Os stores de uma célula removida mantêm as linhas de estado que contêm, então a limpeza completa do estado roda antes de eles serem preparados novamente.
  • A credencial de operador do router é lco_ seguida de 128 caracteres hexadecimais minúsculos (um router sem LOOM_ROUTER_OPERATOR_SHA256 responde 503 à API de operador com NO_OPERATOR_CREDENTIAL), que loom cell credential new --operator gera; o router guarda apenas o SHA-256. As recusas da API de operador não têm limite de taxa: um limite por endereço permitiria que um estranho atrás de um ingress compartilhado bloqueasse todos os operadores, e 512 bits não são adivinhados online. Um comando de operador só conhece seu resultado quando a conexão nunca foi aberta ou o próprio router respondeu, exceto BACKEND_UNAVAILABLE (um COMMIT pode ser concluído após seu limite); após um timeout, uma conexão interrompida ou a página de um gateway, ele informa que a alteração pode ter sido feita e o que uma nova tentativa mostra. A credencial de operador é rotacionada definindo o novo hash em LOOM_ROUTER_OPERATOR_SHA256 e reiniciando o router; enquanto suas réplicas são atualizadas, algumas ainda recusam a nova credencial com 401, e o operador executa o comando novamente até que todas as réplicas a aceitem. Os comandos chamam o router em --router, ou em LOOM_CELL_ROUTER_URL, na raiz (um caminho ali é recusado, pois o router encaminha um para uma célula), e enviam a credencial de operador somente por https (http em loopback), de modo que um endereço de router http na rede interna atende a uma célula, mas não esses comandos.
  • loom cell credential new gera uma credencial de router offline e a imprime com seu SHA-256; loom cell credential --cell <cell> --next <sha256> registra o SHA-256 de uma nova credencial de router como o hash next da célula; como o prepare, recebe o hash como argumento, na mesma forma. Usa a credencial de operador do router, grava apenas o diretório e mantém o lock do diretório; é recusado quando qualquer célula registra esse hash como current ou next, e enquanto houver um next pendente. O router aceita ambos nas chamadas de placement e nas leituras de estado, cada réplica dentro de LOOM_ROUTER_DIRECTORY_CACHE_S de --next, de modo que a nova credencial só vai para os pods depois disso; loom router migrate roda antes de um router que lê o hash next, e uma rotação começa quando todas as réplicas do router o fazem. Um router revertido para um build que lê apenas o hash current recusa um pod com o próximo: faça o rollback sem next pendente (--revert antes) e não entre --finish e a saída da credencial antiga dos pods. Quando a nova credencial estiver nos pods da célula e, enquanto o modo da primeira célula for recording, na configuração da CLI, loom cell credential --cell <cell> --finish torna next o current e descarta o antigo; ele não verifica o que não consegue ver (o router não sabe qual credencial um pod possui), e uma célula finalizada cedo demais falha de forma fechada: suas chamadas de placement e leituras de estado respondem 401, no mais tardar quando o cache do router com os hashes da célula expira (LOOM_ROUTER_DIRECTORY_CACHE_S), até que seus pods tenham a nova credencial, ou que o hash antigo seja registrado novamente com --next e finalizado. loom cell credential --cell <cell> --revert descarta um next pendente, de modo que um valor errado ou vazado nunca precise ser finalizado; --finish e --revert são recusados sem next pendente.
  • As configurações de uma nova célula nomeiam LOOM_CELL, seu host público (LOOM_PUBLIC_BASE_URL, LOOM_OAUTH_ISSUER, LOOM_JWT_ISSUER), suas chaves, seu prefixo de bucket, suas orgs configuradas, seu cliente OIDC do provedor de identidade e o token SCIM, e sua credencial de router (LOOM_CELL_ROUTER_URL, LOOM_CELL_ROUTER_TOKEN, que seus pods possuem, e LOOM_CELL_ROUTER_TIMEOUT_S).
  • Cada célula informa gravações por segundo, linhas por namespace e bytes por chave em /v1/health?include=capacity, contra cerca de 13.6 KB por chave no ClickHouse e 6.8 KB no Postgres (Memória em escala).
  • Uma org permanece em sua célula. Mover uma org entre células é um projeto à parte: exige que as gravações da org sejam bloqueadas em todos os processos da célula, uma cópia de cada store que não conte nada duas vezes e uma remoção verificada.
  • Os dados de uma célula permanecem em seus stores. Movê-los para outros stores (outro deployment id, nome de bucket ou prefixo), ou adicionar um bucket a uma célula preparada sem um, é um projeto à parte: processos antigos e novos gravariam em stores diferentes durante qualquer rollout, então exige que as gravações da célula sejam bloqueadas, como em uma movimentação de org.
  • Uma célula permanece anexada. Aposentar uma célula é um projeto à parte: exige prova, vinda dos próprios stores, de que toda cópia dos dados de suas orgs foi apagada, antes que qualquer coisa possa afirmar que foi. Até lá, uma célula que está fora do ar continua sendo uma célula: suas orgs respondem 503, e seus nomes, issuers, hosts e placements permanecem reservados.

Modos de falha

Falha O que acontece
O diretório está fora do ar as requisições por host, por emissor e para a primeira célula são roteadas; novas orgs e consultas sem cache respondem 503
A chamada de posicionamento do roteador falha a requisição responde 503 e nada é gravado; as orgs que a célula mantém continuam sendo atendidas
O emissor de uma célula posiciona orgs em massa a partir de enforced, suas chamadas de posicionamento respondem 503 com Retry-After acima da sua taxa, e suas chamadas para novas orgs respondem 503 acima da sua cota, se houver uma definida; as outras células posicionam como antes
Um token SCIM de outra célula, ou uma aplicação no host da célula errada o processo não inicia, ou /scim/v2 responde 401 e não grava nada
O Postgres ou o ClickHouse de uma célula essa célula falha como uma implantação única (autoridade de armazenamento); as outras células continuam atendendo
As linhas próprias de uma célula ou o modo de tenancy ficam ilegíveis com LOOM_CELL definido, um processo mantém as últimas linhas e o último modo dentro do limite de obsolescência e depois fica bloqueado; um processo de servidor cuja primeira leitura falha não inicia (bloqueado e não pronto com migrações do Postgres pendentes), e um processo filho de workers que nunca as leu fica bloqueado; com ele indefinido, um processo de servidor mantém seu veredito sem limite, e uma primeira leitura com falha faz o boot falhar (bloqueado até que uma leitura funcione, com migrações do Postgres pendentes)
Uma linha first ou de modo removida, ou ambas ao lado de uma linha de tenancy ou própria os gatilhos de org, onde a célula os tem, agem como em enforced e todos os processos ficam bloqueados; loom doctor aponta o problema, e uma nova execução de prepare grava as linhas de volta
Nenhuma linha de estado, de tenancy ou própria em uma célula que o diretório registra aberto; loom doctor aponta o problema; loom cell restore o fecha após uma restauração, e uma nova execução de prepare o fecha após um prepare interrompido
O valor first de uma célula ainda não foi lido toda requisição, exceto as sondas de saúde e a rota de sonda, responde 503 (SCIM com Retry-After); o processo fica não pronto e não executa nenhum worker (um processo filho de workers, ou um processo de servidor com migrações do Postgres pendentes; qualquer outro processo de servidor falha no boot)
Uma requisição para a org de outra célula 409 WRONG_CELL após a verificação, nada é gravado
Uma chamada de plataforma, de org * ou sem principal para uma org que não é mantida em uma primeira célula, 503 enquanto o diretório responde attaching ou não pode ser lido antes de uma resposta serving; 409 WRONG_CELL depois de serving e em uma célula posterior
Um pooler que remove o marcador de tenancy das sessões de uma célula a verificação de prontidão cell_marker falha em enforced e partial e emite aviso em recording; o heartbeat informa marked false e o attach recusa o processo
Uma célula restaurada para um momento anterior loom cell restore grava de volta as linhas das orgs posicionadas antes de iniciar
Uma primeira célula restaurada para antes do seu prepare, ainda não anexada em processos com LOOM_CELL definido, toda requisição, exceto as sondas de saúde e a rota de sonda, responde 503 até que o prepare seja executado de novo
O diretório perdido cada célula atende as orgs que mantém; posicionamentos e consultas sem cache respondem 503 e os comandos do diretório são recusados, até que ele volte
Uma célula em recording, com o diretório ilegível uma nova org responde 503; as orgs que ela mantém continuam sendo atendidas
Um processo travado durante o primeiro attach o attach é recusado após --wait e a célula volta para recording
Um insert de recording mantido aberto durante o primeiro attach o attach para de tentar quando resta pouco de --wait para a espera, informando o modo que lê de volta; uma nova execução o retoma
O attach trava enquanto mantém o lock da tabela de modo o Postgres encerra sua sessão em segundos e libera o lock; novas orgs respondem dentro do seu prazo
Uma transação aberta desde antes do snapshot do passo 4 o attach é recusado quando --wait se esgota (uma transação preparada, de imediato), nomeando a transação que esperou, e deixa a célula em enforced
Um comando da CLI com LOOM_CELL indefinido, iniciado antes do passo 3 do attach ele leu o estado enquanto a primeira célula estava em recording e continua gravando no ClickHouse após serving; o runbook define LOOM_CELL em toda CLI antes do attach
Uma CLI de um build anterior à leitura do estado ela não é recusada em uma célula enforced; toda imagem de CLI e de CI executa um build com a leitura antes do attach (atualizações)

Atualizações graduais

A verificação de tenancy, a chamada de placement e a leitura do estado da célula, as declarações de org da CLI, LOOM_CELL, loom cell prepare, scim.refuses_subject, o e-mail que um grant armazena, loom.cell_self, o gate de requisição e a verificação de prontidão da fingerprint de um processo contra a própria linha, a recusa do token SCIM de outra célula, o requisito de SCIM e o modo, a fingerprint e o LOOM_CELL do heartbeat são entregues em uma única release. O gate em um processo com LOOM_CELL não definido, o marcador de sessão e os triggers de org são entregues juntos em uma única release; o prepare de uma primeira célula admite um processo da release anterior, que atende enquanto a célula está em recording, e o loom cell attach, que é entregue em uma release posterior e lê a própria chave de heartbeat, recusa a operação até que todos os processos ativos executem essa release, de modo que o único rollback suportado a partir de uma célula anexada cai em um build que envia o marcador. A migração dos triggers de org é aditiva, e os triggers não fazem nada em um deployment que nunca foi preparado (sem linhas de estado, a regra da linha first). Com LOOM_CELL não definido, um processo lê apenas as linhas de modo e first e se existe uma linha de tenancy ou própria, e somente sob a autoridade Postgres, onde um deployment nunca preparado não tem nenhuma (as tabelas são criadas vazias), então os builds N-1 e N atendem lado a lado sem mudanças. O roteador roteia por host, issuer e pela primeira célula, nunca pelas ops de uma célula, então a release de uma célula não espera pela do roteador, exceto pela que o próximo parágrafo cita.

As chaves ao lado da fingerprint de um heartbeat (as chaves do heartbeat) são as chaves de heartbeat próprias da release do attach: um build anterior a elas lê apenas a versão e os campos de uma fingerprint, então aceita o heartbeat de um build mais novo como está, e o attach recusa um processo que não informa nenhuma. Essa release espera pelas dos roteadores: toda réplica do roteador a executa antes de qualquer processo de qualquer célula, já que uma primeira célula preparada consulta a rota de estado desde a primeira leitura de estado da célula até ler serving, e somente um roteador dessa release a responde a partir do seu cache (atualizações).

Invariantes

  • Uma org é atendida por exatamente uma célula, a que o seu placement indica, e o seu placement nunca é excluído nem alterado.
  • Um processo com LOOM_CELL definido não responde a nada além de seus health probes e da rota de probe, e não executa nenhum worker, a menos que sua configuração corresponda a um valor da linha da própria célula, que as recusas de sobreposição do diretório já verificaram; um processo com LOOM_CELL não definido em uma célula cujas linhas de estado contam como enforced ou estão em um estado partial (a regra da linha first) não responde a nada além de seus health probes e da rota de probe e não executa nenhum worker.
  • Nenhum emissor de bearer token, host, cliente OIDC, padrão de org ou prefixo de bucket é aceito por duas células, e nenhum id de deployment ou credencial de roteador é mantido por duas.
  • Todo caminho de segurança falha de forma fechada, com quatro exceções. Primeira: um processo de servidor com LOOM_CELL não definido mantém seu veredito diante de leituras com falha das linhas de estado, sem limite de obsolescência: aberto em open e recording, como é a indisponibilidade parcial de um deployment único, e bloqueado em todos os outros estados; uma primeira leitura com falha faz o boot falhar ou, com migrações do Postgres pendentes, o deixa bloqueado até que uma leitura seja concluída. Segunda: uma célula registrada sem linha de estado, de tenancy ou própria (seu Postgres restaurado para antes do seu prepare, ou um prepare interrompido antes da gravação da sua linha), que fica aberta até loom cell restore (após uma restauração) ou uma nova execução do prepare (após um prepare interrompido) e é apontada por loom doctor enquanto isso: uma linha, um modo ou um valor de first não lido causa recusa; com o diretório inacessível, placements, consultas fora do cache, os comandos loom cell que o leem ou gravam e as leituras de estado das células de registro são recusados, enquanto cada célula continua atendendo as orgs que mantém. Terceira: um boot com migração que não consegue criar ou habilitar um trigger de org ou o guard loom.tenancy em uma tabela, ou restaurar os triggers de loom.cell_first para always (seu lock não obtido em três tentativas de 100 ms, ou uma tabela que o role não pode alterar), registra o problema em log e passa a atender, deixando essa tabela sem proteção até que um boot posterior tenha êxito: os triggers são apenas uma salvaguarda contra escritores que não enviam marcador, recusar o boot derrubaria uma célula por causa de uma salvaguarda, e o attach recusa um trigger ausente. Quarta: um comando de revogação sem org que não pode devolver acesso (um loom revoke-token simples, não um que restringe ou expira, a revogação de um usuário SQL, loom signing-key retire, loom bot disable, loom sso unlink) com LOOM_CELL definido, cuja leitura da linha first da célula falha porque o Postgres não responde, é executado e informa que a célula não foi verificada, já que uma revogação precisa funcionar durante uma indisponibilidade; qualquer outra leitura com falha, incluindo a falta de uma permissão, é recusada.

Pontos de entrada do código-fonte

  • server/core/cell_probe.py: a rota de sonda e o listener de sonda, que todo processo web aceita e que o processo filho dos workers nunca abre;
  • server/core/cell.py: o estado próprio da célula (loom.cell_first, loom.tenancy_mode, loom.cell_self), a regra de estado do deployment (state, sobre as linhas que refresh lê, incluindo se loom.tenancy tem alguma linha entre elas), sua impressão digital e gate_reason, o gate nos processos com LOOM_CELL definido ou não definido, que o middleware de requisição (server/transport/model_maintenance.py), verify_token, a prontidão, o lease dos workers e a leitura do heartbeat usam; start_cell_gate, em server/boot.py, é a leitura de boot de um processo do servidor;
  • server/core/cell_triggers.py: o marcador dos triggers de org, ensure (a criação e o reparo, no boot que executa migrações, dos triggers e da proteção de loom.tenancy) e missing (o que loom doctor aponta), com suas funções em schemas/pg_migrations/011_tenancy_triggers.sql e 012_tenancy_guard.sql; server/cli/doctor_cell.py: as verificações de célula do loom doctor;
  • server/cli/cell_scan.py: a varredura de orgs do primeiro attach, uma biblioteca que nenhum comando chama: as tabelas dos dois stores com uma coluna org, avaliadas por engine e de acordo com a classificação do apagamento, com todos os hosts de um cluster listando o mesmo, e as orgs distintas de cada tabela fora de LOG_TABLES; server/cli/cell_writers.py: a verificação de escritores do ClickHouse (os usuários, diretórios de usuários, objetos e réplicas fora das listas de permissão do operador); server/cli/cell_ch.py: o que os dois compartilham (os hosts do cluster, as leituras por host);
  • schemas/pg_migrations/008_cells.sql, schemas/pg_migrations/009_cell_probe.sql e schemas/migrations/094_cell_heartbeats.sql: as tabelas da célula;
  • server/auth/tenancy.py (ensure_held): a verificação de tenancy e a chamada de posicionamento, executadas pelo gate de ops (server/transport/gates.py), por check_authorized, por admit_org e pelas rotas que nomeiam uma org; server/transport/tenancy_gate.py verifica a org do próprio token nas rotas fora do registro que agem nela, e tests/unit/test_cell_tenancy.py contém o censo de todas as rotas;
  • server/router/app.py (loom router serve): a API de posicionamento, a leitura do estado da primeira célula (que server/core/cell_router.py faz em uma primeira célula), o roteamento pelas regras 1 a 4 (server/router/routing.py, que decide, e o encaminhamento), a consulta de org com seu cache de orgs posicionadas (que loom login --org, loom.credentials.org_server, consulta), seus limites de taxa (server/router/limits.py) e as verificações por que um posicionamento passa; sua API de operador, com as rotas de attach da primeira célula, que loom cell limit, loom cell credential e loom cell remove (server/cli/cell.py, com loom cell which) chamam com a credencial de operador do router (LOOM_ROUTER_OPERATOR_TOKEN; o router guarda apenas LOOM_ROUTER_OPERATOR_SHA256); server/router/directory.py e schemas/router_migrations/: o diretório, no banco Postgres próprio do router (LOOM_ROUTER_PG_DSN, loom router migrate).

O restante do código de célula é adicionado pelos pull requests que implementam esta página. Ele se baseia em:

  • server/auth/jwt.py (verify_token, AuthUnavailable): onde o gate de impressão digital roda primeiro;
  • server/auth/scim.py (tokens) e server/auth/scim_routes.py (scim_settings_problem, _authorized): o parser de tokens SCIM e suas verificações;
  • server/core/instances.py: o heartbeat que informa o modo, a impressão digital, LOOM_CELL e as chaves ao lado da impressão digital;
  • server/workers/leader.py: o lease do qual um processo com gate se afasta;
  • server/core/pg.py (same_deployment): o id do deployment que os dois stores carregam;
  • server/transport/gates.py (resolve_org, authorize): onde a verificação de tenancy roda;
  • server/cli/_ch.py (run_connected, connect_checked, connect_declared): as declarações de org da CLI, que tests/unit/test_cell_cli_orgs.py exige de toda conexão;
  • server/auth/authz.py (check_acted_for, _check_creator) e server/auth/oauth.py (_refresh_session): as verificações SCIM ao agir e ao renovar;
  • server/identity/app/scim_groups.py (_caller): a segunda rota SCIM.

Rejeitado

  • Um plano de controle compartilhado pelas células (um único conjunto de chaves, concessões e workers, com os dados divididos por org): uma verificação de segurança, um lease de worker, uma exclusão, uma geração de política e a cadeia de auditoria passariam a abranger vários armazenamentos, e cada divisão exigiria um protocolo próprio.
  • Alocar uma org na primeira requisição, antes da verificação: qualquer pessoa poderia escolher a célula de uma org, e um token emitido em uma célula poderia endereçar uma org alocada em outra.
  • Uma lista dos caminhos que criam uma org, cada um alocando-a: as orgs passam a existir por mais caminhos do que uma lista consegue acompanhar (tokens de gateway e federados, bots, importações); a verificação é o único ponto por onde toda requisição passa.
  • Redirecionar um fluxo de uma célula para outra no meio do caminho: o cliente, os códigos e os refresh tokens de um fluxo vivem na célula que o iniciou.
  • O roteador mantendo os usuários do provedor de identidade para todas as células: o alcance de cada e-mail em cada célula, uma versão que sobreviva à perda do diretório, os envios e as buscas seriam, cada um, um protocolo próprio, enquanto o provedor de identidade já desprovisiona todos os aplicativos aos quais uma pessoa está atribuída.
  • Cada réplica acessando os armazenamentos de todas as células: um pool por réplica por célula, o custo que Um banco de dados por tenant rejeita.
  • Rotear por namespace dentro de uma org: uma operação que abrange a org inteira (sua exclusão, ids resolvidos entre namespaces, compartilhamento) passaria a abranger várias células; uma org grande recebe uma célula própria.

Testes

Um teste de integração com duas células e um roteador no job de Postgres do CI:

  • uma requisição verificada de uma nova org em cada célula a posiciona uma única vez sob requisições concorrentes, e a outra célula responde WRONG_CELL; uma org emitida pelo gateway, uma org prefix* de um emissor de usuário final e a org de um bot são posicionadas da mesma forma após enforced, e a requisição de um principal da plataforma para uma org não mantida não posiciona nada;
  • toda rota, incluindo as entradas em lote do MCP e todo comando da CLI, recusa a org de outra célula e não grava nada no Postgres nem no ClickHouse dela (os censos de rotas, de campos de op e da CLI cobrem o restante);
  • o primeiro attach posiciona toda org que tenha uma linha em qualquer tabela; uma org vista pela primeira vez durante o attach é posicionada no passo 4, assim como uma que uma inserção direta no Postgres gravou entre o snapshot do passo 2 e enforced, uma linha do ClickHouse que uma CLI mais antiga gravou nesse intervalo e um objeto do bucket catalogado nesse intervalo; um processo que passou de LOOM_JWT_REVOCATION_MAX_STALE_SECONDS com leituras falhas das próprias linhas ou do modo fica bloqueado e volta a servir quando uma leitura é bem-sucedida; um pod com LOOM_CELL não definido fica não pronto, nomeando a configuração, responde 503 a uma requisição com bearer, passa na sonda de saúde, responde à rota de sonda e não executa nenhum worker em uma célula anexada e em uma célula posterior entre prepare e attach, continua servindo em uma primeira célula em recording e mantém o último modo que leu durante uma leitura falha, recording incluído após o passo 3 ou o passo 4 devolver a célula a esse modo; um comando da CLI que declara uma org com ele não definido é recusado em uma célula enforced ou partial, um comando sem org (uma revogação de token) é executado, inclusive com o Postgres fora do ar em um deployment nunca preparado, e um comando de armazenamento de loom cell recusa; loom cell limit --closed tem sucesso com o Postgres da célula fora do ar; após loom cell credential --cell <cell> --next, ambas as credenciais posicionam e leem o estado, --finish recusa a credencial antiga, para uma célula finalizada antes de seus pods terem a nova o roteador recusa as chamadas dela com 401, a requisição dela responde 503 sem gravar nada, e ela se recupera registrando o hash antigo novamente, --revert descarta um next pendente, que passa a ser recusado, e a credencial antiga continua posicionando, e um segundo --next enquanto há um pendente e um hash que outra célula registra como current ou next são recusados; loom cell limit e loom cell credential --next, --finish e --revert recusam enquanto o diretório está indisponível; posicionamentos concorrentes em um abaixo de placements_max em duas réplicas do roteador gravam um; um comando da CLI que declara uma org com LOOM_CELL_ROUTER_TOKEN definido recusa, nomeando-o, em uma primeira célula assim que ela está enforced (attaching incluído) e em uma célula posterior, e em uma primeira célula em recording executa e registra a org; o attach com placements_max abaixo das orgs que a primeira célula mantém as posiciona todas, e o attach de uma célula posterior além da cota ou fechada recusa, nomeando a org; uma primeira célula com --closed e placements_max definidos antes do passo 2 faz o attach, e uma org que uma requisição registra entre o passo 2 e enforced é posicionada pelo passo 4 sem 503; após a gravação do modo da célula no passo 3, um processo cujo cache ainda lê recording envia a requisição de uma nova org à chamada de posicionamento, que uma célula fechada responde com 503; um comando da CLI cuja inserção encontra enforced recusa, nomeando a org, e não faz chamada de posicionamento; depois que a espera recusada do passo 3 ou a nova verificação do passo 4 devolve a célula a recording, uma nova org é registrada sem chamada de posicionamento, e uma em um processo cujo cache ainda lê enforced é posicionada pela barreira até o cache expirar; cada ordenação da gravação do modo pelo attach com uma inserção em registro vale como descrito acima (em execução, iniciando durante a gravação, um fluxo de inserções sobrepostas, cada uma mais curta que uma tentativa, com o attach definindo enforced em uma ou duas tentativas, mantida por várias tentativas, mantida até restar pouco de --wait, um attach travado, um commit interrompido pelo timeout, um commit cuja conexão é perdida enquanto espera o standby, relido somente depois que esse backend se foi e gravado novamente de forma durável se ler enforced); uma transação REPEATABLE READ cuja primeira instrução rodou antes de enforced ser confirmado, com o papel do attach ou um segundo papel, segura o passo 4 até terminar e a gravação dela de uma org não mantida é então posicionada, uma cuja primeira instrução rodou depois é recusada pelo trigger, uma transação que começa depois que o attach toma o lock mas antes de seu commit ficar visível segura o passo 4, uma transação aberta em recording que sobrevive ao --wait de uma execução segura o passo 4 da reexecução, após uma recusa e após loom cell restore elevar o modo, um worker de autovacuum em uma tabela do loom não segura o passo 4 e um background worker com uma transação aberta desde recording segura, uma transação preparada (após uma reinicialização com max_prepared_transactions aumentado durante a espera) faz o passo 4 recusar de imediato, nomeando-a, com o modo ainda enforced e uma reexecução recusada até ela ser resolvida e a configuração voltar a 0, uma transação de escrita aberta em um segundo banco do mesmo servidor segura o passo 4 e é nomeada, uma leitura longa no standby síncrono, ou em um segundo standby, com hot_standby_feedback ligado não o segura, nem um backup base em execução durante ele, uma escrita mantida aberta em uma conexão replication=database segura o passo 4, assim como uma transação REPEATABLE READ em uma, aberta em recording e sem gravar nada antes de enforced, um dump lógico longo (uma transação somente leitura REPEATABLE READ) no banco da célula além de --wait faz o passo 4 recusar, nomeando-o, com a célula deixada enforced, e o attach da primeira célula sem pg_read_all_stats ou com max_prepared_transactions acima de 0 recusa antes do passo 1 com o modo ainda recording, enquanto o attach de uma célula posterior não exige nenhum dos dois; um trigger de org ausente ou desabilitado é recusado pelo attach e nomeado por loom doctor, uma gravação para uma org não mantida em uma célula enforced cuja linha de modo foi apagada é recusada e o estado é nomeado por loom doctor; nessa célula um pod com LOOM_CELL não definido fica não pronto e não executa worker, e um comando da CLI que declara uma org com ele não definido é recusado, como um pod é; atualizar, apagar ou truncar a linha first em uma célula enforced é recusado, inclusive sob session_replication_role = replica, e um trigger da linha first ausente ou desabilitado é recusado pelo attach e nomeado por loom doctor; um processo em execução com LOOM_CELL definido em uma célula cuja linha de modo foi removida responde 503 a uma requisição com bearer e não executa nenhuma passagem de worker, e volta a servir depois que uma reexecução de loom cell prepare grava a linha de volta enquanto ele roda; uma célula que o diretório registra sem linha de estado, de tenancy ou própria é nomeada por loom doctor, seus processos com LOOM_CELL definido permanecem não prontos, um processo com ele não definido serve como um deployment único, e loom cell restore grava as duas linhas de volta, uma célula anexada voltando então a servir e uma não anexada após uma reexecução de prepare; uma célula com as duas linhas ausentes ao lado de uma linha de tenancy, e uma ao lado de apenas a linha própria, faz a função recusar uma org não mantida (uma inicialização não cria trigger ali), todos os processos bloqueados e loom doctor a nomeando, e uma reexecução de prepare grava as linhas de volta; uma restauração somente do Postgres de uma primeira célula anexada para antes do prepare é nomeada por loom doctor e fechada por loom cell restore; uma reexecução de prepare durante um loom cell update pendente em uma célula anexada, com processos nos dois valores e loom.cell_self perdido, grava os dois valores de volta e mantém os dois conjuntos de processos servindo, e uma antes do attach recusa as duas configurações; uma reexecução de prepare em uma célula anexada cujo current está ausente e cuja configuração dos pods difere da linha do diretório recusa, e uma antes do attach cujos heartbeats informam outro prefixo de bucket recusa; uma reexecução de prepare que recebe um hash de credencial que não é nem o current nem o next da linha é recusada; uma reexecução de prepare em uma célula posterior serving cujo prefixo contém dados grava de volta uma linha de modo removida; uma célula com linha de modo e sem linha first faz a função recusar uma org não mantida (uma inicialização não cria trigger ali), todos os processos bloqueados e loom doctor a nomeando, e uma reexecução de prepare grava a linha de volta; uma célula posterior cuja linha de modo é definida como recording não registra nada, seu trigger recusa uma org não mantida, um processo com LOOM_CELL definido ali serve como em enforced, um pod com LOOM_CELL não definido ali fica não pronto e não executa worker, loom cell prepare nomeia a linha, um comando da CLI que declara uma org com LOOM_CELL_ROUTER_TOKEN definido recusa, nomeando-o, e o roteador recusa a leitura de estado dela; um memory.set de um processo da build N-1 e a passagem de entrega em um deployment nunca preparado após a migração de N ter sucesso não gravam linha de tenancy, e na primeira célula em recording uma inicialização não cria trigger de org, e um criado à mão lê o estado e não consulta nada, uma gravação sob session_replication_role = replica para uma org não mantida é ignorada (triggers de origem), um INSERT ... ON CONFLICT DO UPDATE que insere uma linha para uma org não mantida é recusado e um que atinge uma linha existente dela não é, toda gravação de uma sessão marcada passa, e os triggers em uma célula enforced cobrem toda tabela que a erasure classifica com uma coluna org, exceto as três exclusões; e uma gravação indexada por org enquanto o attach segura o lock da tabela de modo retorna de imediato, com requisições de novas orgs respondendo dentro do prazo e leituras do cache de modo retornando de imediato o tempo todo; loom cell restore após uma recusa no lock do passo 3 deixa a célula enforced, e o attach retomado roda a partir da espera do passo 3; um LOOM_CELL_ROUTER_TOKEN que não tem a forma lcr_ é recusado na inicialização e nomeado por loom doctor; loom cell credential new imprime uma credencial dessa forma e seu SHA-256, com o diretório e os armazenamentos inacessíveis; prepare e --next recusam um argumento que não seja 64 caracteres hexadecimais minúsculos, a credencial e seu segredo puro de 128 caracteres incluídos, sem armazenar nada; orgs que uma primeira célula registra em recording sem dados são listadas por loom doctor; uma enxurrada de posicionamentos sem cota definida é contida pelo limite de taxa em cada réplica do roteador, loom doctor nomeia a célula como uma sem cota, e uma chamada recusada além dele em uma réplica responde 503 com um Retry-After de no máximo 60 s, após o qual sua nova tentativa nessa réplica, sem nenhuma outra chamada da célula admitida entre elas, é admitida; o primeiro prepare de uma célula, sem linha no diretório ainda, passa na verificação do deployment-id; um pod ou CLI que perdeu LOOM_PG_DSN ou LOOM_STORAGE_AUTHORITY em uma célula é recusado pela verificação de autoridade; os tokens, refresh tokens e clientes OAuth existentes da primeira célula continuam funcionando durante a transição, e um logout pelo host compartilhado revoga o refresh token dela;
  • o attach recusa um emissor compartilhado, segredo raiz, caminho do Keeper, prefixo de bucket aninhado ou org configurada, uma segunda célula que contém dados e um segundo attach enquanto um está em execução;
  • um login OIDC, a autorização de um cliente MCP e um device flow para uma org na segunda célula são concluídos no host dessa célula após uma consulta; loom login --org mantém o host dele em NO_CELL e em um deployment sem roteador, tenta de novo após o Retry-After de um 429 até --wait se esgotar e então recusa como recusa por taxa e, enquanto o diretório está fora do ar, inicia o fluxo no host da célula de uma org que o roteador tem em cache e recusa, sem iniciar nenhum fluxo, para uma que ele não tem;
  • com SCIM ligado, uma pessoa que o provedor de identidade nunca atribuiu a uma célula não pode fazer login, atualizar a sessão, ser representada nem usar um token do gateway ali, uma desativação enviada ao aplicativo de uma célula encerra a pessoa ali, um bot de administração da plataforma ainda alcança uma célula cujo SCIM desativou todos, e o attach recusa uma célula com subjects ativos não provisionados ou que compartilha o cliente OIDC de outra;
  • um attach interrompido no passo 3 depois de definir enforced, antes de a espera terminar, é retomado com a espera antes da precondição de SCIM, e um recusado pela precondição de SCIM também é retomado a partir da espera, com o modo ainda enforced; um attach posterior recusado antes de sua transação no diretório deixa attach_started_at vazio, de modo que uma reexecução verifica novamente as recusas de uma nova célula, e um primeiro attach retomado encontra suas orgs configuradas posicionadas nesta célula e prossegue;
  • uma célula restaurada para antes do enforced do primeiro attach recebe seu modo de volta de loom cell restore; uma cuja execução de loom cell restore foi pulada responde 503 para uma org que ela não mantém, a org de outra célula incluída, não grava linha de tenancy para ela e é nomeada por loom doctor; uma indisponibilidade do diretório durante a implantação de LOOM_CELL e entre prepare e attach deixa a primeira célula servindo as orgs que mantém, uma nova org respondendo 503 em todo processo com LOOM_CELL definido; a leitura de estado é aceita de uma primeira célula que está attaching antes do passo 2 do attach, e somente com a credencial própria da célula nomeada, e uma resposta recusada ou tardia conta como ilegível;
  • uma concessão renovada em N que foi gravada em N-1 é verificada contra a linha da pessoa, uma renovação enquanto o SCIM está ilegível responde 503 e mantém a sessão, e um processo com LOOM_CELL definido antes de loom cell prepare permanece não pronto;
  • um token delegado durante o primeiro attach por uma pessoa nunca provisionada é recusado após enforced; um gateway agindo por um bot é atendido e por um handle simples é recusado;
  • com o diretório indisponível, toda célula serve as orgs que mantém, os posicionamentos respondem 503, e loom doctor em uma célula informa suas verificações do diretório como não executadas e termina com código diferente de zero;
  • LOOM_CELL é implantado após loom cell prepare com todos os pods prontos, antes do attach;
  • preparar uma célula vazia antes do deployment do host compartilhado é recusado, e uma célula restaurada do snapshot de outra célula é recusada no prepare;
  • um prepare interrompido entre a gravação no diretório e a gravação na célula, com LOOM_CELL já implantado, é reexecutado por probe_url contra processos bloqueados; uma reexecução de prepare antes do attach cujos heartbeats não correspondem nem ao current nem ao next atuais recusa; uma reexecução de prepare anexada em que só o next foi perdido o grava de volta, e uma cujo current atual difere do diretório o sobrescreve; uma reexecução de prepare isolada após uma restauração somente do Postgres de uma primeira célula anexada para antes do prepare deixa loom doctor nomeando as linhas de tenancy ausentes, e um pod com LOOM_CELL não definido serve toda org ali até a reexecução e fica bloqueado depois dela, enquanto com LOOM_CELL definido uma org recebe sua linha de tenancy de volta pela chamada de posicionamento; uma reexecução de prepare contra pods com LOOM_CELL não definido em estado partial alcança a rota de sonda deles e grava a linha ausente de volta; prepare recusa o probe_url de uma célula posterior que informa um id diferente do de seus armazenamentos, attach recusa uma célula cujo host informa um id diferente do de seu probe_url, e prepare recusa um argumento de endereço de sonda para a primeira célula, e o roteador sonda apenas LOOM_ROUTER_UPSTREAM_PROBE_URL; o primeiro prepare de uma célula posterior tem sucesso; loom cell update --probe-url recusa um endereço que informa outro deployment id ou falha no eco do nonce, e recusa a primeira célula; loom cell update move os endereços de sonda e de upstream da primeira célula somente quando toda réplica do roteador os executa, após a sonda deles e a verificação de id do upstream, e uma reexecução de prepare por uma réplica ainda nos valores antigos (ou nos novos, antes da mudança) é recusada, nomeando o endereço da linha; um probe_url com userinfo ou outro esquema é recusado; a porta principal responde apenas o id em memória, com qualquer Host, sem ler nenhum armazenamento; o roteador sonda um probe_url https cujo certificado é assinado por uma CA em seu SSL_CERT_FILE; o listener de sonda responde 429 além de sua taxa; e um prepare que recebe uma cópia dos armazenamentos da primeira célula é recusado pelo nonce;
  • a primeira célula padrão (LOOM_JWT_ISSUER=loom, um LOOM_OAUTH_ISSUER vazio) faz o attach; uma célula reimplantada com o host compartilhado como URL pública fica não pronta;
  • um posicionamento inserido na cota de uma célula cuja chamada expirou por timeout é repetido e responde seu vencedor, e a célula grava a linha de tenancy; o mesmo em uma célula fechada nesse meio-tempo, e para uma reexecução de loom cell place;
  • um attach que morre entre sua gravação no diretório e sua gravação em loom.cell_self é retomado até serving, e seus emissores permanecem reservados nesse meio-tempo; um loom cell place para uma org que outra célula mantém não grava linha, e um para uma org que o diretório não posiciona é recusado, sem gravar linha, para uma célula fechada, além de placements_max, para uma célula posterior ainda attaching, para uma primeira célula antes de o diretório registrar enforced, com uma configuração cuja impressão digital não corresponde a nenhum dos valores da linha da célula, e enquanto o diretório está indisponível, e não é recusado quando a taxa da célula se esgota nem conta para ela (as chamadas de posicionamento da própria célula continuam admitidas após uma sequência de places do operador); um para uma org que o diretório posiciona nesta célula grava sua linha de tenancy em uma célula fechada ou cheia; loom bot create para uma nova org em uma primeira célula em recording registra a org enquanto o diretório responde attaching e é recusado enquanto ele responde serving ou não pode ser lido;
  • um host de emissor OAuth que difere do host público da célula é recusado no prepare, e o host compartilhado roteia antes de qualquer célula ser anexada; um loom cell place sem outras gravações mantém a org em sua célula;
  • uma primeira célula restaurada para entre os passos 1 e 3 do attach depois de estar serving fica pronta em enforced assim que loom cell restore é executado;
  • uma célula restaurada para antes de um loom cell update --finish volta a servir assim que loom cell restore reescreve sua linha própria, uma célula cujos dois armazenamentos são restaurados recebe suas linhas de volta apenas de loom cell restore, e uma célula preparada e não anexada mantém sua linha própria restaurada;
  • uma primeira célula restaurada para antes do prepare recebe suas linhas de volta, responde 503 no host compartilhado em processos com LOOM_CELL definido até loom cell prepare ser reexecutado, e então serve; o SCIM em um deployment com LOOM_CELL não definido funciona como antes em N, durante prepare, a implantação de LOOM_CELL e o attach;
  • o SCIM da primeira célula continua respondendo seu token sem nome durante a transição, uma célula posterior recusa um token sem nome, nenhuma célula aceita o token de outra célula, lsc_b_… e um token lsc_ malformado são recusados na primeira célula, e uma célula posterior com uma linha de SCIM gravada antes de LOOM_CELL é recusada no attach; um token da célula a-b é recusado na célula a, e um nome de célula com _ é recusado;
  • uma célula posterior com oidc_jit_org definido inicializa e reinicia seus pods entre prepare e attach, com o JIT para essa org respondendo 503 até o attach posicioná-la; o autocadastro da primeira célula em uma org que nenhuma requisição registrou, entre prepare e attach, a registra e conclui o cadastro; uma célula posterior com repositórios indexados não grava linha de código antes do attach e então faz o attach; uma primeira célula em recording mantém suas passagens de worker para uma org que nenhuma requisição tocou desde a implantação; o attach de uma célula posterior interrompido após attach_started_at é retomado com suas orgs configuradas posicionadas e mantidas; uma atualização entre prepare e attach que muda a org de código tem essa org posicionada pelo attach, e após --finish ela indexa; uma atualização após o attach recusa uma org configurada alterada que outra célula mantém, nomeando-a, e, para uma org que o diretório ainda não posiciona, é recusada para uma célula fechada e além de placements_max; uma atualização que muda uma org configurada de uma célula posterior ainda attaching após sua transação no diretório é recusada até a célula estar serving; --revert mantém uma org configurada que a atualização posicionou; as orgs de código e de tracker de uma célula posterior servem e indexam quando ela está serving, uma op code.* de um membro de outra org incluída, e o mesmo vale para uma org configurada que loom cell update altera; um attach posterior em corrida com a atualização de outra célula que amplia um emissor recusa um dos dois; uma org configurada que outra célula posiciona entre as recusas do attach e seu posicionamento faz o attach recusar, nomeando-a, e não grava nada; prepare recusa uma credencial de roteador que outra célula registra; uma chamada de posicionamento que nomeia outra célula com uma credencial válida desta não posiciona nada na outra;
  • a chamada de posicionamento de uma célula preparada e não anexada para uma org que o diretório não posiciona responde 503, uma para uma org que ele posiciona responde o vencedor mesmo com a credencial antiga ainda em cache após loom cell credential --finish ou uma impressão digital que não corresponde a nenhum dos valores, um vencedor com o nome desta célula sob outro deployment id responde 503 e não grava linha de tenancy, e um processo cuja configuração difere da linha de sua célula não posiciona nada;
  • uma célula anexada com o SCIM desligado e ligado por loom cell update recusa enquanto um token de agent-signup está ativo, inclusive um emitido enquanto a atualização é implantada, e um processo configurado com o emissor de outra célula responde 503 a toda requisição com bearer, alcançado pelo roteador ou diretamente;
  • durante um loom cell update, os processos na configuração antiga e na nova servem, --finish libera um emissor reduzido somente depois que nenhum processo o aceita, uma atualização que morre após sua gravação no diretório mantém o emissor ampliado reservado, e as builds N e N+1 com uma configuração correspondem à mesma linha;
  • rotacionar um token SCIM não altera nenhuma impressão digital; um processo se recusa a inicializar com o token SCIM de outra célula, um provedor de identidade apontado para o host da célula errada recebe 401 e não grava nada, e uma célula revertida para N ainda se bloqueia pela própria linha e recusa o token SCIM de outra célula; uma enxurrada de posicionamentos do emissor de uma célula é recusada além de sua cota;
  • um gateway agindo pela conta de serviço pessoal de uma pessoa nunca provisionada é recusado, e uma célula que passa a aceitar o emissor de outra célula não recebe posicionamentos;
  • um processo que não corresponde a nenhum dos valores de sua linha responde 503 ao login, à renovação, aos endpoints de token e device do OAuth, ao callback de login e ao cadastro, e sua rota de sonda ainda ecoa o nonce do prepare; --revert espera os processos que correspondem apenas a next; update --config recusa enquanto um next diferente está pendente, e uma atualização que morreu antes de sua gravação em loom.cell_self é retomada para a frente; prepare recusa enquanto um processo pré-N está ativo; uma mudança de configuração durante attaching passa por loom cell update e o attach retomado reserva os dois valores; um processo cujos armazenamentos configurados diferem da linha de sua célula responde 503 e se afasta dos workers, de modo que uma build mais nova bloqueada ao lado de uma mais antiga não bloqueada deixa os workers em execução e apagando; loom cell update recusa uma mudança no deployment id, no nome do bucket ou no prefixo, adicionar um bucket incluído; um processo bloqueado em modo on não executa nenhuma passagem de worker; preparar um clone com o nome de bucket e o prefixo da primeira célula é recusado, no endpoint dele ou em qualquer outro; uma célula posterior cujo prefixo contém objetos de outro deployment é recusada no prepare; dois prepares concorrentes de prefixos aninhados não passam ambos; duas células sem bucket fazem prepare ambas; prepare recusa uma célula posterior cujo processo carrega o LOOM_CELL de outra célula, e um processo cuja linha first nomeia outra célula responde 503 e não executa worker; uma enxurrada na rota de id da porta principal não trava o attach; e uma célula restaurada em um novo endpoint de Postgres, ClickHouse ou bucket serve assim que sua configuração o nomeia; uma requisição com bearer no host compartilhado é atendida antes do prepare, entre prepare e attach e durante o attach;
  • o chart não renderiza listener de sonda por padrão, e com ele ligado renderiza o Service de sonda e não altera nenhuma NetworkPolicy, de modo que, com a política do chart ligada, nenhuma regra própria admite a porta de sonda; prepare nomeia PROBE_UNREACHABLE e PROBE_BUSY do roteador quando --wait se esgota; uma enxurrada na porta principal não afeta a taxa do listener de sonda;
  • uma célula posterior iniciada a partir do ambiente da primeira célula, com seu bucket e prefixo, roda bloqueada desde a primeira inicialização e não apaga nenhum original; prepare recusa uma célula posterior enquanto um processo ativo não tem LOOM_CELL;
  • loom cell limit --closed faz as chamadas de posicionamento da célula responderem 503 enquanto ela continua servindo as orgs que mantém, --open as restaura, e --placements-max entra em vigor na próxima chamada de posicionamento;
  • uma restauração do Postgres de uma célula enforced para antes do posicionamento de uma org, com essa org apagada depois do ponto, reconcilia com código de saída 0 após loom cell restore e então serve a org;
  • uma célula restaurada de antes do posicionamento de uma org a serve quando fica pronta, uma erasure deixa o posicionamento da org, e, com o diretório perdido, toda célula serve as orgs que mantém.