blobcache

type AEADAlgo string

type ActionSet uint64

type CID = cadata.ID

type Conditions struct {
	AllEqual []Handle  `json:"all_equal,omitempty"`
	NOTEqual *NOTEqual `json:"not,omitempty"`
}

type DEK [32]byte

type Endpoint struct {
	Peer   PeerID         `json:"peer"`
	IPPort netip.AddrPort `json:"ip_port"`
}

type ErrBadData struct {
	Salt     *CID
	Expected CID
	Actual   CID
	Len      int
}

type ErrCannotSalt struct{}

type ErrInvalidHandle struct {
	Handle Handle
}

type ErrNoLink struct {
	Base   OID
	Target OID
}

type ErrNotFound struct {
	Type string
	ID   OID
}

type ErrTxDone struct {
	ID OID
}

type ErrTxNotGC struct {
	Op string
}

type ErrTxReadOnly struct {
	Tx OID
	Op string
}

type FQOID struct {
	Peer PeerID
	OID  OID
}

type GetOpts struct {
	// Salt is required to verify the data, if the volume uses salts.
	Salt *CID
	// SkipVerify causes the retrieved data not to be verified against the CID.
	// This should only be done if you are going to verify the data at a higher level
	// or if you consider the specific volume backend to be inside your security perimeter.
	SkipVerify bool
}

type Handle struct {
	OID    OID
	Secret [16]byte
}

type HandleAPI interface {
	// Drop causes a handle to be released immediately.
	// If all the handles to an object are dropped, the object is deleted.
	Drop(ctx context.Context, h Handle) error
	// KeepAlive extends the TTL for some handles.
	KeepAlive(ctx context.Context, hs []Handle) error
	// InspectHandle returns info about a handle.
	InspectHandle(ctx context.Context, h Handle) (*HandleInfo, error)
	// Share creates a copy of the handle according to the mask, and the
	// sharing rules for the handles actions.
	Share(ctx context.Context, h Handle, to PeerID, mask ActionSet) (*Handle, error)
}

type HandleInfo struct {
	OID OID `json:"oid"`

	CreatedAt tai64.TAI64 `json:"created_at"`
	ExpiresAt tai64.TAI64 `json:"expires_at"`
}

type HashAlgo string

type HashFunc func(salt *CID, data []byte) CID

type NOTEqual struct {
	Volume Handle
	Value  []byte
}

type OID [OIDSize]byte

type PeerID = inet256.ID

type PostOpts struct {
	Salt *CID
}

type Schema string

type Service interface {
	// Endpoint returns the endpoint of the service.
	// If the endpoint is the zero value, the service is not listening for peers.
	Endpoint(ctx context.Context) (Endpoint, error)

	HandleAPI
	VolumeAPI
	TxAPI
}

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

type TxAPI interface {
	// InspectTx returns info about a transaction.
	InspectTx(ctx context.Context, tx Handle) (*TxInfo, error)
	// Commit commits a transaction.
	Commit(ctx context.Context, tx Handle) error
	// Abort aborts a transaction.
	Abort(ctx context.Context, tx Handle) error
	// Load loads the volume root into dst
	Load(ctx context.Context, tx Handle, dst *[]byte) error
	// Save writes to the volume root.
	// Like all operations in a transaction, Save will not be visible until Commit is called.
	Save(ctx context.Context, tx Handle, src []byte) error
	// Post posts data to the volume
	Post(ctx context.Context, tx Handle, data []byte, opts PostOpts) (CID, error)
	// Get returns the data for a CID.
	Get(ctx context.Context, tx Handle, cid CID, buf []byte, opts GetOpts) (int, error)
	// Exists checks if several CID exists in the volume
	// len(dst) must be equal to len(cids), or Exists will return an error.
	Exists(ctx context.Context, tx Handle, cids []CID, dst []bool) error
	// Delete deletes a CID from the volume
	Delete(ctx context.Context, tx Handle, cids []CID) error
	// Copy has the same effect as Post, but it does not require sending the data to Blobcache.
	// It returns a slice of booleans, indicating if the CID could be added.
	// srcTxns are the transactions to copy from.  They will be checked in random order.
	// If none of them have the blob to copy, then false is written to success for that blob.
	// Error is only returned if there is an internal error, otherwise the success slice is used to signal
	// whether a CID was successfully copied.
	Copy(ctx context.Context, tx Handle, cids []CID, srcTxns []Handle, success []bool) error
	// AllowLink allows the Volume to reference another volume.
	// The volume must still have a recognized Container Schema for the volumes to be persisted.
	AllowLink(ctx context.Context, tx Handle, subvol Handle) error
	// Visit is only usable in a GC transaction.
	// It marks each CID as being visited, so it will not be removed by GC.
	Visit(ctx context.Context, tx Handle, cids []CID) error
	// IsVisited is only usable in a GC transaction.
	// It checks if each CID has been visited.
	IsVisited(ctx context.Context, tx Handle, cids []CID, yesVisited []bool) error
}

type TxInfo struct {
	ID       OID
	Volume   OID
	MaxSize  int64
	HashAlgo HashAlgo
	Params   TxParams
}

type TxParams struct {
	Mutate bool
	// GC causes the transaction to remove all blobs that have not been
	// observed in the transaction.
	// This happens at the end of the transaction.
	// Mutate must be true if GC is set, or BeginTx will return an error.
	GC bool
}

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

type VolumeAPI interface {
	// CreateVolume creates a new volume.
	// CreateVolume always creates a Volume on the local Node.
	// CreateVolume returns a handle to the Volume.  If no other references to the Volume
	// have been created by the time the handle expires, the Volume will be deleted.
	// Leave caller nil to skip Authorization checks.
	// Host describes where the Volume should be created.
	// If the Host is nil, the Volume will be created on the local Node.
	CreateVolume(ctx context.Context, host *Endpoint, vspec VolumeSpec) (*Handle, error)
	// InspectVolume returns info about a Volume.
	InspectVolume(ctx context.Context, h Handle) (*VolumeInfo, error)
	// OpenFiat returns a handle to an object by it's ID.
	// This is where any Authorization checks are done.
	// It's called "fiat" because it's up to the Node to say yes or no.
	// The result is implementation dependent, unlike OpenFrom, which should behave
	// the same way on any Node.
	OpenFiat(ctx context.Context, x OID, mask ActionSet) (*Handle, error)
	// OpenFrom returns a handle to an object by it's ID.
	// base is the handle of a Volume, which links to the object.
	// the base Volume's schema must be a Container.
	OpenFrom(ctx context.Context, base Handle, x OID, mask ActionSet) (*Handle, error)
	// Await waits for a set of conditions to be met.
	Await(ctx context.Context, cond Conditions) error
	// BeginTx begins a new transaction, on a Volume.
	BeginTx(ctx context.Context, volh Handle, txp TxParams) (*Handle, error)
	// CloneVolume clones a Volume, copying it's configuration, blobs, and cell data.
	CloneVolume(ctx context.Context, caller *PeerID, volh Handle) (*Handle, error)
}

type VolumeBackend[T handleOrOID] struct {
	Local  *VolumeBackend_Local    `json:"local,omitempty"`
	Remote *VolumeBackend_Remote   `json:"remote,omitempty"`
	Git    *VolumeBackend_Git      `json:"git,omitempty"`
	Vault  *VolumeBackend_Vault[T] `json:"vault,omitempty"`
}

type VolumeBackend_Git struct {
	URL string `json:"url"`

	VolumeParams
}

type VolumeBackend_Local struct {
	VolumeParams
}

type VolumeBackend_Remote struct {
	Endpoint Endpoint `json:"endpoint"`
	Volume   OID      `json:"volume"`
	HashAlgo HashAlgo `json:"hash_algo"`
}

type VolumeBackend_Vault[T handleOrOID] struct {
	Inner  T        `json:"inner"`
	Secret [32]byte `json:"secret"`
}

type VolumeInfo struct {
	ID OID `json:"id"`
	VolumeParams
	Backend VolumeBackend[OID] `json:"backend"`
}

type VolumeParams struct {
	Schema   Schema   `json:"schema"`
	HashAlgo HashAlgo `json:"hash_algo"`
	MaxSize  int64    `json:"max_size"`
	Salted   bool     `json:"salted"`
}

type VolumeSpec = VolumeBackend[Handle]