plugin-tutorial.md

Building New Plugins

This section describes the plugin interface for adding custom services and registering them with PuzzleDB.

Plugin Interface

Each plugin service implements the following Service interface (located in puzzledb/plugins):

type Service interface {
    // ServiceType returns the service type.
    ServiceType() ServiceType
    // ServiceName returns the service name.
    ServiceName() string
    // Start starts the service
    Start() error
    // Stop stops the service
    Stop() error
}

Standard Plugin Interfaces

Standard plugin service types are listed below; refer to reserved interfaces in the plugins directory.

Major Type	Sub Type	Description	Plug-ins	Distributed	Dependency
System	-	System services	gRPC	O
			Actor	O	Coordinator
Query	-	Query handler services	Redis	O	Store (Document)
			MongoDB	O	Store (Document)
			MySQL	O	Store (Document)
			PostgreSQL	O	Store (Document)
Coordinator	-	Coordination services	memdb	X	-
			FoundationDB	O	-
			etcd (Planning)	O	-
			ZooKeeper (Planning)
Coder	Document	Document coder services	CBOR	O	-
	Key	Key coder services	Tuple	O	-
Store	Document	Doument store services	Key-value based store	O	Store (Key-value), Coder (Document), Coder (Key)
	Key-value	Key-value store services	memdb	X	Coder (Document), Coder (Key)
			FoundationDB	O	Coder (Document), Coder (Key)
			TiKV (Planning)	O	-
			JunoDB (Planning)
	Key-Value Cache	Key-value cache store services	Ristretto	O	Store (Key-value)
Tracer	-	Distributed tracing services	OpenTelemetry	O
			OpenTracing	O
Metric	-	Metrics services	Prometheus	O
			Graphite (Planning)	O
Job	-	Job services	memdb	X
			FoundationDB	O
Extend	-	User-defined services	-	-	-

For implementation examples, see existing plugins under plugins/.

Registering a Plugin

To register a custom plugin service, override Server::LoadPlugins():

import (
    "github.com/cybergarage/puzzledb-go/puzzledb"
)

type UserServer struct {
    *puzzledb.Server
    Host string
}

func NewServerWithConfig(config puzzledb.Config) *UserServer {
    server := &UserServer{
        Server: puzzledb.NewServerWithConfig(config),
    }
    return server
}

func (server *UserServer) LoadPlugins() error {
    if err := server.Server.LoadPlugins(); err != nil {
        return err
    }
// Register your plugin service
    var service puzzledb.Service = ....
    server.RegisterService(service)
    return nil
}