data

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package data is blobfs's persistence: its standard-tier SQL statements, the pattern namespace it publishes, and the Store that runs the statements through sqlate on any engine sqlate has a dialect for.

The catalog and the engine:

  • Namespace is the pattern namespace blobfs publishes, and Patterns its pattern source, which a consumer registers in its catalog.
  • New compiles the statements once against that catalog into a Store; Option configures it, and WithEngine installs an Engine.
  • Engine builds a Variant, the variation points an engine implements natively, over the baseline it is given.
  • Store.Statements lists the compiled inventory, and Store.Verify prepares it against the schema.

The handles, whose methods run one step each on the session the caller passes:

  • Store.Directories, a *Directories, creates, finds, lists, moves, and deletes directory rows and marks a branch deleting.
  • Store.Files, a *Files, creates, completes, finds, lists, moves, holds, deletes, and purges file rows. Files.Ensure reports what it did with the name as a WriteOutcome: WriteCreated, WriteResumed, or WritePresent.
  • Listing is the interface both handles' listings satisfy.
  • Marked counts the rows Directories.MarkDeleting changed.

The options:

  • ListOption configures a listing; IncludeDeleting lists deleting rows too.
  • CreateOption configures a create; WithID supplies the row's id.
  • VersionOption configures a guarded step; AtVersion names the version.
  • SweepOption configures a sweep: Batch bounds a pass, OnRemoveDirectory runs the consumer's cleanup in each directory removal's transaction, and StaleOlderThan also reclaims the pending and deleting file rows older than an age.
  • WriteOption configures a write, Store.WriteFile's or Store.EnsureFile's: OnComplete runs the consumer's function in the transaction of the completion the call itself makes.
  • RemoveOption configures Store.RemoveFile: AtVersion, a VersionOption, names the version, and OnDelete runs the consumer's function in the transaction that marks the file deleting.

The protocols, which run the steps end to end over the consumer's object store:

  • ObjectStore is the store as the write protocols call it, a blobfs.KeyValidator, an ObjectPutter, and an ObjectDeleter; the delete protocols and the sweep take an ObjectDeleter alone.
  • Store.WriteFile runs the two-phase write, and Store.EnsureFile its retry-safe form under a fixed id.
  • Store.RemoveFile runs the two-phase delete of the file a callback picks, Store.RemoveFileID of the file with an id, and Store.PurgeFile the last two steps of a delete already begun.
  • Store.Sweep runs one bounded pass that finishes the deletes callers began and reports it as a SweepResult; SweepUntilDone runs a consumer's passes until the work is done.

Every operation takes the context and a session first and passes the session through unwrapped, so a call runs on the pool or inside the caller's transaction. An operation correct only inside a transaction takes a *sqlate.Tx: Directories.Move, Directories.LockTree, Directories.MarkDeleting, Files.Hold, and Files.Delete. The Store's protocols and Sweep take the *sqlate.DB, since they open transactions of their own.

Every refusal is a sentinel of the root package, or of the query library, matched with errors.Is. A violation of one of blobfs's constraints is a blobfs.ViolationError naming the sentinel and the constraint, and blobfs.ErrDeleting is a blobfs.DeletingError naming whose delete refused. blobfs.ErrDeleting outranks query.ErrVersionMismatch: a step that refuses a deleting row reports it whatever version the caller names. Each exported method names its error once, as "data: <op>: ", except the errors of the caller's own callbacks, begin and pick, which the protocols return as they came.

docs/concepts.md explains the protocols and docs/features.md states every operation, refusal, and option.

Index

Constants

View Source 
const Namespace = "blobfs"

Namespace is the pattern namespace blobfs publishes: a consumer's statement includes one of its patterns as {{> blobfs.name}}.

Variables

This section is empty.

Functions

func Patterns 

func Patterns() query.Source

Patterns is blobfs's published pattern source, the column lists directory_columns and file_columns, which a consumer registers in its catalog beside query.Patterns(). Every pattern is parameter-free, since a projection base that included one would gain its parameters.

func SweepUntilDone added in v0.3.0 

func SweepUntilDone(ctx context.Context, stop <-chan struct{}, pass func(context.Context) (SweepResult, error), report func(SweepResult, error)) error

SweepUntilDone runs pass, the consumer's closure over one Store.Sweep, while it reports More, and hands each result to report. It returns nil once the work is done or stop closes, and ctx's error once ctx ends. A pass's error never ends the loop. See The sweep in docs/features.md.

Types

type CreateOption 

type CreateOption func(*createOptions)

CreateOption configures one call of an operation that creates a row, Create or Ensure, beyond its required arguments.

func WithID 

func WithID(id string) CreateOption

WithID supplies the id of the row the call inserts, in place of a minted one, so a seeded row keeps its id across resets. It is checked with blobfs.ParseID before any SQL; a row an Ensure finds keeps its own id.

type Directories 

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

Directories is the handle over blobfs_directory rows, the Store's Directories field. Every operation takes a directory by id.

func (*Directories) BranchRoots added in v0.5.0 

func (d *Directories) BranchRoots(ctx context.Context, sess sqlate.Session, limit int) (_ []blobfs.Directory, err error)

BranchRoots returns at most limit roots of the branches being deleted, in id order: each deleting directory under an active parent. A limit below 1 is refused before any SQL.

func (*Directories) Continue 

func (d *Directories) Continue(ctx context.Context, sess sqlate.Session, parentID string, req query.Directives, after query.Cursor, size int, opts ...ListOption) (_ query.Collection[blobfs.Directory], err error)

Continue reads the size directories under parentID past after, the Next of an earlier page of the listing called the same way. Refusals: List's, and a query.CursorError before any SQL. See Listings in docs/features.md.

func (*Directories) Create 

func (d *Directories) Create(ctx context.Context, sess sqlate.Session, parentID, name string, opts ...CreateOption) (_ blobfs.Directory, err error)

Create creates a directory named name under parentID and returns the row. The name and the id are checked before any SQL. A name a deleting directory holds is refused with that directory's blobfs.DeletingError, not blobfs.ErrNameTaken. See Directories in docs/features.md.

func (*Directories) Delete 

func (d *Directories) Delete(ctx context.Context, sess sqlate.Session, id string, opts ...VersionOption) (err error)

Delete removes the empty directory with id, only at the version AtVersion names when it is given; a branch is deleted with MarkDeleting and Store.Sweep. Refusals: blobfs.ErrRootDirectory, blobfs.ErrNotEmpty, blobfs.ErrReferenced, blobfs.ErrNotFound, and query.ErrVersionMismatch. See Directories in docs/features.md.

func (*Directories) Ensure 

func (d *Directories) Ensure(ctx context.Context, sess sqlate.Session, parentID, name string, opts ...CreateOption) (_ blobfs.Directory, _ bool, err error)

Ensure returns the directory named name under parentID, creating it when none exists, and reports whether this call created it. A found row keeps its own id, and a found deleting one is blobfs.ErrDeleting. Its refusals are Create's, and blobfs.ErrNameTaken inside a transaction for a creator that commits the name after the lookup. See Directories in docs/features.md.

func (*Directories) Find 

func (d *Directories) Find(ctx context.Context, sess sqlate.Session, id string) (_ blobfs.Directory, err error)

Find returns the directory with id, or blobfs.ErrNotFound. The root is Find of blobfs.RootID.

func (*Directories) FindByName 

func (d *Directories) FindByName(ctx context.Context, sess sqlate.Session, parentID, name string) (_ blobfs.Directory, err error)

FindByName returns the child directory of parentID named name, which is normalized first; a file of the same name is not found. Refusals: blobfs.NameError before any SQL, blobfs.ErrNotFound.

func (*Directories) FindByPath 

func (d *Directories) FindByPath(ctx context.Context, sess sqlate.Session, startID, path string) (_ blobfs.Directory, err error)

FindByPath returns the directory at the relative path a/b below startID; the empty path is the start. Refusals: blobfs.ErrInvalidPath, and blobfs.ErrNotFound with the failing prefix in the text. See Directories in docs/features.md.

func (*Directories) IsWithin 

func (d *Directories) IsWithin(ctx context.Context, sess sqlate.Session, id, ancestorID string) (_ bool, err error)

IsWithin reports whether the directory with id lies within the subtree of the directory with ancestorID, that directory included: Move's cycle check, for a consumer's own. The answer holds only while no other transaction moves directories. See Directories in docs/features.md.

func (*Directories) List 

func (d *Directories) List(ctx context.Context, sess sqlate.Session, parentID string, req query.Directives, page query.Page, opts ...ListOption) (_ query.Collection[blobfs.Directory], err error)

List reads one page, by number, of the directories under parentID under req, hiding deleting ones unless IncludeDeleting is given. Refusals: query.ErrDirectives before any SQL; blobfs.ErrDeleting for a deleting parent. See Listings in docs/features.md.

func (*Directories) LockTree 

func (d *Directories) LockTree(ctx context.Context, tx *sqlate.Tx) (err error)

LockTree takes the variant's tree lock inside tx, held until tx ends, for a tree-shape change of the caller's own; Move and MarkDeleting take it themselves. See Variant.

func (*Directories) MarkDeleting added in v0.2.0 

func (d *Directories) MarkDeleting(ctx context.Context, tx *sqlate.Tx, id string, opts ...VersionOption) (_ Marked, err error)

MarkDeleting is the first step of a branch's delete: in tx, under the tree lock, it marks the directory with id, every directory beneath it, and every file in them deleting, and reports the rows it changed. A repeated mark converges and reaches a straggler. Refusals: blobfs.ErrRootDirectory, blobfs.ErrNotFound, and query.ErrVersionMismatch under AtVersion. See Deleting a branch in docs/features.md.

func (*Directories) Move 

func (d *Directories) Move(ctx context.Context, tx *sqlate.Tx, id, parentID, name string, version int64) (_ blobfs.Directory, err error)

Move moves the directory with id under parentID as name, guarded by version, and returns the row; its children and files follow it. It runs in tx under the tree lock, after the cycle check. Refusals: blobfs.ErrRootDirectory, blobfs.NameError, blobfs.ErrCycle, blobfs.ErrNotFound, blobfs.ErrNameTaken, a blobfs.DeletingError, query.ErrVersionMismatch, and sqlate.ErrSerializationFailure above read committed. See Moves in docs/concepts.md.

func (*Directories) Path 

func (d *Directories) Path(ctx context.Context, sess sqlate.Session, id string) (_ string, err error)

Path returns the path of the directory with id from the root, / for the root and /a/b below it, computed at read time in one statement whose cost is the directory's depth. Its text after the leading slash is the path FindByPath resolves from blobfs.RootID.

Refusals: blobfs.ErrNotFound; blobfs.ErrCycle when the chain of parents loops.

func (*Directories) Serializes 

func (d *Directories) Serializes() bool

Serializes reports whether LockTree serializes tree-shape changes across transactions on the store's variant. See Variant.

type Engine 

type Engine func(catalog *query.Catalog, dialect sqlate.Dialect, base Variant) (Variant, error)

Engine builds a store's variant over base, the baseline New bound, against the store's catalog and dialect; it compiles only its own statements and embeds base, or another Engine's variant, for what it does not override: 

func(c *query.Catalog, d sqlate.Dialect, base data.Variant) (data.Variant, error) {
	return lockless{Variant: base}, nil
}

type Files 

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

Files is the handle over blobfs_file rows, the Store's Files field. A file is written with Create (or Ensure) and Complete around the consumer's put, and deleted with Delete and Purge around its object delete. See The two-phase write in docs/concepts.md.

func (*Files) Complete 

func (f *Files) Complete(ctx context.Context, sess sqlate.Session, id string, version int64, obj blobfs.Object) (_ blobfs.File, err error)

Complete is the write's last step: it moves the pending row with id, at version, to available with what the store reported in obj, and returns it. Refusals: blobfs.ErrNotFound; a blobfs.DeletingError for a deleting row; query.ErrVersionMismatch, which a retry after a completion that committed meets too; a blobfs.TransitionError for a row available at version. See Files in docs/features.md.

func (*Files) Continue 

func (f *Files) Continue(ctx context.Context, sess sqlate.Session, directoryID string, req query.Directives, after query.Cursor, size int, opts ...ListOption) (_ query.Collection[blobfs.File], err error)

Continue reads the size files in directoryID past after, the Next of an earlier page of the listing called the same way. Refusals: List's, and a query.CursorError before any SQL. See Listings in docs/features.md.

func (*Files) Create 

func (f *Files) Create(ctx context.Context, sess sqlate.Session, keys blobfs.KeyValidator, directoryID, name, contentType string, opts ...CreateOption) (_ blobfs.File, err error)

Create is the write's first step: it inserts the row pending with the declared contentType and a key built by blobfs.NewKey and checked by keys, and returns it. The name, the id, and the key are checked before any SQL. A name a deleting file holds is refused with that file's blobfs.DeletingError, not blobfs.ErrNameTaken. See Files in docs/features.md.

func (*Files) Delete 

func (f *Files) Delete(ctx context.Context, tx *sqlate.Tx, id string, opts ...VersionOption) (_ blobfs.File, err error)

Delete is the delete's first step: it moves the row of the file with id to deleting and returns it; the caller deletes the object under its Key and then calls Purge. A row already deleting is returned as it is, the step's retry. The consumer checks for its own references in tx after the call. Refusals: blobfs.ErrNotFound; query.ErrVersionMismatch under AtVersion. See Files in docs/features.md.

func (*Files) Ensure 

func (f *Files) Ensure(ctx context.Context, sess sqlate.Session, keys blobfs.KeyValidator, directoryID, name, contentType string, opts ...CreateOption) (_ blobfs.File, _ WriteOutcome, err error)

Ensure is the retry-safe first step: it returns the row that holds name in directoryID, creating it pending when none does, and the WriteOutcome that says which. A found row, a deleting one included, keeps its own id and key. Its refusals are Create's, except that a deleting row that holds the name is returned as WritePresent, and blobfs.ErrNameTaken inside a transaction for a writer that commits the name after the lookup. See Files in docs/features.md.

func (*Files) Find 

func (f *Files) Find(ctx context.Context, sess sqlate.Session, id string) (_ blobfs.File, err error)

Find returns the file with id, whatever its status, or blobfs.ErrNotFound.

func (*Files) FindByName 

func (f *Files) FindByName(ctx context.Context, sess sqlate.Session, directoryID, name string) (_ blobfs.File, err error)

FindByName returns the file named name in directoryID, whatever its status; the name is normalized first, and a directory of the same name is not found. It is how a retried write finds its pending row. Refusals: blobfs.NameError before any SQL, blobfs.ErrNotFound.

func (*Files) Hold 

func (f *Files) Hold(ctx context.Context, tx *sqlate.Tx, id string, opts ...VersionOption) (err error)

Hold locks the row of the file with id for the rest of tx without changing it, so a Delete of the file waits for tx: the library's half of the reference-then-delete rule. Refusals: blobfs.ErrNotFound, a blobfs.DeletingError, and query.ErrVersionMismatch under AtVersion. See Reference-then-delete in docs/concepts.md.

func (*Files) List 

func (f *Files) List(ctx context.Context, sess sqlate.Session, directoryID string, req query.Directives, page query.Page, opts ...ListOption) (_ query.Collection[blobfs.File], err error)

List reads one page, by number, of the files in directoryID under req, hiding deleting ones unless IncludeDeleting is given. Refusals: query.ErrDirectives before any SQL; blobfs.ErrDeleting for a deleting directory. See Listings in docs/features.md.

func (*Files) Move 

func (f *Files) Move(ctx context.Context, sess sqlate.Session, id, directoryID, name string, version int64) (_ blobfs.File, err error)

Move moves the file with id into directoryID as name, guarded by version, and returns the row; a rename is a move within its directory. The key is untouched. Refusals: blobfs.NameError, blobfs.ErrNotFound, blobfs.ErrNameTaken, a blobfs.DeletingError, and query.ErrVersionMismatch. See Files in docs/features.md.

func (*Files) Purge 

func (f *Files) Purge(ctx context.Context, sess sqlate.Session, id string) (err error)

Purge is the last step of a file delete: it removes the deleting row of the file with id, after the caller deleted its object. A row already gone is success.

Refusals: blobfs.ErrNotDeleting for a row whose delete has not begun; blobfs.ErrReferenced for a consumer's foreign key, which leaves the row deleting.

type ListOption added in v0.2.0 

type ListOption func(*listOptions)

ListOption configures one call of a listing beyond its required arguments: Directories.List, Directories.Continue, Files.List, or Files.Continue.

func IncludeDeleting added in v0.2.0 

func IncludeDeleting() ListOption

IncludeDeleting makes a listing show deleting rows and list a deleting directory, which is how the work of a delete is found. A cursor continues only a listing called the same way, with the option or without it. See Listings in docs/features.md.

type Listing added in v0.3.0 

type Listing[T any] interface {
	List(ctx context.Context, sess sqlate.Session, id string, req query.Directives, page query.Page, opts ...ListOption) (query.Collection[T], error)
	Continue(ctx context.Context, sess sqlate.Session, id string, req query.Directives, after query.Cursor, size int, opts ...ListOption) (query.Collection[T], error)
}

Listing is the interface of the two listings, Directories and Files, each anchored on one directory's id: List reads a page by number, and Continue reads the page past a cursor an earlier page returned. A consumer that reads either listing the same way takes a Listing of the row type.

type Marked added in v0.2.0 

type Marked struct {
	Directories int64
	Files       int64
}

Marked counts the rows Directories.MarkDeleting moved to deleting, directories and files; a row deleting already is not counted.

type ObjectDeleter added in v0.2.0 

type ObjectDeleter interface {
	DeleteObject(ctx context.Context, key string) error
}

ObjectDeleter is the consumer's object store as Store.Sweep and the delete protocols call it. DeleteObject must treat a missing object as success, since a step may run again.

type ObjectPutter added in v0.3.0 

type ObjectPutter interface {
	PutObject(ctx context.Context, key string, body io.Reader, contentType string, size int64) (blobfs.Object, error)
}

ObjectPutter is the consumer's object store as Store.WriteFile and Store.EnsureFile call it. PutObject stores size bytes of body under key in contentType, all or nothing, replacing whatever the key held, and reports the stored object as Files.Complete records it.

type ObjectStore added in v0.3.0 

type ObjectStore interface {
	blobfs.KeyValidator
	ObjectPutter
	ObjectDeleter
}

ObjectStore is the consumer's object store as the protocols call it: the key check, the put, and the delete. The consumer implements it with one adapter over its store, which the write's begin also passes to Files.Create or Files.Ensure as their KeyValidator.

type Option 

type Option func(*options)

Option configures New beyond its required arguments.

func WithEngine 

func WithEngine(e Engine) Option

WithEngine makes the store forward its variation points to the variant e builds instead of the baseline. New calls e once. See Engine.

type RemoveOption added in v0.7.0 

type RemoveOption interface {
	// contains filtered or unexported methods
}

RemoveOption configures one call of Store.RemoveFile beyond its required arguments: AtVersion, a VersionOption, or OnDelete.

func OnDelete added in v0.7.0 

func OnDelete(fn func(ctx context.Context, tx *sqlate.Tx, f blobfs.File) error) RemoveOption

OnDelete runs fn in the transaction that begins the delete, after pick and Files.Delete have marked the file deleting, with the call's context and the File as marked: where a consumer writes its own rows that must commit exactly when the delete begins. A retry, which finds the file already deleting, runs no hook and finishes the delete. An error from fn rolls the transaction back, leaving the file as it was and its object in place; the call returns an error wrapping fn's.

type Store 

type Store struct {
	// Directories holds the operations over blobfs_directory rows.
	Directories *Directories

	// Files holds the operations over blobfs_file rows.
	Files *Files
	// contains filtered or unexported fields
}

Store is blobfs's persistence: the statements compiled once against the consumer's catalog and the operation handles over them. It holds no session; every operation takes one.

func New 

func New(catalog *query.Catalog, dialect sqlate.Dialect, opts ...Option) (_ *Store, err error)

New compiles blobfs's statements against catalog for dialect and binds them, with no I/O. The catalog must carry the blobfs namespace from Patterns() and the query library's from query.Patterns(); a catalog without the blobfs namespace is refused before compiling, and any other compile failure is returned as the loader reports it. The dialect chooses the form of each returning command. With WithEngine, New passes the baseline it bound to the Engine and runs the variant it returns; an Engine's error is returned as "data: new store: engine: ...".

func (*Store) EnsureFile added in v0.5.0 

func (s *Store) EnsureFile(ctx context.Context, db *sqlate.DB, objects ObjectStore, id string, body io.Reader, size int64, begin func(*sqlate.Tx) (blobfs.File, WriteOutcome, error), opts ...WriteOption) (_ blobfs.File, stored bool, err error)

EnsureFile is the retry-safe WriteFile of the file under the fixed id: begin runs Files.Ensure with WithID(id) in one transaction on db. A row begin created, or a pending one under id, is written as WriteFile writes it, OnComplete's hook in its completion, and stored reports true; an available row under id is returned as it stands. A completion another writer won returns that writer's row, stored false. The hook runs only when this call completes the file: never for a row found available or one another writer completed. A row under another id is not the caller's and is refused. See The protocols in docs/features.md.

func (*Store) PurgeFile added in v0.5.0 

func (s *Store) PurgeFile(ctx context.Context, db *sqlate.DB, objects ObjectDeleter, file blobfs.File) (err error)

PurgeFile runs the delete's last two steps for a file whose Files.Delete the caller ran itself: it deletes the object under the file's Key, then purges the row on db. An object delete that fails leaves the row deleting, which a retry or the sweep's stale reclaim finishes.

func (*Store) RemoveFile added in v0.5.0 

func (s *Store) RemoveFile(ctx context.Context, db *sqlate.DB, objects ObjectDeleter, pick func(*sqlate.Tx) (string, error), opts ...RemoveOption) (err error)

RemoveFile runs the two-phase delete of the file pick names. pick and Files.Delete under opts run in one transaction on db, where the caller removes its own references to the file; RemoveFile then deletes the object and purges the row, as PurgeFile does. OnDelete runs its hook in that transaction, after the file is marked deleting; a hook error rolls it back and nothing is purged. A retry of an interrupted RemoveFile, which finds the file already deleting, runs no hook and finishes it; a retry of a finished one returns blobfs.ErrNotFound. pick's error, or its transaction's, is returned as it came. See The protocols in docs/features.md.

func (*Store) RemoveFileID added in v0.5.0 

func (s *Store) RemoveFileID(ctx context.Context, db *sqlate.DB, objects ObjectDeleter, id string, opts ...VersionOption) (err error)

RemoveFileID is RemoveFile of the file with id, for a caller with no scope to check and no reference to remove in the delete's transaction.

func (*Store) Statements 

func (s *Store) Statements() []query.Statement

Statements returns the compiled inventory in name order, followed by the variant's own statements.

func (*Store) Sweep added in v0.2.0 

func (s *Store) Sweep(ctx context.Context, db *sqlate.DB, objects ObjectDeleter, opts ...SweepOption) (_ SweepResult, err error)

Sweep runs one bounded, stateless pass that finishes the deletes callers began: the marked branches, and with StaleOlderThan the stale rows. A refusal leaves its row for a later pass, and the pass returns every refusal joined. See The sweep in docs/features.md.

func (*Store) Verify 

func (s *Store) Verify(ctx context.Context, sess sqlate.Session) error

Verify prepares every statement, the variant's included, against the schema the session reaches, and probes both listings' field contracts and a page past a cursor, so a program that calls it at startup fails there and not at first use.

func (*Store) WriteFile added in v0.5.0 

func (s *Store) WriteFile(ctx context.Context, db *sqlate.DB, objects ObjectStore, body io.Reader, size int64, begin func(*sqlate.Tx) (blobfs.File, error), opts ...WriteOption) (_ blobfs.File, err error)

WriteFile runs the two-phase write of the file begin creates, with size bytes of body as its object. begin runs Files.Create in one transaction on db; the put runs outside any transaction; the completion runs in a transaction on db and returns the row available. OnComplete runs its hook in the completion's transaction. A failed put or completion, the hook's error among them, abandons the write. begin's error, or its transaction's, is returned as it came. See The protocols in docs/features.md.

type SweepOption added in v0.2.0 

type SweepOption func(*sweepOptions)

SweepOption configures one call of Store.Sweep beyond its required arguments.

func Batch added in v0.2.0 

func Batch(n int) SweepOption

Batch bounds the records one pass of Store.Sweep handles to n: each file finished, each directory removed, and each stale row reclaimed counts one. The default is 100; an n below 1 is refused before any SQL.

func OnRemoveDirectory added in v0.2.0 

func OnRemoveDirectory(fn func(ctx context.Context, tx *sqlate.Tx, dir blobfs.Directory) error) SweepOption

OnRemoveDirectory runs fn in the transaction that removes each directory of a branch, before the removal: where a consumer removes its own rows that reference the directory. An error from fn rolls the removal back for the next pass.

func StaleOlderThan added in v0.2.0 

func StaleOlderThan(age time.Duration) SweepOption

StaleOlderThan makes a pass of Store.Sweep also reclaim the pending and deleting file rows last written more than age ago, oldest first. age must exceed the longest write the consumer lets run; see Stale rows and orphaned objects in docs/concepts.md.

type SweepResult added in v0.2.0 

type SweepResult struct {
	Files       int
	Directories int
	Stale       int
	More        bool
}

SweepResult is what one pass of Store.Sweep did: Files counts the branches' files finished, Directories the directories removed, and Stale the stale rows reclaimed, each row once. More reports work remaining; a caller runs passes while it is true.

type Variant 

type Variant interface {
	// LockTree takes the tree lock in tx, held until tx ends.
	LockTree(ctx context.Context, tx *sqlate.Tx) error
	// Serializes reports whether LockTree serializes across transactions.
	Serializes() bool
	// ResolvePath walks segments down from startID and returns the deepest
	// directory reached and the number of segments matched. A missing
	// start is blobfs.ErrNotFound; no segments returns the start at depth
	// 0.
	ResolvePath(ctx context.Context, sess sqlate.Session, startID string, segments []string) (blobfs.Directory, int, error)
	// HoldFile takes the row lock Files.Delete waits on, for the rest of
	// tx, and reports whether it held a row that is not deleting and sits
	// at *version when version is not nil. A false takes no lock and is
	// not an error.
	HoldFile(ctx context.Context, tx *sqlate.Tx, id string, version *int64) (bool, error)
	// Statements returns the variant's own compiled statements.
	Statements() []query.Statement
	// Verify prepares the variant's own statements against sess.
	Verify(ctx context.Context, sess sqlate.Session) error
}

Variant is the set of variation points an engine may implement natively. A variant embeds the variant its Engine is given and overrides what it needs; a type that implements Variant without embedding the given one is outside the contract. See Variants and engines in docs/features.md.

type VersionOption added in v0.2.0 

type VersionOption func(*versionOptions)

VersionOption configures a call that acts on a row the caller read, beyond its required arguments: Files.Hold, Files.Delete, Directories.Delete, Directories.MarkDeleting, Store.RemoveFileID, and, as a RemoveOption, Store.RemoveFile.

func AtVersion 

func AtVersion(version int64) VersionOption

AtVersion makes the call act on the row only at version, the value the caller read from a listing or an earlier read; a row at another version is query.ErrVersionMismatch and is left as it is. A row already deleting is Files.Delete's or Directories.MarkDeleting's retry, which converges.

type WriteOption added in v0.7.0 

type WriteOption func(*writeOptions)

WriteOption configures one call of a write protocol, Store.WriteFile or Store.EnsureFile, beyond its required arguments.

func OnComplete added in v0.7.0 

func OnComplete(fn func(ctx context.Context, tx *sqlate.Tx, f blobfs.File) error) WriteOption

OnComplete runs fn in the transaction that completes the file, after Files.Complete has made the row available, with the call's context and the completed File: where a consumer writes its own rows that must commit exactly when the file does. An error from fn rolls the completion back and abandons the write as a failed completion does, the pending row deleted with its object; the call returns an error wrapping fn's. Store.EnsureFile runs fn only when the call completes the file itself: never for a row it finds available, or one another writer completed.

type WriteOutcome 

type WriteOutcome string

WriteOutcome is what Files.Ensure did with the name. 

const (
	// WriteCreated reports a new pending row: the write's first step ran.
	WriteCreated WriteOutcome = "created"

	// WriteResumed reports a pending row an earlier write left, for the
	// caller to put under its Key and complete at its Version.
	WriteResumed WriteOutcome = "resumed"

	// WritePresent reports a row that is available or deleting, returned
	// unchanged; its Status says which, and the caller decides what it
	// means.
	WritePresent WriteOutcome = "present"
)

Source Files

View all Source files

Directories

Path Synopsis
Package datatest is the conformance suite of the data package: the checks every data.Store must pass against a live database, whatever the engine, the returning commands' form, and the variant.
 Package datatest is the conformance suite of the data package: the checks every data.Store must pass against a live database, whatever the engine, the returning commands' form, and the variant.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.