kolo docsbeta

kolo-blobs

Armazenamento de arquivos criptografado e endereçado por conteúdo. Guarde um arquivo de qualquer tamanho, leia qualquer intervalo dele e mantenha-o em peers de fixação que não conseguem lê-lo.

Nesta página

A kolo-blobs guarda os bytes de um arquivo e nada mais: nem nomes, nem pastas, nem versões. Write corta um arquivo em fragmentos em pontos que dependem do conteúdo (FastCDC), criptografa cada fragmento (AES-GCM, NIST SP 800-38D) com chaves derivadas por HKDF (RFC 5869) de uma chave aleatória para esse arquivo, monta uma árvore de Merkle sobre eles e retorna o ID do blob, o hash SHA-256 (FIPS 180-4) da raiz da árvore. Open retorna um leitor que verifica cada fragmento contra a árvore enquanto transmite, e lê qualquer intervalo buscando só os fragmentos que o cobrem. Com NewLogBackend, as partes de um blob são entradas de um log da kolo-store, então elas viajam com a kolo-sync e ficam guardadas em peers de fixação da kolo-pin, que só têm texto cifrado e nunca uma chave. O pacote Go se chama koloblobs.

Todos os passos

De um arquivo a um ID de blob

Um blob é só os bytes de um arquivo. Nomes, pastas e versões ficam na camada de cima, como a kolo-files.

  1. Write corta o arquivo em fragmentos onde o conteúdo indica: pelo menos 256 KiB, cerca de 1 MiB em média. Os pontos de corte também dependem da chave do arquivo, então mudam com cada chave.
  2. Cada fragmento vira um objeto: um MAC de conteúdo de 32 bytes e depois o fragmento selado com AES-256-GCM com uma chave derivada da chave do arquivo e do conteúdo. O hash SHA-256 do objeto é o seu nome.
  3. Uma árvore lista o hash e o tamanho de cada objeto, até 256 filhos por nó. Um arquivo de até 256 fragmentos precisa de uma só raiz acima deles.
  4. A raiz também se compromete com a chave do arquivo. O ID do blob é o hash SHA-256 do objeto raiz, então ele nomeia cada byte do arquivo com essa chave.
  5. Uma versão nova escrita com a mesma chave corta os mesmos fragmentos longe da edição. Só o fragmento em volta dela e uma raiz nova são guardados; os outros objetos são compartilhados.

Instalação

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

Compila com CGO_ENABLED=0 para gerar um binário só em Go. Compartilhe arquivos entre dois terminais mostra passo a passo como enviar um arquivo de um peer para outro com um código de compartilhamento.

Início rápido

Este programa guarda um arquivo de 20 MB em um log da kolo-store no disco, em um diretório temporário. Ele lê de volta 16 bytes do meio e depois guarda uma versão editada com a mesma chave.

main.go
package main

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"log"
	"math/rand/v2"
	"os"
	"path/filepath"

	koloblobs "github.com/ciranda-dev/kolo-blobs"
	koloid "github.com/ciranda-dev/kolo-id"
	kolostore "github.com/ciranda-dev/kolo-store"
)

func main() {
	dir, err := os.MkdirTemp("", "kolo-blobs")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)
	ctx := context.Background()

	// A kolo-store log on disk holds the blob, one object per entry.
	db, err := kolostore.OpenPebble(filepath.Join(dir, "store"))
	if err != nil {
		log.Fatal(err)
	}
	st := kolostore.New(db)
	defer st.Close()
	me, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	l, err := st.Create(me)
	if err != nil {
		log.Fatal(err)
	}
	blobs := koloblobs.New(koloblobs.NewLogBackend(l))

	// A 20 MB file under a new key. The key and the ID are what a reader needs.
	file := make([]byte, 20_000_000)
	rand.NewChaCha8([32]byte{1}).Read(file)
	key := koloblobs.NewKey()
	id, err := blobs.Write(ctx, key, bytes.NewReader(file))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("stored %d bytes as %d log entries\n", len(file), l.Len())

	// A range read fetches and checks only the chunk under it and the tree above it.
	r, err := blobs.Open(ctx, id, key)
	if err != nil {
		log.Fatal(err)
	}
	part, err := io.ReadAll(io.NewSectionReader(r, 12_000_000, 16))
	r.Close()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("bytes 12000000 to 12000016 match: %v\n", bytes.Equal(part, file[12_000_000:12_000_016]))

	// An edited version under the same key shares every chunk away from the edit.
	before := l.Len()
	edited := append(append(append([]byte{}, file[:10_000_000]...), "an insertion"...), file[10_000_000:]...)
	if _, err := blobs.Write(ctx, key, bytes.NewReader(edited)); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("the edited version added %d entries\n", l.Len()-before)
}

Ele imprime:

Texto
stored 20000000 bytes as 17 log entries
bytes 12000000 to 12000016 match: true
the edited version added 2 entries

O primeiro número foi 17, 18 ou 19 em seis execuções, porque os limites dos fragmentos dependem da chave aleatória: os fragmentos mais uma raiz. A versão editada acrescenta o fragmento em volta da inserção e uma raiz nova.

Referência da API

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

Pacote koloblobs · github.com/ciranda-dev/kolo-blobs · v0.1.0

Package koloblobs stores files as encrypted, content-addressed blobs for Kolo: the content layer under kolo-files, with no names, folders or versions.

Write cuts a file into content-defined chunks, encrypts each under keys derived from a random per-file key, builds a Merkle tree over them and returns the blob's ID, the hash of the tree's root. Open returns a Reader that checks every chunk against the tree while it streams, and reads any range by fetching only the chunks that cover it. Objects live in a Backend; LogBackend keeps them as kolo-log entries, so blobs travel with kolo-sync and rest on kolo-pin pinning peers, which hold only ciphertext and never a key.

Experimental: the API may change before v1.0.0.

Constantes

const (
	// KeySize is the size in bytes of a file key.
	KeySize = 32
	// HashSize is the size in bytes of an object hash and a content ID.
	HashSize = sha256.Size
	// MaxObjectSize is the largest object, the largest kolo-log entry value that kolo-sync carries.
	MaxObjectSize = 4128764
	// ObjectOverhead is what encryption adds to a chunk or node: a 32-byte content MAC and a 16-byte tag.
	ObjectOverhead = 48
	// MaxChunkSize is the largest chunk of plaintext, so that its object is at most MaxObjectSize.
	MaxChunkSize = MaxObjectSize - ObjectOverhead
	// MinChunkSize is the smallest chunk the chunker cuts; only a blob's last chunk can be smaller.
	MinChunkSize = 256 << 10
	// Fanout is the most children a tree node lists.
	Fanout = 256
	// MaxHeight is the most node levels above the chunks; 256^6 chunks of MinChunkSize exceed MaxSize.
	MaxHeight = 6
	// MaxSize is the largest blob in bytes, the largest offset of io.Seeker.
	MaxSize = math.MaxInt64
)

Variáveis

var (
	// ErrInvalidArgument means a nil store, backend, log, source, context or function, a negative or
	// out-of-range offset, an unknown whence, or a Put whose hash is not the object's.
	ErrInvalidArgument = errors.New("koloblobs: invalid argument")
	// ErrNotFound means the backend does not have an object of the blob.
	ErrNotFound = errors.New("koloblobs: object not found")
	// ErrCorrupt means an object does not match its hash, does not decrypt or breaks a tree rule.
	ErrCorrupt = errors.New("koloblobs: object does not verify")
	// ErrWrongKey means the blob's root does not open under the key, or commits to another key.
	ErrWrongKey = errors.New("koloblobs: wrong key for this blob")
	// ErrTooLarge means a source longer than MaxSize, or an object over MaxObjectSize.
	ErrTooLarge = errors.New("koloblobs: too large")
	// ErrReadOnly means Put on a RemoteBackend, or on a LogBackend whose log cannot append.
	ErrReadOnly = errors.New("koloblobs: backend is read-only")
	// ErrClosed means a Read, ReadAt or Seek on a closed Reader.
	ErrClosed = errors.New("koloblobs: reader closed")
)

Tipos

type Backend

type Backend interface {
	// Get returns the object stored under h, or an error wrapping ErrNotFound. The caller does not modify it.
	// A Get that waits on the network returns when ctx is done.
	Get(ctx context.Context, h Hash) ([]byte, error)
	// Put stores obj under h, its SHA-256, atomically; an object already stored is not stored again. Put must not keep obj.
	Put(ctx context.Context, h Hash, obj []byte) error
}

Backend holds objects by hash. Implementations must be safe for concurrent use.

type FetchFunc

type FetchFunc func(ctx context.Context, index uint64) ([]byte, error)

FetchFunc returns the value of a content-log entry, checked by the transport; deleted or keyless entries wrap kololog.ErrDeleted or kololog.ErrKeyUnavailable.

type Hash

type Hash [HashSize]byte

Hash is the SHA-256 of an object, the name a Backend stores it under.

func (Hash) String
func (h Hash) String() string

String returns the hash as lowercase hex.

type ID

type ID [HashSize]byte

ID is a blob's content ID: the hash of its root object.

func (ID) String
func (id ID) String() string

String returns the ID as lowercase hex.

type Key

type Key [KeySize]byte

Key is a file key, for one file and its versions only; it formats and logs as [redacted].

func NewKey
func NewKey() Key

NewKey returns a random file key; use a new one for each file.

func (Key) Format
func (Key) Format(f fmt.State, _ rune)

Format writes [redacted] for every verb, so no fmt verb prints the key.

func (Key) LogValue
func (Key) LogValue() slog.Value

LogValue returns [redacted].

func (Key) MarshalJSON
func (Key) MarshalJSON() ([]byte, error)

MarshalJSON returns "[redacted]"; store a key only in a binary encoding.

func (Key) String
func (Key) String() string

String returns [redacted].

type LocateFunc

type LocateFunc func(h Hash) (uint64, bool)

LocateFunc returns the content-log index of the object h, or false if it does not know it.

type Log

type Log interface {
	Len() uint64
	Get(index uint64) ([]byte, error)
	EntryInfo(index uint64) (kololog.EntryInfo, error)
}

Log is what a LogBackend reads: a kolo-store or kolo-log log or replica. One with an Append(v any) (uint64, error) method, such as a log, can also be written to. Get and EntryInfo must be safe for concurrent use: a LogBackend reads several entries at once when it indexes a log.

type LogBackend

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

LogBackend keeps objects as entries of a log, one per entry, indexed by hash on first use; it is safe for concurrent use.

func NewLogBackend
func NewLogBackend(l Log) *LogBackend

NewLogBackend returns a Backend on l. Put appends to l if l has an Append method, and returns ErrReadOnly otherwise.

func (LogBackend) Get
func (b *LogBackend) Get(ctx context.Context, h Hash) ([]byte, error)

Get returns the object stored under h, or ErrNotFound. Entries that are deleted or whose kolo-log key is not here cannot be read, and their objects are not found. ctx bounds the index scan.

func (LogBackend) Index
func (b *LogBackend) Index(ctx context.Context, h Hash) (uint64, error)

Index returns the entry index of the object h in the log, or an error wrapping ErrNotFound; a deleted entry is not found. ctx bounds the index scan.

func (LogBackend) Put
func (b *LogBackend) Put(ctx context.Context, h Hash, obj []byte) error

Put appends obj as a new entry unless the log already holds it live. It returns ErrInvalidArgument if h is not the SHA-256 of obj and ErrTooLarge over MaxObjectSize. ctx bounds the index scan.

type Reader

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

Reader reads one blob as an io.Reader, io.ReaderAt and io.Seeker, checking every object before returning its bytes; it is safe for concurrent use, one call at a time.

func (Reader) Close
func (r *Reader) Close() error

Close clears the reader's key material and chunk; later reads return ErrClosed. Closing twice is fine.

func (Reader) Read
func (r *Reader) Read(p []byte) (int, error)

Read reads from the current offset and advances it.

func (Reader) ReadAt
func (r *Reader) ReadAt(p []byte, off int64) (int, error)

ReadAt reads len(p) bytes from offset off, or up to the end of the blob with io.EOF.

func (Reader) Seek
func (r *Reader) Seek(offset int64, whence int) (int64, error)

Seek sets the offset of the next Read, as io.Seeker; an offset past the end reads io.EOF.

func (Reader) Size
func (r *Reader) Size() int64

Size returns the blob's size in bytes.

type RemoteBackend

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

RemoteBackend reads objects from a content log on another peer, one entry per object; it is read-only and safe for concurrent use if fetch and locate are.

func NewRemoteBackend
func NewRemoteBackend(fetch FetchFunc, locate LocateFunc) *RemoteBackend

NewRemoteBackend returns a Backend that finds an object's entry with locate and gets it with fetch.

func (RemoteBackend) Get
func (b *RemoteBackend) Get(ctx context.Context, h Hash) ([]byte, error)

Get fetches the entry holding h; an unknown object or a deleted or keyless entry is ErrNotFound.

func (RemoteBackend) Put
func (b *RemoteBackend) Put(context.Context, Hash, []byte) error

Put returns ErrReadOnly: objects are written on the peer that owns the content log.

type Stats

type Stats struct {
	BytesWritten   uint64 // plaintext bytes Write read from its sources
	BytesRead      uint64 // plaintext bytes returned by Readers
	ObjectsPut     uint64 // objects passed to Backend.Put
	ObjectsFetched uint64 // objects returned by Backend.Get
	Rejected       uint64 // fetched objects that failed a check
}

Stats are a Store's totals since New.

type Store

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

Store writes and reads blobs on a Backend; it is safe for concurrent use.

func New
func New(b Backend) *Store

New returns a Store on b.

func (Store) Objects
func (s *Store) Objects(ctx context.Context, id ID, key Key) iter.Seq2[Hash, error]

Objects lists the hash of every object of the blob id, root first, fetching the nodes but not the chunks; it stops at the first error, yielded with a zero Hash.

func (Store) Open
func (s *Store) Open(ctx context.Context, id ID, key Key) (*Reader, error)

Open returns a Reader for the blob id under key after checking the root: ErrWrongKey for another key, ErrNotFound if the backend lacks it. The Reader passes ctx to every Backend.Get it makes.

func (Store) Stats
func (s *Store) Stats() Stats

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

func (Store) Write
func (s *Store) Write(ctx context.Context, key Key, src io.Reader) (ID, error)

Write reads src to its end, stores it as a blob under key and returns its ID; the same bytes and key give the same ID, so a Write killed part way is resumed by running it again. It checks ctx between chunks.

Chunking, sealing and Put run as a pipeline, so a Write uses several cores and a slow Put does not hold up the chunker. Put is still called from one goroutine, one object at a time in chunk order, so the objects, the tree and the ID are those of a Write that does everything in turn. A panic of src or of Put reaches the caller of Write.

Bom saber

Os mesmos bytes com a mesma chave dão o mesmo ID e não guardam nenhum objeto novo. Assim, um Write que foi parado ou morto é retomado rodando-o de novo com a mesma chave e a mesma fonte, e uma versão nova escrita com a chave do arquivo guarda só os fragmentos que mudaram. A kolo-store acrescenta cada entrada de forma atômica e a sincroniza no disco, então uma escrita morta deixa só entradas inteiras. O custo de retomar é ler a fonte e calcular o hash dela de novo. Depois de uma falha ou um cancelamento, o Write para de ler a fonte na hora e não cifra mais fragmentos. Um pânico da fonte, do Put do backend ou da cifragem chega a quem chama o Write na goroutine dele, com o mesmo valor, então quem chama pode recuperá-lo; as goroutines da escrita terminam e os buffers dela são apagados.

Todos os passos

Ler e verificar um intervalo

Cada objeto é verificado contra o hash que o pai lista, então uma leitura retorna os bytes certos ou um erro, nunca bytes errados.

  1. Open busca a raiz pelo ID do blob, verifica que o hash SHA-256 dela é o ID, a descriptografa e verifica o compromisso da chave. Outra chave dá ErrWrongKey.
  2. ReadAt desce um nó por nível, escolhido pelos tamanhos dos filhos que o pai lista, e verifica cada nó contra o hash que o pai informa.
  3. Ele busca só os fragmentos que cobrem o intervalo. Cada um é verificado contra o seu hash, descriptografado, e tem o MAC de conteúdo calculado de novo antes de um byte ser retornado.
  4. Um objeto que falta ou foi alterado para a leitura com ErrNotFound ou ErrCorrupt. Os bytes de antes voltam com o erro, nunca um byte errado.
  5. Os objetos vêm de um Backend: um log local da kolo-store, uma réplica copiada com a kolo-sync ou entradas buscadas uma a uma em outro peer.

Um Reader é um io.Reader, um io.ReaderAt e um io.Seeker, seguro para uso concorrente. Chamadas concorrentes a ReadAt rodam uma de cada vez, porque o lock fica preso enquanto um fragmento é buscado, então use um Reader por goroutine para buscar em paralelo. ReadAt busca um nó por nível da árvore e os fragmentos que cobrem o intervalo, e io.NewSectionReader(r, start, length) dá um intervalo como fluxo. Cada objeto é verificado antes de qualquer byte dele ser retornado; uma leitura que encontra um objeto ruim ou ausente retorna os bytes anteriores e o erro. O leitor passa o contexto dado a Open para cada Backend.Get, então encerrar o contexto encerra as leituras com ctx.Err().

NewLogBackend guarda cada objeto como uma entrada de um log ou réplica da kolo-store ou da kolo-log. O primeiro Get, Put ou Index dele lê e decifra uma vez cada entrada viva do log que tem a chave, sob o lock do backend, para indexar as entradas pelo hash do objeto. Essa primeira varredura custa uma leitura do log inteiro, não do blob, e o contexto a encerra com ctx.Err(); as chamadas seguintes leem só as entradas acrescentadas desde então. As entradas sem chave são lidas de novo, em janelas de 64 entradas em até 4 goroutines, só quando um Get ou um Index não acha o objeto, nunca em um Put. Para ler intervalos de um log grande sem essa varredura, use NewRemoteBackend com um fetch que lê o log (Get) e um locate a partir de uma tabela de objetos que o escritor fez com Objects e Index.

NewRemoteBackend(fetch, locate) lê um log de conteúdo em outro peer, uma entrada por objeto, por exemplo com o Fetch por intervalos da kolo-sync e a prova de inclusão de cada entrada. Uma leitura de um intervalo com ele busca a raiz, um nó por nível e os fragmentos sob o intervalo. Uma entrada que o peer serve sem a chave da kolo-log, como faz um peer de fixação, é lida como ErrNotFound, a não ser que o leitor tenha essa chave. Um blob em um peer de fixação é lido de dois jeitos: faça pull do log dele para uma réplica e pegue as chaves das entradas de um dos aparelhos do dono; ou, para ler intervalos com o dono offline, pegue uma vez o head do dono e as chaves das entradas do blob com FetchHead e FetchKeys da kolo-sync, guarde-os e ligue o fetch ao FetchWithKeys da kolo-sync com esse head. A kolo-sync então abre cada entrada localmente com a chave guardada, depois de fechar o stream; nenhuma chave chega ao peer de fixação, que não tem nenhuma. Uma chave guardada que não confere é kolosync.ErrKeyMismatch, retornado envolvido. O README tem o código.

Limites

Todos são constantes do formato, não configurações: cada uma vem de algo fora da biblioteca, e mudar uma mudaria todos os IDs. Nenhuma limita o tamanho de um arquivo abaixo de MaxSize; um arquivo ocupa tantos fragmentos e nós quantos precisar.

  • MaxObjectSize, 4.128.764 bytes: o maior valor de entrada da kolo-log que a kolo-sync carrega, então todo objeto sincroniza. Um leitor compara o tamanho de um objeto com ele antes de calcular o hash ou decifrar.
  • ObjectOverhead, 48 bytes por objeto: o MAC do conteúdo (32) e a tag do GCM (16).
  • MaxChunkSize, 4.128.716 bytes, MaxObjectSize menos ObjectOverhead. Um fragmento é cortado ali quando nenhum ponto de corte é encontrado.
  • MinChunkSize, 262.144 bytes (256 KiB). Só o último fragmento de um blob é menor. Os fragmentos têm em média cerca de 1 MiB.
  • Fanout, 256 filhos por nó. Um nó cheio tem cerca de 10 KiB.
  • MaxHeight, 6 níveis: 256^6 fragmentos do tamanho mínimo passam de MaxSize, então nenhuma árvore honesta é mais alta, e um leitor recusa uma mais alta.
  • MaxSize, 2^63 - 1 bytes, o maior deslocamento do io.Seeker do Go. Uma fonte mais longa é ErrTooLarge.
  • KeySize e HashSize, 32 bytes. ID.String() e Hash.String() são hexadecimal em minúsculas.
  • Memória: Write roda o fragmentador, 2 goroutines de cifragem e o Put do backend como uma esteira, então mantém no máximo 5 fragmentos em andamento, cada um com um buffer de texto em claro e um buffer de objeto, mais o buffer do fragmentador e um nó pendente por nível da árvore. Um Reader mantém os nós do caminho até o último fragmento e o texto em claro desse fragmento. Nenhum dos dois depende do tamanho do arquivo: um arquivo gerado de 10 GiB é escrito e lido de volta com pico de heap de 54 MiB e pico de memória residente de 84 MiB, e de 82 MiB e 173 MiB por um log da kolo-store no Pebble, com GOMEMLIMIT=64MiB. Um LogBackend acrescenta o índice, que cresce com o log e não tem limite: cerca de 140 bytes de heap por entrada (142 medidos com 1 milhão de entradas), então um log de 10 milhões de entradas de um peer em que você não confia custa cerca de 1,4 GB depois de indexado.
  • Objects é a única operação cujo trabalho segue o tamanho que a raiz declara, e não os bytes pedidos: cerca de um hash por MinChunkSize do tamanho declarado, até cerca de 2^45 para MaxSize, com uma busca de nó a cada 256. Dê a ela um contexto com prazo para blobs de escritores em que você não confia.

Segurança

  • A criptografia é criptografia determinística com uma chave derivada do conteúdo. O HKDF-SHA256 (RFC 5869) deriva três subchaves da chave do arquivo: uma chave de MAC do conteúdo, uma chave de objeto e a tabela que o fragmentador usa. Um objeto é um HMAC-SHA256 (RFC 2104) de 32 bytes do rótulo de tipo e do texto em claro sob a chave de MAC do conteúdo, seguido do texto em claro selado com AES-256-GCM (NIST SP 800-38D) sob uma chave que é o HMAC desse valor sob a chave de objeto, com um nonce fixo. Cada chave derivada criptografa um único texto em claro. Ao abrir, o leitor calcula o MAC de novo e recusa uma diferença com ErrCorrupt, então cada texto em claro tem exatamente um objeto.
  • A deduplicação fica dentro de uma chave. Sem a chave ninguém consegue calcular um objeto, o hash dele ou os pontos de corte para um arquivo suposto, então quem tem os objetos não consegue testar se um arquivo conhecido está guardado. Chaves diferentes nunca compartilham um objeto.
  • A raiz guarda SHA-256("kolo-blobs/key/v0" ‖ key), verificado ao abrir, então um ID abre com uma única chave, e cada outro objeto fica fixado pelo hash na árvore: um ID dá um único texto em claro. Cada tipo de objeto (fragmento, nó, raiz) tem o próprio rótulo, e um objeto de um tipo nunca abre como outro.
  • O ID, o SHA-256 do objeto raiz, se compromete com a chave, o tamanho, a forma da árvore e cada fragmento, vem só do conteúdo e da chave, e não revela nada do conteúdo sem a chave.
  • O que o armazenamento vê: em um Backend puro, o tamanho exato de cada objeto (o do fragmento mais 48 bytes), hashes repetidos e o número de objetos por escrita. Só o LogBackend preenche: cada objeto é uma entrada da kolo-log, criptografada de novo com uma chave de entrada que o peer de armazenamento não tem e preenchida pela kolo-log, então um peer de fixação vê quantas entradas existem e os tamanhos com preenchimento, e quantas entradas novas cada versão acrescenta. Um peer que serve Fetch ou FetchWithKeys para um RemoteBackend vê a identidade do leitor, quais entradas ele busca e quando, os tamanhos delas e o tamanho do head contra o qual ele confere, então fica sabendo a forma da árvore, qual blob é aberto, quais intervalos dele são lidos e onde uma leitura para. Nunca fica sabendo o conteúdo nem as chaves.
  • Os tamanhos dos fragmentos vêm de uma tabela derivada da chave do arquivo, então os pontos de corte não podem ser comparados entre chaves. Com a mesma chave, alguém que conhece ou escolhe parte de um arquivo e vê os tamanhos dos fragmentos pode aprender o bastante dessa tabela para testar palpites sobre outro conteúdo com essa chave a partir dos tamanhos dos fragmentos.
  • Duas camadas de chaves em um log: as chaves de entrada da kolo-log protegem cada entrada em trânsito e em cada peer, e só viajam para peers com acesso Keys da kolo-sync; a chave do arquivo protege o blob e viaja com o ID para quem pode lê-lo. Um peer de fixação não tem nenhuma das duas. O teste da biblioteca despeja o armazenamento de um peer de fixação e não encontra nenhuma chave de arquivo, subchave, chave de entrada, objeto de blob nem texto em claro.
  • Um valor Key, um ponteiro para um ou um em um campo exportado de struct é impresso e registrado como [redacted] com fmt, slog e encoding/json. Em um campo não exportado de struct, %v e %+v do fmt e o handler de texto do slog imprimem os bytes crus, então nunca guarde uma chave em um campo não exportado de uma struct que é impressa ou registrada. key[:] dá os bytes; guarde-os só criptografados. Nenhum erro leva bytes de chave nem conteúdo.
  • Reader.Close apaga as subchaves e o buffer de fragmento do leitor. As cópias internas das chaves de objeto nas cifras AES ficam na memória até o runtime reutilizá-las, como na kolo-log.
  • A exclusão é de melhor esforço, e esta biblioteca nunca exclui. Uma camada acima que remove um blob exclui as entradas dele do log com o Delete da kolo-log, que vale nos peers que seguem o protocolo; um peer que já tem a chave da entrada pode ficar com os dados. Veja Exclusão. Versões escritas com a mesma chave, e reescritas idênticas, compartilham entradas, então excluir os Objects de uma versão quebra as outras: exclua só as entradas que nenhum blob mantido com a chave lista. Os objetos de uma escrita que nunca terminou ficam no log até serem excluídos.

Construir um sistema de atualização por cima

São fatos da biblioteca, não um recurso: a kolo-blobs não tem um sistema de atualização.

  • Cada objeto é verificado contra o seu hash antes de devolver os bytes, então ler um blob até o fim verifica tudo contra o ID dele.
  • Uma leitura de intervalo busca só os fragmentos que cobrem o intervalo, mais um nó da árvore por nível.
  • O mesmo conteúdo só é deduplicado com a mesma chave. A kolo-files dá uma chave a cada arquivo, então conteúdo novo escrito no mesmo caminho de um volume da kolo-files reaproveita os fragmentos que não mudaram.
  • Um peer de fixação serve só texto cifrado.

Limites conhecidos

  • Sem instruções AES na CPU (algumas CPUs de 32 bits ou embarcadas), o AES em software do Go é mais lento.
  • A primeira varredura do LogBackend lê cada entrada viva com chave do log, então em um log grande a primeira leitura de um intervalo custa essa varredura. RemoteBackend com uma tabela de objetos evita isso.
  • Todos os testes rodam em 127.0.0.1. Experimental. A API pode mudar antes da v1.0.0.

Erros

ErroMensagem
ErrClosedkoloblobs: reader closed
ErrCorruptkoloblobs: object does not verify
ErrInvalidArgumentkoloblobs: invalid argument
ErrNotFoundkoloblobs: object not found
ErrReadOnlykoloblobs: backend is read-only
ErrTooLargekoloblobs: too large
ErrWrongKeykoloblobs: wrong key for this blob

Teste os erros com errors.Is; nenhum leva bytes de chave nem conteúdo. ErrNotFound também cobre uma entrada excluída e uma sem a chave em um LogBackend, e um objeto que locate não conhece ou que fetch informa como excluído ou sem chave em um RemoteBackend. Uma raiz que não abre com a chave, ou que se compromete com outra chave, é ErrWrongKey, e o mesmo vale para um objeto que não é a raiz dado como ID. Os erros da fonte e do backend voltam envolvidos, e Write retorna ctx.Err() quando o contexto termina.

Referências