vaultik/internal/types/types.go

// Package types provides custom types for better type safety across the
// vaultik codebase. Using distinct types for IDs, hashes, and paths prevents
// accidental mixing of semantically different values that happen to share the
// same underlying type.
package types //nolint:revive,nolintlint // rename decision tracked in #76

import (
	"database/sql/driver"
	"errors"
	"fmt"

	"github.com/google/uuid"
)

// errCannotScan is returned when a database value cannot be scanned into
// an ID type.
var errCannotScan = errors.New("cannot scan value")

// FileID is a UUID identifying a file record in the database.
//
// used on values.
//
//nolint:recvcheck // Scan requires a pointer receiver; String/Value are
type FileID uuid.UUID

// NewFileID generates a new random FileID.
func NewFileID() FileID {
	return FileID(uuid.New())
}

// ParseFileID parses a string into a FileID.
func ParseFileID(s string) (FileID, error) {
	id, err := uuid.Parse(s)
	if err != nil {
		return FileID{}, err
	}

	return FileID(id), nil
}

// IsZero returns true if the FileID is the zero value.
func (id FileID) IsZero() bool {
	return uuid.UUID(id) == uuid.Nil
}

// Value implements driver.Valuer for database serialization.
func (id FileID) Value() (driver.Value, error) {
	return uuid.UUID(id).String(), nil
}

// Scan implements sql.Scanner for database deserialization.
func (id *FileID) Scan(src any) error {
	if src == nil {
		*id = FileID{}

		return nil
	}

	var s string

	switch v := src.(type) {
	case string:
		s = v
	case []byte:
		s = string(v)
	default:
		return fmt.Errorf("%w: %T into FileID", errCannotScan, src)
	}

	parsed, err := uuid.Parse(s)
	if err != nil {
		return fmt.Errorf("invalid FileID: %w", err)
	}

	*id = FileID(parsed)

	return nil
}

// BlobID is a UUID identifying a blob record in the database.
// This is distinct from BlobHash which is the content-addressed hash of the blob.
//
// used on values.
//
//nolint:recvcheck // Scan requires a pointer receiver; String/Value are
type BlobID uuid.UUID

// NewBlobID generates a new random BlobID.
func NewBlobID() BlobID {
	return BlobID(uuid.New())
}

// ParseBlobID parses a string into a BlobID.
func ParseBlobID(s string) (BlobID, error) {
	id, err := uuid.Parse(s)
	if err != nil {
		return BlobID{}, err
	}

	return BlobID(id), nil
}

// IsZero returns true if the BlobID is the zero value.
func (id BlobID) IsZero() bool {
	return uuid.UUID(id) == uuid.Nil
}

// Value implements driver.Valuer for database serialization.
func (id BlobID) Value() (driver.Value, error) {
	return uuid.UUID(id).String(), nil
}

// Scan implements sql.Scanner for database deserialization.
func (id *BlobID) Scan(src any) error {
	if src == nil {
		*id = BlobID{}

		return nil
	}

	var s string

	switch v := src.(type) {
	case string:
		s = v
	case []byte:
		s = string(v)
	default:
		return fmt.Errorf("%w: %T into BlobID", errCannotScan, src)
	}

	parsed, err := uuid.Parse(s)
	if err != nil {
		return fmt.Errorf("invalid BlobID: %w", err)
	}

	*id = BlobID(parsed)

	return nil
}

// SnapshotID identifies a snapshot, typically in format "hostname_name_timestamp".
type SnapshotID string

// ChunkHash is the SHA256 hash of a chunk's content.
// Used for content-addressing and deduplication of file chunks.
type ChunkHash string

// BlobHash is hex(SHA256(SHA256(uncompressed blob contents))), computed before
// compression and encryption (see blobgen.DoubleSHA256 and
// docs/REPOSTRUCTURE.md). It is used as the filename in S3 storage for
// content-addressed retrieval.
type BlobHash string

// FilePath represents an absolute path to a file or directory.
type FilePath string

// SourcePath is the source directory a scan found a file under, made
// absolute and with symlinks resolved.
type SourcePath string

// Hostname identifies a host machine.
type Hostname string

// Version is a semantic version string.
type Version string

// GitRevision is a git commit SHA.
type GitRevision string

// GlobPattern is a glob pattern for file matching (e.g., "*.log", "node_modules").
type GlobPattern string

// String methods for Stringer interface

func (id FileID) String() string     { return uuid.UUID(id).String() }
func (id BlobID) String() string     { return uuid.UUID(id).String() }
func (id SnapshotID) String() string { return string(id) }
func (h ChunkHash) String() string   { return string(h) }
func (h BlobHash) String() string    { return string(h) }
func (p FilePath) String() string    { return string(p) }
func (p SourcePath) String() string  { return string(p) }
func (h Hostname) String() string    { return string(h) }
func (v Version) String() string     { return string(v) }
func (r GitRevision) String() string { return string(r) }
func (p GlobPattern) String() string { return string(p) }