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
FuncionalUm 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
FuncionalUm 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
FuncionalUm 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
- kolo-id
- kolo-dht
- kolo-swarm
- kolo-secure
- kolo-transport
- kolo-relay
- kolo-codec
- kolo-store
- kolo-sync
- kolo-invite
- kolo-braid
Tutorial
Exemplo de desktop para videochamadas
FuncionalUm 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
- kolo-id
- kolo-dht
- kolo-swarm
- kolo-secure
- kolo-transport
- kolo-relay
- kolo-store
- kolo-invite
- kolo-moq
- kolo-media
- kolo-audio
- kolo-video
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.
-localmanté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-conversationsmuda 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, ouKOLO_CHAT_RELAYSquando 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-keye-pin-tokensão recusados com uma mensagem que indica a variável e o arquivo. DefinaKOLO_CHAT_CONVERSATION_KEYeKOLO_CHAT_PIN_TOKEN, ou use-conversation-key-filee-pin-token-file(tambémKOLO_CHAT_CONVERSATION_KEY_FILEeKOLO_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.
GOMEMLIMITo 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(ouKOLO_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(ouKOLO_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(ouKOLO_SHARE_CONGESTION) muda isso. O BBR mantém uma fila fixa de 25 a 150 ms e tira banda de outros fluxos, então definarenoem 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, ouKOLO_SHARE_RELAYSquando 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 oConn.Statsda 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.
GOMEMLIMITo 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-fileouKOLO_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(ouKOLO_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),30ou15. - Números da conexão: a linha
localdo relatório de qualidade da chamada, e a de-quality-log, tem um objetonetcom 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
GOMEMLIMITesteja definido, e o log diz qual. - Versão: a tag do git, em Configurações, no status e em cada pacote;
devem 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, ouKOLO_BOARD_RELAYSquando 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
GOMEMLIMITesteja 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, dizemdev.
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.
wails3 buildUma vez: crie uma pasta privada para os dados da demo.
mkdir -p -m 700 /tmp/kolo-board-demoSem 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.
./bin/kolo-board -data /tmp/kolo-board-demo/ana -first 127.0.0.1:4000Terminal 2: Bia.
./bin/kolo-board -data /tmp/kolo-board-demo/bia -bootstrap 127.0.0.1:4000Na 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:
go run ./cmd/braid-scenarios -listRode um:
go run ./cmd/braid-scenarios -run partition-healRode 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:
go run ./cmd/braid-peer --firstTeste o harness e todos os cenários curtos:
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.