kolo docsbeta

Como escolher peers de fixação

Mantenha cada log em dois ou mais peers de fixação em lugares diferentes, escolhidos do mesmo jeito por todos os dispositivos.

Nesta página

Um peer de fixação pode ficar offline ou perder o disco, então uma aplicação costuma manter cada log em dois ou mais deles, rodados por pessoas diferentes ou em lugares diferentes. A kolo-pin escolhe esses peers com Select e adiciona o log a eles com AddMany.

Dê um grupo a cada peer

A aplicação mantém uma lista de peers de fixação, cada um um pin.Peer com a sua chave, o seu endereço IPv4 e um Group opcional, como o seu provedor ou a sua região. Os peers de um mesmo grupo podem falhar juntos, então Select pega os peers escolhidos de grupos diferentes quando consegue.

Como Select escolhe

Todos os passos

Como um pin é escolhido

Hashing de rendezvous: todo dispositivo calcula a mesma escolha para um log, sem coordenação. Aqui os pesos estão encurtados.

  1. Para cada pin, o cliente calcula um peso: SHA-256 do ID do pin e do ID do log.
  2. Os pins são ordenados pelo peso, do mais pesado ao mais leve.
  3. Select pega o pin mais pesado de cada grupo até ter cópias suficientes, 2 por padrão. O pin 1 é pulado: o grupo dele já tem o pin 3. Com poucos grupos, os próximos mais pesados completam.
  4. Adicione o pin 5, em um grupo novo. Para este log ele fica em segundo, então toma o lugar do pin 4. Um log em que ele não fica no topo continua como estava.

Select(peers, logID, n) usa rendezvous hashing (Thaler e Ravishankar, 1998, o artigo original sobre a técnica). Cada par de um peer e um log recebe um peso, o hash SHA-256 do ID do peer seguido do ID do log. Os peers com os maiores pesos para aquele log ganham.

  • Todo dispositivo que tem a mesma lista escolhe os mesmos peers para um log, sem nenhuma coordenação. A ordem da lista não importa.
  • Quando um peer entra ou sai, só mudam de lugar os logs para os quais esse peer está entre os escolhidos. Todos os outros logs ficam onde estão.
  • Cada log recebe a sua própria ordem, então os logs se espalham de forma equilibrada pelos peers.

Seguindo essa ordem, Select pega o primeiro peer de cada grupo até ter n. Se houver menos grupos que n, os próximos peers de maior peso completam a seleção, e SharedGroups é true. Um peer sem grupo conta como um grupo próprio, os peers com um ID inválido são ignorados, e de IDs repetidos fica só um. Um n de 0 ou menos quer dizer DefaultCopies, 2.

Adicione o log com AddMany

Uma capability indica um único peer de fixação, então IssueMany assina uma para cada peer, todas com o mesmo horário de emissão. AddMany(ctx, id, peers, log, capabilities, n) adiciona o log aos n peers que Select escolhe, usando a capability que indica cada um.

Quando um peer escolhido está inalcançável, AddMany tenta o próximo peer não escolhido na mesma ordem, no máximo MaxFallback (2) vezes. Esse próximo peer pode estar em um grupo já usado. Um peer que responde com um erro fica como Refused e não é substituído. O Report lista cada tentativa com o seu Outcome (Accepted, Refused ou Unreachable) e conta quantos aceitaram. AddMany só retorna ErrNoPeer se nenhum aceitou, e não há nova tentativa em segundo plano: chame a função de novo mais tarde.

Este programa roda três peers de fixação no loopback, em dois grupos, com os dados em um diretório temporário, e fixa um log em dois deles:

main.go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"path/filepath"
	"sync"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	"github.com/ciranda-dev/kolo-pin"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
)

func main() {
	dir, err := os.MkdirTemp("", "kolo-pin-choose")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)
	var wg sync.WaitGroup
	defer wg.Wait()
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// Three pinning peers in two groups; an application reads this list from its configuration.
	var peers []pin.Peer
	for i, group := range []string{"provider-a", "provider-a", "provider-b"} {
		d := filepath.Join(dir, fmt.Sprint("pin", i))
		id, err := pin.LoadIdentity(d)
		if err != nil {
			log.Fatal(err)
		}
		ln, err := kolosecure.Listen(ctx, "127.0.0.1:0", id, nil)
		if err != nil {
			log.Fatal(err)
		}
		defer ln.Close()
		wg.Go(func() { pin.Serve(ctx, ln, pin.Options{Dir: d}) })
		peers = append(peers, pin.Peer{ID: id.PublicKey(), Addr: ln.Addr().String(), Group: group})
	}

	alice, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	st := kolostore.New(kolostore.NewMemory())
	defer st.Close()
	l, err := st.Create(alice)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := l.Append([]byte("chat history")); err != nil {
		log.Fatal(err)
	}

	sel := pin.Select(peers, l.ID(), 2)
	fmt.Printf("chosen: %s and %s, shared group: %v\n", sel.Peers[0].Group, sel.Peers[1].Group, sel.SharedGroups)

	// One capability per peer, so a fallback peer has one too.
	caps, err := pin.IssueMany(alice, peers, pin.Capability{Expires: time.Now().Add(30 * 24 * time.Hour)})
	if err != nil {
		log.Fatal(err)
	}
	report, err := pin.AddMany(ctx, alice, peers, l, caps, 2)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("accepted by %d peers\n", report.Accepted)
	for _, r := range report.Results {
		fmt.Printf("  %s: %v, %d entries\n", r.Peer.Group, r.Outcome, r.Info.Entries)
	}
}

Ele imprime algo parecido com isto. Os dois grupos podem vir na ordem inversa, porque as chaves são novas a cada execução:

Texto
chosen: provider-a and provider-b, shared group: false
accepted by 2 peers
  provider-a: accepted, 1 entries
  provider-b: accepted, 1 entries

O programa assina uma capability para cada peer da lista, não só para os escolhidos. Um peer de reserva sem uma capability que o indique fica como Refused.

Próximos passos