tlog

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package tlog provides log metadata storage for per-log configuration.

internal/tlog/manager.go

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppendReceipt 

type AppendReceipt struct {
	Index              uint64
	TreeSize           uint64
	HeadCID            string
	Checkpoint         []byte // raw signed checkpoint note
	RevocationsHeadCID string // head CID of the revocations log (empty if no revocations)
}

AppendReceipt holds the data returned synchronously after an append.

type BlobFetcher 

type BlobFetcher interface {
	FetchBlob(ctx context.Context, cid string) ([]byte, error)
}

BlobFetcher is an interface for fetching blobs by CID.

type CIDStore 

type CIDStore interface {
	GetLatestCID(logID string) (string, error)
	SetLatestCID(logID string, cid string) error
}

CIDStore tracks the latest index CAR root CID for each log.

type DelegatedManagerConfig 

type DelegatedManagerConfig struct {
	BasePath      string
	Signer        Signer
	PrivateKey    []byte
	OriginPrefix  string
	ServiceSigner principal.Signer
	StoreManager  *sqlite.StoreManager // Optional: if nil, will be created from BasePath
	ReplicaCount  uint                 // Number of blob replicas (default: 3, some accounts max out at 2)
	Logger        *slog.Logger
}

DelegatedManagerConfig configures a Manager for customer-delegated storage.

type Ed25519Signer 

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

Ed25519Signer implements tessera.Signer using Ed25519 keys

func NewEd25519Signer 

func NewEd25519Signer(privateKey ed25519.PrivateKey, name string) (*Ed25519Signer, error)

NewEd25519Signer creates a new Ed25519 signer for Tessera checkpoints

func (*Ed25519Signer) KeyHash 

func (s *Ed25519Signer) KeyHash() uint32

KeyHash returns the key ID per the signed note format (c2sp.org/signed-note). The key ID is SHA256(name + "\n" + encoded_key)[:4] where encoded_key is the type byte (0x01 for Ed25519) followed by the public key bytes.

func (*Ed25519Signer) Name 

func (s *Ed25519Signer) Name() string

Name returns the signer's name (used in checkpoint format)

func (*Ed25519Signer) PublicKey 

func (s *Ed25519Signer) PublicKey() ed25519.PublicKey

PublicKey returns the Ed25519 public key

func (*Ed25519Signer) Sign 

func (s *Ed25519Signer) Sign(data []byte) ([]byte, error)

Sign creates an Ed25519 signature over the given data

type FileCIDStore 

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

FileCIDStore implements CIDStore by reading from the filesystem. Each log's latest CID is stored at {basePath}/logs/{logID}/.state/latest-index-cid

func NewFileCIDStore 

func NewFileCIDStore(basePath string) *FileCIDStore

NewFileCIDStore creates a new file-based CID store.

func (*FileCIDStore) GetLatestCID 

func (s *FileCIDStore) GetLatestCID(logID string) (string, error)

GetLatestCID retrieves the latest index CAR root CID for a log.

func (*FileCIDStore) SetLatestCID 

func (s *FileCIDStore) SetLatestCID(logID string, cid string) error

SetLatestCID updates the latest index CAR root CID for a log.

type LogInstance 

type LogInstance struct {
	Appender *tessera.Appender
	Reader   tessera.LogReader
	Driver   tessera.Driver // Store driver for reuse in RecreateAppender
	SpaceDID string         // Customer's space DID (for delegated storage)
	// contains filtered or unexported fields
}

LogInstance holds both the appender and reader for a log.

type LogMeta 

type LogMeta struct {
	// LogDID is the DID of the log (derived from log ID key)
	LogDID string `json:"log_did"`

	// SpaceDID is the customer's Storacha space DID
	SpaceDID string `json:"space_did"`

	// HeadIndexCID is the CID of the latest index CAR root
	HeadIndexCID string `json:"head_index_cid,omitempty"`

	// TreeSize is the current log size (number of entries)
	TreeSize uint64 `json:"tree_size"`

	// CreatedAt is when the log was created
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the log was last modified
	UpdatedAt time.Time `json:"updated_at"`
}

LogMeta contains per-log metadata including customer space information.

type LogMetaStore 

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

LogMetaStore handles persistence of log metadata.

func NewLogMetaStore 

func NewLogMetaStore(basePath string) *LogMetaStore

NewLogMetaStore creates a new log metadata store.

func (*LogMetaStore) Create 

func (s *LogMetaStore) Create(logID, logDID, spaceDID string) (*LogMeta, error)

Create creates new log metadata.

func (*LogMetaStore) Delete 

func (s *LogMetaStore) Delete(logID string) error

Delete removes log metadata.

func (*LogMetaStore) Exists 

func (s *LogMetaStore) Exists(logID string) bool

Exists checks if log metadata exists.

func (*LogMetaStore) Get 

func (s *LogMetaStore) Get(logID string) (*LogMeta, error)

Get retrieves log metadata by log ID.

func (*LogMetaStore) Save 

func (s *LogMetaStore) Save(logID string, meta *LogMeta) error

Save persists log metadata.

func (*LogMetaStore) UpdateHead 

func (s *LogMetaStore) UpdateHead(logID string, headCID string, treeSize uint64) error

UpdateHead updates the head index CID and tree size for a log.

type Manager 

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

Manager handles Tessera tlog operations.

func NewDelegatedManager 

func NewDelegatedManager(cfg DelegatedManagerConfig) (*Manager, error)

NewDelegatedManager creates a tlog manager that uses customer-delegated Storacha storage. Each log uses the customer's own Storacha space via UCAN delegation.

func NewManager 

func NewManager(basePath string, signer Signer) (*Manager, error)

NewManager creates a new tlog manager.

func NewStorachaManager 

func NewStorachaManager(basePath string, signer Signer, privateKey []byte, originPrefix string, storachaClient storacha.StorachaClient, spaceDID string) (*Manager, error)

NewStorachaManager creates a new tlog manager backed by Storacha/IPFS storage. privateKey is the Ed25519 private key used for signing checkpoints. originPrefix is the prefix for log origins (e.g., "ucanlog" results in origins like "ucanlog/logs/<logID>").

func (*Manager) AddEntryWithDelegation 

func (m *Manager) AddEntryWithDelegation(ctx context.Context, logID string, data []byte, dlg delegation.Delegation) (uint64, error)

AddEntryWithDelegation adds an entry to a log using the provided delegation. A fresh GuppyClient is created per call, ensuring each write uses its own delegation.

func (*Manager) Close 

func (m *Manager) Close()

Close shuts down all active log drivers (e.g. upload queue workers). Call this on server shutdown.

func (*Manager) CreateLog 

func (m *Manager) CreateLog(ctx context.Context, logID string) error

CreateLog creates a new transparency log. Deprecated: Use CreateLogWithDelegation for customer-delegated storage.

func (*Manager) CreateLogWithDelegation 

func (m *Manager) CreateLogWithDelegation(ctx context.Context, logID string, spaceDID string, dlg delegation.Delegation) error

CreateLogWithDelegation creates a log using customer-delegated Storacha storage. The customer's delegation grants the service write access to their space.

func (*Manager) GetAppender 

func (m *Manager) GetAppender(ctx context.Context, logID string) (*tessera.Appender, error)

GetAppender retrieves a log appender by ID.

func (*Manager) GetBlobFetcher 

func (m *Manager) GetBlobFetcher(ctx context.Context, logID string, spaceDID string, dlg delegation.Delegation) (BlobFetcher, error)

GetBlobFetcher returns a client that can fetch blobs from the space. This is used for fetching delegations during revocation.

func (*Manager) GetLogInstance 

func (m *Manager) GetLogInstance(ctx context.Context, logID string) (*LogInstance, error)

GetLogInstance retrieves a log instance by ID. If the log is not in memory but exists on disk, it is lazily restored.

func (*Manager) GetLogSpaceDID 

func (m *Manager) GetLogSpaceDID(ctx context.Context, logID string) (string, error)

GetLogSpaceDID returns the customer's space DID for a log.

func (*Manager) GetReader 

func (m *Manager) GetReader(ctx context.Context, logID string) (tessera.LogReader, error)

GetReader retrieves a log reader by ID.

func (*Manager) LastAppendReceipt 

func (m *Manager) LastAppendReceipt(logID string) *AppendReceipt

ReadCheckpoint reads the latest checkpoint from the specified log. LastAppendReceipt returns the receipt from the most recent append to logID.

func (*Manager) LogExists 

func (m *Manager) LogExists(ctx context.Context, logID string) (bool, error)

LogExists checks if a log exists.

func (*Manager) ReadCheckpoint 

func (m *Manager) ReadCheckpoint(ctx context.Context, logID string) ([]byte, error)

func (*Manager) ReadEntryBundle 

func (m *Manager) ReadEntryBundle(ctx context.Context, logID string, index uint64, p uint8) ([]byte, error)

ReadEntryBundle reads an entry bundle from the specified log.

func (*Manager) ReadRange 

func (m *Manager) ReadRange(ctx context.Context, logID string, startIndex, endIndex uint64) ([][]byte, error)

ReadRange reads entries from startIndex to endIndex (exclusive) from the specified log. This uses Tessera's bundle-based storage to efficiently read multiple entries.

Note: Tessera stores entries in bundles, and partial bundles contain cumulative entries. This implementation provides basic ReadRange functionality by parsing bundles. In production, you'd want more sophisticated bundle parsing and caching.

func (*Manager) ReadTile 

func (m *Manager) ReadTile(ctx context.Context, logID string, level, index uint64, p uint8) ([]byte, error)

ReadTile reads a tile from the specified log.

func (*Manager) RecoverLog 

func (m *Manager) RecoverLog(ctx context.Context, logID string, headCID string, revocationsHeadCID string) error

RecoverLog re-seeds the state stores for logID (and its revocations log) from the IPFS gateway after a total DB wipeout.

headCID is required — it is the last known headCID for the main log.

revocationsHeadCID must be supplied if the revocations log ever had entries written to it. Pass an empty string only if you are certain no revocations were ever recorded; omitting it when revocations existed leaves the log exposed to formerly revoked credentials.

After a successful RecoverLog the normal ModeResume startup path will find the restored state for both logs.

func (*Manager) RecreateAppender 

func (m *Manager) RecreateAppender(ctx context.Context, logID string) error

RecreateAppender recreates the appender for a log to avoid state corruption. It reuses the existing driver to preserve the index persistence manager's connection to the same objStore and its onDirty callback.

func (*Manager) UpdateDelegation 

func (m *Manager) UpdateDelegation(ctx context.Context, logID string, dlg delegation.Delegation) error

UpdateDelegation updates the delegation for an existing log. This allows customers to refresh expired delegations. Note: With per-request delegation passing, this method now just verifies the log exists. The new delegation will be used on the next write via AddEntryWithDelegation.

type Signer 

type Signer interface {
	Name() string
	Sign([]byte) ([]byte, error)
	KeyHash() uint32
}

Signer signs checkpoints for transparent logs

type StateStoreCIDStore 

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

StateStoreCIDStore implements CIDStore using SQLite-backed StateStore. Reads the head CID from latest_head_car (updated synchronously on every append).

func NewStateStoreCIDStore 

func NewStateStoreCIDStore(getStore StateStoreGetterFunc) *StateStoreCIDStore

NewStateStoreCIDStore creates a new StateStore-backed CID store.

func (*StateStoreCIDStore) GetLatestCID 

func (s *StateStoreCIDStore) GetLatestCID(logID string) (string, error)

GetLatestCID retrieves the latest head CID for a log.

func (*StateStoreCIDStore) SetLatestCID 

func (s *StateStoreCIDStore) SetLatestCID(logID string, cid string) error

SetLatestCID is a no-op: the head CID is maintained by the append path.

type StateStoreGetterFunc 

type StateStoreGetterFunc func(logDID string) (storage.StateStore, error)

StateStoreGetterFunc is a function that returns a StateStore for a log DID.

Source Files

View all Source files

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.