network/pkg/client/interface.go

package client

import (
	"context"
	"fmt"
	"io"
	"time"
)

// NetworkClient provides the main interface for applications to interact with the network
type NetworkClient interface {
	// Database operations (namespaced per app)
	Database() DatabaseClient

	// Pub/Sub messaging
	PubSub() PubSubClient

	// Network information
	Network() NetworkInfo

	// Storage operations (IPFS)
	Storage() StorageClient

	// Lifecycle
	Connect() error
	Disconnect() error
	Health() (*HealthStatus, error)

	// Config access (snapshot copy)
	Config() *ClientConfig
}

// DatabaseClient provides database operations for applications
type DatabaseClient interface {
	Query(ctx context.Context, sql string, args ...interface{}) (*QueryResult, error)
	Transaction(ctx context.Context, queries []string) error
	CreateTable(ctx context.Context, schema string) error
	DropTable(ctx context.Context, tableName string) error
	GetSchema(ctx context.Context) (*SchemaInfo, error)
}

// PubSubClient provides publish/subscribe messaging
type PubSubClient interface {
	Subscribe(ctx context.Context, topic string, handler MessageHandler) error
	Publish(ctx context.Context, topic string, data []byte) error
	Unsubscribe(ctx context.Context, topic string) error
	ListTopics(ctx context.Context) ([]string, error)
}

// NetworkInfo provides network status and peer information
type NetworkInfo interface {
	GetPeers(ctx context.Context) ([]PeerInfo, error)
	GetStatus(ctx context.Context) (*NetworkStatus, error)
	ConnectToPeer(ctx context.Context, peerAddr string) error
	DisconnectFromPeer(ctx context.Context, peerID string) error
}

// StorageClient provides IPFS storage operations
type StorageClient interface {
	// Upload uploads content to IPFS and pins it
	Upload(ctx context.Context, reader io.Reader, name string) (*StorageUploadResult, error)

	// Pin pins an existing CID
	Pin(ctx context.Context, cid string, name string) (*StoragePinResult, error)

	// Status gets the pin status for a CID
	Status(ctx context.Context, cid string) (*StorageStatus, error)

	// Get retrieves content from IPFS by CID
	Get(ctx context.Context, cid string) (io.ReadCloser, error)

	// Unpin removes a pin from a CID
	Unpin(ctx context.Context, cid string) error
}

// MessageHandler is called when a pub/sub message is received
type MessageHandler func(topic string, data []byte) error

// Data structures

// QueryResult represents the result of a database query
type QueryResult struct {
	Columns []string        `json:"columns"`
	Rows    [][]interface{} `json:"rows"`
	Count   int64           `json:"count"`
}

// SchemaInfo contains database schema information
type SchemaInfo struct {
	Tables []TableInfo `json:"tables"`
}

// TableInfo contains information about a database table
type TableInfo struct {
	Name    string       `json:"name"`
	Columns []ColumnInfo `json:"columns"`
}

// ColumnInfo contains information about a table column
type ColumnInfo struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Nullable bool   `json:"nullable"`
	Default  string `json:"default"`
}

// PeerInfo contains information about a network peer
type PeerInfo struct {
	ID        string    `json:"id"`
	Addresses []string  `json:"addresses"`
	Connected bool      `json:"connected"`
	LastSeen  time.Time `json:"last_seen"`
}

// NetworkStatus contains overall network status
type NetworkStatus struct {
	NodeID       string               `json:"node_id"`
	PeerID       string               `json:"peer_id"`
	Connected    bool                 `json:"connected"`
	PeerCount    int                  `json:"peer_count"`
	DatabaseSize int64                `json:"database_size"`
	Uptime       time.Duration        `json:"uptime"`
	IPFS         *IPFSPeerInfo        `json:"ipfs,omitempty"`
	IPFSCluster  *IPFSClusterPeerInfo `json:"ipfs_cluster,omitempty"`
}

// IPFSPeerInfo contains IPFS peer information for discovery
type IPFSPeerInfo struct {
	PeerID         string   `json:"peer_id"`
	SwarmAddresses []string `json:"swarm_addresses"`
}

// IPFSClusterPeerInfo contains IPFS Cluster peer information for cluster discovery
type IPFSClusterPeerInfo struct {
	PeerID    string   `json:"peer_id"`    // Cluster peer ID (different from IPFS peer ID)
	Addresses []string `json:"addresses"`  // Cluster multiaddresses (e.g., /ip4/x.x.x.x/tcp/9098)
}

// HealthStatus contains health check information
type HealthStatus struct {
	Status       string            `json:"status"` // "healthy", "degraded", "unhealthy"
	Checks       map[string]string `json:"checks"`
	LastUpdated  time.Time         `json:"last_updated"`
	ResponseTime time.Duration     `json:"response_time"`
}

// StorageUploadResult represents the result of uploading content to IPFS
type StorageUploadResult struct {
	Cid  string `json:"cid"`
	Name string `json:"name"`
	Size int64  `json:"size"`
}

// StoragePinResult represents the result of pinning a CID
type StoragePinResult struct {
	Cid  string `json:"cid"`
	Name string `json:"name"`
}

// StorageStatus represents the status of a pinned CID
type StorageStatus struct {
	Cid               string   `json:"cid"`
	Name              string   `json:"name"`
	Status            string   `json:"status"` // "pinned", "pinning", "queued", "unpinned", "error"
	ReplicationMin    int      `json:"replication_min"`
	ReplicationMax    int      `json:"replication_max"`
	ReplicationFactor int      `json:"replication_factor"`
	Peers             []string `json:"peers"`
	Error             string   `json:"error,omitempty"`
}

// ClientConfig represents configuration for network clients
type ClientConfig struct {
	AppName           string        `json:"app_name"`
	DatabaseName      string        `json:"database_name"`
	BootstrapPeers    []string      `json:"peers"`
	DatabaseEndpoints []string      `json:"database_endpoints"`
	GatewayURL        string        `json:"gateway_url"` // Gateway URL for HTTP API access (e.g., "http://localhost:6001")
	ConnectTimeout    time.Duration `json:"connect_timeout"`
	RetryAttempts     int           `json:"retry_attempts"`
	RetryDelay        time.Duration `json:"retry_delay"`
	QuietMode         bool          `json:"quiet_mode"` // Suppress debug/info logs
	APIKey            string        `json:"api_key"`    // API key for gateway auth
	JWT               string        `json:"jwt"`        // Optional JWT bearer token
}

// DefaultClientConfig returns a default client configuration
func DefaultClientConfig(appName string) *ClientConfig {
	// Base defaults
	peers := DefaultBootstrapPeers()
	endpoints := DefaultDatabaseEndpoints()

	return &ClientConfig{
		AppName:           appName,
		DatabaseName:      fmt.Sprintf("%s_db", appName),
		BootstrapPeers:    peers,
		DatabaseEndpoints: endpoints,
		GatewayURL:        "http://localhost:6001",
		ConnectTimeout:    time.Second * 30,
		RetryAttempts:     3,
		RetryDelay:        time.Second * 5,
		QuietMode:         false,
		APIKey:            "",
		JWT:               "",
	}
}