kolo docsbeta

kolo-files

Uma árvore criptografada de arquivos e pastas com todo o histórico. Recupere qualquer versão anterior, compare duas e mantenha só os arquivos de que um aparelho precisa.

Nesta página

A kolo-files guarda pastas, nomes e versões sobre a kolo-blobs, com os nomes na forma de normalização Unicode C (UAX #15). Um Volume é uma árvore de arquivos e pastas guardada em dois logs da kolo-store de um mesmo dono: um log de metadados com uma op por mudança (criar uma pasta, escrever um arquivo, mover, excluir) e um log de conteúdo com objetos da kolo-blobs. A árvore é reconstruída reproduzindo o log de metadados, e cada op é uma versão: Snapshot recupera qualquer árvore anterior e Diff compara duas. Cada arquivo tem a própria chave, guardada dentro da op de criação dele, então um peer de fixação da kolo-pin que tenha os dois logs não vê nem nomes, nem chaves, nem conteúdo. Volume e Snapshot implementam io/fs, então fs.WalkDir, fs.ReadFile e fs.Glob funcionam com eles; para escrever um em disco, siga Escrever um volume em disco, não os.CopyFS. Um leitor guarda uma réplica do log de metadados e lê o conteúdo de uma réplica de conteúdo ou, entrada por entrada, de outro peer; as marcas escolhem quais arquivos um aparelho mantém. O pacote Go se chama kolofiles.

Todos os passos

Ops, nós e caminhos

Nenhuma árvore é guardada em disco. Ela é reconstruída reproduzindo o log de metadados desde a primeira entrada.

  1. Cada mudança é uma op do log de metadados. A entrada 0 é VOLUME, que nomeia o log de conteúdo. REMOVE e PURGE, das exclusões, não são desenhadas.
  2. Uma op nomeia um nó, não um caminho. Cada arquivo e cada pasta recebe um ID de nó aleatório de 16 bytes ao ser criado. A raiz é o ID com todos os bytes em zero.
  3. Um movimento é uma op que define o pai e o nome de um nó. O ID do nó continua o mesmo, então uma pasta movida leva a subárvore junto e o histórico acompanha o arquivo.
  4. Reproduzir o log constrói a árvore. Um caminho segue o io/fs: separado por barras, nomes em NFC sem caracteres de controle e, por padrão, no máximo 765 bytes por nome e 2048 nomes de profundidade.

Instalação

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

Compila com CGO_ENABLED=0 para gerar um binário só em Go. Compartilhe arquivos entre dois terminais mostra passo a passo como compartilhar uma pasta e cada versão nova dela com outro peer.

Início rápido

Este programa guarda uma árvore pequena em um volume em disco, em um diretório temporário. Ele lista a árvore, recupera uma versão anterior, compara duas versões e exclui um arquivo.

main.go
package main

import (
	"context"
	"fmt"
	"io/fs"
	"log"
	"os"
	"path/filepath"
	"strings"

	kolofiles "github.com/ciranda-dev/kolo-files"
	koloid "github.com/ciranda-dev/kolo-id"
	kolostore "github.com/ciranda-dev/kolo-store"
)

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

	// Two kolo-store logs of one owner on disk: one for names and versions, one for content.
	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)
	}
	meta, err := st.Create(me)
	if err != nil {
		log.Fatal(err)
	}
	content, err := st.Create(me)
	if err != nil {
		log.Fatal(err)
	}
	v, err := kolofiles.Create(meta, content)
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()

	must := func(err error) {
		if err != nil {
			log.Fatal(err)
		}
	}
	// Every call below is one op, so every call makes a version.
	must(v.Mkdir("notes"))
	must(v.WriteFile(ctx, "notes/todo.txt", strings.NewReader("buy bread")))
	first := v.Len()
	must(v.WriteFile(ctx, "notes/todo.txt", strings.NewReader("buy bread and milk")))
	must(v.Move("notes/todo.txt", "notes/shopping.txt"))
	must(v.WriteFile(ctx, "draft.txt", strings.NewReader("not for keeping")))

	list := func(name string, fsys fs.FS) {
		fmt.Println(name)
		must(fs.WalkDir(fsys, ".", func(p string, d fs.DirEntry, err error) error {
			if err != nil || d.IsDir() {
				return err
			}
			b, err := fs.ReadFile(fsys, p)
			fmt.Printf("  %s: %s\n", p, b)
			return err
		}))
	}
	list("now:", v)
	old, err := v.Snapshot(first)
	must(err)
	list(fmt.Sprintf("at version %d:", first), old)

	changes, err := v.Diff(first, v.Len())
	must(err)
	for _, c := range changes {
		fmt.Printf("changed: %q -> %q, content modified: %v\n", c.Old, c.New, c.Modified)
	}

	// Delete destroys the name, the key and every object of the file; no version shows it again.
	must(v.Delete("draft.txt"))
	_, err = v.Stat("draft.txt")
	fmt.Println("draft.txt after delete:", err)
}

Ele imprime:

Texto
now:
  draft.txt: not for keeping
  notes/shopping.txt: buy bread and milk
at version 3:
  notes/todo.txt: buy bread
changed: "" -> "draft.txt", content modified: false
changed: "notes/todo.txt" -> "notes/shopping.txt", content modified: true
draft.txt after delete: kolofiles: stat draft.txt: file does not exist

Create escreve a entrada 0, então um volume vazio é a versão 1. Mkdir faz a versão 2 e o primeiro WriteFile a versão 3, por isso first vale 3. Entre a versão 3 e agora há duas mudanças: draft.txt foi adicionado, e todo.txt foi renomeado e editado, que é uma única mudança porque o nó é o mesmo.

Referência da API

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

Pacote kolofiles · github.com/ciranda-dev/kolo-files · v0.1.0

Package kolofiles keeps a tree of files and folders with its whole history in two Kolo logs: names, folders and versions on top of kolo-blobs.

A Volume is a metadata log of ops (one entry per change: mkdir, create, write, move, remove, purge) and a content log of kolo-blobs objects, both kolo-store logs of one owner. The tree is rebuilt by replaying the metadata log; every op is a version, so any earlier tree can be checked out with Snapshot and compared with Diff. Each file has its own kolo-blobs key, kept inside its create op, so a pinning peer that holds both logs sees neither names, keys nor content. Delete destroys every name, key and object of a file or folder with kolo-log's deletion. Volume and Snapshot implement io/fs. A reader opens a replica of the metadata log and reads content from a content replica or, entry by entry, from another peer; marks choose per path which files a device keeps.

Experimental: the API may change before v1.0.0.

Constantes

const (
	// DefaultMaxDepth is the default of WithMaxDepth: the deepest tree one Linux path argument can name.
	DefaultMaxDepth = 2048
	// DefaultMaxNameLength is the default of WithMaxNameLength, in bytes: 255 UTF-16 units of at most 3 bytes each.
	DefaultMaxNameLength = 765
)

Variáveis

var (
	// ErrNotDir means an element of a path that should be a directory is a file.
	ErrNotDir = errors.New("kolofiles: not a directory")
	// ErrIsDir means a file operation on a directory.
	ErrIsDir = errors.New("kolofiles: is a directory")
	// ErrLimit means a path or a log over MaxDepth or MaxNameLength, or an op to append over the largest entry kolo-sync carries.
	ErrLimit = errors.New("kolofiles: over a bound")
	// ErrReadOnly means a write on a reader.
	ErrReadOnly = errors.New("kolofiles: read-only volume")
	// ErrClosed means a call on a closed Volume, or on a Snapshot or file of one.
	ErrClosed = errors.New("kolofiles: volume closed")
	// ErrCorrupt means the log is not a kolo-files log, or an op or an object table breaks a rule of the format.
	ErrCorrupt = errors.New("kolofiles: corrupt volume")
	// ErrUnsafeName means LocalPath refused a name the host reserves for a device (some versions open the device
	// instead) or cannot create.
	ErrUnsafeName = errors.New("kolofiles: name not allowed on this system")
	// ErrInvalidArgument means a nil, out of range or mismatched argument, or a mark where marks do not apply.
	ErrInvalidArgument = errors.New("kolofiles: invalid argument")
)

Funções

func ContentLog

func ContentLog(meta *kolostore.Replica) (kololog.LogID, error)

ContentLog returns the ID of the content log that the volume in meta names in its first entry.

func LocalPath

func LocalPath(name string) (string, error)

LocalPath converts a path of a volume into a path for the host operating system. On Windows it refuses with ErrUnsafeName a name Windows reserves for a device (some versions open the device instead) or cannot create: CON, NUL.txt, COM1 and the other device names, one of < > : " | ? * \, a trailing dot or space, a control character, or more than 255 UTF-16 units. A path that is not an io/fs path, or holds a NUL, is fs.ErrInvalid. Errors are *fs.PathError.

LocalPath checks names only and never looks at the disk. To write a volume to disk, create each folder and file under an os.Root with Mkdir and O_CREATE|O_EXCL, so a name aliasing another (case, a Windows 8.3 short name) fails with fs.ErrExist instead of overwriting, and no link leads outside the directory, as the example does.

Tipos

type Change

type Change struct {
	Node     NodeID
	Old, New string // the path at the older and at the newer version; empty where the node is not in the tree
	Modified bool   // the file's content differs
	Deleted  bool   // the node was deleted between the versions; its paths are destroyed with it
}

Change is one node that differs between two versions, as Diff reports it.

type Mark

type Mark uint8

Mark says what a reader device keeps of a file; a directory's mark applies to everything below it.

const (
	// MarkInherit clears a mark: the node takes its nearest marked ancestor's mark.
	MarkInherit Mark = iota
	// MarkFetchOnDemand fetches only the objects a read needs, when it needs them, and keeps none. The root's default.
	MarkFetchOnDemand
	// MarkKeepLocal keeps every object of the file's current version on the device, so it reads offline.
	MarkKeepLocal
)
func (Mark) String
func (m Mark) String() string

String returns the mark's name.

type NodeID

type NodeID [16]byte

NodeID identifies a file or directory for its whole life; moves and renames keep it. The root is the zero ID.

func (NodeID) String
func (id NodeID) String() string

String returns the ID as lowercase hex.

type NodeInfo

type NodeInfo struct {
	ID      NodeID
	Version uint64       // the version in which the node last changed: the length of the log after its last op
	Blob    koloblobs.ID // the blob of a file's content; zero for a directory
}

NodeInfo is what fs.FileInfo.Sys returns for a file or directory of a Volume or Snapshot.

type Option

type Option func(*options)

Option configures Create, Open and the readers.

func WithMaxDepth
func WithMaxDepth(n int) Option

WithMaxDepth sets how many names below the root a path may have, at least 1; the default is DefaultMaxDepth.

func WithMaxNameLength
func WithMaxNameLength(n int) Option

WithMaxNameLength sets the longest name in bytes after NFC, 1 to the largest op; the default is DefaultMaxNameLength.

type Snapshot

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

Snapshot is the tree at one version of a volume; it is immutable, safe for concurrent use and needs no closing. Its reads go through the volume, so they fail with ErrClosed once the volume is closed.

func (Snapshot) Open
func (s *Snapshot) Open(name string) (fs.File, error)

Open opens a file or directory of the snapshot for reading, as Volume.Open.

func (Snapshot) OpenContext
func (s *Snapshot) OpenContext(ctx context.Context, name string) (fs.File, error)

OpenContext is Open with a context that bounds every content read of the file it returns.

func (Snapshot) ReadDir
func (s *Snapshot) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir lists a directory of the snapshot, as Volume.ReadDir.

func (Snapshot) Stat
func (s *Snapshot) Stat(name string) (fs.FileInfo, error)

Stat describes a file or directory of the snapshot, as Volume.Stat.

func (Snapshot) Version
func (s *Snapshot) Version() uint64

Version returns the snapshot's version: the length of the metadata log it was replayed from.

type Stats

type Stats struct {
	Ops            uint64 // ops appended to the metadata log
	Replayed       uint64 // entries replayed by opens, refreshes, snapshots and diffs
	BytesWritten   uint64 // file content read by WriteFile
	BytesRead      uint64 // file content returned by files
	ObjectsFetched uint64 // objects from the content backend
	ObjectsLocal   uint64 // objects served by the local backend of a reader
}

Stats are a Volume's totals since it was opened.

type Volume

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

Volume is a tree of files and folders kept in a metadata log and a content log. It is safe for concurrent use. A Volume from Create or Open writes; one from a reader constructor reads a replica.

func Create
func Create(meta, content *kolostore.Log, opts ...Option) (*Volume, error)

Create starts a new volume in meta and content, two empty logs of one owner with the kololog.Bytes encoding, and takes them over: Close closes them. If Create fails, the logs stay open.

func Open
func Open(meta, content *kolostore.Log, opts ...Option) (*Volume, error)

Open rebuilds the volume in meta, your own metadata log, with content, the log its first entry names, and takes them over. It finishes a Delete that a crash interrupted. If Open fails, the logs stay open.

func OpenFetchReader
func OpenFetchReader(meta *kolostore.Replica, fetch koloblobs.FetchFunc, local kolostore.Backend, opts ...Option) (*Volume, error)

OpenFetchReader is OpenReader with content read from another peer, one content log entry per fetch call.

func OpenReader
func OpenReader(meta *kolostore.Replica, content koloblobs.Backend, local kolostore.Backend, opts ...Option) (*Volume, error)

OpenReader rebuilds a read-only volume from meta, a replica of the owner's metadata log, and takes it over. content holds the objects, local (may be nil) the marks and kept objects. If it fails, the replica stays open.

func (Volume) Close
func (v *Volume) Close() error

Close closes the volume and the logs or the replica it took over, not the backends. It waits for a running WriteFile, Prefetch or Refresh, for example on a stalled fetch, until that call's context ends. A second Close returns nil.

func (Volume) Delete
func (v *Volume) Delete(name string) error

Delete removes the file or directory name with everything below it and destroys every name, file key and object it held. The root cannot be deleted; a delete that fails after its REMOVE op is finished by the next Open.

func (Volume) Diff
func (v *Volume) Diff(a, b uint64) ([]Change, error)

Diff returns one Change per node added, moved, modified or deleted between versions a and b, 1 <= a <= b <= Len, sorted by path, then node ID. A node deeper than MaxDepth, which only a hostile log has, has empty paths.

func (Volume) ID
func (v *Volume) ID() kololog.LogID

ID returns the volume's ID, the ID of its metadata log.

func (Volume) Len
func (v *Volume) Len() uint64

Len returns the number of metadata log entries the tree is built from, which is the current version. On a reader it is at most the size of the replica's last verified head, and less while an entry key or a purge op is missing.

func (Volume) Mark
func (v *Volume) Mark(name string) (Mark, error)

Mark returns the mark set on a path itself, MarkInherit when it has none.

func (Volume) Mkdir
func (v *Volume) Mkdir(name string) error

Mkdir creates the directory name; its parent must exist, and an existing name is fs.ErrExist.

func (Volume) Move
func (v *Volume) Move(from, to string) error

Move renames or moves from to the path to, whose parent must exist; a directory moves with everything below it. An existing to is fs.ErrExist; the root, or a move into from's own subtree, is fs.ErrInvalid.

func (Volume) Open
func (v *Volume) Open(name string) (fs.File, error)

Open opens a file or directory for reading, as fs.FS: a file is also an io.ReaderAt and io.Seeker, a directory an fs.ReadDirFile. Reads of remote content cannot be cancelled; use OpenContext for that.

func (Volume) OpenContext
func (v *Volume) OpenContext(ctx context.Context, name string) (fs.File, error)

OpenContext is Open with a context that bounds every content read of the file it returns.

func (Volume) Prefetch
func (v *Volume) Prefetch(ctx context.Context) error

Prefetch reads every MarkKeepLocal file's current version through the local backend, keeping its objects and dropping those of older versions. It goes on after a file fails and returns every error. It holds the change lock, so Refresh, SetMark and Close wait for it: end a long one with ctx.

func (Volume) ReadDir
func (v *Volume) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir lists a directory sorted by name in byte order, as fs.ReadDirFS.

func (Volume) Refresh
func (v *Volume) Refresh() error

Refresh brings a reader up to its replica's latest verified head, in place when it can, else by a full replay. Len may go down. On a writer it does nothing. On an error before the new tree is installed it stays as it was; an error from the clean-up of the local backend after that leaves the new tree.

func (Volume) SetMark
func (v *Volume) SetMark(name string, m Mark) error

SetMark sets the mark of a path on this reader device, MarkInherit clears it; a directory's mark covers everything below it. Marks need a reader opened with a local backend.

func (Volume) Snapshot
func (v *Volume) Snapshot(ver uint64) (*Snapshot, error)

Snapshot returns the tree after the first ver entries, 1 to Len. A deleted node is in no snapshot.

func (Volume) Stat
func (v *Volume) Stat(name string) (fs.FileInfo, error)

Stat describes a file or directory, as fs.StatFS; its Sys is a NodeInfo.

func (Volume) Stats
func (v *Volume) Stats() Stats

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

func (Volume) WriteFile
func (v *Volume) WriteFile(ctx context.Context, name string, src io.Reader) error

WriteFile creates the file name, whose parent must exist, or stores new content for an existing file, reading src to its end. Only changed chunks are stored; a write killed part way is resumed by calling it again.

Bom saber

Um caminho segue io/fs.ValidPath: separado por barras, relativo à raiz do volume, com . como a raiz. Um caminho que quebra uma regra é fs.ErrInvalid dentro de um *fs.PathError:

RegraDecisão
CodificaçãoUTF-8 válido
NormalizaçãoOs nomes são guardados em NFC, e todo caminho dado à API é normalizado antes, então e mais um acento agudo combinante e o é pré-composto são um mesmo nome
Pontos de código não atribuídosRecusados ao criar um nome (na versão do Unicode da versão do Go); um leitor os aceita, pois as tabelas de um escritor mais novo podem conhecer mais
Caracteres de controleRecusados (categoria geral Cc)
., .., vazio, / em um nomeRecusados
MaiúsculasOs nomes são comparados byte a byte: README e readme podem existir juntos, e renomear só a caixa é um movimento comum
Regras só do Windows (<>:"|?*, CON e os demais nomes de dispositivo com ou sem extensão, um ponto ou espaço no fim, mais de 255 unidades UTF-16)Permitidas, porque outros sistemas criam esses nomes; o código que escreve um volume em disco converte cada caminho com LocalPath, que no Windows os recusa com ErrUnsafeName (filepath.Localize sozinho aceita NUL.txt e <>|?*"; os.CopyFS não usa estas regras). Veja Escrever um volume em disco
Tamanho do nomeNo máximo MaxNameLength bytes após o NFC, 765 por padrão (DefaultMaxNameLength)
ProfundidadeNo máximo MaxDepth nomes abaixo da raiz, 2048 por padrão (DefaultMaxDepth)

Cada arquivo e cada pasta tem um NodeID aleatório de 16 bytes, escolhido ao ser criado e que nenhum movimento nem renomeação muda. As ops se referem a nós, nunca a caminhos, então renomear é uma op, uma pasta movida leva a subárvore junto e o histórico acompanha um arquivo através das renomeações. FileInfo.Sys() é um NodeInfo: o ID do nó, a versão em que ele mudou pela última vez e o ID do blob. Stat informa os arquivos como 0444 e as pastas como fs.ModeDir | 0555; a hora de modificação é o relógio do escritor na op, só para exibição. As listagens vêm ordenadas por nome, byte a byte. Um arquivo também é um io.ReaderAt e um io.Seeker, e a leitura de um intervalo busca um nó por nível da árvore e os fragmentos que o cobrem. OpenContext dá a um arquivo um contexto que encerra as leituras dele.

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.

WriteFile cria um arquivo (a pasta pai dele precisa existir) ou guarda conteúdo novo para um existente, lendo a fonte até o fim. Só os fragmentos que mudaram em relação às versões anteriores são guardados, porque a kolo-blobs deduplica dentro de uma mesma chave, e uma escrita morta é retomada chamando-a de novo com o mesmo conteúdo. ctx é verificado entre fragmentos. Mkdir precisa da pasta pai e falha com fs.ErrExist se o nome já existe. Move renomeia ou move um arquivo ou uma pasta inteira; a pasta pai do destino precisa existir e o destino não (fs.ErrExist), mover um nó para dentro da própria subárvore ou mover a raiz é fs.ErrInvalid, e mover para o mesmo caminho não faz nada. Um Volume e um Snapshot são seguros para uso concorrente. As escritas são serializadas do início da escrita de um blob até o acréscimo da op, as leituras nunca esperam a escrita de um blob, e um acréscimo que falha deixa a árvore como estava.

Nomes

Um nome é uma string UTF-8 em NFC. Um caminho dado em outra forma é normalizado primeiro, então é digitado como e mais um acento combinante e o é pré-composto são um só nome, e os bytes originais não são guardados. Os nomes são comparados byte a byte, então maiúsculas e minúsculas são mantidas e README e readme podem coexistir. Caracteres de controle, nomes vazios, . e .. são recusados.

Escrever um volume em disco

LocalPath converte um caminho do volume em um caminho para o sistema hospedeiro. No Windows recusa com ErrUnsafeName um nome que o Windows reserva para um dispositivo, em qualquer combinação de maiúsculas ASCII (CON, NUL.txt, COM1 e os demais, com ou sem extensão; algumas versões do Windows abrem o dispositivo em vez de criar um arquivo), um de <>:"|?*\, um ponto ou espaço no fim, um caractere de controle e um nome com mais de 255 unidades UTF-16. Ele só confere nomes e nunca olha o disco.

Um disco pode dar a dois nomes do volume uma só entrada: nomes que diferem apenas em maiúsculas em um disco que não as distingue (o padrão do macOS e do Windows), ou um nome curto 8.3 do Windows como LONGFI~1.TXT para longfilename.txt ou PROGRA~1 para uma pasta. Um link que já esteja no destino também pode levar para fora dele. Por isso crie cada pasta e cada arquivo sob um os.Root, com Mkdir e O_CREATE|O_EXCL: um alias então falha com fs.ErrExist em vez de sobrescrever outra entrada, e o os.Root recusa um caminho que sai do diretório. Este programa é o exemplo LocalPath da biblioteca, compilado e executado por go test. Ele escreve o volume em um diretório temporário e extrai a mesma árvore duas vezes; a segunda extração não sobrescreve nada:

main.go
package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"io/fs"
	"log"
	"os"
	"path/filepath"
	"strings"

	kolofiles "github.com/ciranda-dev/kolo-files"
	koloid "github.com/ciranda-dev/kolo-id"
	kolostore "github.com/ciranda-dev/kolo-store"
)

// checkout writes the tree of v into dir, which should be empty. Each folder and file is created under an
// os.Root, with Mkdir and O_EXCL, so a name that aliases one already written (a case-only pair on a
// case-insensitive disk, a Windows 8.3 short name) fails with fs.ErrExist instead of overwriting it, and no link
// leads outside dir.
func checkout(v fs.FS, dir string) error {
	root, err := os.OpenRoot(dir)
	if err != nil {
		return err
	}
	defer root.Close()
	return fs.WalkDir(v, ".", func(name string, d fs.DirEntry, err error) error {
		if err != nil || name == "." {
			return err
		}
		local, err := kolofiles.LocalPath(name)
		if err != nil {
			return err
		}
		if d.IsDir() {
			return root.Mkdir(local, 0o777)
		}
		src, err := v.Open(name)
		if err != nil {
			return err
		}
		defer src.Close()
		dst, err := root.OpenFile(local, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o666)
		if err != nil {
			return err
		}
		if _, err := io.Copy(dst, src); err != nil {
			dst.Close()
			return err
		}
		return dst.Close()
	})
}

func main() {
	st := kolostore.New(kolostore.NewMemory())
	defer st.Close()
	me, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	meta, err := st.Create(me)
	if err != nil {
		log.Fatal(err)
	}
	content, err := st.Create(me)
	if err != nil {
		log.Fatal(err)
	}
	v, err := kolofiles.Create(meta, content)
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()
	if err := v.Mkdir("notes"); err != nil {
		log.Fatal(err)
	}
	if err := v.WriteFile(context.Background(), "notes/todo.txt", strings.NewReader("buy bread")); err != nil {
		log.Fatal(err)
	}

	dir, err := os.MkdirTemp("", "checkout")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)
	if err := checkout(v, dir); err != nil {
		log.Fatal(err)
	}
	b, err := os.ReadFile(filepath.Join(dir, "notes", "todo.txt"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))
	// A second checkout into the same directory overwrites nothing.
	fmt.Println(errors.Is(checkout(v, dir), fs.ErrExist))
}

Ele imprime:

Texto
buy bread
true

os.CopyFS não substitui isso: ele segue links que já estão no destino, junta pastas cujos nomes só diferem em maiúsculas e, no Windows, renomeia um ponto ou espaço no fim e escreve nomes de dispositivo com extensão como NUL.txt, tudo sem erro. filepath.Localize sozinho também não basta: ele aceita NUL.txt e <>|?*".

Versões

Todos os passos

Versões, checkout e diff

Cada op é uma versão, então o histórico tem a granularidade de uma única mudança.

  1. Uma versão é o comprimento do log de metadados: a árvore depois das primeiras entradas. A versão 1 é a raiz vazia, e Len é a versão atual.
  2. Snapshot(3) reproduz as 3 primeiras entradas em uma árvore própria. Ela é imutável, não precisa ser fechada e é um sistema de arquivos io/fs.
  3. Snapshot(Len) é a árvore de agora. Aqui o log tem 6 entradas, então a versão atual é a 6.
  4. Diff(3, 6) retorna um Change para cada nó adicionado, movido, modificado ou excluído entre as duas, ordenados por caminho. Uma pasta movida é uma única mudança.
  5. A exclusão vence o histórico: um nó excluído não está em nenhum snapshot, como se nunca tivesse existido. Um diff só o mostra como um Change com Deleted ativo e sem caminhos.

Len é a versão atual: o número de entradas de metadados com que a árvore é construída. Snapshot(version), com version de 1 a Len, retorna a árvore depois das primeiras version entradas como um Snapshot imutável com os mesmos Open, OpenContext, ReadDir e Stat, e Version. A versão 1 é a raiz vazia. Diff(a, b), com 1 <= a <= b <= Len, retorna um Change para cada nó adicionado, movido, modificado ou excluído entre as duas, ordenados por caminho e depois por ID de nó; uma pasta movida é uma única mudança. A exclusão vence o histórico: um nó excluído não está em nenhum snapshot, como se nunca tivesse existido, e em um diff aparece só como um Change com Deleted ativo e sem caminhos. O conteúdo sobrescrito é mantido, então toda versão anterior de um arquivo vivo continua legível; só Delete remove histórico. Um Snapshot custa uma passada pelas primeiras version entradas.

Ler de outro aparelho

OpenReader(meta, content, local) monta um volume só de leitura a partir de uma réplica do log de metadados. content é um Backend da kolo-blobs, como koloblobs.NewLogBackend sobre uma réplica do log de conteúdo. OpenFetchReader(meta, fetch, local) lê o conteúdo de outro peer, onde fetch(ctx, index) busca uma entrada do log de conteúdo, por exemplo com o Fetch da kolo-sync, ou com FetchWithKeys a partir de um peer de fixação da kolo-pin que serve só texto cifrado enquanto o leitor tiver as chaves das entradas. O peer de fixação nunca recebe uma chave. O README tem o código, e kolofiles.ContentLog(meta) dá o ID do log de conteúdo a partir da primeira entrada.

Um leitor reproduz o prefixo mais longo que consegue reproduzir com exatidão: ele para em uma entrada que tem sem a chave e antes de uma entrada destruída que nenhum purge completo lista, e Len diz qual versão é essa. Refresh o atualiza até o head verificado mais recente da réplica, de forma incremental quando dá, e Len pode diminuir. Um refresh incremental confere cada entrada abaixo de Len em busca de um marcador de exclusão, então custa tempo em Len. Quando o dono muda o volume, faça pull do log de metadados de novo e chame Refresh; uma versão escrita depois do head que você guardou precisa de um head novo e das chaves dela. Um aparelho leitor guarda o log de metadados com as chaves de entrada, que vêm do dono ou de qualquer peer com acesso Keys da kolo-sync, e Close deixa abertos os backends local e content.

Sincronização seletiva

Todos os passos

Sincronização seletiva

As marcas são a escolha de um aparelho. O uso de disco não cresce sozinho: por padrão nada é mantido.

  1. Um leitor guarda uma réplica do log de metadados, então tem todos os nomes e todas as versões e pode listar e percorrer a árvore inteira.
  2. O conteúdo não é copiado por padrão. Com MarkFetchOnDemand, o valor da raiz, uma leitura busca de outro peer só os objetos de que precisa, um nó por nível da árvore e os fragmentos que cobrem o intervalo, e não mantém nenhum.
  3. MarkKeepLocal mantém todos os objetos da versão atual dos arquivos que cobre. Um nó sem marca assume a do ancestral marcado mais próximo, e a marca de uma pasta cobre os arquivos adicionados depois.
  4. Prefetch busca os objetos de cada arquivo mantido que faltam no aparelho e remove os objetos mantidos de versões antigas. Cada objeto mantido é conferido contra o hash dele.
  5. As marcas são guardadas por ID de nó no backend local deste aparelho e em nenhum outro lugar, então acompanham os movimentos e não estão em nenhum log compartilhado.

SetMark, Mark e Prefetch funcionam em um leitor aberto com um backend local. MarkKeepLocal mantém no aparelho todos os objetos da versão atual do arquivo, então ele é lido offline. MarkFetchOnDemand busca só os objetos de que uma leitura precisa e não mantém nada. MarkInherit limpa uma marca. Um nó sem marca assume a do ancestral marcado mais próximo, e o valor da raiz é MarkFetchOnDemand, então o uso de disco não cresce sozinho. As marcas são guardadas por ID de nó, então acompanham os movimentos, e são descartadas junto com o nó. Prefetch lê a versão atual de cada arquivo MarkKeepLocal pelo backend local, remove os objetos mantidos dele de versões antigas, segue em frente se um arquivo falha e retorna todos os erros. Um objeto mantido é conferido contra o hash dele antes de ser mantido e antes de ser servido; o que falha é descartado. Um movimento que coloca um arquivo sob um nó com outra marca, visto por Refresh, remove os objetos mantidos para ele. Uma marca é a escolha de um aparelho, então nunca está nos logs compartilhados. Marcas em um escritor, ou em um leitor sem backend local, são ErrInvalidArgument.

Stats retorna os totais desde a abertura, lidos com atômicos: Ops, Replayed, BytesWritten, BytesRead, ObjectsFetched e ObjectsLocal.

Exclusão

Delete remove um arquivo ou uma pasta com tudo que há abaixo e destrói o que eles guardavam. Ele acrescenta uma op REMOVE, que leva só o ID do nó, e ops PURGE que listam as entradas de metadados e de conteúdo da subárvore, cada uma abaixo da maior entrada que a kolo-sync carrega, e depois destrói essas entradas com o Delete da kolo-log. O que é destruído: todos os nomes que o nó já teve, a chave do arquivo dele (então todas as versões deixam de ser legíveis de uma vez nos peers que seguem o protocolo) e todos os objetos. O que fica: as ops REMOVE e PURGE (um ID de nó e índices de entradas), os registros assinados e os marcadores da kolo-log, e o fato de que houve uma exclusão. Uma queda em qualquer passo é concluída pelo próximo Open. A raiz não pode ser excluída. Veja Exclusão.

Limites

Os dois limites abaixo são configurações de segurança, não limites do produto, e cada um tem uma opção.

  • MaxDepth, 2048 por padrão (DefaultMaxDepth), com WithMaxDepth(n), no mínimo 1: a árvore mais profunda que cabe em um argumento de caminho do Linux (PATH_MAX 4096 com o NUL, nomes de um byte).
  • MaxNameLength, 765 bytes por padrão (DefaultMaxNameLength), com WithMaxNameLength(n), de 1 até a maior op, o MaxObjectSize da kolo-blobs (4.128.764 bytes), porque um nome precisa caber em uma op. 765 bytes comportam todos os nomes que o ext4 (255 bytes) e o Windows permitem: os nomes do Windows têm no máximo 255 unidades UTF-16, e uma unidade UTF-16 ocupa no máximo 3 bytes de UTF-8.
  • Um caminho acima de um limite é ErrLimit. Um escritor aplica os limites em cada criação e movimento, então um leitor com as mesmas configurações abre tudo o que o escritor escreveu. Um leitor confere uma criação ou um movimento reproduzidos só pela profundidade do nó que cria ou move, não pelos nós abaixo de uma pasta movida, então um log hostil pode pôr nós mais fundos que MaxDepth; um nó assim não tem caminho (buscá-lo dá ErrLimit e Diff o informa com caminhos vazios).
  • Todo o resto é limitado pelo que a kolo-store já aceitou: não há limite de arquivos, pastas, versões nem tamanho de arquivo.
  • Os percursos para cima na árvore (movimentos, caminhos, marcas) dão no máximo MaxDepth passos. Os percursos para baixo (uma exclusão, uma verificação antes de um movimento) dão no máximo tantos passos quantos nós. Todos os percursos são iterativos.
  • Uma tabela de objetos é lida como um fluxo: a contagem dela é conferida contra os objetos que cabem em um blob desse tamanho e contra o tamanho da tabela, e a memória cresce com os bytes que o blob da tabela realmente tem, não com o tamanho que um escritor declara.
  • Memória: a árvore atual fica na memória, cerca de 211 bytes por nó vivo com um nome de 10 bytes (BenchmarkStateNode, 64 bits, Apple M5, Go 1.27.3), mais o ID de cada nó que uma exclusão removeu, 8 bytes por entrada destruída, e o custo próprio da kolo-store por entrada. Reproduzir um log inteiro mantém cada op decodificada até aplicá-las, cerca de 344 bytes por entrada com um nome de 10 bytes (BenchmarkReplayEntry, a mesma máquina) além da árvore, então abra um volume muito grande com GOMEMLIMIT definido. Snapshots e diffs mantêm a própria árvore enquanto rodam e nada depois.

Segurança

  • Um peer que serve entradas a um leitor com Fetch ou FetchWithKeys vê quais entradas de conteúdo são buscadas e quando. Pela ordem (uma tabela, a raiz, um nó por nível, depois fragmentos) ele fica sabendo qual arquivo é aberto e quais intervalos são lidos, e o tamanho do head contra o qual o leitor confere.
  • Com a mesma chave de arquivo, fragmentos iguais são texto cifrado igual, então duas versões de um arquivo mostram quais fragmentos compartilham. Arquivos diferentes nunca compartilham um objeto, porque cada arquivo tem a própria chave.
  • Cada arquivo recebe uma chave da kolo-blobs ao ser criado, dentro da op de criação dele. As chaves não ficam na memória e nunca são devolvidas, impressas nem registradas; uma cópia lida do log é apagada depois do uso. Nenhum erro leva uma chave, conteúdo de arquivo nem bytes de uma entrada.
  • Cada versão escreve também uma tabela de objetos, um segundo blob sob a chave do arquivo que lista cada objeto do blob de conteúdo e a entrada do log de conteúdo que o guarda. Um leitor sem a réplica de conteúdo acha cada entrada por ela sem varrer o log, e Delete pode listar as entradas de todas as versões.
  • A exclusão é uma lápide de melhor esforço: vale em todo peer que segue o protocolo e aplica os marcadores de exclusão, e um peer que já recebeu uma chave pode ficar com os dados. Um leitor que vê entradas destruídas antes da op PURGE que as lista volta até logo antes delas até a op chegar, e descarta as marcas e os objetos mantidos dos nós removidos na próxima abertura ou refresh. Remover um objeto mantido do armazenamento Pebble local também é uma lápide, então os bytes antigos ficam até a compactação.
  • Uma escrita morta antes de a op ser acrescentada deixa objetos sem referência. Em um arquivo novo ninguém consegue lê-los, porque a chave dele nunca foi guardada; em um arquivo existente eles estão sob a chave desse arquivo e são destruídos quando o arquivo é excluído.
  • Um volume tem um único escritor, o dono. Um log com dependências de outro escritor é ErrCorrupt. Um leitor recusa com ErrCorrupt toda op que quebra uma regra do formato; o README lista as regras e os formatos.

Construir um sistema de atualização por cima

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

  • Uma versão é um comprimento do log de metadados assinado pelo dono, e Snapshot e Diff leem qualquer versão.
  • O ID de blob de cada arquivo está em NodeInfo, com Stat().Sys().
  • Prefetch busca só os objetos que o aparelho ainda não tem, e um Prefetch interrompido recomeça com os objetos que faltam.
  • A kolo-files não guarda modos de arquivo, bit executável nem links simbólicos, e Delete também tira um nó dos snapshots anteriores. Uma camada que instala aplicativos guarda os modos, os links simbólicos e os IDs de blob esperados no seu próprio manifesto assinado.

Limites conhecidos

  • Um único escritor.
  • Stat não informa outras permissões além de 0444 e 0555, e a hora de modificação é o relógio do escritor.
  • As regras de nomes só do Windows não são aplicadas dentro de um volume: escreva um volume em disco com LocalPath e a receita de Escrever um volume em disco. LocalPath só confere nomes.
  • Todos os testes rodam em 127.0.0.1. Experimental. A API pode mudar antes da v1.0.0.

Erros

ErroMensagem
ErrClosedkolofiles: volume closed
ErrCorruptkolofiles: corrupt volume
ErrInvalidArgumentkolofiles: invalid argument
ErrIsDirkolofiles: is a directory
ErrLimitkolofiles: over a bound
ErrNotDirkolofiles: not a directory
ErrReadOnlykolofiles: read-only volume
ErrUnsafeNamekolofiles: name not allowed on this system

Teste os erros com errors.Is; nenhum leva uma chave, conteúdo de arquivo nem bytes de uma entrada. Os erros de caminho são *fs.PathError com Op começando por kolofiles:, então fs.ErrNotExist, fs.ErrExist e fs.ErrInvalid conferem; os nomes aparecem só em PathError.Path, como quem chamou os deu. Os erros da kolo-blobs, da kolo-store e da kolo-log passam envolvidos. Um arquivo cujas entradas foram destruídas é lido como kololog.ErrDeleted (e fs.ErrNotExist). ErrLimit cobre também uma op a acrescentar acima da maior entrada que a kolo-sync carrega, ErrClosed cobre também a leitura de um Snapshot ou de um arquivo de um volume fechado, e ErrInvalidArgument cobre também uma versão fora do intervalo, logs de donos diferentes e um log não vazio dado a Create.

Referências

  • O pacote io/fs da biblioteca padrão do Go.
    • Usa: a sintaxe de caminhos (ValidPath), as interfaces FS, ReadDirFS, StatFS, File e ReadDirFile, PathError e seus sentinelas; path/filepath.Localize e os.Root para escrever um volume em disco.
    • Não implementa: nada.
  • Unicode Standard Annex #15, Unicode Normalization Forms (revisão 58, Unicode 18.0.0, 12 de agosto de 2026).
    • Usa: NFC para os nomes, e a política de estabilidade para os caracteres atribuídos.
    • Não implementa: NFKC e NFKD.
  • As regras de nomes de arquivo dos sistemas de arquivos POSIX, em palavras simples.
    • Usa: nenhum byte NUL e nenhum / em um nome.
    • Não implementa: nada.
  • As referências da kolo-blobs.
    • Usa: as chaves de arquivo, os objetos e a árvore sob cada arquivo, por meio da kolo-blobs.
    • Não implementa: veja as Referências da kolo-blobs.
  • RFC 9562, Universally Unique IDentifiers (UUIDs) (Proposed Standard, maio de 2024).
    • Usa: nada.
    • Não implementa: os UUIDs. Os IDs de nó são 16 bytes aleatórios, deliberadamente não UUIDs.