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:
git fetch origin --tagsTraga 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:
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'| Arquivo | O 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.sum | Adicionam o kolo-braid v0.1.0 e o que ele precisa. |
mux.go | Divide 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.go | O que a janela mostra sobre as listas (chat:state), e a pausa de um membro cujo braid quebra o protocolo. |
chatservice.go | Abre 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.go | Cada 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.go | Os perfis ficam no diretório kolo-kv de cada membro; as listas de salas e de membros do dono saem. |
pin.go | A leitura do pin pega só os autores da lista de membros. |
conversations.go | A 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.go | Os 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:
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:
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:
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:
// 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:
// 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:
// 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:
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:
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:
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:
// 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:
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:
// 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:
// 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:
// 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:
// 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:
// 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:
{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:
<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:
await RemoveMember(conv, who.key)10Rode
Inicie o nó de bootstrap e deixe-o rodando:
go run ./cmd/bootstrapEm outro terminal, inicie o pin local e deixe-o rodando:
go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin run -data .data/pin -max-bytes 100MBCompile o app:
GOWORK=off wails3 buildAs 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:
export KOLO_CHAT_PIN_KEY=$(go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin id -data .data/pin)./bin/kolo-chat -data .data/alice-7Na 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:
./bin/kolo-chat -data .data/bob-7./bin/kolo-chat -data .data/carol-7./bin/kolo-chat -data .data/dave-7Na 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:
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.jsonis 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 semconversation.jsonsó é 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 umconversation.jsonque é 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.mddele 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-7do repositório do starter.