kolo docsbeta

Construye un documento compartido en dos terminales

Una guía paso a paso. Dos personas escriben un mismo documento con kolo-braid, ven las mismas líneas en el mismo orden, descubren qué significan asentado y tentativo, y quitan a un escritor.

En esta página

En esta guía dos personas escriben juntas un documento, cada una en una ventana de terminal de tu ordenador. Cada línea que alguien escribe va firmada por quien la escribe, y las dos terminales muestran las mismas líneas en el mismo orden. Después verás qué significan "asentada" y "tentativa", reiniciarás una terminal y quitarás a un escritor.

El programa usa kolo-braid, que une los logs firmados de varios miembros en un solo orden que cada peer calcula de la misma manera. Todo se queda en tu ordenador, en la dirección 127.0.0.1. Partes del repositorio kolo-braid-starter, que también contiene el código terminado.

1Comprueba lo que necesitas

Necesitas Go 1.26 o posterior, git y dos ventanas de terminal. Construye un chat en tu terminal explica cómo instalar Go. Aquí la Terminal 1 es Ana, que crea el documento, y la Terminal 2 es Bruno, que se une a él.

2Descarga el starter

En la Terminal 1, clona el starter y entra en su carpeta:

Terminal
git clone https://github.com/ciranda-dev/kolo-braid-starter.git && cd kolo-braid-starter

main.go ya está hecho: lee las opciones, guarda tu clave en la carpeta que indicas con -dir y pasa cada línea que escribes a doc.go. doc.go solo declara lo que main.go llama. (La versión terminada está en finished/, y su main.go es el mismo archivo que este.) Crea una carpeta temporal para Ana:

bash
ANA="$(mktemp -d)"

Ejecuta el starter tal como está:

bash
go run . -dir "$ANA" -listen 127.0.0.1:7450

Imprime la clave de Ana. Escribe show y pulsa Intro:

Texto
07:05:06 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:06 type: say <text>, show, add <key>, remove <key>
07:05:07 not written yet: follow the guide

Pulsa Ctrl-C para pararlo. El siguiente paso completa doc.go.

3Escribe doc.go

Sustituye el contenido de doc.go por las cinco piezas siguientes, una detrás de otra.

La primera pieza es la regla que convierte el orden en el documento. kolo-braid llama a apply para cada entrada, en el mismo orden en cada peer. Cada línea se guarda bajo su posición, con los 4 primeros bytes de la clave de quien la escribió. Una línea vacía o de más de 500 bytes se rechaza con Reject, igual en todos los peers. apply no debe leer el reloj, sacar números aleatorios ni hacer E/S, para que todos los peers construyan el mismo documento. say también rechaza una línea así al escribirla, con el error a line is 1 to 500 bytes, de modo que nunca se escribe una línea que ningún peer mostraría.

doc.go
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...))
}

La segunda pieza abre el documento guardado en la carpeta, o crea uno nuevo (-listen), o se une a uno (-peer). La carpeta contiene una base de datos Pebble de kolo-store, así que el documento sigue ahí después de reiniciar. Imprime listening on IP:PORT cuando escucha. Close espera a las goroutines (el bucle de accept, los manejadores de conexión y follow) antes de cerrar el braid y el store.

doc.go
// 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()
}

La tercera pieza ejecuta los comandos. say añade una entrada a tu propio strand, tu kolo-log firmado. show lee dos instantáneas: View (líneas asentadas y tentativas) y Settled (solo las asentadas), y marca cada línea según dónde está. add y remove reciben una clave de 64 dígitos hexadecimales y rechazan cualquier otra cosa con a key is 64 hex digits.

doc.go
// 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")
	}
}

La cuarta pieza se ejecuta del lado de Ana. Cada conexión es una conexión kolo-secure, así que Ana conoce la clave de quien está al otro lado. Con un miembro se sincroniza con ServeConn. Una clave para la que Ana escribió add puede enviar una solicitud para unirse: Admit la añade como escritor y devuelve la bienvenida. El permiso se gasta solo después de que Admit haya funcionado, así que una conexión que no envía ninguna solicitud no lo quema y Ana no tiene que escribir add otra vez. Cualquier otra conexión se cierra.

doc.go
// 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
}

La última pieza se ejecuta del lado de Bruno. NewJoin crea su strand y su solicitud para unirse. Bruno la envía a Ana una vez por segundo hasta que ella lo deja entrar, y luego Complete abre el documento con la bienvenida de Ana. Después se queda conectado a Ana, sincroniza con ServeConn y vuelve a conectarse si ella reinicia.

doc.go
// 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):
		}
	}
}

Compara tu archivo con el terminado. Esto no imprime nada si son iguales:

Terminal
git diff --no-index doc.go finished/doc.go

4Crea el documento en la Terminal 1

En la Terminal 1, ejecuta el programa otra vez con la carpeta de Ana:

bash
go run . -dir "$ANA" -listen 127.0.0.1:7450

Ana conserva su clave y crea un documento nuevo. Tus horas y tus claves serán otras:

Texto
07:05:08 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:08 started a new document
07:05:08 type: say <text>, show, add <key>, remove <key>

5Únete desde la Terminal 2

En la Terminal 2, ve a la misma carpeta kolo-braid-starter (usa la ruta donde la clonaste):

Terminal
cd kolo-braid-starter

Crea una carpeta temporal para Bruno:

bash
BRUNO="$(mktemp -d)"

Después únete con la clave de Ana, la larga de su línea me (pega la tuya):

bash
go run . -dir "$BRUNO" -peer 127.0.0.1:7450 -key 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87

Bruno espera a Ana:

Texto
07:05:10 me 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abf
07:05:10 waiting for the owner to type add and my key

En la Terminal 1, escribe add y la clave de Bruno (pega la tuya):

Texto
add 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abf

Ana lo deja entrar:

Texto
07:05:13 3fa349c6 can join now
07:05:13 added 3fa349c6

En la Terminal 2, Bruno ya está dentro:

Texto
07:05:13 joined the document
07:05:13 type: say <text>, show, add <key>, remove <key>

6Escribid juntos

En la Terminal 1, escribe:

Texto
say Kolo meeting notes

En la Terminal 2, escribe:

Texto
say We meet on Friday at 10

Escribe show en las dos terminales. Las dos imprimen el mismo documento, en el mismo orden, con la clave corta de quien escribió cada línea:

Texto
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)

7Mira una línea tentativa

Una línea es tentativa mientras su lugar en el orden todavía puede cambiar, por ejemplo cuando otra persona escribió una línea al mismo tiempo. Está asentada cuando un settler fija su lugar, y a partir de ahí ya no se mueve. Aquí Ana es el único settler, así que una línea solo se asienta mientras Ana está conectada.

Para a Ana con Ctrl-C en la Terminal 1. En la Terminal 2, escribe say Ana brings the slides y después show:

Texto
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (tentative)

La línea nueva de Bruno está en su documento, pero su lugar aún no está fijado. En la Terminal 1, vuelve a iniciar a Ana con la misma carpeta:

bash
go run . -dir "$ANA" -listen 127.0.0.1:7450

Su clave y su documento siguen ahí, así que no crea uno nuevo:

Texto
07:05:23 me 16dbfe82b405e09e5d28706ab7ff5974d8c52c9c9f88a8f14f20ba25cb13da87
07:05:23 type: say <text>, show, add <key>, remove <key>

Bruno se vuelve a conectar en pocos segundos y le envía su línea nueva, que ella asienta. Escribe show en las dos terminales:

Texto
1. 16dbfe82: Kolo meeting notes (settled)
2. 3fa349c6: We meet on Friday at 10 (settled)
3. 3fa349c6: Ana brings the slides (settled)

8Quita a un escritor

En la Terminal 1, quita a Bruno con su clave (pega la tuya):

Texto
remove 3fa349c6c47a2177b99ebfb71af5ab9db93e411e8448e7a0ce725225469e9abf

Después, en la Terminal 1, escribe say Bruno left the project, y en la Terminal 2, escribe say Bruno writes after the removal. Espera unos segundos y escribe show en las dos terminales. El documento de Ana tiene su línea nueva, no la de Bruno:

Texto
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)

El documento de Bruno no recibe la línea nueva de Ana, y la suya sigue tentativa:

Texto
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)

Ana dejó de enviarle nada a Bruno, y toda entrada que Bruno escribe después de que lo quitaran es nula en todas partes: ningún otro miembro la muestra. De su lado sigue tentativa, porque ya nada se asienta para él. Bruno conserva las líneas que recibió antes.

9Páralo todo

Pulsa Ctrl-C en la Terminal 2 y después en la Terminal 1.

Qué acaba de pasar

  • Cada persona escribió en un strand propio: un kolo-log en el que cada entrada va firmada por quien la escribe, guardado con kolo-store.
  • kolo-braid unió los strands en un solo orden. Cada peer que tiene las mismas entradas calcula el mismo orden, byte a byte, y llama a apply en ese orden, así que los dos documentos eran iguales.
  • Ana creó el documento, así que era su admin y su único settler. Bruno entró como escritor: puede escribir, pero no añadir ni quitar a nadie.
  • Los cambios de miembros se ordenan igual que las líneas. Las líneas de Bruno anteriores a que lo quitaran conservaron su lugar; la posterior fue nula.
  • Las dos terminales se sincronizaron por una conexión kolo-secure en 127.0.0.1, con ServeConn.

Entre dos computadoras

Las dos terminales se conectan directamente: -listen abre el puerto y -peer marca esa dirección. No usan la DHT ni el swarm, así que no hay bootstrap que configurar.

  • -listen y -peer deben ser un IP:PORT IPv4 que no sea 0.0.0.0 y tenga un puerto distinto de 0. Cualquier otra cosa termina con "..." is not an IPv4 IP:PORT such as 127.0.0.1:7450.
  • En una sola computadora usa 127.0.0.1, como en los pasos anteriores.
  • En la misma red local, la Terminal 1 pasa -listen con la dirección IPv4 de su tarjeta de red, como -listen 192.168.1.20:7450, y la Terminal 2 pasa -peer 192.168.1.20:7450 con la clave.
  • Entre dos redes distintas solo funciona si la primera computadora tiene una dirección IPv4 pública a la que la segunda pueda llegar, con el puerto UDP abierto en el firewall.
  • Dos computadoras que están ambas detrás de routers domésticos no se conectarán: este programa no atraviesa el NAT y no usa relay.

Para ese caso usa los ejemplos de Kolo (chat, share, meet, board) o la biblioteca kolo-swarm, que encuentran a los pares por los nodos de entrada públicos de forma predeterminada.

Antes de construir sobre esto

  • kolo-braid está en beta y es experimental, como todas las bibliotecas de Kolo en v0.x: la API puede cambiar antes de v1.0.0.
  • Está probada con pruebas unitarias, de propiedades y fuzz, comprobaciones de modelo acotadas del asentamiento y de los miembros, que cubren solo los tamaños que enumeran y no son una prueba para cualquier tamaño, y escenarios con varios procesos en un Mac, solo en 127.0.0.1. No se ha probado en una red real ni a través de NAT.
  • Con un solo settler, el documento depende de ese dispositivo: mientras Ana está desconectada, nada se asienta. Admit sin opciones admite a un miembro simple, como hace este programa con Bruno; AdmitOptions.GrowSettlers hace que los primeros en entrar sean admins y settlers, hasta 4 puestos, y es para personas de las que te fías tanto.
  • Una línea nunca se puede borrar: cada peer guarda cada entrada, el historial nunca se recorta y cada entrada ocupa unos 600 bytes de disco en cada peer. Guarda fuera de la braid los datos que puedan necesitar borrarse.
  • El orden entre líneas escritas al mismo tiempo no es justo, y un settler puede intentar elegirlo, así que no construyas sobre él una regla de "gana el primero".
  • El asentamiento guarda una pequeña marca de ronda por settler en cada ronda, hasta que cambia la configuración de settlers. Con 4 settlers que asientan todo el día al ritmo por defecto, son hasta unos 22 MB de memoria y 55 MB de disco al día. Son lo que permite que un pulso que llega tarde obtenga su ronda exacta, y un cambio de la configuración de settlers las elimina.
  • La entrada aquí es la más pequeña que funciona: Ana deja entrar una clave que escribió, por una conexión directa. Una app real lleva la solicitud y la bienvenida con kolo-invite, como en Invita a alguien a un grupo, en un programa de terminal y en la página de kolo-braid.
  • ServeConn funciona con conexiones directas y retransmitidas. Para llegar a alguien detrás de un NAT, consulta Ejecuta tu propia infraestructura.

Qué no se probó

Todas las ejecuciones de esta guía fueron en un Mac, en 127.0.0.1. Los comandos de Windows y Linux no se ejecutaron.

Próximos pasos