kolo docsbeta

kolo-sync

Copia um log assinado da kolo-log de um peer para outro, só por pull, ou busca algumas das suas entradas sem réplica.

Nesta página

A kolo-sync mantém atualizada uma réplica do log da kolo-log de alguém a partir de qualquer peer que tenha uma cópia, pelo modelo de buscar e verificar do Certificate Transparency 2.0 (RFC 9162): heads, provas de consistência e provas de inclusão, verificados apenas com as assinaturas do dono. Um Server oferece os logs que a aplicação escolhe e pergunta a ela qual peer pode fazer pull de qual log. Pull abre um stream por log em uma conexão, verifica o head assinado do peer, busca as entradas que faltam com provas de consistência e faz crescer uma réplica da kolo-store, que verifica cada entrada antes de guardá-la. Os marcadores de exclusão vêm junto, assim como as chaves das entradas para os peers que podem lê-las. Fetch busca um intervalo de entradas por conta própria, cada uma verificada com a sua prova de inclusão contra um head assinado, para ler parte de um log sem guardá-lo. Ela usa uma conexão que você já tem e nunca encontra peers nem abre conexões com eles. Funciona com conexões diretas e por relay: cada chamada recebe um Conn, que uma conexão da kolo-secure e um link de peer da kolo-swarm, direto ou por um relay, satisfazem. Veja Réplicas.

Todos os passos

Um pull entre dois peers

Quem faz o pull pede e confere; o servidor só responde. Nada é gravado antes de ser verificado.

  1. Quem faz o pull abre um stream na sua conexão kolo-secure e envia HEAD_REQ com a chave do dono e o ID do log.
  2. O servidor pergunta à sua função authorize sobre esse peer e esse log. Um log que ele não oferece e um peer sem acesso recebem o mesmo erro de não encontrado. Se não, ele responde HEAD: o head assinado e o cabeçalho do log.
  3. Quem faz o pull confere a assinatura do head. Se já tem um head anterior, PROOF_REQ pede uma prova de consistência de que o novo o estende.
  4. ENTRIES_REQ pede o intervalo que falta. Cada resposta tem no máximo 4 MiB, e Replica.Update confere cada registro e cada prova antes de gravar qualquer coisa.
  5. STATE_REQ pede os marcadores de exclusão e as chaves. Quem faz o pull confere e aplica os marcadores, depois adiciona as chaves.
  6. Quem faz o pull fecha o stream. O servidor nunca escreve em quem faz o pull: kolo-sync é só pull.

Instalação

go get github.com/ciranda-dev/kolo-sync

Compila sem cgo.

Início rápido

Alice grava um log de duas entradas e o oferece só para bob. Bob se conecta pelo loopback, busca o cabeçalho assinado do log, abre uma réplica e faz o pull. Depois ele busca uma entrada sem réplica, verificada contra o head assinado de alice.

main.go
package main

import (
	"context"
	"crypto/ed25519"
	"fmt"
	"log"
	"time"

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

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	alice, err := koloid.Generate()
	check(err)
	bob, err := koloid.Generate()
	check(err)

	// Alice writes a log and offers it, with its entry keys, to bob only.
	as := kolostore.New(kolostore.NewMemory())
	defer as.Close()
	l, err := as.Create(alice)
	check(err)
	_, err = l.Append([]byte("hello from alice"))
	check(err)
	_, err = l.Append([]byte("second entry"))
	check(err)
	srv := kolosync.NewServer(func(peer, _ ed25519.PublicKey, _ kololog.LogID) kolosync.Access {
		if peer.Equal(bob.PublicKey()) {
			return kolosync.Keys
		}
		return kolosync.NoAccess
	})
	check(srv.Offer(l))
	ln, err := kolosecure.Listen(ctx, "127.0.0.1:0", alice, nil)
	check(err)
	defer ln.Close()
	go func() {
		conn, err := ln.Accept(ctx)
		if err != nil {
			return
		}
		srv.Serve(ctx, conn)
	}()

	// Bob knows alice's key and the log ID, and keeps a replica in his own store.
	conn, err := kolosecure.Dial(ctx, ln.Addr().String(), bob, alice.PublicKey(), nil)
	check(err)
	defer conn.Close()
	bs := kolostore.New(kolostore.NewMemory())
	defer bs.Close()
	header, err := kolosync.FetchHeader(ctx, conn, alice.PublicKey(), l.ID())
	check(err)
	rep, err := bs.OpenReplica(alice.PublicKey(), l.ID(), header)
	check(err)
	check(kolosync.Pull(ctx, conn, rep))
	v, err := rep.Get(0)
	check(err)
	fmt.Printf("bob read %q from %d entries\n", v, rep.Len())

	// Without a replica, bob checks one entry against alice's signed head.
	h, err := kolosync.FetchHead(ctx, conn, alice.PublicKey(), l.ID())
	check(err)
	got, err := kolosync.Fetch(ctx, conn, h, 1, 1)
	check(err)
	fmt.Printf("bob fetched %q at index %d\n", got[0].Data, got[0].Index)
}

func check(err error) {
	if err != nil {
		log.Fatal(err)
	}
}

O programa imprime:

Texto
bob read "hello from alice" from 2 entries
bob fetched "second entry" at index 1

Uma aplicação real mantém os seus stores em disco com kolostore.OpenPebble.

Referência da API

A referência da API é gerada a partir do código Go e está em inglês.

Pacote kolosync · github.com/ciranda-dev/kolo-sync · v0.1.0

Package kolosync replicates kolo-log logs between two peers, pull only, over any authenticated Conn: a kolo-secure connection or a kolo-swarm link, direct or relayed.

A Server offers logs, and authorizes each peer per log. Pull opens one stream per log, verifies the peer's signed head, fetches the missing range with consistency proofs, and grows a kolo-store Replica, which verifies every entry before it stores it. Delete markers and, for authorized peers, entry keys follow. Fetch gets a range of entries without a replica, each checked with its inclusion proof against a head the client trusts; FetchWithKeys opens them with keys the client holds, which FetchKeys gets from a peer with Keys access, so a client can read from a peer that holds ciphertext only. Many logs share one connection.

Experimental: the API may change before v1.0.0.

Constantes

const (
	// DefaultInFlight is PullOptions.InFlight when it is 0.
	DefaultInFlight = 3
	// MaxInFlight is the largest PullOptions.InFlight.
	MaxInFlight = 8
)
const (
	// DefaultMaxTotalStreams is the default ServerOptions.MaxTotalStreams: 16 connections each serving MaxStreams streams.
	DefaultMaxTotalStreams = 16 * MaxStreams
	// DefaultMaxAnswerBytes is the default ServerOptions.MaxAnswerBytes, a quarter of kolo-transport's DefaultMaxMemory (1 GiB),
	// which leaves the rest of that budget to the connections themselves.
	DefaultMaxAnswerBytes = 256 << 20
)
const (
	// MaxMessageSize is the largest message, length prefix excluded, that a peer sends or accepts.
	MaxMessageSize = 4 << 20
	// MaxStreams is how many streams Serve handles at once per connection; more are answered busy.
	MaxStreams = 16
	// Timeout bounds opening a stream, the wait for the next request, and the start of each message read or write.
	// A message of n bytes may then take another n at MinRate, so a slow but moving 4 MiB answer is not cut off.
	Timeout = 60 * time.Second
	// MinRate is the slowest average speed, in bytes a second, at which a message may be read or written.
	MinRate = 16 << 10
)

Variáveis

var (
	// ErrInvalidArgument means a nil connection, replica, source or key, a key of the wrong size, a zero head,
	// a Fetch, FetchWithKeys or FetchKeys range that is empty or past the head (wrapping kololog.ErrOutOfRange),
	// or a PullOptions.KeysFrom past the replica's length.
	ErrInvalidArgument = errors.New("kolosync: invalid argument")
	// ErrNotFound means the peer does not serve the log to us: it does not have it, did not offer it, or did not authorize us.
	ErrNotFound = errors.New("kolosync: log not found")
	// ErrDiverged means the owner signed two histories: the peer's signed head or record conflicts with ours or with the head
	// Fetch, FetchWithKeys or FetchKeys checks against. Neither log was changed.
	ErrDiverged = errors.New("kolosync: logs diverged")
	// ErrInvalid means the peer sent a head, proof, entry, marker or key that does not verify; a kolo-log error is wrapped too.
	ErrInvalid = errors.New("kolosync: peer sent data that does not verify")
	// ErrProtocol means a malformed, truncated or unexpected message, or another protocol version.
	ErrProtocol = errors.New("kolosync: protocol error")
	// ErrTooLarge means a message over MaxMessageSize, or an entry too large to fit in one.
	ErrTooLarge = errors.New("kolosync: message too large")
	// ErrBehind means the peer's head has fewer entries than the head Fetch, FetchWithKeys or FetchKeys checks against,
	// or, for PullWith with NoMarkers, than the head the replica is filling toward (after ErrMarked); no entry or key is added.
	ErrBehind = errors.New("kolosync: peer is behind the head")
	// ErrKeyMismatch, in Fetched.Err, means a key given to FetchWithKeys does not match its entry's record.
	ErrKeyMismatch = errors.New("kolosync: held key does not match its record")
	// ErrBusy means the peer refused the stream or an answer (MaxStreams, ServerOptions) or could not read its log, or another Pull of the replica is running.
	ErrBusy = errors.New("kolosync: peer busy")
	// ErrMarked means the peer serves a deleted entry to a PullWith with NoMarkers; the replica then holds
	// only the entries before it, so its Len is that entry's index.
	ErrMarked = errors.New("kolosync: peer serves a deleted entry")
	// ErrTimeout means a message read or write took longer than Timeout.
	ErrTimeout = errors.New("kolosync: timeout")
)

Funções

func FetchHead

func FetchHead(ctx context.Context, conn Conn, owner ed25519.PublicKey, logID kololog.LogID) (kololog.VerifiedHead, error)

FetchHead returns the signed head of the log logID that the peer on conn serves, verified against owner.

func FetchHeader

func FetchHeader(ctx context.Context, conn Conn, owner ed25519.PublicKey, logID kololog.LogID) ([]byte, error)

FetchHeader returns the signed header of the log logID that the peer on conn serves, checked against owner, for opening a new replica with kolostore.Store.OpenReplica.

func FetchKeys

func FetchKeys(ctx context.Context, conn Conn, h kololog.VerifiedHead, start, end uint64) ([]kololog.EntryKey, error)

FetchKeys gets the entry keys of the entries start to end, end included, from a peer with Keys access, without their ciphertexts; element i is the key of entry start+i, or nil where the peer gave none.

func Pull

func Pull(ctx context.Context, conn Conn, rep *kolostore.Replica) error

Pull brings rep up to date with the copy of its log that the peer on conn serves, then applies the peer's delete markers and, if the peer gives them, the keys rep lacks; a key other than one rep holds is ErrInvalid. Only rep's Update, ApplyDelete and AddKey store anything, and each verifies first. A second Pull of the same replica while one runs returns ErrBusy; pulls of different replicas may run at once on one connection.

func PullCiphertext

func PullCiphertext(ctx context.Context, conn Conn, rep *kolostore.Replica) error

PullCiphertext is Pull for a peer that must never hold entry keys: it never asks for them, never calls AddKey, and an answer that carries a key anyway is ErrProtocol, with nothing from it stored.

Tipos

type Access

type Access int

Access is what a peer may pull from one offered log.

const (
	// NoAccess gives the peer the same answer as a log we do not have.
	NoAccess Access = iota
	// Ciphertext gives records, proofs, ciphertexts and delete markers, but no entry keys.
	Ciphertext
	// Keys gives everything Ciphertext gives, and the entry keys.
	Keys
)

type Conn

type Conn interface {
	RemotePublicKey() ed25519.PublicKey
	OpenStream(ctx context.Context) (*kolotransport.Stream, error)
	AcceptStream(ctx context.Context) (*kolotransport.Stream, error)
}

Conn is an authenticated connection to one peer, direct or relayed, such as a *kolosecure.Conn or a koloswarm.Conn; RemotePublicKey must return the key the peer proved in the end-to-end handshake.

type Fetched

type Fetched struct {
	Index uint64
	Data  []byte // the entry's value, as kololog.Log.Get returns it; nil when Err is set
	// Err is kololog.ErrDeleted, kololog.ErrKeyUnavailable, ErrKeyMismatch or nil (see the README).
	Err error
}

Fetched is one entry that Fetch got from the peer and verified.

func Fetch
func Fetch(ctx context.Context, conn Conn, h kololog.VerifiedHead, start, end uint64) ([]Fetched, error)

Fetch gets the entries start to end, end included, of the log of h from the peer on conn, without a replica. Each entry is checked with its inclusion proof in the tree of h's size, so the peer must hold h's entries: a peer with a smaller head is ErrBehind, one with another root at h's size ErrDiverged.

func FetchWithKeys
func FetchWithKeys(ctx context.Context, conn Conn, h kololog.VerifiedHead, start, end uint64,
	keys func(index uint64) (kololog.EntryKey, error)) ([]Fetched, error)

FetchWithKeys is Fetch for a caller that holds entry keys, such as one reading from a peer that serves ciphertext only; keys returns a copy of the key held for an entry that came without one (see the README). keys is asked after the stream is closed, so its use shows only in how long FetchWithKeys takes to return.

type PullMeter

type PullMeter struct {
	// contains filtered or unexported fields
}

PullMeter collects the statistics of a pull while it runs. Its zero value is ready to use: pass it in PullOptions.Meter and call Stats from any goroutine. A meter measures one pull at a time: starting a pull with a meter another pull is using is ErrInvalidArgument, and one that starts after the last has ended resets it.

func (PullMeter) Stats
func (m *PullMeter) Stats() PullStats

Stats returns the statistics so far, or the whole pull's once it has ended; it is safe to call at any time.

type PullOptions

type PullOptions struct {
	// NoMarkers makes the pull neither request nor store delete markers: a chunk is stored only up
	// to its first deleted entry (ErrMarked), and STATE markers are ignored.
	NoMarkers bool
	// KeysFrom is the first index the caller may hold without its key; the pull scans and asks for
	// keys only from there.
	KeysFrom uint64
	// InFlight is the most requests for entries the pull has waiting at once, 1 to MaxInFlight. A peer that streams is
	// sent credit in requests of 2 MiB and keeps from 2 up to InFlight of them waiting, as many as twice the measured
	// round trip times the speed asks for; 0 is MaxInFlight, and 1 asks again only when the credit is used up.
	// For a peer that does not stream, such as v0.1.7, it is how many answers are asked for before the first is
	// stored: 0 is DefaultInFlight, and 1 asks for each after the one before is stored. The pull holds at most 6 MiB
	// of answers not yet stored whatever it is.
	InFlight int
	// Meter, if not nil, collects the statistics of the pull while it runs; see PullMeter.
	Meter *PullMeter
}

PullOptions changes how PullWith pulls; the zero value pulls as Pull does.

type PullResult

type PullResult struct {
	// KeysFrom is the first index still held without its key after the pull.
	KeysFrom uint64
	// Stats is how the pull went, also when it failed.
	Stats PullStats
}

PullResult is what PullWith reports.

func PullWith
func PullWith(ctx context.Context, conn Conn, rep *kolostore.Replica, opts *PullOptions) (PullResult, error)

PullWith is Pull with opts (nil for none). On an error the result's KeysFrom is opts.KeysFrom, and a KeysFrom past rep.Len() is ErrInvalidArgument.

type PullStats

type PullStats struct {
	// Streamed is true when the peer served the entries as a stream (STREAM_REQ) and false when the pull asked for them one
	// answer at a time, as for a peer that predates streaming.
	Streamed bool
	// Elapsed is the time since the pull started, or its whole length once it has ended.
	Elapsed time.Duration
	// Bytes, Entries and Answers count the ENTRIES answers read: their message bytes, entries and messages.
	Bytes   uint64
	Entries uint64
	Answers uint64
	// Requests counts the requests for entries sent: ENTRIES_REQ, or STREAM_REQ and CREDIT_REQ.
	Requests uint64
	// ReaderWait is the time the reader spent waiting for the bytes of answers, not counting waits for memory.
	ReaderWait time.Duration
	// CommitBusy is the time the goroutine that stores the answers spent verifying and storing them, and CommitIdle the
	// time it spent waiting for an answer.
	CommitBusy time.Duration
	CommitIdle time.Duration
	// FirstByteMin, FirstByteAvg and FirstByteMax are the time from writing the request for entries to reading the
	// first bytes of its answer. A request sent while others wait includes the time of the answers before it; a streamed
	// pull has one sample for each fill: its STREAM_REQ.
	FirstByteMin time.Duration
	FirstByteAvg time.Duration
	FirstByteMax time.Duration
	// InFlightMax and InFlightAvg are the most requests for entries asked for and not yet answered, and their average over
	// time. For a streamed pull a request is 2 MiB of credit.
	InFlightMax int
	InFlightAvg float64
	// InFlightBlocked counts the times the limit on requests in flight, PullOptions.InFlight, held a request back.
	InFlightBlocked uint64
	// MemoryBlocked counts the times the reader had to wait for room under the 6 MiB of answers a pull holds, and
	// MemoryWait is the time it waited. HeldMax is the most bytes of answers held at once.
	MemoryBlocked uint64
	MemoryWait    time.Duration
	HeldMax       int
}

PullStats says where the time of a pull went and how full it kept the link. All durations are wall time.

func (PullStats) AvgAnswer
func (s PullStats) AvgAnswer() uint64

AvgAnswer returns the average size in bytes of an ENTRIES answer, 0 if none was read.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server serves the logs the application offers to the peers it authorizes; it is safe for concurrent use. A log is named by its owner's key and its log ID, so two owners' logs with one ID are two logs.

func NewServer
func NewServer(authorize func(peer, owner ed25519.PublicKey, logID kololog.LogID) Access) *Server

NewServer returns a Server with no offered logs. authorize is asked on every request, for any owner and log ID; nil, a panic or any other value than Ciphertext or Keys means NoAccess.

func NewServerWith
func NewServerWith(authorize func(peer, owner ed25519.PublicKey, logID kololog.LogID) Access, opts *ServerOptions) (*Server, error)

NewServerWith is NewServer with the server-wide limits of opts; nil is all defaults. A negative limit, or a MaxAnswerBytes below 2 * MaxMessageSize, is ErrInvalidArgument.

func (Server) Offer
func (s *Server) Offer(src Source) error

Offer makes src available under its owner's key and log ID, replacing an earlier source with both the same. src's header must be signed by its owner and name src's log ID; past that, Offer trusts src to serve that log.

func (Server) Serve
func (s *Server) Serve(ctx context.Context, conn Conn) error

Serve answers the streams the peer opens on conn, for Pull, PullCiphertext, FetchHeader, FetchHead, Fetch, FetchWithKeys and FetchKeys, until ctx is done or conn ends, then waits for them. It must be the only caller of conn.AcceptStream.

func (Server) Stats
func (s *Server) Stats() ServerStats

Stats returns the server's totals; it is safe to call at any time.

func (Server) Withdraw
func (s *Server) Withdraw(owner ed25519.PublicKey, logID kololog.LogID)

Withdraw stops offering the log logID of owner; requests for it then get the answer of a missing log.

type ServerOptions

type ServerOptions struct {
	// MaxTotalStreams is the most streams served at once over all connections.
	MaxTotalStreams int
	// MaxAnswerBytes is the most memory the answers being built or written may hold at once; each answer counts twice its
	// size, the entries read from the log and the frame sent. At least 2 * MaxMessageSize, so one largest answer always fits.
	MaxAnswerBytes int64
}

ServerOptions are the limits a Server applies over all the connections it serves, on top of MaxStreams for each. A zero field is its default. A stream or an answer over a limit is answered busy, which a Pull or Fetch returns as ErrBusy.

type ServerStats

type ServerStats struct {
	BytesSent      uint64 // frame bytes written, every answer included
	ActiveStreams  int    // streams being served now, refused ones not included
	RefusedByLimit uint64 // streams and answers refused because MaxTotalStreams or MaxAnswerBytes was reached
	AnswerBytes    int64  // memory the answers being built or written hold now, counted as MaxAnswerBytes counts it
}

ServerStats are a Server's totals over all its connections.

type Source

type Source interface {
	ID() kololog.LogID
	Header() kololog.LogHeader
	Head() (kololog.Head, error)
	Record(index uint64) (kololog.Record, error)
	Entry(index uint64) (kololog.Entry, error)
	EntryInfo(index uint64) (kololog.EntryInfo, error)
	Key(index uint64) (kololog.EntryKey, error)
	InclusionProof(index, size uint64) (kololog.InclusionProof, error)
	ConsistencyProof(oldSize, newSize uint64) (kololog.ConsistencyProof, error)
}

Source is a log a Server can offer: a kolo-store Log or Replica, or a kolo-log Log or Replica.

Bom saber

Todos os passos

Ler entradas avulsas

Fetch lê algumas entradas de qualquer peer sem copiar o log. Cada entrada é conferida contra um head em que você já confia.

  1. O leitor tem um head verificado de tamanho n, de FetchHead ou de um pull anterior. Fetch confere o intervalo contra ele antes de enviar qualquer coisa.
  2. HEAD_REQ traz o head do peer. Um peer com um log mais curto não consegue provar essas entradas: Fetch retorna ErrBehind, então pergunte a outro peer.
  3. FETCH_REQ pede do início ao fim, na árvore de tamanho n.
  4. FETCH responde cada entrada com o seu registro, o seu texto cifrado ou marcador de exclusão, a sua chave quando o acesso permite e uma prova de inclusão nessa árvore.
  5. OpenEntry confere o registro e a prova contra a raiz confiável, depois decifra. Uma entrada excluída volta como ErrDeleted.

A confiança vem só das assinaturas do dono, então qualquer peer com uma cópia verificada pode servi-la: um Source é um *Log ou uma *Replica da kolo-store ou da kolo-log, e uma réplica serve o último head que ela tem por inteiro. Um Source próprio precisa de ID, Header, Head, Record, Entry, EntryInfo, Key, InclusionProof e ConsistencyProof. Offer identifica o log por src.Header().LogKey e src.ID() e substitui uma fonte anterior com os dois iguais. Ele recusa uma fonte cujo cabeçalho não foi assinado por essa chave ou que nomeia outro ID de log (ErrInvalidArgument envolvendo kololog.ErrBadLogHeader). Depois de Withdraw, as requisições desse log recebem a resposta de um log ausente.

Pull verifica tudo contra a chave do dono no cabeçalho da réplica e retorna nil quando o peer está atrás ou empatado. Um pull interrompido no meio deixa um alvo na réplica, que a kolo-store guarda; o próximo pull preenche esse alvo primeiro, e retorna nil se o head do peer estiver abaixo dele. Uma chave em uma resposta STATE para uma entrada que a réplica já tem com a sua chave precisa ser essa chave, ou o pull falha com ErrInvalid. Um pull sem nada novo não lê nenhum texto cifrado em nenhum dos lados: as duas pontas usam os indicadores por entrada da kolo-log e leem só os marcadores de exclusão e as chaves que enviam ou aplicam.

FetchHead retorna o head assinado do peer, verificado contra a chave do dono e o ID de log, para um cliente que ainda não tem nenhum head. É o head que esse peer tem, que pode ser mais antigo que o mais novo. Fetch(ctx, conn, h, start, end) busca as entradas de start a end, end incluída, contra o head h em que o cliente confia. Cada Fetched tem Index, Data e Err: nil, kololog.ErrDeleted para uma entrada com um marcador de exclusão verificado, ou kololog.ErrKeyUnavailable quando o peer não enviou a chave. Qualquer outra falha faz a chamada inteira falhar e não retorna nenhuma entrada. Um peer cujo head é menor que h dá ErrBehind; pergunte a outro peer. Fetch guarda os valores do intervalo que você pediu, então a memória dele é esse intervalo, no máximo uma mensagem a mais.

Conexões diretas e por relay

Cada chamada recebe um Conn: RemotePublicKey, OpenStream e AcceptStream, os únicos métodos que a kolo-sync usa. Um *kolosecure.Conn e um koloswarm.Conn o satisfazem, então a kolo-sync funciona com conexões diretas e por relay, e uma conexão por relay leva a sincronização exatamente como uma direta. RemotePublicKey precisa devolver a chave que o peer provou no handshake de ponta a ponta. Um link por relay prova essa chave do mesmo jeito, então authorize recebe a mesma chave que em um link direto. As verificações da chave do peer e o formato de rede não mudam.

Um Conn nil, ou um que contém um ponteiro nil, como um *kolosecure.Conn nil, é ErrInvalidArgument. Serve recusa com ErrInvalidArgument um Conn cujo RemotePublicKey não tem 32 bytes, antes de aceitar um stream.

Pull sem marcadores de exclusão

PullWith(ctx, conn, rep, opts) é o Pull com um *PullOptions e retorna um PullResult. Com nil ou o valor zero ele faz o pull e envia exatamente as mensagens que Pull envia. PullOptions tem quatro campos; NoMarkers e KeysFrom são descritos aqui, InFlight mais abaixo e Meter em Estatísticas do pull.

  • NoMarkers: o pull não pede nem guarda marcadores de exclusão, então um peer que excluiu entradas, ou diz que excluiu, não consegue apagá-las da réplica. Uma resposta ENTRIES é verificada antes de guardar qualquer coisa: na sua primeira entrada que traz um marcador, só as entradas anteriores vão para Replica.Update, com mais um pedido PROOF para esse prefixo mais curto, para que a réplica continue verificada, e o pull retorna ErrMarked com o nome desse índice. rep.Len() passa a ser esse índice, e a réplica se preenche em direção ao head desse peer: faça pull do resto de um peer cujo head seja pelo menos igual. Um peer atrás desse head não adiciona nada e retorna ErrBehind (Pull retorna nil nesse caso). O marcador nunca é decodificado nem verificado, então um forjado interrompe o pull do mesmo jeito. Os marcadores do STATE são ignorados, também os ruins ou fora de lugar, e nenhum pedido STATE pede só marcadores; as chaves das respostas STATE são verificadas e adicionadas como em Pull. Um marcador que a réplica já tem permanece.
  • KeysFrom: o primeiro índice que quem chama pode ter sem a sua chave. A varredura local por chaves que faltam e os pedidos STATE de chaves começam ali. Com NoMarkers, um pull passa a custar as entradas novas e as que continuam sem chave, não o log inteiro; sem ele, os marcadores de exclusão continuam sendo pedidos a partir do índice 0. Um valor maior que rep.Len() é ErrInvalidArgument.

PullResult.KeysFrom é o primeiro índice que continua sem chave depois do pull (as entradas excluídas são puladas), ou rep.Len() quando todas as entradas têm a sua chave: guarde-o junto com a réplica e passe-o ao próximo pull. Em caso de erro, ele vale opts.KeysFrom, então o cursor nunca pula uma entrada. O formato de rede não muda.

Um pull que tenta o próximo peer quando um serve uma entrada excluída ou está atrás do head em direção ao qual a réplica se preenche:

Go
func pullLive(ctx context.Context, peers []*kolosecure.Conn, rep *kolostore.Replica, keysFrom uint64) (uint64, error) {
	err := kolosync.ErrNotFound
	for _, conn := range peers {
		var res kolosync.PullResult
		res, err = kolosync.PullWith(ctx, conn, rep, &kolosync.PullOptions{NoMarkers: true, KeysFrom: keysFrom})
		if err == nil {
			return res.KeysFrom, nil
		}
		if !errors.Is(err, kolosync.ErrMarked) && !errors.Is(err, kolosync.ErrBehind) {
			return keysFrom, err
		}
		// rep holds the entries before the deleted one; the next peer goes on from rep.Len().
	}
	return keysFrom, err
}

Respostas em voo

Um pull pede as entradas em respostas de cerca de 1 MiB. Pedir uma resposta de cada vez envia a próxima requisição só quando chegam os primeiros bytes da resposta anterior, então move cerca de uma resposta, 1 MiB, a cada tempo de ida e volta, seja qual for a capacidade do enlace: 10 MB/s a 100 ms. Um pull de um peer desta versão pede as entradas uma única vez e mantém o enlace cheio. Sua primeira requisição de entradas, STREAM_REQ, diz onde começar e dá crédito em bytes; o peer então envia cada resposta, seguida da prova de onde ela termina, sem esperar outra requisição, enquanto o crédito durar, e o pull envia mais crédito (CREDIT_REQ) antes que ele acabe. Uma goroutine lê o stream, e a goroutine de quem chama verifica e guarda as respostas em ordem com Replica.Update, então a réplica só cresce com respostas verificadas, em ordem.

  • Com um peer que faz streaming, InFlight limita as requisições de crédito, de 2 MiB cada, que esperam no peer: de 1 a MaxInFlight (8), e 0 é MaxInFlight; qualquer outro valor é ErrInvalidArgument. O pull mantém 2 em espera e mais conforme mede o tempo de ida e volta e a velocidade com que lê (o dobro do produto largura de banda por atraso, em requisições), até InFlight, então no máximo 16 MiB de respostas estão a caminho. Com 1 o pull pede de novo só quando o crédito anterior acaba.
  • Um peer que não faz streaming responde a STREAM_REQ com um erro e fecha o stream. O pull então abre outro stream e pede uma requisição e uma prova por resposta, até InFlight requisições à frente (0 é DefaultInFlight, 3), ao custo de dois tempos de ida e volta em cada pull que tem entradas a buscar. Um servidor só faz streaming quando pedem, então também atende um pull que não faz streaming.
  • As respostas que já esperam quando uma é guardada vão para o mesmo Update, um commit e uma sincronização do armazenamento, até 4 MiB de respostas; se ele falha, elas são guardadas uma a uma, então as entradas guardadas antes de uma resposta ruim, e o erro, são os mesmos de quando cada uma é guardada sozinha.
  • Uma falha, uma resposta hostil ou um cancelamento deixam a réplica como estava depois da última resposta guardada inteira, e rep.Len() é onde o próximo Pull retoma. Um peer que para de enviar no meio do crédito dá ErrTimeout.
  • Um pull retém no máximo 6 MiB de respostas ainda não guardadas, seja qual for o InFlight. O crédito em espera são as respostas do peer na rede e nas janelas do transporte, não na memória do pull.

A janela que a kolo-transport dá a um stream ainda limita um stream à sua janela por tempo de ida e volta, então um pull alcança o menor entre isso e o enlace: uma janela de stream de 4 MiB dá cerca de 40 MB/s a 100 ms e 20 MB/s a 200 ms. Subir os tetos de janela da kolo-transport, MaxGrownStreamReceiveWindow e MaxGrownConnReceiveWindow, é o jeito de um pull ir mais rápido que isso (veja kolo-transport). O InFlight não precisa mudar para isso.

Estatísticas do pull

PullResult.Stats diz para onde foi o tempo de um PullWith, também quando ele falhou. Para ter os números enquanto ele roda, dê a PullOptions.Meter um *PullMeter (o valor zero dele já está pronto) e chame Meter.Stats() de qualquer goroutine. Um medidor mede um pull de cada vez: um pull que começa com um medidor que outro pull está usando retorna ErrInvalidArgument.

  • Streamed: o peer enviou as entradas em streaming; false para um peer anterior ao STREAM_REQ.
  • Elapsed, Bytes, Entries, Answers e Requests: o tempo do pull, as respostas ENTRIES lidas e as requisições de entradas enviadas.
  • ReaderWait, CommitBusy e CommitIdle: o tempo que o leitor esperou por bytes, e o tempo que a goroutine que verifica e guarda ficou ocupada e ociosa.
  • FirstByteMin, FirstByteAvg e FirstByteMax: de quando uma requisição de entradas é escrita até os primeiros bytes da resposta dela.
  • InFlightMax, InFlightAvg, InFlightBlocked, MemoryBlocked, MemoryWait e HeldMax: as requisições em espera, as vezes em que o InFlight ou os 6 MiB seguraram o pull, e o máximo de bytes de respostas retidos.

CommitIdle e ReaderWait perto de Elapsed querem dizer que o pull espera o peer ou a rede, não esta máquina. CommitBusy perto de Elapsed quer dizer que a máquina verifica e guarda o mais rápido que consegue. FirstByteMin bem acima do tempo de ida e volta quer dizer que o peer demora para ler o log dele.

Ler de um pin que serve só texto cifrado

Um peer de fixação (pin) guarda uma cópia verificada de um log e a serve com acesso Ciphertext, então não tem chaves de entradas. Um Fetch contra ele devolve cada entrada viva com kololog.ErrKeyUnavailable. Use Fetch quando o peer envia as chaves (acesso Keys) ou você só precisa saber quais entradas existem. Use FetchWithKeys quando as chaves já estão com você e o peer serve só texto cifrado, por exemplo para ler enquanto o dono está offline.

As chaves vêm de você, nunca do pin. Pegue um head com FetchHead e as chaves do intervalo com FetchKeys do dono ou de outro peer com acesso Keys, e guarde-as onde a sua aplicação guarda o estado. Depois, FetchWithKeys(ctx, conn, h, start, end, keys) é o Fetch com uma função keys(index) que devolve a chave que você tem para uma entrada que chegou sem ela. Log.Key e Replica.Key servem como keys se você guarda um log ou uma réplica, e a função pode ler de um mapa ou de um arquivo do mesmo jeito. As duas chamadas são conferidas contra o head h, como o Fetch.

main.go
package main

import (
	"context"
	"crypto/ed25519"
	"errors"
	"fmt"
	"log"
	"time"

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

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	alice, err := koloid.Generate()
	check(err)
	device, err := koloid.Generate() // another device of alice, with Keys access
	check(err)
	reader, err := koloid.Generate() // reads from the pin, with Ciphertext access
	check(err)

	// One server plays both parts here: it gives keys to the device and
	// ciphertext only to the reader, as a pin would.
	as := kolostore.New(kolostore.NewMemory())
	defer as.Close()
	l, err := as.Create(alice)
	check(err)
	_, err = l.Append([]byte("hello from alice"))
	check(err)
	_, err = l.Append([]byte("second entry"))
	check(err)
	srv := kolosync.NewServer(func(peer, _ ed25519.PublicKey, _ kololog.LogID) kolosync.Access {
		switch {
		case peer.Equal(device.PublicKey()):
			return kolosync.Keys
		case peer.Equal(reader.PublicKey()):
			return kolosync.Ciphertext
		}
		return kolosync.NoAccess
	})
	check(srv.Offer(l))
	ln, err := kolosecure.Listen(ctx, "127.0.0.1:0", alice, nil)
	check(err)
	defer ln.Close()
	go func() {
		for {
			conn, err := ln.Accept(ctx)
			if err != nil {
				return
			}
			go srv.Serve(ctx, conn)
		}
	}()

	// The device gets a head and the keys of both entries, and keeps them.
	dconn, err := kolosecure.Dial(ctx, ln.Addr().String(), device, alice.PublicKey(), nil)
	check(err)
	defer dconn.Close()
	h, err := kolosync.FetchHead(ctx, dconn, alice.PublicKey(), l.ID())
	check(err)
	keys, err := kolosync.FetchKeys(ctx, dconn, h, 0, 1)
	check(err)

	// The reader asks the pin. Fetch alone cannot open the entries.
	rconn, err := kolosecure.Dial(ctx, ln.Addr().String(), reader, alice.PublicKey(), nil)
	check(err)
	defer rconn.Close()
	got, err := kolosync.Fetch(ctx, rconn, h, 0, 1)
	check(err)
	fmt.Println("without keys:", errors.Is(got[0].Err, kololog.ErrKeyUnavailable))

	// FetchWithKeys opens them with the held keys, which never leave the reader.
	got, err = kolosync.FetchWithKeys(ctx, rconn, h, 0, 1, func(i uint64) (kololog.EntryKey, error) {
		return append(kololog.EntryKey(nil), keys[i]...), nil
	})
	check(err)
	for _, f := range got {
		if f.Err != nil { // for example kolosync.ErrKeyMismatch
			log.Fatal(f.Err)
		}
		fmt.Printf("with keys: %q at index %d\n", f.Data, f.Index)
	}
}

func check(err error) {
	if err != nil {
		log.Fatal(err)
	}
}

Ele imprime:

Texto
without keys: true
with keys: "hello from alice" at index 0
with keys: "second entry" at index 1

O que fica no cliente: as chaves, e quais delas ele tem. O pin recebe as mesmas requisições que com Fetch e não precisa de material de chaves. keys só é consultada depois que a última resposta chegou e o stream foi fechado, então nem o ritmo nem o fim do stream dizem ao pin se você tem chaves. FetchWithKeys zera cada chave depois de usá-la, então keys devolve uma cópia.

Uma chave nil ou vazia, ou um erro que envolve kololog.ErrKeyUnavailable, significa que nenhuma é guardada e a entrada é informada com kololog.ErrKeyUnavailable. O kololog.ErrOutOfRange de Log.Key e Replica.Key conta como nenhuma, e o kololog.ErrDeleted delas informa a entrada como excluída. Uma chave guardada que não confere com o registro assinado da entrada é informada só para aquela entrada com ErrKeyMismatch, e as outras são abertas. Qualquer outro erro de keys faz a chamada falhar. Quando o ctx termina, nenhuma chave a mais é pedida, e em qualquer erro nenhuma entrada é devolvida e os valores já abertos são zerados.

O tempo que FetchWithKeys leva para retornar depende das chaves guardadas: ele abre as entradas depois que o stream termina, então um peer que vê a sua próxima requisição na mesma conexão pode saber pela demora se você tinha chaves e se elas conferiam. O mesmo vale para o que a sua aplicação faz em seguida, como parar depois de um ErrKeyMismatch. Nada muda na rede com as chaves. Se isso importa, abra o próximo stream depois de uma espera fixa, ou em outra conexão.

FetchKeys(ctx, conn, h, start, end) devolve um elemento por entrada pedida: o elemento i é a chave da entrada start+i, ou nil onde o peer não deu nenhuma (uma entrada excluída, uma chave que ele não tem ou falta de acesso Keys: as três parecem iguais). Ele não confere a chave, porque a kolo-log não tem uma conferência de uma chave sem o texto cifrado; FetchWithKeys confere, contra o registro assinado. Zere as chaves quando terminar.

Rode um Serve por conexão, como o único chamador de conn.AcceptStream, e um Pull por réplica de cada vez (um segundo retorna ErrBusy). Pulls de réplicas diferentes e vários fetches podem compartilhar uma conexão, cada um no seu próprio stream, e as duas pontas podem servir e fazer pull na mesma conexão.

Limites

  • MaxMessageSize: 4 MiB por mensagem, com o prefixo de tamanho verificado antes da alocação. Uma entrada cujo texto cifrado com preenchimento não cabe em uma mensagem não pode ser sincronizada nem buscada com Fetch (ErrTooLarge), veja Limites conhecidos.
  • MaxStreams: 16 streams servidos ao mesmo tempo por conexão, de pull ou de fetch, o mesmo que o limite padrão de streams da kolo-transport. Os outros recebem como resposta “ocupado”, e o cliente recebe ErrBusy.
  • ServerOptions.MaxTotalStreams: 256 streams servidos ao mesmo tempo em todas as conexões (DefaultMaxTotalStreams, 16 conexões de MaxStreams). ServerOptions.MaxAnswerBytes: 256 MiB de respostas sendo montadas ou escritas em todas as conexões (DefaultMaxAnswerBytes), no mínimo 2 x MaxMessageSize; uma resposta conta o dobro do seu tamanho. Eles são definidos com NewServerWith. Um stream ou uma resposta além de qualquer um dos dois recebe “ocupado”, o cliente recebe ErrBusy e ServerStats.RefusedByLimit conta isso.
  • Timeout: 60s para abrir um stream, para o início de cada leitura ou escrita de mensagem e para a espera pela próxima requisição. Uma mensagem de n bytes pode levar Timeout mais n a MinRate (16 KiB/s), então uma mensagem completa de 4 MiB só é cortada abaixo de 16 KiB/s. Um peer calado ocupa um stream por no máximo Timeout; um cliente que espera demais recebe ErrTimeout.
  • Uma resposta a uma requisição de entradas é preenchida até cerca de 1 MiB quando já contém uma entrada; uma entrada maior vai sozinha, até MaxMessageSize.
  • PullOptions.InFlight: de 1 a 8 (MaxInFlight); qualquer outro valor é ErrInvalidArgument. Com um peer que faz streaming é o máximo de requisições de crédito, de 2 MiB cada, em espera (0 é 8); com um peer mais antigo, as respostas em voo (0 é DefaultInFlight, 3). Um pull retém no máximo 6 MiB de respostas ainda não guardadas, e um commit guarda as respostas que esperam, até 4 MiB.
  • Crédito de um pull em streaming: o peer aceita no máximo 64 MiB de crédito por stream e recusa uma requisição de mais.
  • Uma resposta STATE olha no máximo 32.768 entradas (MaxMessageSize / 128), depois para antes do fim, e quem faz o pull pede o resto. Ela lê só os marcadores de exclusão e as chaves que envia, nunca um texto cifrado.
  • Na rede, heads, cabeçalhos, registros, marcadores e provas têm no máximo 4 KiB cada, e uma chave de entrada tem 0 ou 32 bytes.
  • Os limites são constantes fixas, exceto os dois de ServerOptions. As conexões vêm da kolo-secure, então a kolo-sync só aceita IPv4.

Segurança

  • As chaves das entradas só viajam na conexão que você passa, nunca em um erro nem em uma linha de log. Nenhum erro carrega bytes que um peer enviou, só números como tamanhos e índices.
  • O head do peer é verificado (assinatura sob kolo-log/tree-head/v0, chave do dono, ID do log) antes de qualquer outra mensagem ser lida, e as provas só são verificadas contra heads verificados. A kolo-sync não assina nada.
  • Cada bloco buscado vai para Replica.Update, que verifica cada assinatura de registro, cada hash de texto cifrado, cada compromisso de chave e a raiz reconstruída antes de guardar qualquer coisa. Replica.AddKey verifica uma chave que chega depois contra o compromisso da chave. Em ErrInvalid, a réplica mantém o que tinha.
  • Os marcadores de exclusão de uma resposta STATE vão para um único Replica.ApplyDelete, em um único commit, depois de todos os itens da resposta serem verificados: um marcador inválido ou fora do lugar, ou qualquer item malformado, não aplica nenhum deles.
  • Fetch verifica tudo contra o head h que você passa, nunca contra a palavra do peer. Cada entrada passa por kololog.OpenEntry, que verifica a sua prova de inclusão na árvore do tamanho de h, a assinatura e o índice do registro, o texto cifrado ou o marcador de exclusão e a chave contra o seu compromisso antes de decifrar. Cada prova precisa ser do índice pedido.
  • ErrDiverged exige evidência: um head de um tamanho que temos, ou do tamanho de h em Fetch, com outra raiz, ou um registro assinado pelo dono, vindo do peer, que difere do nosso no último índice que temos. Uma prova inválida sem essa evidência é ErrInvalid, já que qualquer peer pode enviar uma. Nenhuma das cópias muda.
  • Quem faz o pull indica o que tem pelo que pede e nunca envia o seu próprio head. O servidor nunca grava.
  • authorize roda antes de os logs oferecidos serem consultados, então um log ausente, um não oferecido, um não autorizado e um ID de log oferecido só com outro dono seguem o mesmo caminho e geram os mesmos bytes. Um log guardado mas não oferecido nunca é lido.
  • Um servidor só aceita requisições e um cliente só aceita respostas, o que é verificado antes dos campos. Outra versão, varints não mínimos ou bytes sobrando encerram o stream.

Limites conhecidos

  • Experimental. A API pode mudar antes da v1.0.0.
  • Formato de rede versão 1. Um peer que fala outra versão recebe um erro de protocolo.
  • Só pull: um peer não consegue fazer push de um log para outro.
  • Uma entrada cujo texto cifrado com preenchimento passa de MaxMessageSize não pode ser sincronizada nem buscada, excluída ou não, e o log não sincroniza além dela. O servidor verifica antes o tamanho do registro e nunca lê essa entrada.
  • Um fork que começa depois das entradas que temos não deixa evidência: as provas dele falham, e o pull retorna ErrInvalid, não ErrDiverged.
  • Fetch não distingue um peer sem acesso Keys de um que não tem a chave ou que decidiu não enviá-la: todos dão kololog.ErrKeyUnavailable.
  • Os heads não têm timestamp, então um head mais novo é um head maior. Para ler as entradas mais novas, pegue antes um head mais novo com FetchHead ou um Pull.
  • Não existe forma JSON do formato de rede.

Erros

ErroMensagem
ErrBehindkolosync: peer is behind the head
ErrBusykolosync: peer busy
ErrDivergedkolosync: logs diverged
ErrInvalidkolosync: peer sent data that does not verify
ErrInvalidArgumentkolosync: invalid argument
ErrKeyMismatchkolosync: held key does not match its record
ErrMarkedkolosync: peer serves a deleted entry
ErrNotFoundkolosync: log not found
ErrProtocolkolosync: protocol error
ErrTimeoutkolosync: timeout
ErrTooLargekolosync: message too large

Teste os erros com errors.Is. ErrInvalid também envolve o erro da kolo-log (como kololog.ErrBadEntry, kololog.ErrInvalidHead ou kololog.ErrBadProof), ErrDiverged pode envolver kololog.ErrDiverged, ErrInvalidArgument envolve kololog.ErrOutOfRange para um intervalo de Fetch vazio ou além do head, e um ErrTimeout na leitura ou escrita de uma mensagem envolve os.ErrDeadlineExceeded. ErrKeyMismatch vem em Fetched.Err e envolve kololog.ErrBadEntry. Depois que ctx termina, Pull, FetchHeader, FetchHead, Fetch, FetchWithKeys, FetchKeys e Serve retornam ctx.Err().

ErrMarked só vem de PullWith com NoMarkers: o peer serve uma entrada excluída, ou com um marcador, onde a réplica precisa de uma viva. A réplica tem as entradas anteriores, então rep.Len() é o seu índice, que a mensagem do erro também nomeia; faça pull do resto de outro peer cujo head alcance o head desse peer. PullWith com NoMarkers também retorna ErrBehind quando o head do peer tem menos entradas que o head em direção ao qual a réplica se preenche, então nenhuma entrada nem chave é adicionada: pergunte a outro peer, ou a um posterior.

Referências

  • RFC 9162, Certificate Transparency Version 2.0 (Experimental, December 2021).
    • Usa: os heads assinados da árvore (4.10), as provas de consistência (2.1.4), as provas de inclusão (2.1.3), get-sth (5.2), get-sth-consistency (5.3), get-entries (5.6) e o monitor que guarda um log inteiro (8.2).
    • Não implementa: HTTPS e JSON (no lugar, mensagens da kolo-codec em um stream da kolo-secure) e get-proof-by-hash como pedido, porque uma réplica tem todas as entradas e reconstrói a raiz.
  • RFC 6962, Certificate Transparency (Experimental, June 2013, obsoleted by RFC 9162).
    • Usa: get-entry-and-proof (4.8), uma entrada com a sua prova de inclusão por índice e tamanho da árvore.
  • RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
    • Usa: Ed25519ctx (5.1, 8.3), por meio dos contextos da kolo-log.
    • Não implementa: a kolo-sync não assina nada.
  • RFC 9113, HTTP/2 (Proposed Standard, June 2022).
    • Usa: o limite de concorrência de streams e os streams recusados (5.1.2, 6.5.2).
    • Não implementa: o HTTP/2 em si.