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.
Ops, nós e caminhos
Nenhuma árvore é guardada em disco. Ela é reconstruída reproduzindo o log de metadados desde a primeira entrada.
- 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.
- 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.
- 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.
- 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-filesCompila 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.
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:
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 existCreate 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.
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 uint8Mark 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() stringString returns the mark's name.
type NodeID
type NodeID [16]byteNodeID 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() stringString 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) OptionWithMaxDepth sets how many names below the root a path may have, at least 1; the default is DefaultMaxDepth.
func WithMaxNameLength
func WithMaxNameLength(n int) OptionWithMaxNameLength 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() uint64Version 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() errorClose 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) errorDelete 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.LogIDID returns the volume's ID, the ID of its metadata log.
func (Volume) Len
func (v *Volume) Len() uint64Len 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) errorMkdir 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) errorMove 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) errorPrefetch 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() errorRefresh 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) errorSetMark 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() StatsStats 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) errorWriteFile 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:
| Regra | Decisão |
|---|---|
| Codificação | UTF-8 válido |
| Normalização | Os 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ídos | Recusados 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 controle | Recusados (categoria geral Cc) |
., .., vazio, / em um nome | Recusados |
| Maiúsculas | Os 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 nome | No máximo MaxNameLength bytes após o NFC, 765 por padrão (DefaultMaxNameLength) |
| Profundidade | No 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.
Arquivos sobre blobs
A kolo-files decide nomes, pastas e versões. A kolo-blobs guarda e verifica os bytes de cada versão.
- 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.
- 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.
- 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.
- 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.
- 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:
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:
buy bread
trueos.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
Versões, checkout e diff
Cada op é uma versão, então o histórico tem a granularidade de uma única mudança.
- 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.
- 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.
- Snapshot(Len) é a árvore de agora. Aqui o log tem 6 entradas, então a versão atual é a 6.
- 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.
- 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
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.
- 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.
- 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.
- 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.
- 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.
- 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), comWithMaxDepth(n), no mínimo 1: a árvore mais profunda que cabe em um argumento de caminho do Linux (PATH_MAX4096 com o NUL, nomes de um byte).MaxNameLength, 765 bytes por padrão (DefaultMaxNameLength), comWithMaxNameLength(n), de 1 até a maior op, oMaxObjectSizeda 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 queMaxDepth; um nó assim não tem caminho (buscá-lo dáErrLimiteDiffo 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
MaxDepthpassos. 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 comGOMEMLIMITdefinido. 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
FetchouFetchWithKeysvê 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
Deletepode 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 comErrCorrupttoda 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
SnapshoteDiffleem qualquer versão. - O ID de blob de cada arquivo está em
NodeInfo, comStat().Sys(). Prefetchbusca só os objetos que o aparelho ainda não tem, e umPrefetchinterrompido recomeça com os objetos que faltam.- A kolo-files não guarda modos de arquivo, bit executável nem links simbólicos, e
Deletetambé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.
Statnã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
LocalPathe a receita de Escrever um volume em disco.LocalPathsó confere nomes. - Todos os testes rodam em 127.0.0.1. Experimental. A API pode mudar antes da v1.0.0.
Erros
| Erro | Mensagem |
|---|---|
ErrClosed | kolofiles: volume closed |
ErrCorrupt | kolofiles: corrupt volume |
ErrInvalidArgument | kolofiles: invalid argument |
ErrIsDir | kolofiles: is a directory |
ErrLimit | kolofiles: over a bound |
ErrNotDir | kolofiles: not a directory |
ErrReadOnly | kolofiles: read-only volume |
ErrUnsafeName | kolofiles: 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/fsda biblioteca padrão do Go.- Usa: a sintaxe de caminhos (
ValidPath), as interfacesFS,ReadDirFS,StatFS,FileeReadDirFile,PathErrore seus sentinelas;path/filepath.Localizeeos.Rootpara escrever um volume em disco. - Não implementa: nada.
- Usa: a sintaxe de caminhos (
- 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.
- Usa: nenhum byte NUL e nenhum
- 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.