kolo docsbeta

Topics

Um topic é um valor de 32 bytes. Os peers anunciam os topics em que estão e procuram os outros, sem servidor de diretório.

Nesta página

Um topic são 32 bytes que os peers combinam entre si, geralmente um hash como sha256("kolo chat example"). Ele dá nome ao que os peers querem compartilhar: uma sala de chat, um documento, um log. O Kolo não mantém uma lista de topics, e os bytes não significam nada para ele.

Anunciar e procurar

Todos os passos

Um lookup, passo a passo

Este exemplo usa IDs de 8 bits. Os IDs reais têm 256 bits, a tabela guarda 20 servidores por bucket e até 10 consultas rodam ao mesmo tempo.

  1. A sua tabela de rotas dá os servidores que ela conhece mais perto do topic: aqui A, B e C. A distância é o XOR dos dois IDs.
  2. Você envia LOOKUP a todos de uma vez. Cada resposta traz servidores mais perto do topic, um token e os registros que houver.
  3. C conhece D e E, que estão mais perto. Você pergunta a eles assim que a resposta chega: não há rodadas fixas.
  4. E conhece F e G, mais perto ainda. A lista é ordenada pela distância depois de cada resposta.
  5. A busca para quando os 20 servidores mais próximos que ela conhece responderam ou esgotaram o tempo, ou depois de 100 consultas. Cada registro é assinado pelo peer que o anunciou, e a assinatura é conferida.
  6. Um lookup retorna registros, não conexões. Connect é uma chamada separada, por meio de um servidor que guardou o registro.
Todos os passos

Conectar através de dois NAT

Os dois peers estão atrás de roteadores domésticos. Um nó bootstrap na internet põe os dois em contato; depois os pacotes vão direto.

  1. A e B anunciam cada um um registro assinado do topic a um nó bootstrap, cada um por trás do seu próprio NAT.
  2. A procura o topic. A resposta traz o registro assinado de B, com a sua chave pública e o seu endereço, e o nó que o guardou.
  3. A envia CONNECT a esse nó, que passa o pedido a B. Nenhum alcança ainda o outro: os dois NAT só deixam entrar respostas.
  4. Os dois enviam pacotes PUNCH um ao outro ao mesmo tempo. Cada NAT vê sair o pacote do seu próprio peer e abre um mapeamento, e assim deixa entrar os do outro.
  5. O caminho direto está aberto: os pacotes vão entre A e B sem passar pelo nó. Depois o kolo-secure prova as duas chaves na conexão.

kolo-dht é uma tabela hash distribuída espalhada pelos peers que rodam como servidores, como o kolo-node.

  • Para ser encontrado, um peer anuncia o topic: ele guarda um registro, assinado com a sua chave, em cada um dos até 20 servidores mais próximos que responderam à sua busca do topic; basta um guardar. Ele renova o registro a cada 15 segundos. Um servidor descarta um registro 20 minutos depois da última renovação.
  • Para encontrar os outros, um peer procura o topic. Ele recebe os registros assinados dos peers que estão nele, verifica cada assinatura e então pode se conectar a eles. O servidor que guardou um registro ajuda os dois peers a abrir um caminho direto através dos seus NATs.

kolo-swarm faz as duas coisas por você: Join anuncia o topic, procura o topic ou faz os dois, e mantém conexões com os peers que encontra.

Grupos grandes são uma direção planejada, com duas bibliotecas planejadas e ainda sem código: a kolo-gossip, para passar mensagens pequenas de membro para membro de um topic sem um relay, conforme a especificação GossipSub (versão 1.1 com a regra IDONTWANT da versão 1.2), e a kolo-mls, para criptografar um grupo de ponta a ponta com MLS (RFC 9420). Veja Planejado no roadmap.

Um novo peer precisa de um primeiro endereço

Um peer entra na DHT por meio de um ou mais servidores conhecidos, os endereços de bootstrap. Se você não fornecer nenhum, ele usa os dois nós de entrada públicos que a Ciranda mantém no ar, embutidos na kolo-dht: de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta. Para uma rede própria, você fornece os seus endereços, e os públicos não são usados. O jeito mais comum é rodar alguns servidores kolo-node em hosts com um endereço IPv4 público.

Bom saber

  • Os servidores no caminho veem quais endereços anunciam e procuram um topic.
  • O Kolo é só IPv4. Endereços IPv6 são recusados.