kolo docsbeta

Passo 7: Combine membros e salas com o kolo-braid

Guarde a lista de membros e a lista de salas de cada conversa em um kolo-braid, para que todos os membros terminem com as mesmas listas, os admins aprovem e removam membros, e o chat fale só com quem está na lista combinada.

Nesta página

No passo anterior um app guardava várias conversas. Agora os membros de uma conversa entram em acordo sobre duas listas: quem está nela e quais salas ela tem.

As mensagens não precisam de uma ordem combinada. Cada membro escreve o próprio log, e duas mensagens escritas no mesmo momento podem aparecer em qualquer ordem sem que ninguém perca nada: elas comutam. A lista de membros e a lista de salas são diferentes: são estado compartilhado. Dois admins podem agir no mesmo momento, um removendo a Carol enquanto o outro aprova o Dave, ou os dois adicionando uma sala chamada "design", e todos os membros precisam terminar com as mesmas listas. O kolo-braid dá isso: ele junta as entradas de todos os membros em uma só ordem que cada peer calcula do mesmo jeito, e uma função apply que você escreve transforma essa ordem nas listas. O chat mantém as mensagens, os perfis e a entrega offline como estavam, leva só as duas listas compartilhadas para um braid, e fala só com as pessoas que estão na lista de membros combinada.

O que essa lista não consegue fazer: um admin é escolhido quando uma solicitação é aprovada e continua admin, o membro que assenta a ordem (a pessoa que começou a conversa) não pode ser removido, e uma remoção vale no app de cada membro só quando esse app fica sabendo dela. Remover alguém não troca a chave da conversa, então não é revogação: a pessoa removida fica com a chave e com o que recebeu. Um membro removido fica com tudo o que recebeu e com a chave; qualquer app que ainda não soube da remoção continua entregando o que tem. O kolo-braid está em beta: o assentamento e a filiação dele foram verificados com model checking dentro de limites, o que não é uma prova, e ele foi testado em um Mac, só em 127.0.0.1, nunca em uma rede real.

Você escreve a lição: a função apply, em state.go, e o braid de uma conversa, em braid.go: abri-lo, com quem o chat fala, o único lugar que entrega uma conexão ao braid e as mudanças que um admin faz. Todo o resto é o encanamento que leva isso pelo app, e você o traz da tag step-7.

1Confira o que você precisa e traga os arquivos prontos

Você precisa do mesmo que no passo 6: Go 1.26 ou mais novo, Node.js, wails3, o nó de bootstrap e um pin local. Parta do projeto que você terminou no passo 6. Busque as tags:

Terminal
git fetch origin --tags

Traga a janela, os arquivos do módulo, o encanamento e os testes deste passo. Eles substituem os seus arquivos do passo 6 com o mesmo nome:

Terminal
git checkout step-7 -- frontend go.mod go.sum mux.go braidstatus.go chatservice.go conversations.go invite.go pin.go profile.go '*_test.go'
ArquivoO que faz
frontend/A janela: aprovar como membro ou como admin, Remove com a confirmação, marcas para as mudanças pendentes e as frases do chat:state.
go.mod, go.sumAdicionam o kolo-braid v0.1.0 e o que ele precisa.
mux.goDivide uma conexão entre as mensagens do chat, o kolo-sync do chat e o braid, com um byte de etiqueta no começo de cada stream.
braidstatus.goO que a janela mostra sobre as listas (chat:state), e a pausa de um membro cujo braid quebra o protocolo.
chatservice.goAbre o armazenamento do braid no início e o braid em enter, dá um mux a cada conexão, põe o ID do nosso braid no hello e consulta o conjunto aceito antes de registrar, responder, servir, ler ou mostrar alguém.
invite.goCada convite espera um admin; quem entra envia uma solicitação de entrada no braid e completa o braid com as boas-vindas que o convite leva.
profile.goOs perfis ficam no diretório kolo-kv de cada membro; as listas de salas e de membros do dono saem.
pin.goA leitura do pin pega só os autores da lista de membros.
conversations.goA organização 3, os invólucros das chamadas novas, uma entrada que falha apaga a pasta, e as verificações da pasta de dados no início.
*_test.goOs testes deste passo.

A tag também tem state.go e braid.go prontos, caso você queira comparar os seus. Até você escrevê-los, o projeto não compila.

2Uma conexão para o chat e o braid

O kolo-swarm mantém uma conexão por chave de peer, e as mensagens do chat, o servidor kolo-sync do chat e o ServeConn do braid precisam ser, cada um, o único que aceita streams nessa conexão. Por isso o mux.go faz cada stream começar com um byte de etiqueta: m para as mensagens do chat, em streams uni; s para o kolo-sync do chat, em streams bidi; e b para o braid, nos dois. Cada stream aceito ganha uma goroutine própria, que lê a etiqueta e entrega o stream à sua parte; uma etiqueta errada ou atrasada cancela só aquele stream. Cada parte parece uma conexão inteira para o kolo-sync e o kolo-braid, e o Close dela encerra só aquela parte. Cada conexão permite 64 streams de entrada por direção, então um braid ocupado nunca fica com o crédito de que o chat precisa:

mux.go
const (
	tagMsg   = 'm'
	tagSync  = 's'
	tagBraid = 'b'
	// maxStreams is the incoming streams per direction a connection allows: 16 for the braid's pulls, 16 for the
	// chat's kolo-sync streams and 32 for the uni messages of both.
	maxStreams = 64
	// maxWaiting is how many streams a braid part may hold waiting; one more is a fault, which closes the part and
	// frees its streams at once. UNSOURCED: half of maxStreams, so a stuck braid never holds the credit the chat needs.
	maxWaiting = maxStreams / 2
	codeBadTag = 3
)

Um peer do passo 6 envia streams sem etiqueta, então as duas versões não conversam.

3Escreva a função apply

O braid guarda a lista de membros sozinho. A sua função apply guarda a lista de salas. Uma entrada de dados do chat tem um formato fixo de bytes, não JSON: o byte 0 é a versão, o byte 1 a operação, o byte 2 o tamanho do nome em bytes, e depois o nome. A versão 1 tem uma operação, "adicionar uma sala". A função apply precisa dar o mesmo resultado em cada peer, então ela lê só a visão, a entrada e a lista de membros na posição da entrada, nunca um relógio nem a ordem de um mapa.

Crie state.go com:

state.go
package main

// The shared state of a conversation: the room list, kept by kolo-braid.
//
// The braid keeps the member list itself (Snapshot.Members), so the view holds only the rooms. A data entry of the chat
// is a fixed byte layout: byte 0 the version, byte 1 the op, byte 2 the name's length in bytes, then the name. Version 1
// has one op, "add a room".

import (
	"errors"
	"fmt"
	"slices"

	kolobraid "github.com/ciranda-dev/kolo-braid"
)

Adicione a state.go o nome do estado do app e a chave da lista de salas:

state.go
const (
	stateApp  = "kolochat/state/v1"
	roomV1    = 1
	opAddRoom = 1
)

var keyRooms = []byte("rooms")

As verificações seguem uma ordem fixa. Toda entrada que não é de dados devolve nil, porque a biblioteca aplica o que as entradas de filiação fazem. Um escritor que não é admin é recusado antes de a versão ser lida, então apps antigos e novos concordam nisso e um membro não consegue parar a visão de ninguém. Uma versão acima de 1 é um erro, que para este app até ele ser atualizado: o que uma versão posterior acrescentar vem depois do byte 0, então um app antigo nunca recusa uma entrada que não entende. Adicione a state.go:

state.go
// applyState keeps the view key "rooms", the sorted list of rooms admins added. It reads only the view, the entry and
// the roster at the entry's position, so every peer computes the same list.
func applyState(tx *kolobraid.Tx, e *kolobraid.Entry) error {
	if e.Kind != kolobraid.KindData {
		return nil // the library applied the membership effect
	}
	// Before the version: old and new apps agree on a non-admin's entry, so nobody can halt every view.
	if m, ok := tx.Member(e.Writer); !ok || m.Roles&kolobraid.RoleAdmin == 0 {
		return kolobraid.Reject("not an admin")
	}
	b := e.Body
	switch {
	case len(b) == 0 || b[0] == 0:
		return kolobraid.Reject("no version")
	case b[0] > roomV1: // a later version halts this app until it is updated, and is never rejected
		return fmt.Errorf("room entry of version %d", b[0])
	case len(b) < 3 || b[1] != opAddRoom || int(b[2]) != len(b)-3:
		return kolobraid.Reject("not a version 1 room entry")
	}
	name := string(b[3:])
	raw, err := tx.Get(keyRooms)
	if err != nil && !errors.Is(err, kolobraid.ErrNotFound) {
		return err
	}
	rooms, err := decodeRooms(raw)
	if err != nil {
		return err
	}
	switch {
	case validRoomName(name) != nil, sameRoom(name, defaultRoom):
		return kolobraid.Reject("bad room name")
	case slices.ContainsFunc(rooms, func(r string) bool { return sameRoom(r, name) }):
		return kolobraid.Reject("room exists")
	case len(rooms) >= maxRooms:
		return kolobraid.Reject("too many rooms")
	}
	rooms = append(rooms, name)
	slices.Sort(rooms)
	return tx.Put(keyRooms, encodeRooms(rooms))
}

A lista de salas na visão é uma lista de nomes, cada um com o tamanho na frente:

state.go
// encodeAddRoom is the body of an entry that adds the room name, which validRoomName accepts: at most 128 bytes.
func encodeAddRoom(name string) []byte {
	return append([]byte{roomV1, opAddRoom, byte(len(name))}, name...)
}

// encodeRooms writes the room list as length-prefixed names.
func encodeRooms(rooms []string) []byte {
	var out []byte
	for _, r := range rooms {
		out = append(append(out, byte(len(r))), r...)
	}
	return out
}

func decodeRooms(b []byte) ([]string, error) {
	var rooms []string
	for len(b) > 0 {
		n := int(b[0])
		if n == 0 || len(b) < 1+n {
			return nil, errors.New("damaged room list")
		}
		rooms, b = append(rooms, string(b[1:1+n])), b[1+n:]
	}
	return rooms, nil
}

// roomsOf reads the rooms admins added from a snapshot of the braid's view.
func roomsOf(s *kolobraid.Snapshot) []string {
	raw, err := s.Get(keyRooms)
	if err != nil {
		return nil
	}
	rooms, _ := decodeRooms(raw)
	return rooms
}

Duas salas têm o mesmo nome quando as letras ASCII batem sem diferenciar maiúsculas, e cada outro byte bate como está. As tabelas Unicode do Go nunca decidem o que um peer aplica:

state.go
// sameRoom compares two names with ASCII letters folded and every other byte as is: Go's Unicode tables never decide
// what a peer applies.
func sameRoom(a, b string) bool {
	if len(a) != len(b) {
		return false
	}
	for i := range len(a) {
		if lowerASCII(a[i]) != lowerASCII(b[i]) {
			return false
		}
	}
	return true
}

func lowerASCII(c byte) byte {
	if 'A' <= c && c <= 'Z' {
		return c + 'a' - 'A'
	}
	return c
}

4Abra o braid

Cada conversa tem um braid no próprio armazenamento, braid/, ao lado de store/, com o kolo-id da conversa como chave de membro. A gênese dele fixa o grupo: um só assentador, a pessoa que começa a conversa; no máximo 64 membros, o padrão do kolo-braid; e corpos de no máximo 1 KiB, o mínimo dele. O fundador cria o braid; quem entra o recebe das boas-vindas que o convite leva.

Crie braid.go com:

braid.go
package main

//lint:file-ignore ST1005 these errors are sentences the window shows as they are

// The braid of a conversation: the member list and the room list, which every member must end with alike.
//
// Each member writes its own strand, and kolo-braid merges them into one order that every peer computes the same way;
// applyState (state.go) turns that order into the room list, and the braid keeps the roster. The chat talks only to
// the keys on that roster (the accepted set): a hello that proves the conversation key and names our group starts the
// braid's sync, and only an accepted key is registered, served, pulled and shown. Removing a member is not
// revocation: it keeps the conversation key.

import (
	"cmp"
	"context"
	"encoding/hex"
	"errors"
	"log"
	"path/filepath"
	"slices"
	"strings"
	"time"

	kolobraid "github.com/ciranda-dev/kolo-braid"
	kolodht "github.com/ciranda-dev/kolo-dht"
	invite "github.com/ciranda-dev/kolo-invite"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
	kolotransport "github.com/ciranda-dev/kolo-transport"
)

Adicione os limites, o grupo e as frases que a janela mostra:

braid.go
const (
	// braidWrite bounds every braid write: kolo-braid's ConfirmWait.
	braidWrite  = 10 * time.Second
	stateTick   = time.Second
	codeRestart = 2 // closes a connection so both braids start fresh on the next one
)

// groupConfig is fixed in the genesis: one settler, the founder; 64 members, kolo-braid's default; 1 KiB bodies, its
// least.
var groupConfig = kolobraid.GroupConfig{
	App: stateApp, Quorum: kolobraid.Majority, MaxMembers: maxMembers, MinSettlers: 1, MaxSettlers: 1, MaxBody: 1024,
}

var (
	ErrNotAdmin         = errors.New("Only an admin can do that.")
	ErrFull             = errors.New("This conversation has 64 members, the most it can have.")
	ErrWaitingForMember = errors.New("Waiting for another member to come online.")
	ErrCannotWrite      = errors.New("This copy of the conversation can no longer write: ask an admin to invite you again.")
	ErrSettler          = errors.New("The member who settles changes to members and rooms cannot be removed.")
	ErrUnknownMember    = errors.New("That person is not on the member list.")
	errNoBraid          = errors.New("the shared member list of this conversation is missing")
)

Abra o braid. noBraidYet decide o que é uma pasta sem conversation.json: uma entrada que não terminou, ou a pasta de um membro que perdeu o arquivo, que é recusada:

braid.go
func braidOptions(db kolostore.Backend) kolobraid.Options {
	// MaxPullAhead is twice the least, so a settler's next pulse is always in reach.
	return kolobraid.Options{Backend: db, App: stateApp, Apply: applyState, Limits: &kolobraid.Limits{MaxPullAhead: 128}}
}

// dhtConfig gives every connection 64 incoming streams per direction: the chat and the braid share them (mux.go).
func dhtConfig() *kolodht.Config {
	return &kolodht.Config{Secure: &kolosecure.Config{Transport: &kolotransport.Config{MaxIncomingStreams: maxStreams}}}
}

func openBraidStore(dir string) (kolostore.Backend, error) {
	return kolostore.OpenPebble(filepath.Join(dir, "braid"))
}

// openBraid opens the conversation's braid, or creates it for the person who starts the conversation. A joiner has
// it from Complete already.
func (c *ChatService) openBraid(founder bool) (err error) {
	if c.braid != nil {
		return nil
	}
	c.braid, err = kolobraid.Open(c.ctx, c.id, braidOptions(c.braidDB))
	if errors.Is(err, kolobraid.ErrNotFound) {
		if !founder {
			return errNoBraid
		}
		c.braid, err = kolobraid.Create(c.ctx, c.id, groupConfig, braidOptions(c.braidDB))
	}
	return err
}

// noBraidYet refuses a folder without conversation.json that holds anything of a member: a completed braid, a copy
// of another member's log, or entries in our own logs. Such a folder lost the file, and is never taken for a join
// that did not finish.
func (c *ChatService) noBraidYet() error {
	b, err := kolobraid.Open(c.ctx, c.id, braidOptions(c.braidDB))
	if err == nil {
		b.Close()
		return &DataDirError{Dir: c.set.DataDir}
	}
	if !errors.Is(err, kolobraid.ErrNotFound) {
		return err
	}
	all, err := c.store.List()
	if err != nil {
		return err
	}
	if len(all) > 2 || c.log.Len() > 0 || c.dirLog.Len() > 0 {
		return &DataDirError{Dir: c.set.DataDir}
	}
	return nil
}

5Fale só com os membros

Um hello tem dois resultados. Ele está provado quando prova a chave da conversa e nomeia o nosso braid. Um peer está aceito quando está provado e na lista de membros da visão do braid. O conjunto aceito vive na memória e é refeito a partir de um só snapshot em cada evento do braid. Quando um peer passa a ser aceito, o chat o registra; quando ele sai da lista, o chat o descarta. Adicione a braid.go:

braid.go
// startBraid builds the accepted set before anything is pulled, and follows the braid's events.
func (c *ChatService) startBraid() {
	c.mu.Lock()
	c.group = c.braid.GroupID()
	c.pauses = map[string]*pause{}
	c.mu.Unlock()
	c.rebuild()
	c.wg.Go(c.stateLoop)
}

// stateLoop follows the braid's events and, at least every stateTick, tells the window the lists and the state. Every
// event rebuilds the accepted set from the whole roster, so an event dropped past MaxEvents changes nothing: the
// events after it rebuild.
func (c *ChatService) stateLoop() {
	for {
		ctx, cancel := context.WithTimeout(c.ctx, stateTick)
		ev, err := c.braid.Next(ctx)
		cancel()
		if c.ctx.Err() != nil || errors.Is(err, kolobraid.ErrClosed) {
			return
		}
		if err == nil {
			c.rebuild()
			switch ev.Kind {
			case kolobraid.EventHalted, kolobraid.EventDiverged, kolobraid.EventSettlementHalted, kolobraid.EventStrandLost:
				log.Printf("member list: event %d at %d", ev.Kind, ev.Position)
			}
		}
		c.publishDirectory()
		c.emitState(c.braid.Status())
	}
}

// rebuild reads the roster from one snapshot of the view into the accepted set. Proven peers that are now accepted
// are registered, get a reply hello and a sync; registered peers that are not accepted any more are dropped.
func (c *ChatService) rebuild() {
	snap := c.braid.View()
	members := snap.Members()
	snap.Close()
	accepted := make(map[string]kolobraid.Member, len(members))
	for _, m := range members {
		accepted[hex.EncodeToString(m.Key)] = m
	}
	c.mu.Lock()
	c.accepted = accepted
	var join []*link
	dropped := false
	for key, l := range c.links {
		_, ok := accepted[key]
		switch {
		case ok && !l.registered && l.hello != nil:
			join = append(join, l)
		case !ok && l.registered:
			l.registered, dropped = false, true
			log.Print("not on the member list: ", key[:8])
		}
	}
	c.mu.Unlock()
	for _, l := range join {
		c.accept(l, *l.hello, true, true)
	}
	if dropped {
		c.emitPeers()
	}
}

// isAccepted says whether author, a hex key, is on the roster of the view.
func (c *ChatService) isAccepted(author string) bool {
	c.mu.Lock()
	defer c.mu.Unlock()
	_, ok := c.accepted[author]
	return ok
}

// IsAdmin says whether we are an admin: who may invite, approve, remove members and add rooms.
func (c *ChatService) IsAdmin() bool {
	c.mu.Lock()
	defer c.mu.Unlock()
	m, ok := c.accepted[hex.EncodeToString(c.pub)]
	return ok && m.Roles&kolobraid.RoleAdmin != 0
}

O chatservice.go pronto confere o conjunto aceito em todos os caminhos do chat: antes de registrar ou responder um hello, mostrar uma mensagem, servir os nossos logs, ou ler o log de um membro do próprio membro ou do pin. É assim que ele serve os nossos logs:

chatservice.go
	if c.isAccepted(hex.EncodeToString(peer)) && owner.Equal(c.pub) && (logID == c.log.ID() || logID == c.dirLog.ID()) {

6Entregue uma conexão ao braid

Um hello provado inicia os streams bidi e a sincronização do braid, também para alguém que ainda não está na lista de membros, para que quem entra possa sincronizar a própria admissão. Um peer que não envia hello é alguém entrando com um convite, e recebe o protocolo de convite no lugar. Este é o único lugar em que uma conexão encontra o braid. Adicione a braid.go:

braid.go
// serveAfterHello serves our logs and the braid to the peer once its hello is proven: it knows the conversation key
// and names our braid. Who is not on the roster yet still gets the braid, so a joiner can sync its own admission. A
// peer that sends no hello in sendTimeout is someone who joins with an invite: one who left keeps its announcement of
// the topic for up to 20 minutes (kolo-dht's record lifetime), so the topic alone does not tell.
func (c *ChatService) serveAfterHello(l *link) {
	timer := time.NewTimer(sendTimeout)
	defer timer.Stop()
	select {
	case <-l.proven:
		c.wg.Go(l.mx.acceptBidi)
		c.wg.Go(func() { c.serveBraid(l) })
		c.srv.Serve(c.ctx, l.mx.part(tagSync))
	case <-timer.C:
		c.mu.Lock()
		if c.links[l.key] == l {
			delete(c.links, l.key)
		}
		c.mu.Unlock()
		c.inv.ServePeer(c.ctx, l.p)
	case <-c.ctx.Done():
	}
}

O braid sincroniza na parte b da conexão. Só ErrNotMember, uma chave que o braid não conhece há 60 segundos, fecha a conexão, então o swarm conecta de novo e os dois braids recomeçam do zero: alguém entrando que encontrou outro antes de a admissão dele ser ordenada, ou um membro removido. Um braid que quebra o protocolo fica pausado com aquele membro, e o chat continua:

braid.go
// serveBraid syncs the braid with one peer on the connection's 'b' part. Only ErrNotMember closes the connection; a
// braid fault pauses the braid with that member and the chat goes on.
func (c *ChatService) serveBraid(l *link) {
	conn := l.p.Conn()
	for {
		if wait := c.pausedFor(l.key); wait > 0 {
			t := time.NewTimer(wait)
			select {
			case <-t.C:
			case <-conn.Context().Done():
				t.Stop()
				return
			case <-c.ctx.Done():
				t.Stop()
				return
			}
			c.unpause(l.key)
			conn.CloseWithError(codeRestart, "kolochat: braid starts fresh")
			return
		}
		part := l.mx.part(tagBraid)
		c.served(l.key)
		err := c.braid.ServeConn(c.ctx, part)
		part.Close()
		switch {
		case errors.Is(err, kolobraid.ErrNotMember): // unknown for 60 s: a joiner tries again, a removed member redials
			conn.CloseWithError(codeRestart, "kolochat: not a member")
			return
		case errors.Is(err, kolobraid.ErrProtocol), part.overflowed.Load():
			c.braidFault(l.key)
		default:
			return
		}
	}
}

7Adicione salas, remova e aprove membros

Cada escrita no braid tem um limite de 10 segundos, o ConfirmWait do kolo-braid. Só um admin escreve. Um admin adiciona uma sala acrescentando uma entrada, e remove um membro com uma chamada ao braid. O assentador não pode ser removido:

braid.go
// writeCtx bounds a braid write.
func (c *ChatService) writeCtx() (context.Context, context.CancelFunc) {
	return context.WithTimeout(c.ctx, braidWrite)
}

// writeError turns an error of a braid write into the sentence the window shows.
func (c *ChatService) writeError(err error) error {
	switch {
	case err == nil:
		return nil
	case errors.Is(err, kolobraid.ErrUnconfirmed):
		c.mu.Lock()
		c.unconfirmed = true
		c.mu.Unlock()
		return ErrWaitingForMember
	case errors.Is(err, kolobraid.ErrStrandLost):
		return ErrCannotWrite
	case errors.Is(err, kolobraid.ErrNotAdmin), errors.Is(err, kolobraid.ErrRemoved), errors.Is(err, kolobraid.ErrNotMember):
		return ErrNotAdmin
	}
	return err
}

// AddRoom adds a room to the room list, which admins write: anyone else gets ErrNotAdmin. A bad name is
// ErrInvalidRoom, and a room that exists (ASCII letters in any case) is ErrRoomExists. Two admins who add one name at
// once end with one room.
func (c *ChatService) AddRoom(name string) error {
	name = strings.TrimSpace(name)
	if !c.isActive() {
		return ErrNotInConversation
	}
	if !c.IsAdmin() {
		return ErrNotAdmin
	}
	if err := validRoomName(name); err != nil {
		return err
	}
	rooms := c.Rooms()
	if slices.ContainsFunc(rooms, func(r string) bool { return sameRoom(r, name) }) {
		return ErrRoomExists
	}
	if len(rooms) > maxRooms {
		return ErrTooManyRooms
	}
	ctx, cancel := c.writeCtx()
	defer cancel()
	_, err := c.braid.Append(ctx, encodeAddRoom(name))
	return c.writeError(err)
}

// RemoveMember takes a member off the member list. Each member's app stops talking to it once it learns of this; the
// member keeps the conversation key, so this is not revocation. The settler cannot be removed.
func (c *ChatService) RemoveMember(key string) error {
	if !c.isActive() {
		return ErrNotInConversation
	}
	if !c.IsAdmin() {
		return ErrNotAdmin
	}
	c.mu.Lock()
	m, ok := c.accepted[key]
	c.mu.Unlock()
	switch {
	case !ok:
		return ErrUnknownMember
	case m.Seat:
		return ErrSettler
	}
	ctx, cancel := c.writeCtx()
	defer cancel()
	_, err := c.braid.RemoveMember(ctx, m.Key)
	if err == nil {
		log.Print("member removed: ", key[:8])
	}
	return c.writeError(err)
}

Agora cada convite espera um admin, porque cada pessoa que entra precisa de boas-vindas próprias do braid. Approve confere primeiro o limite de membros, depois admite quem está entrando com o papel dele, e depois responde ao convite com as boas-vindas. Se o convite não conseguir mais levá-las, quem estava entrando é removido de novo. O papel fica para sempre: o kolo-braid não tem um jeito público de mudá-lo depois:

braid.go
// Approve lets in the person behind a request, as a member or as an admin; the role stays for good. The braid gets
// its AddMember entry, and the invite carries the conversation and the braid's welcome. If the invite cannot carry it,
// the joiner is removed again. Deny refuses it. Both need an admin.
func (c *ChatService) Approve(request uint64, admin bool) error {
	if c.inv == nil {
		return errors.New("not started")
	}
	if !c.IsAdmin() {
		return ErrNotAdmin
	}
	c.mu.Lock()
	r, ok := c.requests[invite.RequestID(request)]
	full := len(c.accepted) >= maxMembers
	c.mu.Unlock()
	switch {
	case !ok:
		return ownerError(invite.ErrNotFound)
	case full:
		return ErrFull
	}
	var role kolobraid.Role
	if admin {
		role = kolobraid.RoleAdmin
	}
	ctx, cancel := c.writeCtx()
	defer cancel()
	welcome, err := c.braid.Admit(ctx, r.ev.Joiner, r.data.Request, &kolobraid.AdmitOptions{Roles: &role})
	if err != nil {
		c.answer(request, func(id invite.RequestID) error { return c.inv.Deny(id) })
		if !admitRefused(err) {
			c.braid.RemoveMember(ctx, r.ev.Joiner) // a write failed after the AddMember entry
		}
		return c.writeError(err)
	}
	payload, err := c.grantPayload(welcome)
	if err == nil {
		err = c.answer(request, func(id invite.RequestID) error { return c.inv.Approve(id, payload) })
	}
	if err != nil {
		c.braid.RemoveMember(ctx, r.ev.Joiner) // the invite ended meanwhile
		return ownerError(err)
	}
	log.Print("member admitted: ", hex.EncodeToString(r.ev.Joiner)[:8])
	return nil
}

// admitRefused says that Admit wrote nothing, so there is nothing to remove.
func admitRefused(err error) bool {
	return errors.Is(err, kolobraid.ErrActiveKey) || errors.Is(err, kolobraid.ErrKnownStrand) ||
		errors.Is(err, kolobraid.ErrInvalidArgument) || errors.Is(err, kolobraid.ErrNotAdmin) ||
		errors.Is(err, kolobraid.ErrRemoved) || errors.Is(err, kolobraid.ErrUnconfirmed)
}

8Leia as listas

A janela lê as duas listas do braid. Pending marca um membro cuja admissão ainda não foi assentada:

braid.go
// Rooms lists the rooms of the conversation: the default room, then the ones admins added, by name.
func (c *ChatService) Rooms() []string {
	rooms := []string{defaultRoom}
	if c.braid == nil {
		return rooms
	}
	snap := c.braid.View()
	defer snap.Close()
	return append(rooms, roomsOf(snap)...)
}

// Members lists the member list of the conversation with their profiles: the settler first, then the admins, then
// the others by key. Pending says the change that added it is not settled yet. A joiner whose braid has not synced
// yet lists itself.
func (c *ChatService) Members() []Member {
	if c.braid == nil {
		return []Member{} // "chat:profiles" sends it as is, and a nil slice would be null
	}
	view, settled := c.braid.View(), c.braid.Settled()
	roster, done := view.Members(), settled.Members()
	view.Close()
	settled.Close()
	me := hex.EncodeToString(c.pub)
	out := make([]Member, 0, len(roster)+1)
	for _, m := range roster {
		key := hex.EncodeToString(m.Key)
		p := c.profileOf(key)
		out = append(out, Member{Key: key, Name: p.Name, Avatar: p.Avatar, Admin: m.Roles&kolobraid.RoleAdmin != 0, Seat: m.Seat,
			Pending: !slices.ContainsFunc(done, func(d kolobraid.Member) bool { return d.Key.Equal(m.Key) })})
	}
	if !slices.ContainsFunc(out, func(m Member) bool { return m.Key == me }) {
		p := c.profileOf(me)
		out = append(out, Member{Key: me, Name: p.Name, Avatar: p.Avatar, Pending: true})
	}
	slices.SortStableFunc(out, func(a, b Member) int {
		rank := func(m Member) int {
			switch {
			case m.Seat:
				return 0
			case m.Admin:
				return 1
			}
			return 2
		}
		return cmp.Or(cmp.Compare(rank(a), rank(b)), strings.Compare(a.Key, b.Key))
	})
	return out
}

9O que a janela faz com isso

A janela mostra as frases do chat:state embaixo do chat:

frontend/src/App.jsx
          {joined ? stateBanners(conv.state).map((text) => <p key={text} className="note">{text}</p>) : null}

Uma solicitação tem dois botões de aprovar, um por papel:

frontend/src/Invite.jsx
          <button type="button" className="btn" onClick={() => answer((q) => Approve(conv, q, false), r.request)}>Approve as member</button>
          <button type="button" className="btn btn--ghost" onClick={() => answer((q) => Approve(conv, q, true), r.request)}>Approve as admin</button>

E Remove, depois de uma confirmação que diz o que remover não faz, chama RemoveMember:

frontend/src/Profile.jsx
      await RemoveMember(conv, who.key)

10Rode

Inicie o nó de bootstrap e deixe-o rodando:

Terminal
go run ./cmd/bootstrap

Em outro terminal, inicie o pin local e deixe-o rodando:

Terminal
go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin run -data .data/pin -max-bytes 100MB

Compile o app:

Terminal
GOWORK=off wails3 build

As pastas de dados do passo 6 agora são recusadas, então use pastas novas. A Alice precisa da chave pública do pin, só no terminal dela:

Terminal
export KOLO_CHAT_PIN_KEY=$(go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin id -data .data/pin)
Terminal
./bin/kolo-chat -data .data/alice-7

Na janela da Alice clique em New conversation, digite "Team" e clique em Create. Ela a funda: é admin e assenta a ordem das mudanças.

Inicie o Bob, a Carol e o Dave, cada um em um terminal próprio, sem a variável:

Terminal
./bin/kolo-chat -data .data/bob-7
Terminal
./bin/kolo-chat -data .data/carol-7
Terminal
./bin/kolo-chat -data .data/dave-7

Na janela da Alice clique em Invite e crie um convite para o Bob. Na janela do Bob clique em Join with an invite, cole o código e clique em Join. Na janela da Alice clique em "Approve as admin". Convide a Carol do mesmo jeito e clique em "Approve as member". Agora o Bob é admin: tem o botão Invite e a caixa para uma sala nova; a Carol não tem nenhum dos dois.

Agora dois admins agem no mesmo momento. Na janela da Alice e na do Bob, digite "design" na caixa para uma sala nova e aperte Enter nas duas o mais junto possível. Todas as janelas terminam com uma só sala chamada "design". Depois faça o Bob remover a Carol enquanto a Alice aprova o Dave: crie um convite na janela da Alice e comece a entrada do Dave; na janela do Bob clique em Remove ao lado da Carol e confirme; na janela da Alice clique em "Approve as member" para o Dave. Todas as janelas que ficam terminam com a mesma lista de membros: Alice, Bob e Dave.

A janela da Carol ainda tem a chave e o que ela recebeu. Ninguém avisa. Em alguns minutos, quando as conexões dela recomeçam, ninguém aceita o hello dela, e a janela dela diz que há membros online mas nenhum responde, então ela pode ter sido removida.

11Rode os testes

Os testes que você trouxe cobrem a função apply em todas as ordens de entrega, os streams com etiqueta, dois admins agindo ao mesmo tempo, um membro removido com quem ninguém fala e que não recebe chaves de entrada, um reinício que mantém as listas, o limite de membros, uma entrada que falha, arquivos especiais na pasta de dados e uma pasta do passo 6:

Terminal
GOWORK=off go test ./...

12O que a lista de membros não consegue fazer

  • Remover não é revogar. Remover um membro muda a lista combinada mas não troca a chave da conversa. O membro removido fica com a chave e com tudo o que recebeu, e ainda consegue ler o que conseguir buscar: as cópias cifradas no pin, com as chaves de qualquer app que ainda não soube da remoção. Ainda não há rotação de chaves.
  • Uma remoção chega a cada app quando ele fica sabendo. Um app que estava offline, ou que desde então não encontrou um admin nem o fundador, ainda fala com o membro removido. O membro removido não é avisado.
  • Os admins são escolhidos na aprovação. Um papel fica para sempre, e os admins têm confiança total. O fundador assenta a ordem das mudanças e não pode ser removido; enquanto o fundador está offline, as mudanças aparecem como pendentes.
  • No máximo 64 membros, sempre com aprovação. Cada solicitação espera um admin, e Approve com 64 membros é recusado.
  • O que um início apaga. Como diz a documentação do app de exemplo: "At start, a folder without conversation.json is deleted only when it is provably a join that did not finish: nothing in it but a kolo-id with its stores, own logs with no entry, no completed braid and no copy of another member's log. Any other one, such as a member's folder that lost the file, is refused with the folder to move aside, and nothing in it is deleted." Ou seja: no início, uma pasta sem conversation.json só é apagada se dá para provar que é uma entrada que não terminou; qualquer outra, como a pasta de um membro que perdeu o arquivo, é recusada indicando a pasta a tirar do caminho, e nada nela é apagado. O starter faz o mesmo, e um conversation.json que é um FIFO, um link ou um arquivo que ele não consegue ler dá uma linha com a pasta, nunca um início travado.
  • Um dispositivo. Uma lista local de conversas funciona porque um kolo-id vive em um dispositivo: usar uma conta em vários dispositivos é outro problema e não é resolvido aqui.
  • Beta. O assentamento e a filiação do kolo-braid foram verificados com model checking dentro de limites, o que não é uma prova para qualquer tamanho, e este chat foi testado em um Mac, só em 127.0.0.1, nunca em uma rede real.

Próximos passos

  • Comece na rede pública e mantenha a sua com -bootstrap: Passo 8: Usar a rede pública.
  • Leia o guia do kolo-braid na página do kolo-braid, e Construa um documento compartilhado em dois terminais, onde um braid guarda todo o estado.
  • O exemplo pronto, kolo-chat-wails3-example, adiciona a passagem do fundador antes de Leave, marcas para os membros cujas entradas foram recusadas, e chaves de entrada derivadas. O docs/shared-state.md dele conta como. O exemplo pronto mostra uma única lista de salas, uma para cada conversa, e o pin dele é opcional: sem ele, as mensagens chegam às pessoas só enquanto elas estão online.
  • Para comparar seus arquivos com os prontos, use a tag step-7 do repositório do starter.