Neste guia duas pessoas escrevem juntas um documento, cada uma em uma janela de terminal do seu computador. Cada linha que alguém digita é assinada por quem a escreveu, e os dois terminais mostram as mesmas linhas na mesma ordem. Depois você vê o que significam "assentada" e "tentativa", reinicia um terminal e remove um escritor.
O programa usa a kolo-braid, que junta os logs
assinados de vários membros em uma única ordem que todo peer calcula do mesmo
jeito. Tudo fica no seu computador, no endereço 127.0.0.1. Você começa pelo
repositório
kolo-braid-starter, que
também traz o código pronto.
1Confira o que você precisa
Você precisa do Go 1.26 ou mais recente, do git e de duas janelas de terminal. Construa um chat no seu terminal mostra como instalar o Go. Aqui o Terminal 1 é a Ana, que cria o documento, e o Terminal 2 é o Bruno, que entra nele.
2Baixe o starter
No Terminal 1, clone o starter e entre na pasta:
git clone https://github.com/ciranda-dev/kolo-braid-starter.git && cd kolo-braid-starterO main.go já está pronto: ele lê as opções, guarda a sua chave na pasta que
você passa com -dir e entrega cada linha digitada ao doc.go. O doc.go só
declara o que o main.go chama. (A versão pronta está em finished/, e o
main.go dela é o mesmo arquivo que este.) Crie uma pasta temporária para a Ana:
ANA="$(mktemp -d)"$ana = (New-Item -ItemType Directory -Path (Join-Path $env:TEMP "kolo-ana-$(Get-Random)")).FullNameANA="$(mktemp -d)"Rode o starter do jeito que ele está:
go run . -dir "$ANA" -listen 127.0.0.1:7450go run . -dir $ana -listen 127.0.0.1:7450go run . -dir "$ANA" -listen 127.0.0.1:7450Ele mostra a chave da Ana. Digite show e aperte Enter:
07:05:06 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:06 type: say <text>, show, add <key>, remove <key>
07:05:07 not written yet: follow the guideAperte Ctrl-C para parar. O próximo passo completa o doc.go.
3Escreva o doc.go
Troque o conteúdo do doc.go pelas cinco partes abaixo, uma depois da outra.
A primeira parte é a regra que transforma a ordem no documento. A kolo-braid
chama apply para cada entrada, na mesma ordem em todo peer. Cada linha fica
guardada na sua posição, com os 4 primeiros bytes da chave de quem a escreveu.
Uma linha vazia ou com mais de 500 bytes é recusada com Reject, do mesmo
jeito em todo peer. O apply não pode ler o relógio, sortear números nem
fazer E/S, para que todo peer monte o mesmo documento. O say também recusa uma
linha assim na hora de digitar, com o erro a line is 1 to 500 bytes, então uma
linha que nenhum peer mostraria nunca é escrita.
package main
import (
"bytes"
"context"
"crypto/ed25519"
"encoding/binary"
"encoding/hex"
"errors"
"fmt"
"io"
"log"
"os"
"path/filepath"
"slices"
"sync"
"time"
kolobraid "github.com/ciranda-dev/kolo-braid"
koloid "github.com/ciranda-dev/kolo-id"
kolosecure "github.com/ciranda-dev/kolo-secure"
kolostore "github.com/ciranda-dev/kolo-store"
)
const (
app = "doc/v1"
maxLine = 500
)
var errKey = errors.New("a key is 64 hex digits")
// apply turns each data entry into one line of the document, kept under its position in the braid's order with the
// first 4 bytes of its writer's key.
func apply(tx *kolobraid.Tx, e *kolobraid.Entry) error {
if e.Kind != kolobraid.KindData {
return nil
}
if len(e.Body) == 0 || len(e.Body) > maxLine {
return kolobraid.Reject("a line is 1 to 500 bytes")
}
key := binary.BigEndian.AppendUint64([]byte("line/"), e.Position)
return tx.Put(key, append(e.Writer[:4:4], e.Body...))
}A segunda parte abre o documento guardado na pasta, ou cria um novo
(-listen), ou entra em um (-peer). A pasta guarda um banco Pebble da
kolo-store, então o documento continua lá depois
de reiniciar. Ele imprime listening on IP:PORT quando escuta. O Close espera
as goroutines (o laço de accept, os tratadores de conexão e o follow) antes de
fechar o braid e o store.
// Doc is one person's copy of the shared document.
type Doc struct {
braid *kolobraid.Braid
db kolostore.Backend
l *kolosecure.Listener
stop context.CancelFunc
wg sync.WaitGroup
allowed sync.Map // keys the owner typed add for, each let in once
}
// openDoc opens the document stored in dir, or starts one (listen) or joins one (peer), and keeps it in sync.
func openDoc(ctx context.Context, id *koloid.Identity, dir, listen, peer string, owner ed25519.PublicKey) (*Doc, error) {
db, err := kolostore.OpenPebble(filepath.Join(dir, "doc"))
if err != nil {
return nil, err
}
opts := kolobraid.Options{Backend: db, App: app, Apply: apply}
br, err := kolobraid.Open(ctx, id, opts)
switch {
case errors.Is(err, kolobraid.ErrNotFound) && listen != "":
log.Print("started a new document")
br, err = kolobraid.Create(ctx, id, kolobraid.GroupConfig{App: app}, opts)
case errors.Is(err, kolobraid.ErrNotFound):
br, err = join(ctx, id, opts, peer, owner)
}
if err != nil {
db.Close()
return nil, err
}
ctx, stop := context.WithCancel(ctx)
d := &Doc{braid: br, db: db, stop: stop}
if listen == "" {
d.wg.Go(func() { d.follow(ctx, id, peer, owner) })
return d, nil
}
if d.l, err = kolosecure.Listen(ctx, listen, id, nil); err != nil {
d.Close()
return nil, err
}
log.Print("listening on ", listen)
d.wg.Go(func() { d.accept(ctx) })
return d, nil
}
// Close stops the document.
func (d *Doc) Close() {
d.stop()
if d.l != nil {
d.l.Close()
}
d.wg.Wait()
d.braid.Close()
d.db.Close()
}A terceira parte roda os comandos. say acrescenta uma entrada ao seu próprio
strand, o seu kolo-log assinado. show lê dois
snapshots: View (linhas assentadas e tentativas) e Settled (só as
assentadas), e marca cada linha conforme onde ela está. add e remove recebem
uma chave de 64 dígitos hexadecimais e recusam qualquer outra coisa com
a key is 64 hex digits.
// do runs one command typed in the terminal.
func (d *Doc) do(ctx context.Context, cmd, arg string) error {
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
key, _ := hex.DecodeString(arg)
switch cmd {
case "say":
if len(arg) == 0 || len(arg) > maxLine {
return errors.New("a line is 1 to 500 bytes")
}
_, err := d.braid.Append(ctx, []byte(arg))
return err
case "show":
d.show(os.Stdout)
return nil
case "add":
if len(key) != ed25519.PublicKeySize {
return errKey
}
d.allowed.Store(string(key), true)
log.Printf("%.8s can join now", arg)
return nil
case "remove":
if len(key) != ed25519.PublicKeySize {
return errKey
}
_, err := d.braid.RemoveMember(ctx, key)
return err
}
return errors.New("commands: say <text>, show, add <key>, remove <key>")
}
// show prints every line in the braid's order with its writer, and whether its place is settled or still tentative.
func (d *Doc) show(w io.Writer) {
view, settled := d.braid.View(), d.braid.Settled()
defer view.Close()
defer settled.Close()
n := 0
for k, v := range view.Scan([]byte("line/"), []byte("line0")) {
state := "tentative"
if s, err := settled.Get(k); err == nil && bytes.Equal(s, v) {
state = "settled"
}
n++
fmt.Fprintf(w, "%d. %x: %s (%s)\n", n, v[:4], v[4:], state)
}
if n == 0 {
fmt.Fprintln(w, "the document is empty")
}
}A quarta parte roda do lado da Ana. Cada conexão é uma conexão
kolo-secure, então a Ana sabe a chave de quem
está do outro lado. Um membro é sincronizado com ServeConn. Uma chave para a
qual a Ana digitou add pode mandar um pedido para entrar: Admit a adiciona
como escritor e devolve as boas-vindas. A permissão só é gasta depois que o
Admit deu certo, então uma conexão que não envia nenhum pedido não a queima e
a Ana não precisa digitar add de novo. Qualquer outra conexão é fechada.
// accept syncs with members, lets in a key the owner typed add for, and closes every other connection.
func (d *Doc) accept(ctx context.Context) {
for {
c, err := d.l.Accept(ctx)
if err != nil {
return
}
d.wg.Go(func() {
defer c.Close()
key := c.RemotePublicKey()
v := d.braid.View()
member := slices.ContainsFunc(v.Members(), func(m kolobraid.Member) bool { return bytes.Equal(m.Key, key) })
v.Close()
if member {
d.braid.ServeConn(ctx, c)
} else if _, ok := d.allowed.Load(string(key)); ok {
if err := d.admit(ctx, c); err != nil {
log.Print("add: ", err)
} else {
d.allowed.Delete(string(key))
}
}
})
}
}
// admit reads a join request on c, adds its sender as a writer and sends the welcome back.
func (d *Doc) admit(ctx context.Context, c *kolosecure.Conn) error {
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
s, err := c.AcceptStream(ctx)
if err != nil {
return err
}
req, err := io.ReadAll(io.LimitReader(s, kolobraid.MaxJoinRequest))
if err != nil {
return err
}
writer := kolobraid.Role(0) // not an admin and not a settler
welcome, err := d.braid.Admit(ctx, c.RemotePublicKey(), req, &kolobraid.AdmitOptions{Roles: &writer})
if err != nil {
return err
}
if _, err := s.Write(welcome); err != nil {
d.braid.RemoveMember(ctx, c.RemotePublicKey())
return err
}
s.Close()
select { // the joiner hangs up once it has the welcome
case <-c.Context().Done():
case <-ctx.Done():
}
log.Printf("added %x", c.RemotePublicKey()[:4])
return nil
}A última parte roda do lado do Bruno. NewJoin cria o strand dele e o pedido
para entrar. Ele manda o pedido para a Ana uma vez por segundo até ela deixá-lo
entrar, e então Complete abre o documento com as boas-vindas dela. Depois ele
fica conectado à Ana, sincroniza com ServeConn e se conecta de novo se ela
reiniciar.
// join asks the owner to let this key in, once a second until the owner typed add for it, and opens the document.
func join(ctx context.Context, id *koloid.Identity, opts kolobraid.Options, peer string, owner ed25519.PublicKey) (*kolobraid.Braid, error) {
j, err := kolobraid.NewJoin(ctx, id, opts)
if err != nil {
return nil, err
}
req, err := j.Request(nil)
if err != nil {
return nil, err
}
log.Print("waiting for the owner to type add and my key")
for {
if welcome, err := ask(ctx, id, peer, owner, req); err == nil {
log.Print("joined the document")
return j.Complete(ctx, welcome)
}
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(time.Second):
}
}
}
// ask sends the join request to the owner and returns the welcome.
func ask(ctx context.Context, id *koloid.Identity, peer string, owner ed25519.PublicKey, req []byte) ([]byte, error) {
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
c, err := kolosecure.Dial(ctx, peer, id, owner, nil)
if err != nil {
return nil, err
}
defer c.Close()
s, err := c.OpenStream(ctx)
if err != nil {
return nil, err
}
s.SetDeadline(time.Now().Add(10 * time.Second))
if _, err := s.Write(req); err != nil {
return nil, err
}
s.Close()
welcome, err := io.ReadAll(io.LimitReader(s, kolobraid.MaxWelcome))
if err == nil && len(welcome) == 0 {
err = errors.New("not added yet")
}
return welcome, err
}
// follow keeps a connection to the owner and syncs the document over it, again after the owner restarts.
func (d *Doc) follow(ctx context.Context, id *koloid.Identity, peer string, owner ed25519.PublicKey) {
for ctx.Err() == nil {
if c, err := kolosecure.Dial(ctx, peer, id, owner, nil); err == nil {
d.braid.ServeConn(ctx, c)
c.Close()
}
select {
case <-ctx.Done():
case <-time.After(time.Second):
}
}
}Compare o seu arquivo com o pronto. Este comando não mostra nada quando eles são iguais:
git diff --no-index doc.go finished/doc.go4Crie o documento no Terminal 1
No Terminal 1, rode o programa de novo com a pasta da Ana:
go run . -dir "$ANA" -listen 127.0.0.1:7450go run . -dir $ana -listen 127.0.0.1:7450go run . -dir "$ANA" -listen 127.0.0.1:7450A Ana mantém a chave dela e cria um documento novo. Os seus horários e as suas chaves vão ser outros:
07:05:08 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:08 started a new document
07:05:08 type: say <text>, show, add <key>, remove <key>5Entre pelo Terminal 2
No Terminal 2, vá para a mesma pasta kolo-braid-starter (use o caminho
onde você a clonou):
cd kolo-braid-starterCrie uma pasta temporária para o Bruno:
BRUNO="$(mktemp -d)"$bruno = (New-Item -ItemType Directory -Path (Join-Path $env:TEMP "kolo-bruno-$(Get-Random)")).FullNameBRUNO="$(mktemp -d)"Depois entre com a chave da Ana, a longa da linha me dela (cole a sua):
go run . -dir "$BRUNO" -peer 127.0.0.1:7450 -key 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87go run . -dir $bruno -peer 127.0.0.1:7450 -key 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87go run . -dir "$BRUNO" -peer 127.0.0.1:7450 -key 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87O Bruno espera pela Ana:
07:05:10 me 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abf
07:05:10 waiting for the owner to type add and my keyNo Terminal 1, digite add e a chave do Bruno (cole a sua):
add 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abfA Ana deixa ele entrar:
07:05:13 3fa349c6 can join now
07:05:13 added 3fa349c6No Terminal 2, o Bruno entrou:
07:05:13 joined the document
07:05:13 type: say <text>, show, add <key>, remove <key>6Escrevam juntos
No Terminal 1, digite:
say Kolo meeting notesNo Terminal 2, digite:
say We meet on Friday at 10Digite show nos dois terminais. Os dois mostram o mesmo documento, na mesma
ordem, com a chave curta de quem escreveu cada linha:
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)7Veja uma linha tentativa
Uma linha é tentativa enquanto o lugar dela na ordem ainda pode mudar, por exemplo quando outra pessoa escreveu uma linha ao mesmo tempo. Ela fica assentada quando um settler fixa o lugar dela, e daí em diante não muda mais. Aqui a Ana é o único settler, então uma linha só se assenta enquanto a Ana está online.
Pare a Ana com Ctrl-C no Terminal 1. No Terminal 2, digite
say Ana brings the slides e depois show:
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (tentative)A linha nova do Bruno está no documento dele, mas o lugar dela ainda não foi fixado. No Terminal 1, inicie a Ana de novo com a mesma pasta:
go run . -dir "$ANA" -listen 127.0.0.1:7450go run . -dir $ana -listen 127.0.0.1:7450go run . -dir "$ANA" -listen 127.0.0.1:7450A chave e o documento dela continuam lá, então ela não cria um novo:
07:05:23 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:23 type: say <text>, show, add <key>, remove <key>O Bruno se conecta de novo em poucos segundos e manda para ela a linha nova,
que ela assenta. Digite show nos dois terminais:
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (settled)8Remova um escritor
No Terminal 1, remova o Bruno com a chave dele (cole a sua):
remove 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abfDepois, no Terminal 1, digite say Bruno left the project, e no
Terminal 2, digite say Bruno writes after the removal. Espere alguns
segundos e digite show nos dois terminais. O documento da Ana tem a linha
nova dela, não a do Bruno:
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (settled)
4. 16dbfe82: Bruno left the project (settled)O documento do Bruno não recebe a linha nova da Ana, e a dele continua tentativa:
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (settled)
4. 3fa349c6: Bruno writes after the removal (tentative)A Ana parou de mandar qualquer coisa para o Bruno, e toda entrada que o Bruno escreve depois de ser removido é nula em todo lugar: nenhum outro membro a mostra. Do lado dele ela continua tentativa, porque nada mais se assenta para ele. O Bruno guarda as linhas que recebeu antes.
9Pare tudo
Aperte Ctrl-C no Terminal 2 e depois no Terminal 1.
O que aconteceu
- Cada pessoa escreveu em um strand só seu: um kolo-log em que cada entrada é assinada por quem a escreveu, guardado com a kolo-store.
- A kolo-braid juntou os strands em uma única ordem. Todo peer que tem as
mesmas entradas calcula a mesma ordem, byte a byte, e chama
applynela, então os dois documentos ficaram iguais. - A Ana criou o documento, então ela era a admin e o único settler. O Bruno entrou como escritor: ele pode escrever, mas não adicionar nem remover ninguém.
- As mudanças de membros entram na ordem como as linhas. As linhas do Bruno de antes da remoção mantiveram o lugar; a de depois foi nula.
- Os dois terminais sincronizaram por uma conexão
kolo-secure em
127.0.0.1, comServeConn.
Entre dois computadores
Os dois terminais se conectam diretamente: -listen abre a porta e -peer
disca para ela. Eles não usam a DHT nem o swarm, então não há bootstrap para
configurar.
-listene-peerprecisam ser umIP:PORTIPv4 que não seja 0.0.0.0 e tenha uma porta diferente de 0. Qualquer outra coisa termina com"..." is not an IPv4 IP:PORT such as 127.0.0.1:7450.- Em um único computador use
127.0.0.1, como nos passos acima. - Na mesma rede local, o Terminal 1 passa
-listencom o endereço IPv4 da sua placa de rede, como-listen 192.168.1.20:7450, e o Terminal 2 passa-peer 192.168.1.20:7450com a chave. - Entre duas redes diferentes só funciona se o primeiro computador tem um endereço IPv4 público que o segundo consiga alcançar, com a porta UDP aberta no firewall.
- Dois computadores que estão ambos atrás de roteadores domésticos não vão se conectar: este programa não atravessa o NAT e não usa relay.
Para esse caso use os exemplos do Kolo (chat, share, meet, board) ou a biblioteca kolo-swarm, que encontram os pares pelos nós de entrada públicos por padrão.
Antes de construir em cima disso
- A kolo-braid está em beta e é experimental, como toda biblioteca do Kolo em v0.x: a API pode mudar antes da v1.0.0.
- Ela é testada com testes unitários, de propriedades e fuzz, verificações de
modelo limitadas do assentamento e dos membros, que cobrem só os tamanhos que
enumeram e não são uma prova para qualquer tamanho, e cenários com vários
processos em um Mac, só em
127.0.0.1. Ela não foi testada em uma rede real nem através de NAT. - Com um único settler, o documento depende desse aparelho: enquanto a Ana
está offline, nada se assenta.
Admitsem opções admite um membro simples, como este programa faz com o Bruno;AdmitOptions.GrowSettlersfaz os primeiros que entram virarem admins e settlers, até 4 lugares, e é para quem você confia a esse ponto. - Uma linha nunca pode ser apagada: todo peer guarda toda entrada, o histórico nunca é podado e cada entrada ocupa uns 600 bytes de disco em cada peer. Guarde fora da braid os dados que possam precisar ser apagados.
- A ordem entre linhas escritas ao mesmo tempo não é justa, e um settler pode tentar escolhê-la, então não crie em cima dela uma regra de "quem chega primeiro ganha".
- O assentamento guarda uma pequena marca de rodada por settler a cada rodada, até a configuração de settlers mudar. Com 4 settlers assentando o dia todo no ritmo padrão, isso dá até uns 22 MB de memória e 55 MB de disco por dia. Elas são o que permite que um pulso que chega tarde receba a sua rodada exata, e uma mudança da configuração de settlers as remove.
- A entrada aqui é a menor que funciona: a Ana deixa entrar uma chave que ela digitou, por uma conexão direta. Um app de verdade leva o pedido e as boas-vindas com a kolo-invite, como em Convide alguém para um grupo, em um programa de terminal e na página da kolo-braid.
ServeConnfunciona com conexões diretas e retransmitidas. Para alcançar alguém atrás de um NAT, veja Rode a sua própria infraestrutura.
O que não foi testado
Todas as execuções por trás deste guia foram em um Mac, em 127.0.0.1. Os
comandos de Windows e Linux não foram executados.
Próximos passos
- Leia a página da kolo-braid: a função apply, o
assentamento, como adicionar um escritor com a kolo-invite e o helper
kv. - Encontre peers por tópico em vez de por endereço: Construa um chat no seu terminal.
- Leia Logs e Peers.