kolo docsbeta

Compartilhe arquivos entre dois terminais

Um tutorial passo a passo. Um terminal compartilha um arquivo com a kolo-blobs, o outro o recebe com um código de compartilhamento e verifica cada byte; depois o mesmo para uma pasta e as versões dela com a kolo-files.

Nesta página

Neste tutorial, você constrói dois programas pequenos e roda cada um em duas janelas de terminal no seu computador. O primeiro compartilha um arquivo: o Terminal 1 o guarda e imprime um código de compartilhamento, e o Terminal 2 usa o código para buscar o arquivo, verificar cada fragmento dele e salvá-lo. O segundo compartilha uma pasta inteira e mantém a cópia atualizada: cada vez que você muda a pasta e aperta Enter, o outro terminal salva a versão nova e imprime o que mudou.

O primeiro programa usa a kolo-blobs, que guarda os bytes de um arquivo. O segundo usa a kolo-files, que mantém arquivos e pastas, os nomes deles e cada versão sobre a kolo-blobs. Tudo fica no seu computador, no endereço 127.0.0.1. O código pronto está no repositório kolo-share-example.

1Confira o que você precisa

Você precisa do Go 1.26 ou mais recente e de duas janelas de terminal. Se o Go ainda não estiver instalado, instale para o seu sistema:

Baixe o instalador para macOS (o arquivo .pkg) em go.dev/dl e execute o arquivo. Se você usa o Homebrew, também dá para instalar assim:

bash
brew install go

Confira a sua versão do Go:

Terminal
go version

Você deve ver a versão 1.26 ou uma mais recente, por exemplo:

Texto
go version go1.27.3 darwin/arm64

Agora abra duas janelas de terminal e deixe uma ao lado da outra:

Abra o app Terminal e aperte Cmd+N para ter uma segunda janela.

Neste tutorial, elas se chamam Terminal 1 (o peer que compartilha) e Terminal 2 (o peer que recebe).

2Crie uma pasta e um módulo

No Terminal 1, crie uma pasta para o projeto e entre nela:

bash
mkdir kolo-share && cd kolo-share

Depois crie um módulo Go dentro dela:

Terminal
go mod init example.com/kolo-share

O Go responde:

Texto
go: creating new go.mod: module example.com/kolo-share

3Baixe as bibliotecas

Ainda no Terminal 1, adicione as bibliotecas do Kolo que os dois programas usam: a kolo-blobs e a kolo-files, para o conteúdo, a kolo-store, para guardá-lo em logs no disco, a kolo-sync, para copiar esses logs para o outro peer, a kolo-secure, para a conexão criptografada, a kolo-id, para a chave de cada peer, e a kolo-log, para os IDs dos logs.

Terminal
go get github.com/ciranda-dev/kolo-blobs@v0.1.0 github.com/ciranda-dev/kolo-files@v0.1.0 github.com/ciranda-dev/kolo-sync@v0.1.0 github.com/ciranda-dev/kolo-store@v0.1.0 github.com/ciranda-dev/kolo-secure@v0.1.0 github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-log@v0.1.0

O Go baixa as bibliotecas com o que elas precisam e imprime uma linha go: added para cada módulo que adiciona ao go.mod.

4Escreva o programa que compartilha um arquivo

Veja o que o programa faz, em cinco passos:

Todos os passos

Um arquivo, dois terminais

O código de compartilhamento é a única coisa que você passa à mão. Quem tiver o código pode ler o arquivo.

  1. file send escreve o arquivo como um blob em um log novo da kolo-store, com uma chave de arquivo nova, e imprime um código de compartilhamento.
  2. Você copia o código para o outro terminal: o endereço e a chave de quem envia, o ID do log, uma semente para a identidade de quem recebe, o ID do blob e a chave do arquivo.
  3. file get transforma a semente na sua identidade e se conecta com a kolo-secure, que verifica que o outro lado tem a chave de quem envia.
  4. A kolo-sync copia o log. Quem envia só o serve para a identidade do código, e cada entrada é verificada contra o head assinado de quem envia.
  5. A kolo-blobs abre o blob com o ID e a chave do código e verifica cada fragmento enquanto salva o arquivo. Um arquivo que falha numa verificação é apagado.

Crie uma pasta chamada file dentro de kolo-share, crie nela um arquivo chamado main.go e cole este programa. Ele tem dois comandos: send FILE guarda o arquivo e o serve, e get CODE OUT o busca com o código de compartilhamento e o salva como OUT.

file/main.go
// Command file shares one file between two peers with kolo-blobs.
//
//	file send FILE      stores FILE as a blob, prints a share code and serves the blob
//	file get CODE OUT   fetches the blob with the code, checks every chunk and saves it as OUT
package main

import (
	"bufio"
	"context"
	"crypto/ed25519"
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"encoding/binary"
	"errors"
	"flag"
	"fmt"
	"io"
	"io/fs"
	"log"
	"net/netip"
	"os"
	"os/signal"
	"path/filepath"
	"strings"
	"sync"
	"syscall"
	"time"

	koloblobs "github.com/ciranda-dev/kolo-blobs"
	koloid "github.com/ciranda-dev/kolo-id"
	kololog "github.com/ciranda-dev/kolo-log"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
	kolosync "github.com/ciranda-dev/kolo-sync"
)

const dialTimeout = 10 * time.Second

func main() {
	listen := flag.String("listen", "127.0.0.1:0", "IPv4 IP:PORT that send listens on; the share code carries it")
	maxBytes := flag.Int64("max-bytes", 1<<30, "most bytes get stores for a file")
	flag.Usage = func() {
		fmt.Fprintln(os.Stderr, "usage: file [-listen IP:PORT] send FILE\n       file [-max-bytes N] get CODE OUT   (CODE - reads the code from standard input)")
		flag.PrintDefaults()
	}
	flag.Parse()
	if *maxBytes <= 0 {
		flag.Usage()
		os.Exit(2)
	}
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)
	defer stop()
	log.SetFlags(log.Ltime)

	var err error
	switch args := flag.Args(); {
	case len(args) == 2 && args[0] == "send":
		err = send(ctx, *listen, args[1])
	case len(args) == 3 && args[0] == "get":
		err = get(ctx, args[1], args[2], *maxBytes)
	default:
		flag.Usage()
		os.Exit(2)
	}
	if err != nil && ctx.Err() == nil {
		log.Fatal(err)
	}
}

// send stores the file as a blob in a new log and serves that log to whoever holds the share code.
func send(ctx context.Context, listen, name string) error {
	addr, err := netip.ParseAddrPort(listen)
	if err != nil || !addr.Addr().Is4() || addr.Addr().IsUnspecified() {
		return fmt.Errorf("-listen needs an IPv4 address the receiver can reach, such as 127.0.0.1:0, not %q", listen)
	}
	f, err := os.Open(name)
	if err != nil {
		return err
	}
	defer f.Close()
	if info, err := f.Stat(); err != nil {
		return err
	} else if !info.Mode().IsRegular() {
		return fmt.Errorf("%s is not a regular file", name)
	}

	st, _, cleanup, err := openStore()
	if err != nil {
		return err
	}
	defer cleanup()
	me, err := koloid.Generate()
	if err != nil {
		return err
	}
	l, err := st.Create(me)
	if err != nil {
		return err
	}
	key := koloblobs.NewKey()
	sum := sha256.New()
	id, err := koloblobs.New(koloblobs.NewLogBackend(l)).Write(ctx, key, io.TeeReader(f, sum))
	if err != nil {
		return fmt.Errorf("store %s: %w", name, err)
	}
	log.Printf("stored %s as blob %s in %d log entries", name, id.String()[:16], l.Len())
	log.Printf("sha256 %x", sum.Sum(nil))

	// The receiver's identity comes from a seed in the share code, so only the code's holder gets the log.
	var seed [32]byte
	rand.Read(seed[:])
	reader, err := koloid.FromSeed(seed[:])
	if err != nil {
		return err
	}
	srv := kolosync.NewServer(func(peer, _ ed25519.PublicKey, _ kololog.LogID) kolosync.Access {
		if peer.Equal(reader.PublicKey()) {
			return kolosync.Keys
		}
		return kolosync.NoAccess
	})
	if err := srv.Offer(l); err != nil {
		return err
	}
	ln, err := kolosecure.Listen(ctx, addr.String(), me, nil)
	if err != nil {
		return err
	}
	defer ln.Close()
	if addr, err = netip.ParseAddrPort(ln.Addr().String()); err != nil { // the port the system chose
		return err
	}

	c := shareCode{addr: addr, sender: me.PublicKey(), log: l.ID(), seed: seed, blob: id, key: key}
	fmt.Printf("share code:\n%s\n", c)
	log.Print("waiting for the receiver, press Ctrl-C to stop")
	var wg sync.WaitGroup
	defer wg.Wait()
	ctx, cancel := context.WithCancel(ctx) // ends the connections below whenever send returns
	defer cancel()
	for {
		conn, err := ln.Accept(ctx)
		if err != nil {
			return err
		}
		log.Printf("peer %x connected", conn.RemotePublicKey()[:4])
		wg.Go(func() {
			defer conn.Close()
			srv.Serve(ctx, conn)
			log.Printf("peer %x left", conn.RemotePublicKey()[:4])
		})
	}
}

// get copies the sender's log, then reads the blob from it and saves it, checking every chunk on the way.
// It stops with errTooBig when the copy would hold more than maxBytes.
func get(ctx context.Context, code, out string, maxBytes int64) error {
	code, err := readCode(code)
	if err != nil {
		return err
	}
	c, err := parseCode(code)
	if err != nil {
		return err
	}
	if _, err := os.Lstat(out); err == nil {
		return fmt.Errorf("%s already exists; choose a new name", out)
	}
	me, err := koloid.FromSeed(c.seed[:])
	if err != nil {
		return err
	}
	st, dir, cleanup, err := openStore()
	if err != nil {
		return err
	}
	defer cleanup()

	dctx, cancel := context.WithTimeout(ctx, dialTimeout)
	defer cancel()
	conn, err := kolosecure.Dial(dctx, c.addr.String(), me, c.sender, nil)
	if err != nil {
		return fmt.Errorf("cannot reach the sender at %s: %w", c.addr, err)
	}
	defer conn.Close()
	header, err := kolosync.FetchHeader(ctx, conn, c.sender, c.log)
	if errors.Is(err, kolosync.ErrNotFound) {
		return fmt.Errorf("the sender does not share this file with this code: %w", err)
	} else if err != nil {
		return fmt.Errorf("ask the sender for its log: %w", err)
	}
	rep, err := st.OpenReplica(c.sender, c.log, header)
	if err != nil {
		return err
	}
	log.Print("downloading")
	lctx, stopLimit := limit(ctx, dir, maxBytes)
	defer stopLimit()
	if err := kolosync.Pull(lctx, conn, rep); err != nil {
		return fmt.Errorf("download: %w", tooBig(lctx, err))
	}
	log.Printf("received %d log entries, each checked against the sender's signed head", rep.Len())

	r, err := koloblobs.New(koloblobs.NewLogBackend(rep)).Open(ctx, c.blob, c.key)
	if err != nil {
		return explain(err)
	}
	defer r.Close()
	if r.Size() > maxBytes {
		return errTooBig
	}
	f, err := os.OpenFile(out, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600) // never replaces a file
	if err != nil {
		return err
	}
	sum := sha256.New()
	_, err = io.Copy(io.MultiWriter(f, sum), r)
	if cerr := f.Close(); err == nil {
		err = cerr
	}
	if err != nil {
		os.Remove(out) // no half-written or unverified file is left behind
		return explain(err)
	}
	log.Printf("saved %s: %d bytes, every chunk checked against the blob ID", out, r.Size())
	log.Printf("sha256 %x", sum.Sum(nil))
	return nil
}

// explain turns the errors of kolo-blobs into a sentence a user can act on.
func explain(err error) error {
	switch {
	case errors.Is(err, koloblobs.ErrWrongKey):
		return fmt.Errorf("the key in the share code does not open this file: %w", err)
	case errors.Is(err, koloblobs.ErrCorrupt):
		return fmt.Errorf("the file failed verification, nothing was saved: %w", err)
	case errors.Is(err, koloblobs.ErrNotFound):
		return fmt.Errorf("the sender's log does not hold this file: %w", err)
	}
	return err
}

// openStore opens a kolo-store in a new temporary folder, removed by the returned function.
func openStore() (*kolostore.Store, string, func(), error) {
	dir, err := os.MkdirTemp("", "kolo-share-")
	if err != nil {
		return nil, "", nil, err
	}
	db, err := kolostore.OpenPebble(dir)
	if err != nil {
		os.RemoveAll(dir)
		return nil, "", nil, err
	}
	st := kolostore.New(db)
	return st, dir, func() {
		st.Close()
		os.RemoveAll(dir)
	}, nil
}

// errTooBig ends a get that would store more than -max-bytes.
var errTooBig = errors.New("the sender offers more than -max-bytes allows; only get codes from people you trust")

// limit returns a context that ends with errTooBig once the folder dir holds more than max bytes.
func limit(ctx context.Context, dir string, max int64) (context.Context, context.CancelFunc) {
	ctx, cancel := context.WithCancelCause(ctx)
	go func() {
		for {
			select {
			case <-ctx.Done():
				return
			case <-time.After(250 * time.Millisecond):
			}
			var n int64
			filepath.WalkDir(dir, func(_ string, d fs.DirEntry, err error) error {
				if err != nil || d.IsDir() {
					return nil
				}
				if info, err := d.Info(); err == nil {
					n += info.Size()
				}
				return nil
			})
			if n > max {
				cancel(errTooBig)
				return
			}
		}
	}()
	return ctx, func() { cancel(nil) }
}

// tooBig returns errTooBig when ctx ended because of limit, and err otherwise.
func tooBig(ctx context.Context, err error) error {
	if errors.Is(context.Cause(ctx), errTooBig) {
		return errTooBig
	}
	return err
}

// readCode returns code, or the first line of standard input when code is "-", so that it stays out of ps and the shell history.
func readCode(code string) (string, error) {
	if code != "-" {
		return code, nil
	}
	line, _ := bufio.NewReader(io.LimitReader(os.Stdin, 4096)).ReadString('\n')
	if line == "" {
		return "", errors.New("no share code on standard input")
	}
	return line, nil
}

// checkAddr refuses the addresses nobody can listen on, so that a share code cannot make get send packets to them.
func checkAddr(a netip.AddrPort) bool {
	ip := a.Addr()
	return a.Port() != 0 && !ip.IsUnspecified() && !ip.IsMulticast() && ip != netip.AddrFrom4([4]byte{255, 255, 255, 255})
}

// shareCode is all the receiver needs: where the sender listens, its public key, the log holding the blob,
// the seed of the receiver's identity, and the blob's ID and key. Whoever has it can read the file.
type shareCode struct {
	addr   netip.AddrPort
	sender ed25519.PublicKey
	log    kololog.LogID
	seed   [32]byte
	blob   koloblobs.ID
	key    koloblobs.Key
}

const (
	codePrefix = "kolo-file:"
	codeSize   = 6 + 32 + kololog.LogIDSize + 32 + koloblobs.HashSize + koloblobs.KeySize
)

func (c shareCode) String() string {
	ip := c.addr.Addr().As4()
	b := binary.BigEndian.AppendUint16(ip[:], c.addr.Port())
	b = append(b, c.sender...)
	b = append(b, c.log[:]...)
	b = append(b, c.seed[:]...)
	b = append(b, c.blob[:]...)
	b = append(b, c.key[:]...)
	return codePrefix + base64.RawURLEncoding.EncodeToString(b)
}

func parseCode(s string) (shareCode, error) {
	rest, ok := strings.CutPrefix(strings.TrimSpace(s), codePrefix)
	b, err := base64.RawURLEncoding.DecodeString(rest)
	if !ok || err != nil || len(b) != codeSize {
		return shareCode{}, fmt.Errorf("this is not a file share code; copy the whole line, it starts with %q", codePrefix)
	}
	var c shareCode
	c.addr = netip.AddrPortFrom(netip.AddrFrom4([4]byte(b[:4])), binary.BigEndian.Uint16(b[4:6]))
	if !checkAddr(c.addr) {
		return shareCode{}, fmt.Errorf("the share code names %s, an address nobody can listen on", c.addr)
	}
	b = b[6:]
	c.sender = ed25519.PublicKey(b[:32])
	b = b[32:]
	b = b[copy(c.log[:], b):]
	b = b[copy(c.seed[:], b):]
	b = b[copy(c.blob[:], b):]
	copy(c.key[:], b)
	return c, nil
}

O que cada parte faz:

  • send cria uma identidade nova para esta execução com koloid.Generate e um log da kolo-store em uma pasta temporária nova (openStore), que é removida quando o programa para.
  • koloblobs.NewKey gera uma chave aleatória para este arquivo, e Write corta o arquivo em fragmentos, criptografa cada um e os acrescenta ao log como entradas. Ele retorna o ID do blob. O programa também calcula o SHA-256 do arquivo enquanto lê, com io.TeeReader, para você comparar com a cópia depois.
  • O código de compartilhamento leva tudo de que quem recebe precisa: o endereço e a chave pública de quem envia, o ID do log, o ID do blob, a chave do arquivo e uma semente aleatória. Quem recebe transforma a semente na sua identidade com koloid.FromSeed. O servidor da kolo-sync dá acesso Keys só a essa identidade, então um peer sem o código não recebe nada.
  • get se conecta com kolosecure.Dial, que verifica que o outro lado tem a chave de quem envia. kolosync.FetchHeader e OpenReplica fazem uma cópia local do log de quem envia, e kolosync.Pull a preenche, verificando cada entrada contra o head assinado de quem envia.
  • Open verifica a raiz do blob contra o ID e a chave, e io.Copy lê o arquivo fragmento por fragmento; cada fragmento é verificado contra a árvore antes que os bytes dele sejam escritos. Se algo falha, o programa remove o arquivo de saída, também quando você o interrompe, então nunca fica para trás um arquivo escrito pela metade ou não verificado. O arquivo é criado com modo 0600: só você pode lê-lo.
  • get também se protege de um código que vem de outra pessoa. Ele para com the sender offers more than -max-bytes allows; only get codes from people you trust quando o que baixa (o armazenamento temporário) ou o que escreve passa de -max-bytes, 1 GiB por padrão (por exemplo go run ./file -max-bytes 100000000 get CODE copy.jpg). Um código que nomeia 0.0.0.0, um endereço multicast, o de broadcast ou a porta 0 é recusado (the share code names ADDR, an address nobody can listen on). Um código é um endereço mais um segredo, então use só códigos de pessoas de confiança. O código pode ser lido da entrada padrão com -, para não aparecer no ps nem no histórico do shell: echo CODE | go run ./file get - copy.txt.
  • explain transforma os erros da kolo-blobs em frases: uma chave errada (ErrWrongKey), um objeto que falha numa verificação (ErrCorrupt) ou um que falta (ErrNotFound).
  • -listen é o endereço em que quem envia escuta, 127.0.0.1:0 por padrão: só o seu computador, em uma porta que o sistema escolhe. O código leva esse endereço, então ele precisa ser um endereço IPv4 que quem recebe consiga alcançar.

5Crie um arquivo para compartilhar

No Terminal 1, na pasta kolo-share, crie um arquivo de texto pequeno:

bash
echo "hello from terminal 1" > hello.txt

Qualquer arquivo serve: uma foto, um vídeo, um arquivo compactado. Um arquivo de qualquer tamanho é guardado em tantos fragmentos quantos precisar.

6Compartilhe pelo Terminal 1

No Terminal 1, rode:

Terminal
go run ./file send hello.txt

Na primeira vez, ele leva um momento para compilar. Depois ele guarda o arquivo, imprime o SHA-256 dele e o código de compartilhamento, e fica esperando. Os seus horários, IDs, hash e código vão ser diferentes:

Texto
21:06:38 stored hello.txt as blob a9d85e576f8d1489 in 2 log entries
21:06:38 sha256 2b3bbe311b98a8d367296b62fcb806cb076ccddb893f9f02dbd0c327c98e2385
share code:
kolo-file:fwAAAfOct7bUTbr73o5USjYMV_QoCysEQPbcwAuLL6DkJGdBSUQglI3Xz74siUO8VhQOnKqBB_BVw5FKd-VlHrXEjaeUYdYkEK2038sz_yilgROh560Mz7emkvCv0wzsYlDWEg5KqdheV2-NFImL7UW_f-0M4Q-5I9a4D2Tiy1BSEnQPJUFePQEC6hq_trv_ybEglewb2IyH6o9exzlkNklfTSSOAw
21:06:38 waiting for the receiver, press Ctrl-C to stop

Um arquivo pequeno ocupa 2 entradas do log: um fragmento e a raiz da árvore dele. Selecione a linha inteira que começa com kolo-file: e copie. Deixe o Terminal 1 rodando.

7Receba pelo Terminal 2

No Terminal 2, vá para a mesma pasta kolo-share (use o caminho onde você a criou):

Terminal
cd kolo-share

Depois rode get com o código que você copiou, entre aspas simples, e um nome para a cópia:

Terminal
go run ./file get '<share code>' copy.txt

Troque <share code> pelo código inteiro, incluindo kolo-file:. O Terminal 2 imprime:

Texto
21:06:38 downloading
21:06:38 received 2 log entries, each checked against the sender's signed head
21:06:38 saved copy.txt: 22 bytes, every chunk checked against the blob ID
21:06:38 sha256 2b3bbe311b98a8d367296b62fcb806cb076ccddb893f9f02dbd0c327c98e2385

E o Terminal 1 mostra quem recebe chegar e sair, com o nome da chave dele:

Texto
21:06:38 peer db309a79 connected
21:06:38 peer db309a79 left

8Confira que a cópia é igual

O programa já verificou cada fragmento contra o ID do blob, e as duas linhas sha256, uma em cada terminal, são iguais. Você também pode pedir ao seu sistema o SHA-256 dos dois arquivos, no Terminal 2:

bash
shasum -a 256 hello.txt copy.txt

As duas linhas trazem o mesmo hash:

Texto
2b3bbe311b98a8d367296b62fcb806cb076ccddb893f9f02dbd0c327c98e2385  hello.txt
2b3bbe311b98a8d367296b62fcb806cb076ccddb893f9f02dbd0c327c98e2385  copy.txt

No Windows, Get-FileHash imprime uma tabela com o hash em maiúsculas. Lá, Set-Content também termina a linha com dois caracteres, então o arquivo tem 23 bytes e outro hash; mesmo assim, os dois arquivos são iguais entre si.

9Veja o que acontece quando algo dá errado

Rode get de novo com o mesmo nome. Ele nunca substitui um arquivo, e remove o arquivo parcial quando falha ou é interrompido:

Terminal
go run ./file get '<share code>' copy.txt
Texto
21:06:39 copy.txt already exists; choose a new name
exit status 1

A última linha vem do go run: o programa saiu com um erro. Agora passe para ele algo que não é um código:

Terminal
go run ./file get 'kolo-file:abc' other.txt
Texto
21:06:39 this is not a file share code; copy the whole line, it starts with "kolo-file:"
exit status 1

Aperte Ctrl-C no Terminal 1 para encerrar quem envia e rode get mais uma vez com o código verdadeiro e um nome novo, no Terminal 2:

Terminal
go run ./file get '<share code>' late.txt

Depois de alguns segundos:

Texto
21:06:53 cannot reach the sender at 127.0.0.1:62364: kolotransport: timeout
exit status 1

late.txt não é criado. Um código com a chave alterada falha com the key in the share code does not open this file, e um código com a semente alterada, com the sender does not share this file with this code: os testes do repositório verificam os dois casos.

10Escreva o programa que compartilha uma pasta

O segundo programa compartilha uma pasta com a kolo-files. A pasta vira um volume: um log de metadados com uma op por mudança e um log de conteúdo que guarda o conteúdo de cada arquivo como um blob da kolo-blobs. Cada op é uma versão nova.

Todos os passos

Uma pasta e suas versões

Quem recebe salva cada versão numa pasta própria, então as versões anteriores ficam como estavam.

  1. folder send coloca cada arquivo e cada pasta em um volume novo da kolo-files e imprime um código de compartilhamento. O código não leva nenhuma chave de arquivo: as chaves viajam dentro do log de metadados.
  2. Você copia o código para o outro terminal: o endereço e a chave de quem envia, o ID do log de metadados e uma semente para a identidade de quem recebe.
  3. folder get copia o log de metadados, acha o log de conteúdo na primeira entrada e o copia também, depois salva o volume com os.CopyFS em OUT/v e o número da versão, como OUT/v5.
  4. Aperte Enter no Terminal 1: arquivos e pastas novos viram ops CREATE e MKDIR, arquivos alterados viram ops WRITE e os apagados, ops REMOVE e PURGE. Cada op é uma versão nova.
  5. A cada 2 segundos quem recebe copia só as entradas novas, atualiza o volume, imprime o Diff entre a versão salva e a nova, e salva a nova.

Crie uma pasta chamada folder dentro de kolo-share, crie main.go nela e cole este programa:

folder/main.go
// Command folder shares a folder between two peers with kolo-files and keeps the copy up to date.
//
//	folder send DIR    puts DIR in a volume, prints a share code and publishes changes each time you press Enter
//	folder get CODE OUT   saves the folder into OUT/v<version>, then each new version the sender publishes
package main

import (
	"bufio"
	"context"
	"crypto/ed25519"
	"crypto/rand"
	"encoding/base64"
	"encoding/binary"
	"errors"
	"flag"
	"fmt"
	"io"
	"io/fs"
	"log"
	"net/netip"
	"os"
	"os/signal"
	"path/filepath"
	"strings"
	"sync"
	"syscall"
	"time"

	koloblobs "github.com/ciranda-dev/kolo-blobs"
	kolofiles "github.com/ciranda-dev/kolo-files"
	koloid "github.com/ciranda-dev/kolo-id"
	kololog "github.com/ciranda-dev/kolo-log"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
	kolosync "github.com/ciranda-dev/kolo-sync"
)

const dialTimeout = 10 * time.Second

func main() {
	listen := flag.String("listen", "127.0.0.1:0", "IPv4 IP:PORT that send listens on; the share code carries it")
	every := flag.Duration("every", 2*time.Second, "how often get asks the sender for a new version")
	maxBytes := flag.Int64("max-bytes", 1<<30, "most bytes get stores, and writes into OUT in all")
	flag.Usage = func() {
		fmt.Fprintln(os.Stderr, "usage: folder [-listen IP:PORT] send DIR\n       folder [-every 2s] [-max-bytes N] get CODE OUT   (CODE - reads the code from standard input)")
		flag.PrintDefaults()
	}
	flag.Parse()
	if *every <= 0 || *maxBytes <= 0 {
		flag.Usage()
		os.Exit(2)
	}
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)
	defer stop()
	log.SetFlags(log.Ltime)

	var err error
	switch args := flag.Args(); {
	case len(args) == 2 && args[0] == "send":
		err = send(ctx, *listen, args[1])
	case len(args) == 3 && args[0] == "get":
		err = get(ctx, args[1], args[2], *every, *maxBytes)
	default:
		flag.Usage()
		os.Exit(2)
	}
	if err != nil && ctx.Err() == nil {
		log.Fatal(err)
	}
}

// send keeps dir in a volume, serves its two logs to whoever holds the share code and adds a version on Enter.
func send(ctx context.Context, listen, dir string) error {
	addr, err := netip.ParseAddrPort(listen)
	if err != nil || !addr.Addr().Is4() || addr.Addr().IsUnspecified() {
		return fmt.Errorf("-listen needs an IPv4 address the receiver can reach, such as 127.0.0.1:0, not %q", listen)
	}
	if info, err := os.Lstat(dir); err != nil {
		return err
	} else if !info.IsDir() {
		return fmt.Errorf("%s is not a folder", dir)
	}
	st, _, cleanup, err := openStore()
	if err != nil {
		return err
	}
	defer cleanup()
	me, err := koloid.Generate()
	if err != nil {
		return err
	}
	meta, err := st.Create(me)
	if err != nil {
		return err
	}
	content, err := st.Create(me)
	if err != nil {
		return err
	}
	v, err := kolofiles.Create(meta, content)
	if err != nil {
		return err
	}
	defer v.Close()
	seen := map[string]stamp{}
	if err := update(ctx, v, dir, seen); err != nil {
		return err
	}
	log.Printf("version %d holds %s", v.Len(), dir)

	var seed [32]byte
	rand.Read(seed[:])
	reader, err := koloid.FromSeed(seed[:])
	if err != nil {
		return err
	}
	srv := kolosync.NewServer(func(peer, _ ed25519.PublicKey, _ kololog.LogID) kolosync.Access {
		if peer.Equal(reader.PublicKey()) {
			return kolosync.Keys
		}
		return kolosync.NoAccess
	})
	for _, l := range []*kolostore.Log{meta, content} {
		if err := srv.Offer(l); err != nil {
			return err
		}
	}
	ln, err := kolosecure.Listen(ctx, addr.String(), me, nil)
	if err != nil {
		return err
	}
	defer ln.Close()
	if addr, err = netip.ParseAddrPort(ln.Addr().String()); err != nil { // the port the system chose
		return err
	}

	c := shareCode{addr: addr, sender: me.PublicKey(), meta: v.ID(), seed: seed}
	fmt.Printf("share code:\n%s\n", c)
	log.Print("change files in the folder, then press Enter to publish them; Ctrl-C stops")
	var wg sync.WaitGroup
	defer wg.Wait()
	ctx, cancel := context.WithCancel(ctx) // ends the goroutines below whenever send returns
	defer cancel()
	wg.Go(func() {
		for {
			conn, err := ln.Accept(ctx)
			if err != nil {
				return
			}
			log.Printf("peer %x connected", conn.RemotePublicKey()[:4])
			wg.Go(func() {
				defer conn.Close()
				srv.Serve(ctx, conn)
				log.Printf("peer %x left", conn.RemotePublicKey()[:4])
			})
		}
	})
	enter := make(chan struct{})
	go func() {
		sc := bufio.NewScanner(os.Stdin)
		for sc.Scan() {
			enter <- struct{}{}
		}
	}()
	for {
		select {
		case <-ctx.Done():
			return nil
		case <-enter:
			before := v.Len()
			if err := update(ctx, v, dir, seen); err != nil {
				return err
			}
			if v.Len() == before {
				log.Print("nothing changed")
			} else {
				log.Printf("published version %d", v.Len())
			}
		}
	}
}

// stamp is what update compares to find a changed file: its size and modification time.
type stamp struct {
	dir  bool
	size int64
	mod  time.Time
}

// update makes the volume match dir: it adds new folders and files, writes changed files and deletes what is gone.
// seen holds the stamps of the last update and is brought up to date.
func update(ctx context.Context, v *kolofiles.Volume, dir string, seen map[string]stamp) error {
	now := map[string]stamp{}
	err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error {
		if errors.Is(err, fs.ErrNotExist) && p != dir {
			return nil // removed while we walked: the next update sees it gone
		}
		if err != nil || p == dir {
			return err
		}
		if !d.IsDir() && !d.Type().IsRegular() {
			return nil // links and devices are not shared
		}
		rel, err := filepath.Rel(dir, p)
		if err != nil {
			return err
		}
		name := filepath.ToSlash(rel)
		info, err := d.Info()
		if errors.Is(err, fs.ErrNotExist) {
			return nil
		} else if err != nil {
			return err
		}
		s := stamp{dir: true}
		if !d.IsDir() {
			s = stamp{size: info.Size(), mod: info.ModTime()}
		}
		old, ok := seen[name]
		if ok && old.dir != s.dir { // a file became a folder or the other way round
			if err := v.Delete(name); err != nil {
				return err
			}
			ok = false
		}
		switch {
		case ok && (s.dir || old == s):
		case s.dir:
			err = v.Mkdir(name)
		default:
			var f *os.File
			if f, err = os.Open(p); err == nil {
				err = v.WriteFile(ctx, name, f)
				f.Close()
			}
		}
		if err != nil {
			log.Printf("skipped %s: %v", name, err)
			if ok {
				now[name] = old // keep the published version; the next update tries again
			}
			if s.dir {
				return fs.SkipDir
			}
			return nil
		}
		now[name] = s
		return nil
	})
	if err != nil {
		return err
	}
	for name := range seen {
		if _, ok := now[name]; !ok {
			// A folder's delete takes everything below it, so a later delete of a child finds nothing,
			// or finds a file where its folder was.
			if err := v.Delete(name); err != nil && !errors.Is(err, fs.ErrNotExist) && !errors.Is(err, kolofiles.ErrNotDir) {
				return err
			}
		}
	}
	clear(seen)
	for name, s := range now {
		seen[name] = s
	}
	return nil
}

// get copies the sender's two logs, saves the folder, then pulls again every few seconds and saves each new version.
// It stops with errTooBig when the copy, or all the versions saved in out together, would hold more than maxBytes.
func get(ctx context.Context, code, out string, every time.Duration, maxBytes int64) error {
	code, err := readCode(code)
	if err != nil {
		return err
	}
	c, err := parseCode(code)
	if err != nil {
		return err
	}
	if _, err := os.Lstat(out); err == nil {
		return fmt.Errorf("%s already exists; choose a new name", out)
	}
	me, err := koloid.FromSeed(c.seed[:])
	if err != nil {
		return err
	}
	st, dir, cleanup, err := openStore()
	if err != nil {
		return err
	}
	defer cleanup()
	dctx, cancel := context.WithTimeout(ctx, dialTimeout)
	defer cancel()
	conn, err := kolosecure.Dial(dctx, c.addr.String(), me, c.sender, nil)
	if err != nil {
		return fmt.Errorf("cannot reach the sender at %s: %w", c.addr, err)
	}
	defer conn.Close()

	lctx, stopLimit := limit(ctx, dir, maxBytes)
	defer stopLimit()
	meta, err := replica(lctx, st, conn, c.sender, c.meta)
	if err != nil {
		return err
	}
	contentID, err := kolofiles.ContentLog(meta)
	if err != nil {
		return err
	}
	content, err := replica(lctx, st, conn, c.sender, contentID)
	if err != nil {
		return err
	}
	v, err := kolofiles.OpenReader(meta, koloblobs.NewLogBackend(content), nil)
	if err != nil {
		return err
	}
	defer v.Close()

	if err := os.MkdirAll(out, 0o700); err != nil { // the folders inside are private too
		return err
	}
	var saved uint64
	var written int64
	defer func() {
		if saved == 0 {
			os.Remove(out) // leaves nothing behind when no version was saved
		}
	}()
	for {
		if n := v.Len(); n > saved {
			if saved > 0 {
				changes, err := v.Diff(saved, n)
				if err != nil {
					return err
				}
				printChanges(changes)
			}
			size, err := treeSize(v)
			if err != nil {
				return err
			}
			if written += size; written > maxBytes {
				return errTooBig
			}
			dst := filepath.Join(out, fmt.Sprintf("v%d", n))
			if err := os.CopyFS(dst, v); err != nil {
				os.RemoveAll(dst) // no half-saved version is left behind
				return fmt.Errorf("save version %d: %w", n, err)
			}
			log.Printf("saved version %d in %s, every file checked against its blob ID", n, dst)
			saved = n
		}
		select {
		case <-ctx.Done():
			return nil
		case <-time.After(every):
		}
		// The metadata first: content pulled after it holds every object its ops name.
		if err := kolosync.Pull(lctx, conn, meta); err != nil {
			return fmt.Errorf("lost the sender: %w", tooBig(lctx, err))
		}
		if err := kolosync.Pull(lctx, conn, content); err != nil {
			return fmt.Errorf("lost the sender: %w", tooBig(lctx, err))
		}
		if err := v.Refresh(); err != nil {
			return err
		}
	}
}

// treeSize adds up the sizes of the files in fsys.
func treeSize(fsys fs.FS) (n int64, err error) {
	err = fs.WalkDir(fsys, ".", func(_ string, d fs.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			return err
		}
		info, err := d.Info()
		if err == nil {
			n += info.Size()
		}
		return err
	})
	return n, err
}

// replica opens a local replica of the sender's log logID and pulls it.
func replica(ctx context.Context, st *kolostore.Store, conn *kolosecure.Conn, owner ed25519.PublicKey, logID kololog.LogID) (*kolostore.Replica, error) {
	header, err := kolosync.FetchHeader(ctx, conn, owner, logID)
	if errors.Is(err, kolosync.ErrNotFound) {
		return nil, fmt.Errorf("the sender does not share this folder with this code: %w", err)
	} else if err != nil {
		return nil, fmt.Errorf("ask the sender for its log: %w", err)
	}
	rep, err := st.OpenReplica(owner, logID, header)
	if err != nil {
		return nil, err
	}
	if err := kolosync.Pull(ctx, conn, rep); err != nil {
		return nil, fmt.Errorf("download: %w", err)
	}
	return rep, nil
}

// printChanges prints what Diff found between two versions.
func printChanges(changes []kolofiles.Change) {
	for _, c := range changes {
		switch {
		case c.Deleted:
			log.Print("  deleted a file or folder (its names are gone with it)")
		case c.Old == "":
			log.Printf("  added %s", c.New)
		case c.Old != c.New && c.Modified:
			log.Printf("  moved %s to %s and changed it", c.Old, c.New)
		case c.Old != c.New:
			log.Printf("  moved %s to %s", c.Old, c.New)
		default:
			log.Printf("  changed %s", c.New)
		}
	}
}

// openStore opens a kolo-store in a new temporary folder, removed by the returned function.
func openStore() (*kolostore.Store, string, func(), error) {
	dir, err := os.MkdirTemp("", "kolo-share-")
	if err != nil {
		return nil, "", nil, err
	}
	db, err := kolostore.OpenPebble(dir)
	if err != nil {
		os.RemoveAll(dir)
		return nil, "", nil, err
	}
	st := kolostore.New(db)
	return st, dir, func() {
		st.Close()
		os.RemoveAll(dir)
	}, nil
}

// errTooBig ends a get that would store more than -max-bytes.
var errTooBig = errors.New("the sender offers more than -max-bytes allows; only get codes from people you trust")

// limit returns a context that ends with errTooBig once the folder dir holds more than max bytes.
func limit(ctx context.Context, dir string, max int64) (context.Context, context.CancelFunc) {
	ctx, cancel := context.WithCancelCause(ctx)
	go func() {
		for {
			select {
			case <-ctx.Done():
				return
			case <-time.After(250 * time.Millisecond):
			}
			var n int64
			filepath.WalkDir(dir, func(_ string, d fs.DirEntry, err error) error {
				if err != nil || d.IsDir() {
					return nil
				}
				if info, err := d.Info(); err == nil {
					n += info.Size()
				}
				return nil
			})
			if n > max {
				cancel(errTooBig)
				return
			}
		}
	}()
	return ctx, func() { cancel(nil) }
}

// tooBig returns errTooBig when ctx ended because of limit, and err otherwise.
func tooBig(ctx context.Context, err error) error {
	if errors.Is(context.Cause(ctx), errTooBig) {
		return errTooBig
	}
	return err
}

// readCode returns code, or the first line of standard input when code is "-", so that it stays out of ps and the shell history.
func readCode(code string) (string, error) {
	if code != "-" {
		return code, nil
	}
	line, _ := bufio.NewReader(io.LimitReader(os.Stdin, 4096)).ReadString('\n')
	if line == "" {
		return "", errors.New("no share code on standard input")
	}
	return line, nil
}

// checkAddr refuses the addresses nobody can listen on, so that a share code cannot make get send packets to them.
func checkAddr(a netip.AddrPort) bool {
	ip := a.Addr()
	return a.Port() != 0 && !ip.IsUnspecified() && !ip.IsMulticast() && ip != netip.AddrFrom4([4]byte{255, 255, 255, 255})
}

// shareCode is all the receiver needs: where the sender listens, its public key, the volume's metadata log and
// the seed of the receiver's identity. The file keys travel inside the metadata log. Whoever has it can read the folder.
type shareCode struct {
	addr   netip.AddrPort
	sender ed25519.PublicKey
	meta   kololog.LogID
	seed   [32]byte
}

const (
	codePrefix = "kolo-folder:"
	codeSize   = 6 + 32 + kololog.LogIDSize + 32
)

func (c shareCode) String() string {
	ip := c.addr.Addr().As4()
	b := binary.BigEndian.AppendUint16(ip[:], c.addr.Port())
	b = append(b, c.sender...)
	b = append(b, c.meta[:]...)
	b = append(b, c.seed[:]...)
	return codePrefix + base64.RawURLEncoding.EncodeToString(b)
}

func parseCode(s string) (shareCode, error) {
	rest, ok := strings.CutPrefix(strings.TrimSpace(s), codePrefix)
	b, err := base64.RawURLEncoding.DecodeString(rest)
	if !ok || err != nil || len(b) != codeSize {
		return shareCode{}, fmt.Errorf("this is not a folder share code; copy the whole line, it starts with %q", codePrefix)
	}
	var c shareCode
	c.addr = netip.AddrPortFrom(netip.AddrFrom4([4]byte(b[:4])), binary.BigEndian.Uint16(b[4:6]))
	if !checkAddr(c.addr) {
		return shareCode{}, fmt.Errorf("the share code names %s, an address nobody can listen on", c.addr)
	}
	b = b[6:]
	c.sender = ed25519.PublicKey(b[:32])
	b = b[32:]
	b = b[copy(c.meta[:], b):]
	copy(c.seed[:], b)
	return c, nil
}

O que há de novo em relação ao primeiro programa:

  • send cria dois logs, e kolofiles.Create faz um volume com eles. update percorre a pasta: chama Mkdir para cada pasta nova, WriteFile para cada arquivo novo ou alterado e Delete para o que sumiu. Um arquivo conta como alterado quando o tamanho ou a hora de modificação dele difere da passada anterior, porque WriteFile sempre acrescenta uma versão, mesmo para o mesmo conteúdo.
  • Cada vez que você aperta Enter, update roda de novo e quem envia imprime a versão nova, ou nothing changed.
  • O código de compartilhamento é mais curto: ele só nomeia o log de metadados. As chaves dos arquivos estão dentro desse log, criptografadas pela kolo-log, e viajam com ele.
  • get faz pull do log de metadados, acha o log de conteúdo com kolofiles.ContentLog e faz pull dele também, depois abre o volume com OpenReader. Um Volume é um sistema de arquivos io/fs, então os.CopyFS o salva no disco, e cada arquivo que ele lê é verificado contra o ID do blob dele. Como o primeiro programa, ele recusa um OUT que já existe e apaga uma versão que não conseguiu salvar inteira. OUT e as pastas dentro dele são criados com modo 0700, então só você pode lê-los.
  • get para com the sender offers more than -max-bytes allows; only get codes from people you trust quando o que baixa, ou todas as versões que escreveu em OUT juntas, passam de -max-bytes (1 GiB por padrão; cada versão é uma cópia completa). O código pode ser lido da entrada padrão com -, e um código que nomeia um endereço em que ninguém pode escutar é recusado, como no primeiro programa.
  • A cada 2 segundos (-every), get faz pull dos dois logs de novo, os metadados primeiro, e chama Refresh. Quando a versão aumentou, Diff lista o que mudou e a versão nova é salva numa pasta própria, ao lado das anteriores.
  • Este programa compara caminhos, então um arquivo renomeado chega a quem recebe como uma exclusão e uma adição. A kolo-files tem Move, que mantém o nó do arquivo e o histórico dele; um app que sabe que um arquivo foi renomeado chama Move.

11Compartilhe uma pasta e altere-a

No Terminal 1, crie uma pasta com alguns arquivos:

bash
mkdir -p shared/notes && echo "buy bread" > shared/todo.txt && echo "first draft" > shared/notes/ideas.txt && cp hello.txt shared/

Compartilhe a pasta:

Terminal
go run ./folder send shared
Texto
21:07:02 version 5 holds shared
share code:
kolo-folder:fwAAAdrwpr17aqfOwmDq_IOx4WKK4QJkgD3tpVO6DthM9tPXLrBvR-B9CcWI5GObQ0v95GHhjronYzB1xx6FQDd5z9F-VhVeZaSEJgNRBoAf-ur59bcaY70ePv58tCTZpJtRxOdI
21:07:02 change files in the folder, then press Enter to publish them; Ctrl-C stops

A versão 5 é o volume vazio mais quatro ops: os arquivos hello.txt, todo.txt e notes/ideas.txt, e a pasta notes. No Terminal 2, receba a pasta em uma pasta chamada copy:

Terminal
go run ./folder get '<share code>' copy
Texto
21:07:02 saved version 5 in copy/v5, every file checked against its blob ID

Deixe os dois rodando. Abra uma terceira janela de terminal na pasta kolo-share, ou use o seu gerenciador de arquivos, e mude a pasta compartilhada: edite um arquivo, adicione um e apague um.

bash
echo "buy bread and milk" > shared/todo.txt && echo "plans for the weekend" > shared/plans.txt && rm shared/hello.txt

Depois aperte Enter no Terminal 1:

Texto
21:07:06 published version 9

Quatro ops desta vez: um WRITE para todo.txt, um CREATE para plans.txt, e um REMOVE e um PURGE para o arquivo apagado. Em até 2 segundos, o Terminal 2 imprime o que mudou e salva a versão nova:

Texto
21:07:06   deleted a file or folder (its names are gone with it)
21:07:06   added plans.txt
21:07:06   changed todo.txt
21:07:06 saved version 9 in copy/v9, every file checked against its blob ID

copy/v5 ainda guarda a primeira versão, com todo.txt dizendo buy bread, e copy/v9 guarda a pasta como ela está agora. Um arquivo apagado não mostra nenhum nome no diff: os nomes, a chave e o conteúdo dele são destruídos junto com ele. Aperte Enter de novo no Terminal 1 sem mudar nada, e ele imprime nothing changed.

12Pare tudo

Aperte Ctrl-C no Terminal 1. Quem envia termina e remove o armazenamento temporário dele. O Terminal 2 percebe no próximo pull e também termina, mantendo o que salvou:

Texto
21:07:18 lost the sender: kolosync: timeout: opening a stream
exit status 1

Entre dois computadores

Os dois programas se conectam diretamente: o código de compartilhamento leva o endereço IPv4 e a porta do emissor, e o receptor disca para ele. Eles não usam a DHT nem o swarm, então não há bootstrap para configurar.

  • Em um único computador funciona do jeito que está: -listen vale 127.0.0.1:0 por padrão.
  • Na mesma rede local, o emissor passa -listen antes de send, com o endereço IPv4 da sua placa de rede e uma porta, como -listen 192.168.1.20:7450, e o receptor chega até ele com o código. O endereço deve ser IPv4 e não 0.0.0.0; senão send para com -listen needs an IPv4 address the receiver can reach.
  • Entre duas redes diferentes só funciona se o emissor tem um endereço IPv4 público que o receptor 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: esses programas não atravessam o NAT e não usam 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.

Um arquivo ou uma pasta

Aspectofile (kolo-blobs)folder (kolo-files)
O que é compartilhadoos bytes de um arquivouma árvore de arquivos e pastas, com os nomes deles
O que o código levao ID do blob e a chave do arquivoo ID do log de metadados; as chaves dos arquivos viajam dentro desse log
Uma mudançaum arquivo novo é um blob novo e um código novocada mudança é uma versão nova do mesmo volume
Históriconenhumtoda versão continua legível, com Snapshot e Diff
Logs copiadosumdois: metadados, depois conteúdo

Use só a kolo-blobs quando o seu app já conhece os arquivos dele e só precisa guardar, enviar e verificar bytes, como um anexo ou um download. Use a kolo-files quando as pessoas compartilham uma pasta que muda, precisam de nomes e pastas ou querem voltar a uma versão anterior.

O que acabou de acontecer

Todos os passos

Arquivos sobre blobs

A kolo-files decide nomes, pastas e versões. A kolo-blobs guarda e verifica os bytes de cada versão.

  1. Um volume são dois logs da kolo-store de um mesmo dono: o log de metadados, uma op por mudança, e o log de conteúdo, que guarda objetos da kolo-blobs. A entrada 0 do log de metadados nomeia o log de conteúdo.
  2. WriteFile entrega os bytes do arquivo à kolo-blobs com a chave própria do arquivo. Seus fragmentos e sua raiz viram entradas do log de conteúdo, e o hash da raiz é o ID do blob.
  3. Ele também escreve uma tabela de objetos, um segundo blob com a mesma chave, que lista a entrada do log de conteúdo de cada objeto, para um leitor achá-los sem percorrer o log.
  4. A op CREATE guarda o nome, a chave do arquivo e a versão: o ID do blob, o ID da tabela e onde estão os objetos da própria tabela. A kolo-log criptografa cada op.
  5. Uma versão nova é uma op WRITE com um blob e uma tabela novos. A chave continua a mesma, então os fragmentos sem mudança não são guardados de novo.
  • A kolo-blobs cortou cada arquivo em fragmentos, criptografou cada fragmento com chaves derivadas da chave do arquivo e nomeou o arquivo pelo hash da raiz da árvore dele: o ID do blob. Veja a kolo-blobs.
  • Os fragmentos e a raiz eram entradas de um log da kolo-store. A kolo-sync copiou esse log para quem recebe, verificando cada entrada contra o head assinado do dono. Veja Logs e Réplicas.
  • Depois, quem recebe verificou cada fragmento contra o ID do blob enquanto lia, então um byte errado teria parado a leitura em vez de chegar ao seu disco.
  • Para a pasta, a kolo-files guardou uma op por mudança em um log de metadados e cada versão de arquivo como um blob em um log de conteúdo, com uma chave por arquivo. Uma versão é o tamanho do log de metadados, então quem recebe pôde salvar cada versão e comparar duas com Diff. Veja a kolo-files.
  • A conexão foi um canal da kolo-secure ligado à chave de quem envia, e o código de compartilhamento foi a única coisa passada à mão.

Próximos passos

  • Compare os seus arquivos com o código pronto no repositório kolo-share-example. Os testes dele rodam os dois programas em 127.0.0.1 e verificam cada erro mostrado aqui.
  • Leia a página da kolo-blobs: leituras de intervalos, os formatos, os limites e como ler um blob de um peer de fixação.
  • Leia a página da kolo-files: nomes, versões, sincronização seletiva e como Delete destrói um arquivo.
  • Os logs dos dois programas também podem ficar em um peer de fixação da kolo-pin, que só guarda texto cifrado, então um arquivo continua acessível enquanto o seu computador está desligado. As páginas da kolo-blobs e da kolo-files explicam como um leitor lê de um peer desses.