Binary Plugin Author Guide¶

package main

import (
    "context"

    pluginsdk "github.com/holomush/holomush/pkg/plugin"
)

type myPlugin struct{}

func (p *myPlugin) HandleEvent(_ context.Context, event pluginsdk.Event) ([]pluginsdk.EmitEvent, error) {
    // Process events here
    return nil, nil
}

func main() {
    pluginsdk.Serve(&pluginsdk.ServeConfig{
        Handler: &myPlugin{},
    })
}

func (p *myPlugin) HandleCommand(_ context.Context, req pluginsdk.CommandRequest) (*pluginsdk.CommandResponse, error) {
    switch req.Command {
    case "greet":
        return pluginsdk.OK("Hello, " + req.CharacterName + "!"), nil
    default:
        return pluginsdk.Errorf("unknown subcommand: %s", req.Args), nil
    }
}

func (p *myPlugin) Init(ctx context.Context, config *pluginv1.ServiceConfig) error {
    // Parse broker addresses from required_services map
    services, err := pluginsdk.ParseBrokerServices(config.GetRequiredServices())
    if err != nil {
        return fmt.Errorf("parse broker services: %w", err)
    }

    // Dial required services via the GRPCBroker
    for name, brokerID := range services {
        conn, err := p.broker.Dial(brokerID)
        if err != nil {
            return fmt.Errorf("dial %s: %w", name, err)
        }
        switch name {
        case "holomush.world.v1.WorldService":
            p.worldClient = worldv1.NewWorldServiceClient(conn)
        }
    }
    return nil
}

import (
    "embed"
    "io/fs"

    "github.com/holomush/holomush/pkg/plugin/storage"
)

//go:embed migrations/*.up.sql
var migrationsFS embed.FS

func NewStore(ctx context.Context, connString string) (*Store, error) {
    pool, err := storage.Connect(ctx, connString)
    if err != nil {
        return nil, err
    }

    // Extract the sub-filesystem for migrations
    sub, err := fs.Sub(migrationsFS, "migrations")
    if err != nil {
        pool.Close()
        return nil, err
    }

    if err := storage.RunMigrationsFS(ctx, pool, sub); err != nil {
        pool.Close()
        return nil, err
    }

    return &Store{pool: pool}, nil
}

type ServiceProvider interface {
    // RegisterServices registers gRPC services on the go-plugin transport.
    RegisterServices(registrar grpc.ServiceRegistrar)

    // Init is called by the host with DB connection string and service config.
    Init(ctx context.Context, config *pluginv1.ServiceConfig) error
}

type scenePlugin struct {
    store   *SceneStore
    service *SceneServiceImpl
}

// HandleEvent processes events (no-op for scenes currently).
func (p *scenePlugin) HandleEvent(_ context.Context, _ pluginsdk.Event) ([]pluginsdk.EmitEvent, error) {
    return nil, nil
}

// HandleCommand handles scene commands.
func (p *scenePlugin) HandleCommand(_ context.Context, req pluginsdk.CommandRequest) (*pluginsdk.CommandResponse, error) {
    return pluginsdk.OK("Use scene service RPCs."), nil
}

// RegisterServices exposes SceneService on the go-plugin transport.
func (p *scenePlugin) RegisterServices(registrar grpc.ServiceRegistrar) {
    scenev1.RegisterSceneServiceServer(registrar, p.service)
}

// Init wires up storage and services.
func (p *scenePlugin) Init(ctx context.Context, config *pluginv1.ServiceConfig) error {
    connStr := config.GetConnectionString()
    if connStr == "" {
        return oops.Code("SCENE_INIT_FAILED").Errorf("connection_string is required")
    }

    store, err := NewSceneStore(ctx, connStr)
    if err != nil {
        return err
    }

    p.store = store
    p.service.store = store
    return nil
}

func main() {
    plugin := &scenePlugin{
        service: &SceneServiceImpl{},
    }

    pluginsdk.ServeWithServices(
        &pluginsdk.ServeConfig{Handler: plugin},
        plugin,
    )
}

type sceneStorer interface {
    CreateScene(ctx context.Context, row *SceneRow) error
    GetScene(ctx context.Context, id string) (*SceneRow, error)
    // ...
}

// In tests, use a mock implementation
type mockStore struct {
    scenes map[string]*SceneRow
}

func (m *mockStore) CreateScene(_ context.Context, row *SceneRow) error {
    m.scenes[row.ID] = row
    return nil
}

func TestCreateSceneRejectsEmptyTitle(t *testing.T) {
    svc := NewSceneServiceImpl(&mockStore{scenes: make(map[string]*SceneRow)})

    _, err := svc.CreateScene(context.Background(), &scenev1.CreateSceneRequest{
        CharacterId: "01ABC",
        Title:       "",
    })

    require.Error(t, err)
    st, ok := status.FromError(err)
    require.True(t, ok)
    assert.Equal(t, codes.InvalidArgument, st.Code())
}

//go:build integration

func TestSceneStoreCreatesAndRetrievesScene(t *testing.T) {
    ctx := context.Background()
    connStr := setupTestDB(t) // testcontainers helper

    store, err := NewSceneStore(ctx, connStr)
    require.NoError(t, err)
    defer store.Close()

    row := &SceneRow{
        ID:      "01TEST",
        Title:   "Test Scene",
        OwnerID: "01OWNER",
        State:   "active",
        // ...
    }

    require.NoError(t, store.CreateScene(ctx, row))

    got, err := store.GetScene(ctx, "01TEST")
    require.NoError(t, err)
    assert.Equal(t, "Test Scene", got.Title)
}

type myPlugin struct {
    sink pluginsdk.EventSink
}

func (p *myPlugin) SetEventSink(sink pluginsdk.EventSink) {
    p.sink = sink
}

func (p *myPlugin) someMethod(ctx context.Context, stream string) error {
    return p.sink.Emit(ctx, pluginsdk.EmitIntent{
        Stream:  stream,
        Type:    "my_event",
        Payload: `{"key":"value"}`,
    })
}

type scenePlugin struct {
    focusClient pluginsdk.FocusClient
}

func (p *scenePlugin) SetFocusClient(client pluginsdk.FocusClient) {
    p.focusClient = client
}

func (p *scenePlugin) handleJoin(ctx context.Context, req pluginsdk.CommandRequest, args string) (*pluginsdk.CommandResponse, error) {
    sceneID := strings.TrimSpace(args)
    // ... persist the DB row first ...

    err := p.focusClient.JoinFocus(ctx, req.SessionID, pluginsdk.FocusKey{
        Kind:     pluginsdk.FocusKindScene,
        TargetID: sceneID,
    })
    if err != nil {
        // Inspect oops error code; FOCUS_ALREADY_MEMBER is idempotent-success.
        return pluginsdk.Errorf("failed to join scene: %v", err), nil
    }
    return pluginsdk.OK(fmt.Sprintf("Joined scene %s.", sceneID)), nil
}