kolo docsbeta

Feito com Kolo

Programas de exemplo escritos pela equipe do Kolo para mostrar as bibliotecas trabalhando juntas. São demonstrações, não software de produção nem produtos.

Nesta página

A página de uma biblioteca mostra uma peça de cada vez. Um exemplo mostra as peças trabalhando juntas: como um peer é encontrado, onde as mensagens ficam guardadas, quem pode entrar.

Estes são programas de exemplo, escritos pela equipe do Kolo para mostrar as bibliotecas trabalhando juntas. São demonstrações, não software de produção nem produtos, e estão em beta, como as bibliotecas. Não são projetos de terceiros. As bibliotecas têm a licença MIT ou Apache-2.0, à sua escolha; os exemplos e os starters deles têm só Apache-2.0.

Os exemplos

Chat para desktop

Funcional

Um exemplo de chat para desktop feito com Wails 3. As mensagens vão direto de peer a peer, ou por um relay que você roda quando dois computadores não conseguem se conectar diretamente, e ficam em um log criptografado. Um pin opcional as guarda para quem está offline, pessoas novas entram com um convite, e cada conversa é uma sala em uma só lista, com perfis. Uma sala se reconecta sozinha e nunca desiste. É o exemplo que você constrói no tutorial, passo a passo.

Código-fonte

ciranda-dev/kolo-chat-wails3-example

Bibliotecas

Tutorial

Exemplo de desktop para compartilhar arquivos

Funcional

Um exemplo de desktop feito com Wails 3. Ele envia um arquivo ou uma pasta em uma sessão que duas pessoas abrem com um código, e o recebe do outro lado, com a kolo-blobs e a kolo-files. Um download interrompido continua sozinho, e itens de 100 GB funcionam.

Código-fonte

ciranda-dev/kolo-share-wails3-example

Bibliotecas

Tutorial

Quadro kanban compartilhado

Funcional

Um quadro kanban para desktop feito com Wails 3 que várias pessoas editam ao mesmo tempo, sobre a kolo-braid. Cada computador sincroniza direto com os outros, ou por um relay que você roda, os membros entram com um convite, e o quadro mostra quais cartões estão assentados.

Código-fonte

ciranda-dev/kolo-board-wails3-example

Bibliotecas

Tutorial

Exemplo de desktop para videochamadas

Funcional

Um exemplo de desktop feito com Wails 3 para chamadas com áudio e vídeo. Uma pessoa cria um convite, e as outras entram na chamada com ele. A imagem acompanha a rede, de 360p a 1080p, e uma chamada volta sozinha depois de uma conexão caída. Quem abriu a chamada pode remover um participante.

Código-fonte

ciranda-dev/kolo-meet-wails3-example

Bibliotecas

Tutorial

Precisa de um relay ou de um pin?

Todo exemplo precisa de nós de entrada para encontrar os outros, e tem três modos de rede:

  • Rede pública (padrão). Sem nenhuma flag, o exemplo usa os dois nós de entrada públicos que a Ciranda mantém no ar, embutidos nas bibliotecas. Nada para configurar: duas pessoas em redes diferentes se encontram. É de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta.
  • A sua própria rede. -bootstrap host:port[,host:port] usa só os seus próprios nós de entrada.
  • Só este computador. -local mantém tudo em 127.0.0.1. O Kolo Share, o Kolo Meet e o Kolo Board têm essa opção; o Kolo Chat não.

Não existe relay público nem pin público: os dois continuam opcionais e você roda os seus. Os comandos estão em Rode a sua própria infraestrutura.

Kolo Chat

  • Janela: uma única lista de salas na barra lateral, e cada conversa é uma sala. A barra lateral se recolhe em uma coluna estreita. O "+" ao lado da lista abre um menu com "Criar uma sala" e "Entrar em uma sala", cada uma em uma caixa de diálogo própria. As mensagens da mesma pessoa com menos de cinco minutos entre elas ficam juntas sob um só nome e um só horário. A janela não mostra os endereços dos nós de entrada públicos.
  • Pin: opcional. Sem ele, as mensagens chegam às pessoas só enquanto elas estão online. Com um, ele guarda uma cópia cifrada das mensagens para quem está offline: cada membro deriva as chaves das mensagens da chave da conversa, então uma mensagem é lida de um pin mesmo quando quem a enviou está offline. O pin precisa de um endereço que todos os membros alcancem: o exemplo nunca chega a um pin por um relay.
  • Salas: um exemplo guarda 64 salas por padrão; -max-conversations muda isso, de 1 a 256.
  • Estados da rede: uma sala mostra o seu estado como um ponto na lista, embaixo do nome e em uma nota: conectando, online, reconectando ou offline, nunca como um erro. Uma sala nunca trava nem desiste. Quando nenhum nó de entrada responde, ela começa mesmo assim, trabalha com o próprio log e pergunta de novo sozinha, esperando 2 segundos e dobrando até 30. Quando a última conexão com um peer termina, ela diz "reconectando" por até 45 segundos, disca de novo para os peers, e cada lado faz pull do que o outro escreveu nesse meio-tempo. As mensagens digitadas nesse meio-tempo ficam no log da sala e aparecem uma vez, em ordem, quando a conexão volta. Um pin que não pode ser alcançado é tentado de novo com uma espera crescente.
  • Muitas salas: o exemplo inicia as suas salas quatro de cada vez, a que está na tela primeiro, porque um nó de entrada público deixa um endereço enviar 50 requisições por segundo.
  • Relay: opcional, para dois computadores atrás de NATs restritivos que não conseguem se conectar diretamente. Quando a conexão direta falha, o convite, as mensagens e a sincronização do histórico, dos nomes e das salas passam por ele, e ele não consegue lê-los.
  • Inicie todos os exemplos com o mesmo relay: -relay host:port@key, repetido ou como lista separada por vírgulas, -relay-file, ou KOLO_CHAT_RELAYS quando nenhuma das flags é dada; no máximo 16. O convite não leva os relays. As configurações mostram o estado de cada relay.
  • Segredos: a chave da conversa e o token do pin nunca são flags, porque um flag aparece na lista de processos e no histórico do shell. -conversation-key e -pin-token são recusados com uma mensagem que indica a variável e o arquivo. Defina KOLO_CHAT_CONVERSATION_KEY e KOLO_CHAT_PIN_TOKEN, ou use -conversation-key-file e -pin-token-file (também KOLO_CHAT_CONVERSATION_KEY_FILE e KOLO_CHAT_PIN_TOKEN_FILE), que leem o segredo de um arquivo que só o dono pode abrir.
  • Memória: na partida é definido um limite flexível de memória: metade da memória física, nunca menos de 512 MiB, e 2 GiB quando não dá para ler a memória. GOMEMLIMIT o substitui.
  • Versão: Configurações mostra a versão em Sobre, a tag do git do build; um build sem tag mostra dev.

Kolo Share

  • Janela: uma barra lateral com as suas sessões, que se recolhe em uma coluna estreita, um menu "+" com "Mostrar um código" e "Colar um código", e um cartão com Histórico e Ajustes. Uma linha discreta diz em que rede o exemplo está. A outra pessoa vê um item como "sendo preparado" enquanto você o prepara, e essa mesma linha vira a oferta. As linhas mostram o progresso e a velocidade reais, e avisam quando nada andou por um tempo.
  • Retomada: um download interrompido continua sozinho a partir dos pedaços que já verificou. -resume-for (ou KOLO_SHARE_RESUME_FOR) define quanto tempo ele espera por bytes que pararam; o padrão é 30 minutos. Itens de 64 MiB ou mais usam um armazenamento ajustado para dados grandes.
  • Itens grandes: um item de 100 GB funciona. -max-download (ou KOLO_SHARE_MAX_DOWNLOAD) é um limite de segurança, 1 TiB por padrão. O disco é verificado antes do primeiro byte, na pasta de dados e na pasta escolhida, e um disco curto encerra a transferência na hora e diz quanto é preciso e quanto está livre. Até 4 itens de uma sessão são recebidos ao mesmo tempo.
  • Velocidade: a conexão com um computador pareado dita o ritmo do que envia com BBR por padrão, e -congestion reno|cubic|bbr (ou KOLO_SHARE_CONGESTION) muda isso. O BBR mantém uma fila fixa de 25 a 150 ms e tira banda de outros fluxos, então defina reno em um link compartilhado. As janelas de recepção só crescem para o computador pareado, e toda outra conexão mantém janelas pequenas. As conexões de pareamento continuam no Reno.
  • Relay: opcional, para dois computadores atrás de NATs restritivos que não conseguem se conectar diretamente. Quando a conexão direta falha, o pareamento, a sessão e os arquivos dela passam por ele, e ele não consegue lê-los.
  • Pin: não é usado. Uma sessão só move arquivos enquanto os dois exemplos estão abertos.
  • Inicie os dois exemplos com o mesmo relay: -relay host:port@key, repetido ou como lista separada por vírgulas, -relay-file, ou KOLO_SHARE_RELAYS quando nenhuma das flags é dada; no máximo 16. Um relay com lista de permissões nunca guarda um código de pareamento, então um pareamento por ele só funciona quando o computador que mostra o código é alcançável diretamente.
  • Números da conexão: as linhas transfer: do log terminam com o que o Conn.Stats da kolo-transport mediu na conexão: o tempo de ida e volta (rtt, min_rtt), a janela de congestionamento e os bytes em trânsito (cwnd, in_flight), os pacotes enviados e perdidos e os bytes perdidos, o controlador (cc), a estimativa de banda do BBR (bw_mbs) e as mudanças para um caminho novo (path_changes). Nenhum nome, chave ou endereço vai para o log.
  • Nomes longos: um nome ou um caminho que este computador não consegue salvar é recusado antes do download: 255 bytes por nome no macOS e no Linux, e um caminho de 1023 bytes no macOS, 4095 no Linux e 32767 unidades UTF-16 no Windows.
  • Memória: na partida é definido um limite flexível de memória: metade da memória física, pelo menos 512 MiB, e 2 GiB quando não dá para ler a memória. GOMEMLIMIT o substitui.
  • Versão: Configurações mostra a tag do git do build; um build sem tag mostra dev.

Kolo Meet

  • Relay da chamada: o exemplo do anfitrião roda um para cada chamada, e a mídia de cada pessoa passa por ele. Não há nada para instalar.
  • Relay de conexão: opcional, para dois computadores atrás de NATs restritivos que não conseguem se conectar diretamente. Ele leva a conexão até o relay da chamada e os links de chaves entre os participantes, e não consegue lê-los. Passe-o para todos os exemplos com -relay, -relay-file ou KOLO_MEET_RELAYS; no máximo 16. Um convidado que não alcança o anfitrião diretamente precisa de um relay sem lista de permissões, já que o relay da chamada tem uma chave criada para aquela chamada.
  • Qualidade: a câmera sobe e desce sozinha uma escada de três imagens, 360p, 720p e o teto de -video-size (1080p por padrão): desce na hora quando a conexão com o relay da chamada não consegue carregar a imagem, e sobe depois de alguns segundos de caminho livre. Com vários convidados, o melhor caminho decide.
  • Conexões ruins: uma chamada tenta por até 60 segundos recuperar a sessão com o relay antes de terminar, e o relay guarda o lugar do convidado pelo mesmo tempo, então ninguém vê o convidado sair. Um vigia abre uma sessão nova quando uma pessoa que envia não entrega nada por 6 segundos. Um espectador que perdeu um grupo pede ao emissor um quadro chave.
  • Pin: não é usado. Uma chamada não guarda nada para depois.
  • O anfitrião pode remover um participante. Os convites que existem naquele momento deixam de deixar essa pessoa voltar; um convite novo do anfitrião deixa.
  • Convites: o convite é servido por um segundo nó de rede com uma chave própria, e o relay da chamada só pelas pessoas que o anfitrião deixou entrar. Um estranho com o convite só alcança o nó do convite, que mantém os 16 streams de entrada da kolo-transport; as pessoas na chamada mantêm 1000. Um anfitrião desta versão precisa de convidados desta versão.
  • Desenho: -display-fps (ou KOLO_MEET_DISPLAY_FPS) define as imagens por segundo que cada quadro da janela desenha: auto (o padrão: 30 enquanto no máximo outras 4 pessoas mostram vídeo, 15 com mais), 30 ou 15.
  • Números da conexão: a linha local do relatório de qualidade da chamada, e a de -quality-log, tem um objeto net com o que a kolo-transport mediu nas conexões com o relay: tempo de ida e volta, perda, janela de congestionamento, bytes em trânsito, controlador, estimativa de banda do BBR e mudanças de caminho. Ele não tem nenhum endereço nem chave.
  • Memória: na partida é definido um limite flexível de memória de 2 GiB, a menos que GOMEMLIMIT esteja definido, e o log diz qual.
  • Versão: a tag do git, em Configurações, no status e em cada pacote; dev em um build de desenvolvimento.

Kolo Board

  • Janela: uma barra lateral com o quadro, que se recolhe em uma coluna estreita, quantos cartões estão assentados e sincronizando, uma linha discreta sobre a rede e um cartão com Configurações. O cabeçalho tem o nome do quadro, os membros e os botões Convidar, Atividade e Membros.
  • Relay: opcional, para dois computadores atrás de NATs restritos que não conseguem se conectar diretamente. Quando a conexão direta falha, o convite, a entrada e a sincronização do quadro passam por ele, e ele não consegue ler o que repassa.
  • Settlers: uma mudança se assenta quando há settlers suficientes online. O exemplo admite cada pessoa que entra com AdmitOptions.GrowSettlers, que decide quem assenta: com um ou dois membros só quem criou o quadro, com três os três, com quatro ou mais quatro deles, e quem entra depois é membro simples. A janela mostra quantos estão online, e as mudanças ficam sincronizando enquanto há poucos.
  • Pin: não é usado. Os membros sincronizam direto entre si enquanto estão online ao mesmo tempo.
  • Inicie todos os exemplos com o mesmo relay: -relay host:port@key, repetido ou como lista separada por vírgulas, -relay-file, ou KOLO_BOARD_RELAYS quando nenhum dos dois flags é passado; no máximo 16. O convite não leva os relays. As configurações mostram o estado de cada relay, e um relay informado com a chave errada é avisado poucos segundos depois do início.
  • Memória: na partida é definido um limite flexível de memória de 2 GiB, a menos que GOMEMLIMIT esteja definido, e uma linha do log indica o limite.
  • Versão: a tag do git do build; um build sem tag, e o wails3 dev, dizem dev.

Experimente o Kolo Board

O Kolo Board é um quadro kanban para desktop que várias pessoas editam ao mesmo tempo, sobre a kolo-braid: só colunas e cartões, sem chat, sem comentários e sem anexos. Você precisa do Go 1.26 ou mais novo, do Node.js com npm e da CLI do Wails 3. Rode os comandos na pasta do repositório.

Uma vez: compile o exemplo.

Terminal
wails3 build

Uma vez: crie uma pasta privada para os dados da demo.

Terminal
mkdir -p -m 700 /tmp/kolo-board-demo

Sem nenhuma flag o exemplo entra na rede pública. Os dois comandos abaixo mantêm a demo neste computador, com um nó de entrada próprio no loopback (-local faz o mesmo com uma só flag). Terminal 1: Ana. -first faz o exemplo dela rodar também o nó de entrada no loopback.

Terminal
./bin/kolo-board -data /tmp/kolo-board-demo/ana -first 127.0.0.1:4000

Terminal 2: Bia.

Terminal
./bin/kolo-board -data /tmp/kolo-board-demo/bia -bootstrap 127.0.0.1:4000

Na janela da Ana, escolha um nome, crie um quadro e gere um convite. Na janela da Bia, escolha um nome, cole o convite e entre. Mantenha a janela da Ana aberta: ela é o nó de entrada. Em dois computadores, inicie os dois exemplos sem flags para usar a rede pública, ou rode um nó de entrada próprio do kolo-node e passe -bootstrap, como em Rode a sua própria infraestrutura.

Kolo Playground

O Kolo Playground é uma ferramenta de testes privada, não uma biblioteca nem um dos exemplos. O braid-peer dele roda um membro da kolo-braid como processo próprio, e o braid-scenarios inicia vários deles em 127.0.0.1, cada um num diretório temporário, e roda cenários com vários peers: convergência, partição e reconexão, mudanças de associação simultâneas, escritores que bifurcam a história, spam, kill -9, dispositivos restaurados e copiados, e membros que entram depois. Cada cenário termina com os mesmos digests assentados em todos os peers honestos, ou com a parada que ele espera, e imprime um relatório de custos. Rode os comandos na pasta do repositório.

Liste os cenários:

Terminal
go run ./cmd/braid-scenarios -list

Rode um:

Terminal
go run ./cmd/braid-scenarios -run partition-heal

Rode um peer à mão, como fundador de um braid novo num diretório temporário. Ele lê comandos pelo stdin e imprime um objeto JSON por linha:

Terminal
go run ./cmd/braid-peer --first

Teste o harness e todos os cenários curtos:

Terminal
go test ./...

O que os cartões dizem

  • Funcional: o exemplo funciona e você pode testá-lo, e seguimos atualizando. O cartão dele traz links para um tutorial e para a página de cada biblioteca que ele usa. No Kolo Chat e no Kolo Meet o tutorial constrói o exemplo. O Kolo Share e o Kolo Board não têm um guia passo a passo próprio: o cartão deles leva ao tutorial da biblioteca principal (kolo-blobs e kolo-files, ou kolo-braid), e o código do exemplo está no repositório.
  • Em andamento: estamos construindo. O cartão ainda não tem links, e vai ganhar quando o exemplo estiver pronto.

Como todas as bibliotecas do Kolo, estes exemplos estão em beta: acompanham as bibliotecas v0.x e mudam com elas.