Células
Células
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.
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 doctorcompara 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óprioLOOM_JWT_ISSUER, seuLOOM_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 (currente, durante uma rotação,next), a impressão digital de seu segredo raiz (keys_fp), seuprobe_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 (currente, durante uma mudança,next; os campos citados em “Verificação contínua”), que o attach eloom cell updategravam 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:
- 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 decellsnomeie 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. - 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/Groupscom um JWT, que vai pelo emissor como na regra 3. As rotas Groups têm verificação de tenancy (elas gravamloom.principal_groupsda org). - 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 estarserving, 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 deLOOM_CELLe o attach; do rollout atéserving, uma nova org também precisa do diretório em todo processo comLOOM_CELLdefinido (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. - 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 logoutrevoga 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/begintraz as impressões digitais da cell exatamente comoloom.cell_selfas 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 noprobe_urlda linha e pergunta aoupstream_urlda 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, gravaattach_started_atuma vez, as impressões digitais somente enquanto a linha não tem nenhuma (outras impressões digitais ali respondem 409: elas mudam comloom cell update) ekeys_fpem toda chamada, e audita as listas de permissão. É idempotente. Seu corpo tem limite próprio, 256 KiB, acima do qual responde 413.attach/placecoloca um lote de no máximo 500 orgs (dentro do limite de corpo de 64 KiB) depois quebeginfoi 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/enforcedregistra o modo do diretórioenforced, depois do qual a primeira cell coloca novas orgs em tempo real; é idempotente.attach/servingexecuta 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_issuersdecurrentenext) e marca a cell comoserving; em uma cellserving, responde na hora, com auditoria.begin,placeeenforcedem uma cellservingrespondem 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/v2responde 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
firstfor(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,0para desligado; exige a autoridade do Postgres e a autenticação ligadas, e escuta em todos os endereços do host): a linha do Postgresloom.cell_probee a chave do KeeperMap, ambas chamadascell-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 portahttp, 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 denetworkPolicy.extraEgressquando a policy do chart está ligada. - O prepare tenta de novo os
PROBE_BUSYePROBE_UNREACHABLEdo roteador (um listener em inicialização fica inalcançável por um tempo), e o attach e oloom cell update --probe-urltentam 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ósRESET ALLna mesma transação: um valor de startup sobrevive ao reset, umSETnã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 comSET, 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 ALLeCOMMIT), e todo processo reporta um valor novo sem prober. Uma sessão que o pooler removeu, ou um processo comLOOM_CELLnão definido sob a autoridade Postgres, lêfalse;nullsignifica 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 readinesscell_markerde um processo comLOOM_CELLdefinido lê o mesmo valor: ela falha emenforcedepartial, 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 emrecording, 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).routererouter_why: comLOOM_CELLdefinido,routerénullerouter_whydiz por quê até que a linhafirstseja 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).routerindica se a última leitura deste processo deGET /cells/v1/cells/<cell>com sua própria credencial respondeu 200 nomeando a célula:nullaté que a primeira leitura responda (ainda em boot),truecom tal resposta, efalsepara 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 umLOOM_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 erouter_whydiz “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 enquantorouterénull,router_whynomeia 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:
- 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 seuLOOM_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 seuLOOM_CELLem toda execução, o que o prepare verifica por conta própria. - 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), comoloom cell credential newa gera offline, imprimindo a credencial e seu hash; o boot eloom doctorrecusam umLOOM_CELL_ROUTER_TOKENde 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, citandoloom 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. - Ele grava as linhas da célula: o modo (
recordingna primeira célula,enforcedem uma célula posterior), a linhafirstecurrent.
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 decheck_acted_fore do provisionamento do namespace pessoal, tanto para HTTP quanto para MCP (via MCP, uma chamada para a org de outra célula respondeisError, de modo que um lote mantém suas outras respostas, e uma chamada na própria org do token, comogates.resolve_orga resolve, é verificada antes de os padrões do chamador serem lidos, já que eles vivem nessa org). As rotas fora do registro verificam porcheck_authorized,admit_orgou 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 marcatoken; 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 porcheck_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_checkedouconnect_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 deLOOM_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 linhafirstnomeie 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. ComLOOM_CELLnão definido, o comando é recusado em uma célula além derecording(acima). Uma org que a célula não possui é registrada na primeira célula emrecording, 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 respondeattaching), e recusada emenforced; nunca é posicionada. Um comando do índice de código declara a org que grava: seu--org, senãoLOOM_CODE_ORG. Uma passagem por todo repositório configurado não declara nenhuma, já que o attach, ou oloom cell updateque 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:listlê,retirerevoga,rotateerecord-rootgravam). ComLOOM_CELLdefinido, uma gravação ou revogação verifica seu ClickHouse contra seu Postgres (check_configured), lê a linhafirstem 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 migrateeloom provider-lock cleargravam 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 sobserver/cli/fora de_ch.py, e em um comandoloom codeque 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 deplacements_max, como a credencial de operador queloom cell placeusa pode para qualquer célula dentro de seuplacements_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 leiarecording, e um comando sem org nunca a usa; uma credencial vazada é contida porloom cell limit --closed, que não precisa de nenhum dos stores da célula, e substituída porloom 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 deplacements_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 comLOOM_CELLdefinido a envia como parâmetro de inicialização (de modo que oRESET ALLdo 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 colunaorg(não a próprialoom.tenancy, nemloom.idempotencyeloom.idempotency_fences, indexadas pela org do token do chamador) um trigger de linhaAFTER INSERTeAFTER UPDATE, habilitado como triggers de origem, ignora uma sessão marcada em seuWHEN(o de update também ignora um update que deixa a org da linha intacta, de modo que umON CONFLICT DO UPDATEque 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, SQLSTATELT001(503TENANCY_REFUSEDpara 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 lidorecording. 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 emenforcede, 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 emrecordingaté o attach definirenforcedenquanto 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 definirenforced, e a célula passa aservingsomente quandocell_triggers.missingnão nomeia nenhum defeito. Uma célula posterior éenforceddesde 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 doctornomeia um desabilitado ou alterado em qualquer estado, um ausente em uma célulaenforced, e uma tabela particionada com colunaorgcomo 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 sobsession_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 aloom.tenancypor linha não marcada; o gate sob o qual eles são lançados é um aumento de p99 dememory.setde no máximo 10 ms e uma taxa de linhas por segundo de uma passagem de entrega emLOOM_PG_DELIVERY_BATCH_ROWSno máximo 10% menor, emenforcedcom 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 dememory.sete 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.tenancytem sua própria proteção, já que uma linha de tenancy torna uma org possuída:tenancy_record, um trigger de origem de linhaAFTER INSERT OR UPDATE OF orgcom o mesmoWHENdo marcador, chamaloom.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 (opentambém, já que a própria linha tornaria o estadopartial), 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 doctortambé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 comINSERTemloom.*(system.grants, com grants de banco de dados, globais e de papel seguidos porsystem.role_grants, e usuários de arquivos de configuração ou comALLimplí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 attachloom doctorlista 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/placementsemLOOM_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 409WRONG_CELLe 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 orgprefix*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 deserving, 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élulaserving(ou da primeira célula enquantoattachingdepois que o diretório registraenforced, 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 deLOOM_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 porLOOM_ROUTER_DIRECTORY_CACHE_S, padrão 5 s) e à taxa da célula, e umloom cell placeapenas 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 comRetry-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 comRetry-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 (umloom cell placede operador é isento da taxa, como acima); e os posicionamentos de cada célula são informados em/v1/health?include=capacitye porloom 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 deORG_MAX_BYTESo 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 emloom cell update, passa pelo gate, célula fechada eplacements_maxincluí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. Emrecording, que dura até o passo 3 gravarenforcedno 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_maxeloom cell limit --closednã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 doctorlista 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_orgda célula, oself_signup_orgde uma célula com cadastro ligado, e suas orgs de código (LOOM_CODE_ORGe a org de cada entrada deLOOM_CODE_REPOS_JSONque 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 marcadaserving. JIT e cadastro próprio passam pela verificação de tenancy como qualquer requisição, e nada recusa no boot: narecordingda primeira célula eles registram sua org enquanto o diretório respondeattaching, e nos demais casos uma org configurada que a célula não possui responde 503 até ser posicionada (422 para uma além deORG_MAX_BYTES, que o diretório recusa), o queloom doctornomeia; todo attach, primeiro ou posterior, novo ou retomado, executa as recusas de sobreposição e posiciona as orgs configuradas dos dois valores deloom.cell_self, de modo que uma que um update colocou emnextantes do attach é posicionada com as demais; depois que o attach grava a linha de diretório da célula,loom cell updateposiciona uma alterada na transação do diretório que gravanext, pelo gate da API de posicionamento para uma org que o diretório ainda não posiciona (células fechadas eplacements_maxincluí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 aindaattachingdepois de sua transação de diretório,loom cell updaterecusa uma alteração de org configurada até a célula estarserving. Emenforced, 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; emrecording, 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_urlinforma, todo processo ativo temLOOM_CELLdefinido 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
currentou onextde seuloom.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 updateos 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 ordemLOOM_CELL, um token nomeado e depois a atribuição da aplicação); - seu
LOOM_PUBLIC_BASE_URLestá definido (um processo comLOOM_CELLdefinido 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 deLOOM_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 tabelahostsdo 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 porhosts, 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
orgsde 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_locknã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_CELLcom 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:
- 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; - 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 deloom.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), oorgdistinto 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'*'; - definir
enforcedcomo 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 definirrecordingde volta), até que todo processo ativo informeenforcede 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-unprovisionedde novo, se informado), para contas feitas antes deenforcedentrar em vigor; se ela recusar, a célula permaneceenforcedeattaching, e executar o attach novamente retoma a partir da espera, como faz um attach retomado (abaixo); - esperar, dentro do que resta de
--wait, até que nenhuma transação que possa ter lidorecordingainda esteja aberta, julgado a partir de um snapshot do Postgres que o attach toma depois de ter lidoenforcedde 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élulaenforced, 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 (oorgdistinto 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 emrecordingdepois do snapshot também é colocado), verificar de novo que todo processo ativo informaenforced(recusando e voltando arecordingcomo o passo 3 faz, se algum não informar) e marcar a célula comoserving. O diretório registra o modo mais alto que o attach elevou ou tentou elevar, queloom cell restoresó escreve de volta para cima: uma célula cujo passo 3 foi recusado no lock é restaurada comoenforced, 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
firste a linha de mode, o que estiver ausente, a partir do directory, como faz um prepare retomado; uma linhafirstpresente 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 (
recordingparaenforced), nunca para baixo; - depois que a linha do directory contém o fingerprint da cell (o attach o grava), o
loom.cell_selfdela a partir dele (currentenext); antes do attach o directory não contém nenhum, e oloom.cell_selfrestaurado permanece como o backup o contém (umcurrentausente é gravado por uma nova execução deloom cell prepareassim que a cell inicia, umnextperdido por outroloom 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 deloom 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> --closedfecha uma célula para novas orgs,--opena reabre e--placements-max <n>define sua cota de placements (--placements-max noneremove a cota).loom cell remove --cell <cell>remove a linha do diretório de uma célula que estáattachingsem nenhum placement (--cellé oLOOM_CELLda 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 deLOOM_PG_DSN, sem ClickHouse, e recusa a operação a menos que leiaopene registre o deployment id da linha, o que impõe a ordem de reversão: removerLOOM_CELLde todos os processos (cada um passa a servir como emrecording), 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êmLOOM_CELLdefinido. 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 semLOOM_ROUTER_OPERATOR_SHA256responde 503 à API de operador comNO_OPERATOR_CREDENTIAL), queloom cell credential new --operatorgera; 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, excetoBACKEND_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 emLOOM_ROUTER_OPERATOR_SHA256e 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 emLOOM_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 routerhttpna rede interna atende a uma célula, mas não esses comandos. loom cell credential newgera 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 hashnextda 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 umnextpendente. O router aceita ambos nas chamadas de placement e nas leituras de estado, cada réplica dentro deLOOM_ROUTER_DIRECTORY_CACHE_Sde--next, de modo que a nova credencial só vai para os pods depois disso;loom router migrateroda antes de um router que lê o hashnext, 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 semnextpendente (--revertantes) e não entre--finishe 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 forrecording, na configuração da CLI,loom cell credential --cell <cell> --finishtornanexto 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--nexte finalizado.loom cell credential --cell <cell> --revertdescarta umnextpendente, de modo que um valor errado ou vazado nunca precise ser finalizado;--finishe--revertsão recusados semnextpendente.- 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, eLOOM_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_CELLdefinido 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 comLOOM_CELLnão definido em uma célula cujas linhas de estado contam comoenforcedou estão em um estadopartial(a regra da linhafirst) 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_CELLnão definido mantém seu veredito diante de leituras com falha das linhas de estado, sem limite de obsolescência: aberto emopenerecording, 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 porloom doctorenquanto isso: uma linha, um modo ou um valor defirstnão lido causa recusa; com o diretório inacessível, placements, consultas fora do cache, os comandosloom cellque 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 guardloom.tenancyem uma tabela, ou restaurar os triggers deloom.cell_firstpara 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 (umloom revoke-tokensimples, 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) comLOOM_CELLdefinido, cuja leitura da linhafirstda 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 querefreshlê, incluindo seloom.tenancytem alguma linha entre elas), sua impressão digital egate_reason, o gate nos processos comLOOM_CELLdefinido 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, emserver/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 deloom.tenancy) emissing(o queloom doctoraponta), com suas funções emschemas/pg_migrations/011_tenancy_triggers.sqle012_tenancy_guard.sql;server/cli/doctor_cell.py: as verificações de célula doloom 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 colunaorg, 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 deLOG_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.sqleschemas/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), porcheck_authorized, poradmit_orge pelas rotas que nomeiam uma org;server/transport/tenancy_gate.pyverifica a org do próprio token nas rotas fora do registro que agem nela, etests/unit/test_cell_tenancy.pyconté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 (queserver/core/cell_router.pyfaz 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 (queloom 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, queloom cell limit,loom cell credentialeloom cell remove(server/cli/cell.py, comloom cell which) chamam com a credencial de operador do router (LOOM_ROUTER_OPERATOR_TOKEN; o router guarda apenasLOOM_ROUTER_OPERATOR_SHA256);server/router/directory.pyeschemas/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) eserver/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_CELLe 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, quetests/unit/test_cell_cli_orgs.pyexige de toda conexão;server/auth/authz.py(check_acted_for,_check_creator) eserver/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 orgprefix*de um emissor de usuário final e a org de um bot são posicionadas da mesma forma apósenforced, 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 deLOOM_JWT_REVOCATION_MAX_STALE_SECONDScom leituras falhas das próprias linhas ou do modo fica bloqueado e volta a servir quando uma leitura é bem-sucedida; um pod comLOOM_CELLnã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 emrecordinge mantém o último modo que leu durante uma leitura falha,recordingincluí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élulaenforcedoupartial, 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 deloom cellrecusa;loom cell limit --closedtem sucesso com o Postgres da célula fora do ar; apósloom cell credential --cell <cell> --next, ambas as credenciais posicionam e leem o estado,--finishrecusa 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,--revertdescarta umnextpendente, que passa a ser recusado, e a credencial antiga continua posicionando, e um segundo--nextenquanto há um pendente e um hash que outra célula registra como current ou next são recusados;loom cell limiteloom cell credential --next,--finishe--revertrecusam enquanto o diretório está indisponível; posicionamentos concorrentes em um abaixo deplacements_maxem duas réplicas do roteador gravam um; um comando da CLI que declara uma org comLOOM_CELL_ROUTER_TOKENdefinido recusa, nomeando-o, em uma primeira célula assim que ela estáenforced(attachingincluído) e em uma célula posterior, e em uma primeira célula emrecordingexecuta e registra a org; o attach complacements_maxabaixo 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--closedeplacements_maxdefinidos antes do passo 2 faz o attach, e uma org que uma requisição registra entre o passo 2 eenforcedé 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êrecordingenvia 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 encontraenforcedrecusa, 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 arecording, 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 definindoenforcedem 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 lerenforced); uma transaçãoREPEATABLE READcuja primeira instrução rodou antes deenforcedser 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 emrecordingque sobrevive ao--waitde uma execução segura o passo 4 da reexecução, após uma recusa e apósloom cell restoreelevar 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 desderecordingsegura, uma transação preparada (após uma reinicialização commax_prepared_transactionsaumentado durante a espera) faz o passo 4 recusar de imediato, nomeando-a, com o modo aindaenforcede 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, comhot_standby_feedbackligado não o segura, nem um backup base em execução durante ele, uma escrita mantida aberta em uma conexãoreplication=databasesegura o passo 4, assim como uma transaçãoREPEATABLE READem uma, aberta emrecordinge sem gravar nada antes deenforced, um dump lógico longo (uma transação somente leituraREPEATABLE READ) no banco da célula além de--waitfaz o passo 4 recusar, nomeando-o, com a célula deixadaenforced, e o attach da primeira célula sempg_read_all_statsou commax_prepared_transactionsacima de 0 recusa antes do passo 1 com o modo aindarecording, 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 porloom doctor, uma gravação para uma org não mantida em uma célulaenforcedcuja linha de modo foi apagada é recusada e o estado é nomeado porloom doctor; nessa célula um pod comLOOM_CELLnã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 linhafirstem uma célulaenforcedé recusado, inclusive sobsession_replication_role = replica, e um trigger da linhafirstausente ou desabilitado é recusado pelo attach e nomeado porloom doctor; um processo em execução comLOOM_CELLdefinido 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 deloom cell preparegrava 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 porloom doctor, seus processos comLOOM_CELLdefinido permanecem não prontos, um processo com ele não definido serve como um deployment único, eloom cell restoregrava 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 eloom doctora 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 porloom doctore fechada porloom cell restore; uma reexecução de prepare durante umloom cell updatependente em uma célula anexada, com processos nos dois valores eloom.cell_selfperdido, 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 cujocurrentestá 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 ocurrentnem onextda linha é recusada; uma reexecução de prepare em uma célula posteriorservingcujo prefixo contém dados grava de volta uma linha de modo removida; uma célula com linha de modo e sem linhafirstfaz a função recusar uma org não mantida (uma inicialização não cria trigger ali), todos os processos bloqueados eloom doctora nomeando, e uma reexecução de prepare grava a linha de volta; uma célula posterior cuja linha de modo é definida comorecordingnão registra nada, seu trigger recusa uma org não mantida, um processo comLOOM_CELLdefinido ali serve como emenforced, um pod comLOOM_CELLnão definido ali fica não pronto e não executa worker,loom cell preparenomeia a linha, um comando da CLI que declara uma org comLOOM_CELL_ROUTER_TOKENdefinido recusa, nomeando-o, e o roteador recusa a leitura de estado dela; ummemory.setde 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 emrecordinguma inicialização não cria trigger de org, e um criado à mão lê o estado e não consulta nada, uma gravação sobsession_replication_role = replicapara uma org não mantida é ignorada (triggers de origem), umINSERT ... ON CONFLICT DO UPDATEque 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élulaenforcedcobrem toda tabela que a erasure classifica com uma colunaorg, 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 restoreapós uma recusa no lock do passo 3 deixa a célulaenforced, e o attach retomado roda a partir da espera do passo 3; umLOOM_CELL_ROUTER_TOKENque não tem a formalcr_é recusado na inicialização e nomeado porloom doctor;loom cell credential newimprime uma credencial dessa forma e seu SHA-256, com o diretório e os armazenamentos inacessíveis; prepare e--nextrecusam 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 emrecordingsem dados são listadas porloom doctor; uma enxurrada de posicionamentos sem cota definida é contida pelo limite de taxa em cada réplica do roteador,loom doctornomeia a célula como uma sem cota, e uma chamada recusada além dele em uma réplica responde 503 com umRetry-Afterde 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 perdeuLOOM_PG_DSNouLOOM_STORAGE_AUTHORITYem 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 --orgmantém o host dele emNO_CELLe em um deployment sem roteador, tenta de novo após oRetry-Afterde um 429 até--waitse 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 aindaenforced; um attach posterior recusado antes de sua transação no diretório deixaattach_started_atvazio, 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
enforceddo primeiro attach recebe seu modo de volta deloom cell restore; uma cuja execução deloom cell restorefoi 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 porloom doctor; uma indisponibilidade do diretório durante a implantação deLOOM_CELLe entre prepare e attach deixa a primeira célula servindo as orgs que mantém, uma nova org respondendo 503 em todo processo comLOOM_CELLdefinido; a leitura de estado é aceita de uma primeira célula que estáattachingantes 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_CELLdefinido antes deloom cell preparepermanece 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 doctorem 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ósloom cell preparecom 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_CELLjá implantado, é reexecutado porprobe_urlcontra processos bloqueados; uma reexecução de prepare antes do attach cujos heartbeats não correspondem nem aocurrentnem aonextatuais recusa; uma reexecução de prepare anexada em que só onextfoi perdido o grava de volta, e uma cujocurrentatual 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 deixaloom doctornomeando as linhas de tenancy ausentes, e um pod comLOOM_CELLnão definido serve toda org ali até a reexecução e fica bloqueado depois dela, enquanto comLOOM_CELLdefinido uma org recebe sua linha de tenancy de volta pela chamada de posicionamento; uma reexecução de prepare contra pods comLOOM_CELLnão definido em estadopartialalcança a rota de sonda deles e grava a linha ausente de volta; prepare recusa oprobe_urlde 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 seuprobe_url, e prepare recusa um argumento de endereço de sonda para a primeira célula, e o roteador sonda apenasLOOM_ROUTER_UPSTREAM_PROBE_URL; o primeiro prepare de uma célula posterior tem sucesso;loom cell update --probe-urlrecusa um endereço que informa outro deployment id ou falha no eco do nonce, e recusa a primeira célula;loom cell updatemove 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; umprobe_urlcom 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 umprobe_urlhttps cujo certificado é assinado por uma CA em seuSSL_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, umLOOM_OAUTH_ISSUERvazio) 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; umloom cell placepara 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 deplacements_max, para uma célula posterior aindaattaching, para uma primeira célula antes de o diretório registrarenforced, 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 createpara uma nova org em uma primeira célula emrecordingregistra a org enquanto o diretório respondeattachinge é recusado enquanto ele respondeservingou 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 placesem 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
servingfica pronta emenforcedassim queloom cell restoreé executado; - uma célula restaurada para antes de um
loom cell update --finishvolta a servir assim queloom cell restorereescreve sua linha própria, uma célula cujos dois armazenamentos são restaurados recebe suas linhas de volta apenas deloom 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_CELLdefinido atéloom cell prepareser reexecutado, e então serve; o SCIM em um deployment comLOOM_CELLnão definido funciona como antes em N, durante prepare, a implantação deLOOM_CELLe 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 tokenlsc_malformado são recusados na primeira célula, e uma célula posterior com uma linha de SCIM gravada antes deLOOM_CELLé recusada no attach; um token da célulaa-bé recusado na célulaa, e um nome de célula com_é recusado; - uma célula posterior com
oidc_jit_orgdefinido 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 emrecordingmanté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ósattach_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--finishela 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 deplacements_max; uma atualização que muda uma org configurada de uma célula posterior aindaattachingapós sua transação no diretório é recusada até a célula estarserving;--revertmanté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 opcode.*de um membro de outra org incluída, e o mesmo vale para uma org configurada queloom cell updatealtera; 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 --finishou 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 updaterecusa 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,--finishlibera 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;
--revertespera os processos que correspondem apenas anext;update --configrecusa enquanto umnextdiferente está pendente, e uma atualização que morreu antes de sua gravação emloom.cell_selfé retomada para a frente; prepare recusa enquanto um processo pré-N está ativo; uma mudança de configuração duranteattachingpassa porloom cell updatee 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 updaterecusa uma mudança no deployment id, no nome do bucket ou no prefixo, adicionar um bucket incluído; um processo bloqueado em modoonnã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 oLOOM_CELLde outra célula, e um processo cuja linhafirstnomeia 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_UNREACHABLEePROBE_BUSYdo roteador quando--waitse 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 --closedfaz as chamadas de posicionamento da célula responderem 503 enquanto ela continua servindo as orgs que mantém,--openas restaura, e--placements-maxentra em vigor na próxima chamada de posicionamento;- uma restauração do Postgres de uma célula
enforcedpara antes do posicionamento de uma org, com essa org apagada depois do ponto, reconcilia com código de saída 0 apósloom cell restoree 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.