mysql

README

MySQL Storage for Trillian Tessera

This directory contains the implementation of a storage backend for Trillian Tessera using MySQL. This allows Tessera to leverage MySQL as its underlying database for storing checkpoint, entry hashes and data in tiles format.

Design

See MySQL storage design documentation.

Requirements

• A running MySQL server instance. This storage implementation has been tested against MySQL 8.4.

Usage

Constructing the Storage Object

Here is an example code snippet to initialise the MySQL storage in Trillian Tessera.

import (
    "context"

    tessera "github.com/transparency-dev/trillian-tessera"
    "github.com/transparency-dev/trillian-tessera/storage/mysql"
    "k8s.io/klog/v2"
)

func main() {
    mysqlURI := "user:password@tcp(db:3306)/tessera"
    db, err := sql.Open("mysql", mysqlURI)
    if err != nil {
        klog.Exitf("Failed to connect to DB: %v", err)
    }

    storage, err := mysql.New(ctx, db)
    if err != nil {
        klog.Exitf("Failed to create new MySQL storage: %v", err)
    }
}

Example personality

See MySQL conformance example.

Future Work

• Separate sequencing and integration

Documentation

Overview

Package mysql contains a MySQL-based storage implementation for Tessera.

Index

• type Storage
  • func New(ctx context.Context, db *sql.DB, opts ...func(*options.StorageOptions)) (*Storage, error)
  • func (s *Storage) Add(ctx context.Context, entry *tessera.Entry) tessera.IndexFuture
  • func (s *Storage) ReadCheckpoint(ctx context.Context) ([]byte, error)
  • func (s *Storage) ReadEntryBundle(ctx context.Context, index, treeSize uint64) ([]byte, error)
  • func (s *Storage) ReadTile(ctx context.Context, level, index, minTreeSize uint64) ([]byte, error)

Types

type Storage

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

Storage is a MySQL-based storage implementation for Tessera.

func New

func New(ctx context.Context, db *sql.DB, opts ...func(*options.StorageOptions)) (*Storage, error)

New creates a new instance of the MySQL-based Storage. Note that `tessera.WithCheckpointSigner()` is mandatory in the `opts` argument.

func (*Storage) Add

func (s *Storage) Add(ctx context.Context, entry *tessera.Entry) tessera.IndexFuture

Add is the entrypoint for adding entries to a sequencing log.

func (*Storage) ReadCheckpoint

func (s *Storage) ReadCheckpoint(ctx context.Context) ([]byte, error)

ReadCheckpoint returns the latest stored checkpoint. If the checkpoint is not found, it returns os.ErrNotExist.

func (*Storage) ReadEntryBundle

func (s *Storage) ReadEntryBundle(ctx context.Context, index, treeSize uint64) ([]byte, error)

ReadEntryBundle returns the log entries at the given index. If the entry bundle is not found, it returns os.ErrNotExist.

TODO: Handle the following scenarios: 1. Full tile request with full tile output: Return full tile. 2. Full tile request with partial tile output: Return error. 3. Partial tile request with full/larger partial tile output: Return trimmed partial tile with correct tile width. 4. Partial tile request with partial tile (same width) output: Return partial tile. 5. Partial tile request with smaller partial tile output: Return error.

func (*Storage) ReadTile

func (s *Storage) ReadTile(ctx context.Context, level, index, minTreeSize uint64) ([]byte, error)

ReadTile returns a full tile or a partial tile at the given level, index and treeSize. If the tile is not found, it returns os.ErrNotExist.

Note that if a partial tile is requested, but a larger tile is available, this will return the largest tile available. This could be trimmed to return only the number of entries specifically requested if this behaviour becomes problematic.