blobcache

type AEADAlgo string

type ActionSet uint64

type CID = cadata.ID

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 = cadata.ErrNotFound

type ErrPermission struct {
	Handle   Handle
	Rights   ActionSet
	Requires ActionSet
}

type ErrTooLarge struct {
	BlobSize int
	MaxSize  int
}

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"`
	Rights ActionSet `json:"rights"`

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

type HashAlgo string

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

type InsertResp struct {
	// Success is the number of messages that were inserted.
	Success uint32
}

type Message struct {
	// Endpoint is the endpoint where the message came from or is going.
	Endpoint Endpoint `json:"endpoint"`
	// Topic is the topic that the message is speaking on.
	Topic TID `json:"topic"`
	// Payload data to deliver.
	Payload []byte `json:"payload"`
}

type NextOpts struct {
	// Min is the minimum number of messages to read before returning.
	// set to 0 for non blocking.
	// If there are messages available at the start of the call,
	// they must be emitted even if Min is 0
	Min uint32 `json:"min"`
	// LeaveIn will cause the emitted messages to stay in the queue.
	LeaveIn bool `json:"leave_in"`
	// Skip drops this many messages before emitting any
	Skip uint32 `json:"skip"`
	// MaxWait is the maximum amount of time to wait.
	MaxWait *time.Duration `json:"max_wait"`
}

type OID [OIDSize]byte

type OIDPath = []OID

type PeerID = inet256.ID

type PostOpts struct {
	Salt *CID
}

type QueueAPI interface {
	// CreateQueue creates a new queue and returns a handle to it.
	CreateQueue(ctx context.Context, host *Endpoint, qspec QueueSpec) (*Handle, error)
	// Next reads from the queue.
	// It reads into buf until buf is full or another criteria is fulfilled.
	Next(ctx context.Context, q Handle, buf []Message, opts NextOpts) (int, error)
	// Insert adds the messages to the end of the queue.
	Insert(ctx context.Context, from *Endpoint, q Handle, msgs []Message) (*InsertResp, error)

	// SubToVolume causes all changes to a Volume's cell to be
	// writen as message to the queue.
	SubToVolume(ctx context.Context, q Handle, vol Handle) error
}

type QueueBackend[T handleOrOID] struct {
	Memory *QueueBackend_Memory `json:"memory,omitempty"`
	Remote *QueueBackend_Remote `json:"remote,omitempty"`
}

type QueueBackend_Memory struct {
	// MaxDepth
	MaxDepth uint32 `json:"max_depth"`
	// EvictOldest will cause the oldest message in the queue to be evicted
	// when the mailbox is full.
	// The default value (false) causes new messages to be dropped when the queue is full.
	EvictOldest bool
}

type QueueBackend_Remote struct {
	Endpoint Endpoint
	OID      OID
}

type QueueInfo struct {
	ID   OID               `json:"id"`
	Spec QueueBackend[OID] `json:"spec"`
}

type QueueSpec = QueueBackend[Handle]

type SchemaName string

type SchemaSpec struct {
	// Name is the name of the schema.
	Name SchemaName `json:"name"`
	// Params are the parameters for the schema.
	Params json.RawMessage `json:"params,omitempty"`
}

type Secret [32]byte

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

type TID [32]byte

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, srcTxns []Handle, cids []CID, success []bool) 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

	// Link adds a link to another volume.
	// All Link operations take effect atomically on Commit
	Link(ctx context.Context, tx Handle, target Handle, mask ActionSet) error
	// Unlink removes a link from the transaction's volume to any and all of the OIDs
	// All Unlink operations take effect atomically on Commit.
	Unlink(ctx context.Context, tx Handle, targets []OID) error
	// VisitLink visits a link to another volume.
	// This is only usable in a GC transaction.
	// Any unvisited links will be deleted at the end of a GC transaction.
	VisitLinks(ctx context.Context, tx Handle, targets []OID) error
}

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

type TxParams struct {
	// Modify is true if the transaction will change the Volume's state.
	Modify 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 URL struct {
	Node   PeerID
	IPPort *netip.AddrPort
	Base   OID
	Path   OIDPath
	Extra  string
}

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)

	// 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"`
	Consensus *VolumeBackend_Consensus `json:"consensus,omitempty"`
}

type VolumeBackend_Consensus struct {
	Schema   SchemaSpec `json:"schema"`
	HashAlgo HashAlgo   `json:"hash_algo"`
	MaxSize  int64      `json:"max_size"`
}

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

	VolumeConfig
}

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

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

type VolumeBackend_Vault[T handleOrOID] struct {
	X        T        `json:"x"`
	Secret   Secret   `json:"secret"`
	HashAlgo HashAlgo `json:"hash_algo"`
}

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

type VolumeInfo struct {
	// ID is always the local OID for the volume.
	ID OID `json:"id"`
	VolumeConfig
	Backend VolumeBackend[OID] `json:"backend"`
}

type VolumeSpec = VolumeBackend[Handle]