Cthulhu is no longer a fork. Now it is a screen reader written in Golang.

internal/remote/service.go

@@ -0,0 +1,322 @@
+// Cthulhu screen reader.
+// Copyright (c) 2026 Storm Dragon
+// Authors: Storm Dragon, Angus Kola
+//
+// This program is free software: you can redistribute it and/or modify it
+// under the terms of the GNU General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option)
+// any later version.
+
+// This program is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+// more details.
+
+// You should have received a copy of the GNU General Public License along with
+// this program. If not, see <https://www.gnu.org/licenses/gpl-3.0.html>.
+
+// Package remote publishes Cthulhu's bounded self-voice D-Bus API.
+package remote
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+
+	"git.stormux.org/storm/cthulhu/internal/sessionbus"
+	"github.com/godbus/dbus/v5"
+)
+
+const (
+	BusName       = "org.stormux.Cthulhu1.Service"
+	InterfaceName = "org.stormux.Cthulhu1.Service"
+	ObjectPath    = dbus.ObjectPath("/org/stormux/Cthulhu1/Service")
+
+	SpeechManagerInterface = "org.stormux.Cthulhu1.SpeechManager"
+	SpeechManagerPath      = dbus.ObjectPath("/org/stormux/Cthulhu1/Service/SpeechManager")
+	OrcaBusName            = "org.gnome.Orca.Service"
+	OrcaInterfaceName      = "org.gnome.Orca.Service"
+	OrcaObjectPath         = dbus.ObjectPath("/org/gnome/Orca/Service")
+
+	maxTextBytes      = 64 * 1024
+	maxRequestIDBytes = 256
+	authorizeTimeout  = 500 * time.Millisecond
+
+	windowsErrorNotSupported     int32 = 50
+	windowsErrorInvalidParameter int32 = 87
+)
+
+// Handler accepts already-authorized presentation requests. Implementations
+// must return quickly and enqueue backend work rather than delivering it inline.
+type Handler interface {
+	PresentMessage(string) bool
+	SpeakText(string, bool) bool
+	BrailleMessage(string) bool
+	CancelSpeech() bool
+	PresentAccessibleEvent(AccessibleEvent) bool
+}
+
+// ControlHandler is optional so existing self-voice users keep their contract.
+// Implementations enqueue commands with their existing owners and return promptly.
+type ControlHandler interface {
+	ShowPreferences() bool
+	Quit() bool
+	RuntimeStateSnapshot() string
+}
+
+// AccessibleEvent is the normalized, bounded Wine helper payload. It contains
+// no native object references and is safe to hand to the presentation owner.
+type AccessibleEvent struct {
+	SourceID, EventType, Name, Role, Value, States, Description, WindowTitle string
+	Position, Count                                                          int32
+}
+
+type connection interface {
+	Export(any, dbus.ObjectPath, string) error
+	RequestName(string, dbus.RequestNameFlags) (dbus.RequestNameReply, error)
+	ReleaseName(string) (dbus.ReleaseNameReply, error)
+	UnixUser(context.Context, string) (uint32, error)
+	Close() error
+}
+
+type dbusConnection struct {
+	*dbus.Conn
+}
+
+func (connection dbusConnection) UnixUser(ctx context.Context, sender string) (uint32, error) {
+	var uid uint32
+	call := connection.BusObject().CallWithContext(
+		ctx,
+		"org.freedesktop.DBus.GetConnectionUnixUser",
+		0,
+		sender,
+	)
+	if err := call.Store(&uid); err != nil {
+		return 0, err
+	}
+	return uid, nil
+}
+
+type connector func() (connection, error)
+
+// Service owns the session-bus connection, exported object, and well-known
+// name. The lifecycle owner must call Stop before its Handler is stopped.
+type Service struct {
+	logger  *slog.Logger
+	handler Handler
+	connect connector
+	orca    bool
+
+	mutex      sync.Mutex
+	connection connection
+	endpoint   *endpoint
+	ownedName  bool
+	bindings   []serviceBinding
+}
+
+type serviceBinding struct {
+	path  dbus.ObjectPath
+	iface string
+	value any
+}
+
+// NewOrca creates an independent compatibility service. A running Orca owns
+// its name exclusively; a name conflict does not affect the native service.
+func NewOrca(logger *slog.Logger, handler Handler) *Service {
+	service := New(logger, handler)
+	service.orca = true
+	return service
+}
+
+func New(logger *slog.Logger, handler Handler) *Service {
+	return newService(logger, handler, func() (connection, error) {
+		connection, err := sessionbus.Connect(logger, "self-voice")
+		if err != nil {
+			return nil, err
+		}
+		return dbusConnection{Conn: connection}, nil
+	})
+}
+
+func newService(logger *slog.Logger, handler Handler, connect connector) *Service {
+	if logger == nil {
+		logger = slog.New(slog.DiscardHandler)
+	}
+	return &Service{logger: logger, handler: handler, connect: connect}
+}
+
+func (service *Service) Start(ctx context.Context) error {
+	if ctx == nil {
+		return errors.New("remote service start requires a non-nil context")
+	}
+	if err := ctx.Err(); err != nil {
+		return fmt.Errorf("start remote service: %w", err)
+	}
+	if service.handler == nil {
+		return errors.New("start remote service without a handler")
+	}
+
+	service.mutex.Lock()
+	defer service.mutex.Unlock()
+	if service.connection != nil {
+		return errors.New("remote service already started")
+	}
+	connection, err := service.connect()
+	if err != nil {
+		return fmt.Errorf("connect to session bus: %w", err)
+	}
+	endpoint := newEndpoint(service.logger, service.handler, func(sender dbus.Sender) bool {
+		authorizeContext, cancel := context.WithTimeout(context.Background(), authorizeTimeout)
+		defer cancel()
+		uid, err := connection.UnixUser(authorizeContext, string(sender))
+		return err == nil && uid == uint32(os.Getuid())
+	})
+
+	name := BusName
+	if service.orca {
+		name = OrcaBusName
+	}
+	registrations := service_bindings(endpoint, service.orca, service.handler)
+	started := false
+	exported := 0
+	defer func() {
+		if !started {
+			for index := exported - 1; index >= 0; index-- {
+				binding := registrations[index]
+				connection.Export(nil, binding.path, binding.iface)
+			}
+			connection.Close()
+		}
+	}()
+	for _, binding := range registrations {
+		if err := connection.Export(binding.value, binding.path, binding.iface); err != nil {
+			return fmt.Errorf("export %s: %w", binding.iface, err)
+		}
+		exported++
+	}
+	reply, err := connection.RequestName(name, dbus.NameFlagDoNotQueue)
+	if err != nil {
+		return fmt.Errorf("request D-Bus name %s: %w", name, err)
+	}
+	if reply != dbus.RequestNameReplyPrimaryOwner && reply != dbus.RequestNameReplyAlreadyOwner {
+		return fmt.Errorf("D-Bus name %s is already owned", name)
+	}
+
+	endpoint.startAccepting()
+	service.connection = connection
+	service.endpoint = endpoint
+	service.ownedName = true
+	service.bindings = registrations
+	if !service.orca {
+		if handler, ok := service.handler.(WineReviewConnectionHandler); ok {
+			if native, ok := connection.(dbusConnection); ok {
+				handler.BindWineReviewConnection(native.Conn)
+			}
+		}
+	}
+	started = true
+	service.logger.Debug("remote D-Bus service ready", "name", name)
+	return nil
+}
+
+func (service *Service) Stop(ctx context.Context) error {
+	if ctx == nil {
+		return errors.New("remote service stop requires a non-nil context")
+	}
+	service.mutex.Lock()
+	connection := service.connection
+	endpoint := service.endpoint
+	ownedName := service.ownedName
+	bindings := service.bindings
+	service.connection = nil
+	service.endpoint = nil
+	service.ownedName = false
+	service.bindings = nil
+	service.mutex.Unlock()
+	if connection == nil {
+		return nil
+	}
+
+	idle := endpoint.stopAccepting()
+	if !service.orca {
+		if handler, ok := service.handler.(WineReviewConnectionHandler); ok {
+			handler.BindWineReviewConnection(nil)
+		}
+	}
+	var stopErrors []error
+	name := BusName
+	if service.orca {
+		name = OrcaBusName
+	}
+	for i := len(bindings) - 1; i >= 0; i-- {
+		binding := bindings[i]
+		if err := connection.Export(nil, binding.path, binding.iface); err != nil {
+			stopErrors = append(stopErrors, fmt.Errorf("unexport %s: %w", binding.iface, err))
+		}
+	}
+	if ownedName {
+		if reply, err := connection.ReleaseName(name); err != nil {
+			stopErrors = append(stopErrors, fmt.Errorf("release D-Bus name %s: %w", name, err))
+		} else if reply != dbus.ReleaseNameReplyReleased && reply != dbus.ReleaseNameReplyNonExistent {
+			stopErrors = append(stopErrors, fmt.Errorf("release D-Bus name %s: reply %d", name, reply))
+		}
+	}
+	select {
+	case <-idle:
+	case <-ctx.Done():
+		stopErrors = append(stopErrors, fmt.Errorf("wait for self-voice calls: %w", ctx.Err()))
+	}
+	if err := connection.Close(); err != nil {
+		stopErrors = append(stopErrors, fmt.Errorf("close session bus: %w", err))
+	}
+	return errors.Join(stopErrors...)
+}
+
+// Keep the Orca export limited to the methods it actually advertises.
+type orcaServiceEndpoint struct {
+	endpoint *endpoint
+	modules  []string
+}
+
+func (service *orcaServiceEndpoint) ShowPreferences(sender dbus.Sender) (bool, *dbus.Error) {
+	return service.endpoint.ShowPreferences(sender)
+}
+
+func (service *orcaServiceEndpoint) PresentMessage(sender dbus.Sender, message string) (bool, *dbus.Error) {
+	return service.endpoint.PresentMessage(sender, message)
+}
+
+func (service *orcaServiceEndpoint) GetVersion(sender dbus.Sender) (string, *dbus.Error) {
+	return service.endpoint.GetVersion(sender)
+}
+
+func (service *orcaServiceEndpoint) Quit(sender dbus.Sender) (bool, *dbus.Error) {
+	return service.endpoint.Quit(sender)
+}
+
+func (service *orcaServiceEndpoint) ListModules(sender dbus.Sender) ([]string, *dbus.Error) {
+	if err := service.endpoint.begin(sender, "ListModules"); err != nil {
+		return nil, err
+	}
+	defer service.endpoint.end()
+	return append([]string(nil), service.modules...), nil
+}
+
+func (service *orcaServiceEndpoint) ListCommands(sender dbus.Sender) ([]namedDescription, *dbus.Error) {
+	if err := service.endpoint.begin(sender, "ListCommands"); err != nil {
+		return nil, err
+	}
+	defer service.endpoint.end()
+	return []namedDescription{
+		{"GetVersion", "Returns Cthulhu's version."},
+		{"ListCommands", "Lists available service commands."},
+		{"ListModules", "Lists available modules."},
+		{"PresentMessage", "Presents a message."},
+		{"Quit", "Quits Cthulhu."},
+		{"ShowPreferences", "Shows preferences."},
+	}, nil
+}