kolo docsbeta

kolo-files

Un árbol cifrado de archivos y carpetas con todo su historial. Recupera cualquier versión anterior, compara dos y conserva solo los archivos que un dispositivo necesita.

En esta página

kolo-files guarda carpetas, nombres y versiones sobre kolo-blobs, con los nombres en la forma de normalización Unicode C (UAX #15). Un Volume es un árbol de archivos y carpetas guardado en dos logs de kolo-store de un mismo propietario: un log de metadatos con una op por cambio (crear una carpeta, escribir un archivo, mover, borrar) y un log de contenido con objetos de kolo-blobs. El árbol se reconstruye reproduciendo el log de metadatos, y cada op es una versión: Snapshot recupera cualquier árbol anterior y Diff compara dos. Cada archivo tiene su propia clave, guardada dentro de su op de creación, así que un peer de anclaje de kolo-pin que tenga los dos logs no ve ni nombres, ni claves, ni contenido. Volume y Snapshot implementan io/fs, así que fs.WalkDir, fs.ReadFile y fs.Glob funcionan con ellos; para escribir uno en disco, sigue Escribir un volumen en disco, no os.CopyFS. Un lector guarda una réplica del log de metadatos y lee el contenido de una réplica de contenido o, entrada a entrada, de otro peer; las marcas eligen qué archivos conserva un dispositivo. El paquete de Go se llama kolofiles.

Todos los pasos

Ops, nodos y rutas

No se guarda ningún árbol en disco. Se reconstruye reproduciendo el log de metadatos desde su primera entrada.

  1. Cada cambio es una op del log de metadatos. La entrada 0 es VOLUME, que nombra el log de contenido. REMOVE y PURGE, de los borrados, no se dibujan.
  2. Una op nombra un nodo, no una ruta. Cada archivo y cada carpeta recibe un ID de nodo aleatorio de 16 bytes al crearse. La raíz es el ID con todos los bytes a cero.
  3. Un movimiento es una op que fija el padre y el nombre de un nodo. El ID del nodo se mantiene, así que una carpeta movida lleva su subárbol y el historial sigue al archivo.
  4. Reproducir el log construye el árbol. Una ruta sigue io/fs: separada por barras, nombres en NFC sin caracteres de control, y por defecto como máximo 765 bytes por nombre y 2048 nombres de profundidad.

Instalación

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

Compila con CGO_ENABLED=0 para obtener un binario solo en Go. Comparte archivos entre dos terminales explica paso a paso cómo compartir una carpeta y cada versión nueva de ella con otro peer.

Inicio rápido

Este programa guarda un árbol pequeño en un volumen en disco, en un directorio temporal. Lista el árbol, recupera una versión anterior, compara dos versiones y borra un archivo.

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

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 escribe la entrada 0, así que un volumen vacío es la versión 1. Mkdir hace la versión 2 y el primer WriteFile la versión 3, por eso first vale 3. Entre la versión 3 y ahora hay dos cambios: se añadió draft.txt, y todo.txt se renombró y se editó, que es un solo cambio porque el nodo es el mismo.

Referencia de la API

La referencia de la API se genera a partir del código Go y está en inglés.

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

Variables

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

Funciones

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.

Conviene saber

Una ruta sigue io/fs.ValidPath: separada por barras, relativa a la raíz del volumen, con . como raíz. Una ruta que incumple una regla es fs.ErrInvalid dentro de un *fs.PathError:

ReglaDecisión
CodificaciónUTF-8 válido
NormalizaciónLos nombres se guardan en NFC, y toda ruta que se da a la API se normaliza antes, así que e más un acento agudo combinado y la é precompuesta son un mismo nombre
Puntos de código sin asignarSe rechazan al crear un nombre (en la versión de Unicode de la versión de Go); un lector los acepta, porque las tablas de un escritor más nuevo pueden conocer más
Caracteres de controlSe rechazan (categoría general Cc)
., .., vacío, / en un nombreSe rechazan
MayúsculasLos nombres se comparan byte a byte: README y readme pueden existir a la vez, y renombrar solo por mayúsculas es un movimiento normal
Reglas solo de Windows (<>:"|?*, CON y los demás nombres de dispositivo con o sin extensión, un punto o un espacio final, más de 255 unidades UTF-16)Se permiten, porque otros sistemas crean esos nombres; el código que escribe un volumen en disco convierte cada ruta con LocalPath, que en Windows los rechaza con ErrUnsafeName (filepath.Localize solo acepta NUL.txt y <>|?*"; os.CopyFS no usa estas reglas). Consulta Escribir un volumen en disco
Longitud del nombreComo máximo MaxNameLength bytes tras NFC, 765 por defecto (DefaultMaxNameLength)
ProfundidadComo máximo MaxDepth nombres bajo la raíz, 2048 por defecto (DefaultMaxDepth)

Cada archivo y cada carpeta tiene un NodeID aleatorio de 16 bytes, elegido al crearse y que ningún movimiento ni renombrado cambia. Las ops se refieren a nodos, nunca a rutas, así que renombrar es una op, una carpeta movida lleva su subárbol y el historial sigue a un archivo a través de los renombrados. FileInfo.Sys() es un NodeInfo: el ID del nodo, la versión en que cambió por última vez y el ID del blob. Stat informa los archivos como 0444 y las carpetas como fs.ModeDir | 0555; la hora de modificación es el reloj del escritor en la op, solo para mostrar. Los listados van ordenados por nombre, byte a byte. Un archivo es también un io.ReaderAt y un io.Seeker, y una lectura de un rango trae un nodo por nivel del árbol y los fragmentos que lo cubren. OpenContext da a un archivo un contexto que termina sus lecturas.

Todos los pasos

Archivos sobre blobs

kolo-files decide los nombres, las carpetas y las versiones. kolo-blobs guarda y comprueba los bytes de cada versión.

  1. Un volumen son dos logs de kolo-store de un mismo dueño: el log de metadatos, una op por cambio, y el log de contenido, que guarda objetos de kolo-blobs. La entrada 0 del log de metadatos nombra el log de contenido.
  2. WriteFile pasa los bytes del archivo a kolo-blobs bajo la clave propia del archivo. Sus fragmentos y su raíz se convierten en entradas del log de contenido, y el hash de la raíz es el ID del blob.
  3. También escribe una tabla de objetos, un segundo blob bajo la misma clave, que enumera la entrada del log de contenido de cada objeto, para que un lector los encuentre sin recorrer el log.
  4. La op CREATE guarda el nombre, la clave del archivo y la versión: el ID del blob, el ID de la tabla y dónde están los objetos de la propia tabla. kolo-log cifra cada op.
  5. Una versión nueva es una op WRITE con un blob y una tabla nuevos. La clave no cambia, así que los fragmentos sin cambios no se guardan otra vez.

WriteFile crea un archivo (su carpeta madre debe existir) o guarda contenido nuevo para uno existente, leyendo la fuente hasta el final. Solo se guardan los fragmentos que cambiaron respecto a versiones anteriores, porque kolo-blobs deduplica dentro de una misma clave, y una escritura matada se reanuda llamándola otra vez con el mismo contenido. ctx se comprueba entre fragmentos. Mkdir necesita su carpeta madre y falla con fs.ErrExist si el nombre ya existe. Move renombra o mueve un archivo o una carpeta entera; la carpeta madre del destino debe existir y el destino no (fs.ErrExist), mover un nodo dentro de su propio subárbol o mover la raíz es fs.ErrInvalid, y mover a la misma ruta no hace nada. Un Volume y un Snapshot son seguros para uso concurrente. Las escrituras se serializan desde el inicio de la escritura de un blob hasta que se añade la op, las lecturas nunca esperan a la escritura de un blob, y un append fallido deja el árbol como estaba.

Nombres

Un nombre es una cadena UTF-8 en NFC. Una ruta dada en otra forma se normaliza primero, así que é escrita como e más un acento combinante y la é precompuesta son un solo nombre, y los bytes originales no se conservan. Los nombres se comparan byte a byte, así que se respetan las mayúsculas y README y readme pueden coexistir. Los caracteres de control, los nombres vacíos, . y .. se rechazan.

Escribir un volumen en disco

LocalPath convierte una ruta del volumen en una ruta para el sistema anfitrión. En Windows rechaza con ErrUnsafeName un nombre que Windows reserva para un dispositivo, en cualquier combinación de mayúsculas ASCII (CON, NUL.txt, COM1 y los demás, con o sin extensión; algunas versiones de Windows abren el dispositivo en lugar de crear un archivo), uno de <>:"|?*\, un punto o un espacio final, un carácter de control y un nombre de más de 255 unidades UTF-16. Solo comprueba nombres y nunca mira el disco.

Un disco puede dar a dos nombres del volumen una sola entrada: nombres que solo difieren en mayúsculas en un disco que no las distingue (el valor por defecto de macOS y Windows), o un nombre corto 8.3 de Windows como LONGFI~1.TXT para longfilename.txt o PROGRA~1 para una carpeta. Un enlace que ya esté en el destino también puede llevar fuera de él. Por eso crea cada carpeta y cada archivo bajo un os.Root, con Mkdir y O_CREATE|O_EXCL: un alias falla entonces con fs.ErrExist en lugar de sobrescribir otra entrada, y os.Root rechaza una ruta que sale del directorio. Este programa es el ejemplo LocalPath de la biblioteca, compilado y ejecutado por go test. Escribe el volumen en un directorio temporal y extrae el mismo árbol dos veces; la segunda extracción no sobrescribe 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))
}

Imprime:

Texto
buy bread
true

os.CopyFS no lo sustituye: sigue los enlaces que ya hay en el destino, une carpetas cuyos nombres solo difieren en mayúsculas y, en Windows, renombra un punto o un espacio final y escribe nombres de dispositivo con extensión como NUL.txt, todo sin un error. filepath.Localize solo tampoco basta: acepta NUL.txt y <>|?*".

Versiones

Todos los pasos

Versiones, checkout y diff

Cada op es una versión, así que el historial tiene la granularidad de un solo cambio.

  1. Una versión es la longitud del log de metadatos: el árbol tras sus primeras entradas. La versión 1 es la raíz vacía, y Len es la versión actual.
  2. Snapshot(3) reproduce las 3 primeras entradas en un árbol propio. Es inmutable, no hay que cerrarlo y es un sistema de archivos io/fs.
  3. Snapshot(Len) es el árbol de ahora. Aquí el log tiene 6 entradas, así que la versión actual es la 6.
  4. Diff(3, 6) devuelve un Change por cada nodo añadido, movido, modificado o borrado entre las dos, ordenados por ruta. Una carpeta movida es un solo cambio.
  5. El borrado gana al historial: un nodo borrado no está en ningún snapshot, como si nunca hubiera existido. Un diff solo lo muestra como un Change con Deleted activo y sin rutas.

Len es la versión actual: el número de entradas de metadatos con las que se construye el árbol. Snapshot(version), con version de 1 a Len, devuelve el árbol tras las primeras version entradas como un Snapshot inmutable con los mismos Open, OpenContext, ReadDir y Stat, y Version. La versión 1 es la raíz vacía. Diff(a, b), con 1 <= a <= b <= Len, devuelve un Change por cada nodo añadido, movido, modificado o borrado entre las dos, ordenados por ruta y luego por ID de nodo; una carpeta movida es un solo cambio. El borrado gana al historial: un nodo borrado no está en ningún snapshot, como si nunca hubiera existido, y en un diff aparece solo como un Change con Deleted activo y sin rutas. El contenido sobrescrito se conserva, así que cada versión anterior de un archivo vivo sigue siendo legible; solo Delete elimina historial. Un Snapshot cuesta una pasada por las primeras version entradas.

Leer desde otro dispositivo

OpenReader(meta, content, local) construye un volumen de solo lectura a partir de una réplica del log de metadatos. content es un Backend de kolo-blobs, como koloblobs.NewLogBackend sobre una réplica del log de contenido. OpenFetchReader(meta, fetch, local) lee el contenido de otro peer, donde fetch(ctx, index) trae una entrada del log de contenido, por ejemplo con el Fetch de kolo-sync, o con FetchWithKeys desde un peer de anclaje de kolo-pin que sirve solo texto cifrado mientras el lector tenga las claves de las entradas. El peer de anclaje nunca recibe una clave. El README tiene el código, y kolofiles.ContentLog(meta) da el ID del log de contenido a partir de la primera entrada.

Un lector reproduce el prefijo más largo que puede reproducir con exactitud: se detiene en una entrada que tiene sin su clave y antes de una entrada destruida que ningún purge completo lista, y Len dice qué versión es esa. Refresh lo pone al día con el último head verificado de la réplica, de forma incremental cuando puede, y Len puede bajar. Un refresco incremental comprueba cada entrada por debajo de Len en busca de una marca de borrado, así que cuesta tiempo en Len. Cuando el propietario cambia el volumen, haz pull del log de metadatos otra vez y llama a Refresh; una versión escrita después del head que guardaste necesita un head nuevo y sus claves. Un dispositivo lector guarda el log de metadatos con sus claves de entrada, que vienen del propietario o de cualquier peer con acceso Keys de kolo-sync, y Close deja abiertos los backends local y content.

Sincronización selectiva

Todos los pasos

Sincronización selectiva

Las marcas son la elección de un dispositivo. El uso de disco no crece solo: por defecto no se conserva nada.

  1. Un lector guarda una réplica del log de metadatos, así que tiene todos los nombres y todas las versiones y puede listar y recorrer todo el árbol.
  2. El contenido no se copia por defecto. Con MarkFetchOnDemand, el valor de la raíz, una lectura trae de otro peer solo los objetos que necesita, un nodo por nivel del árbol y los fragmentos que cubren el rango, y no conserva ninguno.
  3. MarkKeepLocal conserva todos los objetos de la versión actual de los archivos que cubre. Un nodo sin marca toma la del ancestro marcado más cercano, y la marca de una carpeta cubre los archivos añadidos después.
  4. Prefetch trae los objetos que le faltan al dispositivo de cada archivo conservado y elimina los objetos conservados de versiones anteriores. Cada objeto conservado se comprueba contra su hash.
  5. Las marcas se guardan por ID de nodo en el backend local de este dispositivo y en ningún otro sitio, así que siguen a los movimientos y no están en ningún log compartido.

SetMark, Mark y Prefetch funcionan en un lector abierto con un backend local. MarkKeepLocal conserva en el dispositivo todos los objetos de la versión actual del archivo, así que se lee sin conexión. MarkFetchOnDemand trae solo los objetos que necesita una lectura y no conserva nada. MarkInherit borra una marca. Un nodo sin marca toma la de su ancestro marcado más cercano, y el valor de la raíz es MarkFetchOnDemand, así que el uso de disco no crece solo. Las marcas se guardan por ID de nodo, así que siguen a los movimientos, y se eliminan con el nodo. Prefetch lee la versión actual de cada archivo MarkKeepLocal a través del backend local, elimina sus objetos conservados de versiones anteriores, sigue adelante si un archivo falla y devuelve todos los errores. Un objeto conservado se comprueba contra su hash antes de conservarlo y antes de servirlo; el que falla se descarta. Un movimiento que pone un archivo bajo un nodo con otra marca, visto por Refresh, elimina los objetos conservados para él. Una marca es la elección de un dispositivo, así que nunca está en los logs compartidos. Las marcas en un escritor, o en un lector sin backend local, son ErrInvalidArgument.

Stats devuelve los totales desde la apertura, leídos con atómicos: Ops, Replayed, BytesWritten, BytesRead, ObjectsFetched y ObjectsLocal.

Borrado

Delete elimina un archivo o una carpeta con todo lo que hay debajo y destruye lo que contenían. Añade una op REMOVE, que solo lleva el ID del nodo, y ops PURGE que listan las entradas de metadatos y de contenido del subárbol, cada una por debajo de la mayor entrada que lleva kolo-sync, y después destruye esas entradas con el Delete de kolo-log. Lo que se destruye: todos los nombres que tuvo el nodo, la clave de su archivo (así que todas las versiones dejan de ser legibles a la vez en los peers que siguen el protocolo) y todos los objetos. Lo que queda: las ops REMOVE y PURGE (un ID de nodo e índices de entradas), los registros firmados y las marcas de kolo-log, y el hecho de que hubo un borrado. Una caída en cualquier paso la termina el siguiente Open. La raíz no se puede borrar. Consulta Borrado.

Límites

Los dos límites siguientes son ajustes de seguridad, no límites del producto, y cada uno tiene su opción.

  • MaxDepth, 2048 por defecto (DefaultMaxDepth), con WithMaxDepth(n), como mínimo 1: el árbol más profundo que cabe en un argumento de ruta de Linux (PATH_MAX 4096 con el NUL, nombres de un byte).
  • MaxNameLength, 765 bytes por defecto (DefaultMaxNameLength), con WithMaxNameLength(n), de 1 hasta la mayor op, el MaxObjectSize de kolo-blobs (4.128.764 bytes), porque un nombre debe caber en una op. 765 bytes admiten todos los nombres que permiten ext4 (255 bytes) y Windows: los nombres de Windows tienen como máximo 255 unidades UTF-16, y una unidad UTF-16 ocupa como máximo 3 bytes de UTF-8.
  • Una ruta que pasa un límite es ErrLimit. Un escritor aplica los límites en cada creación y movimiento, así que un lector con los mismos ajustes abre todo lo que escribió el escritor. Un lector comprueba una creación o un movimiento reproducidos solo con la profundidad del nodo que crea o mueve, no con los nodos bajo una carpeta movida, así que un log hostil puede poner nodos más profundos que MaxDepth; un nodo así no tiene ruta (buscarlo da ErrLimit y Diff lo informa con rutas vacías).
  • Todo lo demás lo limita lo que kolo-store ha aceptado: no hay límite de archivos, carpetas, versiones ni tamaño de archivo.
  • Los recorridos hacia arriba del árbol (movimientos, rutas, marcas) dan como máximo MaxDepth pasos. Los recorridos hacia abajo (un borrado, una comprobación antes de un movimiento) dan como máximo tantos pasos como nodos. Todos los recorridos son iterativos.
  • Una tabla de objetos se lee como un flujo: su cuenta se comprueba contra los objetos que cabe en un blob de ese tamaño y contra el tamaño de la tabla, y la memoria crece con los bytes que el blob de la tabla tiene de verdad, no con el tamaño que declara un escritor.
  • Memoria: el árbol actual se mantiene en memoria, unos 211 bytes por nodo vivo con un nombre de 10 bytes (BenchmarkStateNode, 64 bits, Apple M5, Go 1.27.3), más el ID de cada nodo que borró un borrado, 8 bytes por entrada destruida, y el coste propio de kolo-store por entrada. Reproducir un log entero mantiene cada op decodificada hasta aplicarlas, unos 344 bytes por entrada con un nombre de 10 bytes (BenchmarkReplayEntry, la misma máquina) además del árbol, así que abre un volumen muy grande con GOMEMLIMIT definido. Los snapshots y los diffs mantienen su propio árbol mientras se ejecutan y nada después.

Seguridad

  • Un peer que sirve entradas a un lector con Fetch o FetchWithKeys ve qué entradas de contenido se traen y cuándo. Por el orden (una tabla, la raíz, un nodo por nivel, luego fragmentos) sabe qué archivo se abre y qué rangos se leen, y el tamaño del head con el que el lector comprueba.
  • Con una misma clave de archivo, los fragmentos iguales son texto cifrado igual, así que dos versiones de un archivo muestran qué fragmentos comparten. Archivos distintos nunca comparten un objeto, porque cada archivo tiene su propia clave.
  • Cada archivo recibe una clave de kolo-blobs al crearse, dentro de su op de creación. Las claves no se guardan en memoria y nunca se devuelven, se imprimen ni se registran; una copia leída del log se borra tras usarla. Ningún error lleva una clave, contenido de un archivo ni bytes de una entrada.
  • Cada versión escribe además una tabla de objetos, un segundo blob con la clave del archivo que lista cada objeto del blob de contenido y la entrada del log de contenido que lo guarda. Un lector sin la réplica de contenido encuentra cada entrada con ella sin recorrer el log, y Delete puede listar las entradas de todas las versiones.
  • El borrado es una lápida de mejor esfuerzo: se cumple en todo peer que sigue el protocolo y aplica las marcas de borrado, y un peer que ya recibió una clave puede quedarse con los datos. Un lector que ve entradas destruidas antes de la op PURGE que las lista retrocede hasta justo antes de ellas hasta que llega la op, y elimina las marcas y los objetos conservados de los nodos borrados en su siguiente apertura o refresco. Quitar un objeto conservado del almacén Pebble local también es una lápida, así que los bytes viejos se quedan hasta la compactación.
  • Una escritura matada antes de añadir su op deja objetos sin referencia. En un archivo nuevo nadie puede leerlos, porque su clave nunca se guardó; en un archivo existente están bajo la clave de ese archivo y se destruyen cuando se borra el archivo.
  • Un volumen tiene un solo escritor, su propietario. Un log con dependencias de otro escritor es ErrCorrupt. Un lector rechaza con ErrCorrupt toda op que incumpla una regla del formato; el README lista las reglas y los formatos.

Construir un sistema de actualización encima

Son hechos de la biblioteca, no una función: kolo-files no tiene un sistema de actualización.

  • Una versión es una longitud del log de metadatos firmado por el propietario, y Snapshot y Diff leen cualquier versión.
  • El ID de blob de cada archivo está en NodeInfo, con Stat().Sys().
  • Prefetch trae solo los objetos que el dispositivo aún no tiene, y un Prefetch interrumpido se reanuda con los objetos que faltan.
  • kolo-files no guarda modos de archivo, bit ejecutable ni enlaces simbólicos, y Delete también quita un nodo de los snapshots anteriores. Una capa que instale aplicaciones guarda los modos, los enlaces simbólicos y los IDs de blob esperados en su propio manifiesto firmado.

Límites conocidos

  • Un solo escritor.
  • Stat no informa más permisos que 0444 y 0555, y la hora de modificación es el reloj del escritor.
  • Las reglas de nombres solo de Windows no se aplican dentro de un volumen: escribe un volumen en disco con LocalPath y la receta de Escribir un volumen en disco. LocalPath solo comprueba nombres.
  • Todas las pruebas se ejecutan en 127.0.0.1. Experimental. La API puede cambiar antes de la v1.0.0.

Errores

ErrorMensaje
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

Comprueba los errores con errors.Is; ninguno lleva una clave, contenido de un archivo ni bytes de una entrada. Los errores de ruta son *fs.PathError con Op que empieza por kolofiles:, así que coinciden fs.ErrNotExist, fs.ErrExist y fs.ErrInvalid; los nombres aparecen solo en PathError.Path, tal como los dio quien llamó. Los errores de kolo-blobs, kolo-store y kolo-log pasan envueltos. Un archivo cuyas entradas se destruyeron se lee como kololog.ErrDeleted (y fs.ErrNotExist). ErrLimit cubre también una op que se iba a añadir por encima de la mayor entrada que lleva kolo-sync, ErrClosed cubre también la lectura de un Snapshot o de un archivo de un volumen cerrado, y ErrInvalidArgument cubre también una versión fuera de rango, logs de propietarios distintos y un log no vacío dado a Create.

Referencias

  • El paquete io/fs de la biblioteca estándar de Go.
    • Toma: la sintaxis de rutas (ValidPath), las interfaces FS, ReadDirFS, StatFS, File y ReadDirFile, PathError y sus centinelas; path/filepath.Localize y os.Root para escribir un volumen en disco.
    • No implementa: nada.
  • Unicode Standard Annex #15, Unicode Normalization Forms (revisión 58, Unicode 18.0.0, 12 de agosto de 2026).
    • Toma: NFC para los nombres, y su política de estabilidad para los caracteres asignados.
    • No implementa: NFKC y NFKD.
  • Las reglas de nombres de archivo de los sistemas de archivos POSIX, en palabras llanas.
    • Toma: ningún byte NUL ni / en un nombre.
    • No implementa: nada.
  • Las referencias de kolo-blobs.
    • Toma: las claves de archivo, los objetos y el árbol bajo cada archivo, a través de kolo-blobs.
    • No implementa: véanse las Referencias de kolo-blobs.
  • RFC 9562, Universally Unique IDentifiers (UUIDs) (Proposed Standard, mayo de 2024).
    • Toma: nada.
    • No implementa: los UUID. Los IDs de nodo son 16 bytes aleatorios, deliberadamente no UUID.