filecas

type Constructor ¶

type Constructor func(StoreConfig) (Store, error)

Constructor builds a backend Store from resolved config.

type PathProvider ¶ added in v0.2.19

type PathProvider interface {
	BlobPath(hash string) (path string, ok bool)
}

PathProvider exposes a blob's local filesystem path, for zero-copy consumers (opening a dataset artifact read-only in place rather than materialising a second multi-GB copy). ok=false when the hash is absent or the backend has no local files (S3). The returned path is content-addressed and therefore immutable — callers MUST NOT write to it.

type ReaderGetter ¶ added in v0.2.19

type ReaderGetter interface {
	GetReader(ctx context.Context, hash string) (io.ReadCloser, int64, error)
}

ReaderGetter streams content out. Returns the reader, the blob size, and ErrNotFound when absent. The caller owns closing the reader.

type ReaderPutter ¶ added in v0.2.19

type ReaderPutter interface {
	PutReader(ctx context.Context, hash string, r io.Reader, size int64) error
}

ReaderPutter streams content in. Implementations MUST hash while streaming and commit create-if-absent ONLY when sha256(stream)==hash — on mismatch they return ErrHashMismatch and store nothing (partial writes must never become visible). size is the exact expected byte count when the caller knows it (Content-Length), or -1; backends that need sizing up front (multipart uploads) may require it.

type Store ¶

type Store interface {
	// Put writes data under hash iff sha256(data)==hash (ErrHashMismatch
	// otherwise) and the hash is absent (create-if-absent dedup; re-Put of
	// identical content is a no-op success).
	Put(ctx context.Context, hash string, data []byte) error
	// Get returns the bytes for hash. ErrNotFound if absent. The result
	// MUST be treated as immutable by the caller.
	Get(ctx context.Context, hash string) ([]byte, error)
	// Exists reports presence without fetching bytes.
	Exists(ctx context.Context, hash string) (bool, error)
	// Name is the backend identity (for logs).
	Name() string
}

Store is a content-addressed blob store. The key IS the content's lowercase sha256 hex.

func Open(name string, cfg StoreConfig) (Store, error)

type StoreConfig ¶

type StoreConfig struct {
	FileDir string

	// Reserved for the out-of-tree S3-compatible backend (fleet overlay).
	S3Bucket string
	S3Prefix string

	// CacheBytes is the in-memory LRU budget (bytes) fronting Get. 0
	// disables the cache (pure pass-through to the backend).
	CacheBytes int64
	// MaxEntryBytes is the per-entry cache guard: a blob larger than this
	// is served straight from the backend and never cached, so one large
	// file can't evict the whole cache. 0 means no per-entry guard.
	MaxEntryBytes int64
}

StoreConfig carries backend-selecting options resolved from chassis config. The file backend uses FileDir; the S3 fields are the fleet overlay seam (unused in open core). CacheBytes/MaxEntryBytes configure the LRU that Open wraps around any backend.

type StreamPutter ¶ added in v0.2.31

type StreamPutter interface {
	PutStream(ctx context.Context, r io.Reader, limit int64) (hash string, size int64, err error)
}

StreamPutter commits an UNTRUSTED stream whose hash is not known until EOF — the inverse of ReaderPutter, which is handed the hash up front by a client that already computed it (`txco apply`). A protocol inlet receiving a document from the network (a print job, an upload) cannot know the content address before the last byte, so the backend spools to a temporary, non-content-addressed location while hashing, and promotes to the content-addressed key only at EOF:

disk: temp file → os.Link into the sharded path
S3:   multipart upload to tmp/<id> → server-side CopyObject → delete tmp

Contract: on ANY error (reader error, ctx cancelled, limit exceeded) nothing becomes visible under any hash and the temporary is removed. limit is the maximum accepted size in bytes; <= 0 means unlimited. A stream of exactly limit bytes is accepted; one byte more is ErrTooLarge. Identical content already present is a successful dedup, not an error.