kalzu-value-store/types/types.go

package types

import "encoding/json"

// Core data structures
type StoredValue struct {
	UUID      string          `json:"uuid"`
	Timestamp int64           `json:"timestamp"`
	Data      json.RawMessage `json:"data"`
}

// Phase 2: Authentication & Authorization data structures

// User represents a system user
type User struct {
	UUID         string   `json:"uuid"`         // Server-generated UUID
	NicknameHash string   `json:"nickname_hash"` // SHA3-512 hash of nickname
	Groups       []string `json:"groups"`       // List of group UUIDs this user belongs to
	CreatedAt    int64    `json:"created_at"`   // Unix timestamp
	UpdatedAt    int64    `json:"updated_at"`   // Unix timestamp
}

// Group represents a user group
type Group struct {
	UUID        string   `json:"uuid"`        // Server-generated UUID
	NameHash    string   `json:"name_hash"`   // SHA3-512 hash of group name
	Members     []string `json:"members"`     // List of user UUIDs in this group
	CreatedAt   int64    `json:"created_at"`  // Unix timestamp
	UpdatedAt   int64    `json:"updated_at"`  // Unix timestamp
}

// APIToken represents a JWT authentication token
type APIToken struct {
	TokenHash string   `json:"token_hash"` // SHA3-512 hash of JWT token
	UserUUID  string   `json:"user_uuid"`  // UUID of the user who owns this token
	Scopes    []string `json:"scopes"`     // List of permitted scopes (e.g., "read", "write")
	IssuedAt  int64    `json:"issued_at"`  // Unix timestamp when token was issued
	ExpiresAt int64    `json:"expires_at"` // Unix timestamp when token expires
}

// ResourceMetadata contains ownership and permission information for stored resources
type ResourceMetadata struct {
	OwnerUUID   string `json:"owner_uuid"`   // UUID of the resource owner
	GroupUUID   string `json:"group_uuid"`   // UUID of the resource group
	Permissions int    `json:"permissions"`  // 12-bit permission mask (POSIX-inspired)
	TTL         string `json:"ttl"`          // Time-to-live duration (Go format)
	CreatedAt   int64  `json:"created_at"`   // Unix timestamp when resource was created
	UpdatedAt   int64  `json:"updated_at"`   // Unix timestamp when resource was last updated
}

// Permission constants for POSIX-inspired ACL
const (
	// Owner permissions (bits 11-8)
	PermOwnerCreate = 1 << 11
	PermOwnerDelete = 1 << 10
	PermOwnerWrite  = 1 << 9
	PermOwnerRead   = 1 << 8
	
	// Group permissions (bits 7-4)
	PermGroupCreate = 1 << 7
	PermGroupDelete = 1 << 6
	PermGroupWrite  = 1 << 5
	PermGroupRead   = 1 << 4
	
	// Others permissions (bits 3-0)
	PermOthersCreate = 1 << 3
	PermOthersDelete = 1 << 2
	PermOthersWrite  = 1 << 1
	PermOthersRead   = 1 << 0
	
	// Default permissions: Owner(1111), Group(0110), Others(0010)
	DefaultPermissions = (PermOwnerCreate | PermOwnerDelete | PermOwnerWrite | PermOwnerRead) |
		(PermGroupWrite | PermGroupRead) |
		(PermOthersRead)
)

// Phase 2: API request/response structures for authentication endpoints

// User Management API structures
type CreateUserRequest struct {
	Nickname string `json:"nickname"`
}

type CreateUserResponse struct {
	UUID string `json:"uuid"`
}

type UpdateUserRequest struct {
	Nickname string   `json:"nickname,omitempty"`
	Groups   []string `json:"groups,omitempty"`
}

type GetUserResponse struct {
	UUID         string   `json:"uuid"`
	NicknameHash string   `json:"nickname_hash"`
	Groups       []string `json:"groups"`
	CreatedAt    int64    `json:"created_at"`
	UpdatedAt    int64    `json:"updated_at"`
}

// Group Management API structures
type CreateGroupRequest struct {
	Groupname string   `json:"groupname"`
	Members   []string `json:"members,omitempty"`
}

type CreateGroupResponse struct {
	UUID string `json:"uuid"`
}

type UpdateGroupRequest struct {
	Members []string `json:"members"`
}

type GetGroupResponse struct {
	UUID      string   `json:"uuid"`
	NameHash  string   `json:"name_hash"`
	Members   []string `json:"members"`
	CreatedAt int64    `json:"created_at"`
	UpdatedAt int64    `json:"updated_at"`
}

// Token Management API structures
type CreateTokenRequest struct {
	UserUUID string   `json:"user_uuid"`
	Scopes   []string `json:"scopes"`
}

type CreateTokenResponse struct {
	Token     string `json:"token"`
	ExpiresAt int64  `json:"expires_at"`
}

// Cluster and member management types
type Member struct {
	ID              string `json:"id"`
	Address         string `json:"address"`
	LastSeen        int64  `json:"last_seen"`
	JoinedTimestamp int64  `json:"joined_timestamp"`
}

type JoinRequest struct {
	ID              string `json:"id"`
	Address         string `json:"address"`
	JoinedTimestamp int64  `json:"joined_timestamp"`
}

type LeaveRequest struct {
	ID string `json:"id"`
}

type PairsByTimeRequest struct {
	StartTimestamp int64  `json:"start_timestamp"`
	EndTimestamp   int64  `json:"end_timestamp"`
	Limit          int    `json:"limit"`
	Prefix         string `json:"prefix,omitempty"`
}

type PairsByTimeResponse struct {
	Path      string `json:"path"`
	UUID      string `json:"uuid"`
	Timestamp int64  `json:"timestamp"`
}

type PutResponse struct {
	UUID      string `json:"uuid"`
	Timestamp int64  `json:"timestamp"`
}

// Phase 2: TTL-enabled PUT request structure
type PutWithTTLRequest struct {
	Data json.RawMessage `json:"data"`
	TTL  string          `json:"ttl,omitempty"` // Go duration format
}

// Phase 2: Tamper-evident logging data structures
type TamperLogEntry struct {
	Timestamp string `json:"timestamp"` // RFC3339 format
	Action    string `json:"action"`    // Type of action
	UserUUID  string `json:"user_uuid"` // User who performed the action
	Resource  string `json:"resource"`  // Resource affected
	Signature string `json:"signature"` // SHA3-512 hash of all fields
}

// Phase 2: Backup system data structures
type BackupStatus struct {
	LastBackupTime    int64  `json:"last_backup_time"`    // Unix timestamp
	LastBackupSuccess bool   `json:"last_backup_success"` // Whether last backup succeeded
	LastBackupPath    string `json:"last_backup_path"`    // Path to last backup file
	NextBackupTime    int64  `json:"next_backup_time"`    // Unix timestamp of next scheduled backup
	BackupsRunning    int    `json:"backups_running"`     // Number of backups currently running
}

// Merkle Tree specific data structures
type MerkleNode struct {
	Hash     []byte `json:"hash"`
	StartKey string `json:"start_key"` // The first key in this node's range
	EndKey   string `json:"end_key"`   // The last key in this node's range
}

// MerkleRootResponse is the response for getting the root hash
type MerkleRootResponse struct {
	Root *MerkleNode `json:"root"`
}

// MerkleTreeDiffRequest is used to request children hashes for a given key range
type MerkleTreeDiffRequest struct {
	ParentNode MerkleNode `json:"parent_node"` // The node whose children we want to compare (from the remote peer's perspective)
	LocalHash  []byte     `json:"local_hash"`  // The local hash of this node/range (from the requesting peer's perspective)
}

// MerkleTreeDiffResponse returns the remote children nodes or the actual keys if it's a leaf level
type MerkleTreeDiffResponse struct {
	Children []MerkleNode `json:"children,omitempty"` // Children of the remote node
	Keys     []string     `json:"keys,omitempty"`     // Actual keys if this is a leaf-level diff
}

// For fetching a range of KV pairs
type KVRangeRequest struct {
	StartKey string `json:"start_key"`
	EndKey   string `json:"end_key"`
	Limit    int    `json:"limit"` // Max number of items to return
}

type KVRangeResponse struct {
	Pairs []struct {
		Path        string      `json:"path"`
		StoredValue StoredValue `json:"stored_value"`
	} `json:"pairs"`
}

// Configuration
type Config struct {
	NodeID             string   `yaml:"node_id"`
	BindAddress        string   `yaml:"bind_address"`
	Port               int      `yaml:"port"`
	DataDir            string   `yaml:"data_dir"`
	SeedNodes          []string `yaml:"seed_nodes"`
	ReadOnly           bool     `yaml:"read_only"`
	LogLevel           string   `yaml:"log_level"`
	GossipIntervalMin  int      `yaml:"gossip_interval_min"`
	GossipIntervalMax  int      `yaml:"gossip_interval_max"`
	SyncInterval       int      `yaml:"sync_interval"`
	CatchupInterval    int      `yaml:"catchup_interval"`
	BootstrapMaxAgeHours int    `yaml:"bootstrap_max_age_hours"`
	ThrottleDelayMs    int      `yaml:"throttle_delay_ms"`
	FetchDelayMs       int      `yaml:"fetch_delay_ms"`
	
	// Phase 2: Database compression configuration
	CompressionEnabled bool `yaml:"compression_enabled"`
	CompressionLevel   int  `yaml:"compression_level"`
	
	// Phase 2: TTL configuration
	DefaultTTL    string `yaml:"default_ttl"`      // Go duration format, "0" means no default TTL
	MaxJSONSize   int    `yaml:"max_json_size"`    // Maximum JSON size in bytes
	
	// Phase 2: Rate limiting configuration
	RateLimitRequests int    `yaml:"rate_limit_requests"` // Max requests per window
	RateLimitWindow   string `yaml:"rate_limit_window"`   // Window duration (Go format)
	
	// Phase 2: Tamper-evident logging configuration
	TamperLogActions []string `yaml:"tamper_log_actions"` // Actions to log
	
	// Phase 2: Backup system configuration
	BackupEnabled   bool   `yaml:"backup_enabled"`    // Enable/disable automated backups
	BackupSchedule  string `yaml:"backup_schedule"`   // Cron schedule format
	BackupPath      string `yaml:"backup_path"`       // Directory to store backups
	BackupRetention int    `yaml:"backup_retention"`  // Days to keep backups
	
	// Feature toggles for optional functionalities
	AuthEnabled            bool `yaml:"auth_enabled"`             // Enable/disable authentication system
	TamperLoggingEnabled   bool `yaml:"tamper_logging_enabled"`   // Enable/disable tamper-evident logging
	ClusteringEnabled      bool `yaml:"clustering_enabled"`       // Enable/disable clustering/gossip
	RateLimitingEnabled    bool `yaml:"rate_limiting_enabled"`    // Enable/disable rate limiting
	RevisionHistoryEnabled bool `yaml:"revision_history_enabled"` // Enable/disable revision history
}