From b9a33f7578265b7ce055ac280415db61ea9bd4dc Mon Sep 17 00:00:00 2001 From: Angus Kola Date: Thu, 12 Nov 2026 22:18:14 -0500 Subject: [PATCH] Share Speech Dispatcher transport and restart recovery --- README.md | 35 ++ speechdispatcher/address.go | 105 ++++++ speechdispatcher/address_test.go | 100 +++++ speechdispatcher/autospawn.go | 187 +++++++++ speechdispatcher/autospawn_test.go | 215 +++++++++++ speechdispatcher/bounds_test.go | 20 + speechdispatcher/catalog.go | 62 +++ speechdispatcher/catalog_test.go | 43 +++ speechdispatcher/defaults.go | 57 +++ speechdispatcher/defaults_test.go | 66 ++++ speechdispatcher/fragments.go | 176 +++++++++ speechdispatcher/query.go | 67 ++++ speechdispatcher/read_all.go | 98 +++++ speechdispatcher/read_all_test.go | 123 ++++++ speechdispatcher/recovery.go | 108 ++++++ speechdispatcher/recovery_test.go | 175 +++++++++ speechdispatcher/settings_test.go | 258 +++++++++++++ speechdispatcher/speech.go | 585 +++++++++++++++++++++++++++++ speechdispatcher/speech_test.go | 471 +++++++++++++++++++++++ 19 files changed, 2951 insertions(+) create mode 100644 speechdispatcher/address.go create mode 100644 speechdispatcher/address_test.go create mode 100644 speechdispatcher/autospawn.go create mode 100644 speechdispatcher/autospawn_test.go create mode 100644 speechdispatcher/bounds_test.go create mode 100644 speechdispatcher/catalog.go create mode 100644 speechdispatcher/catalog_test.go create mode 100644 speechdispatcher/defaults.go create mode 100644 speechdispatcher/defaults_test.go create mode 100644 speechdispatcher/fragments.go create mode 100644 speechdispatcher/query.go create mode 100644 speechdispatcher/read_all.go create mode 100644 speechdispatcher/read_all_test.go create mode 100644 speechdispatcher/recovery.go create mode 100644 speechdispatcher/recovery_test.go create mode 100644 speechdispatcher/settings_test.go create mode 100644 speechdispatcher/speech.go create mode 100644 speechdispatcher/speech_test.go diff --git a/README.md b/README.md index cabc7cd..e9d5472 100644 --- a/README.md +++ b/README.md @@ -91,3 +91,38 @@ pinned module versions: after review and live acceptance, release/tag the common module, then update `go.mod` and `go.sum` in **both** readers and test with `GOWORK=off`. A shared source change does not update already installed binaries; they must be rebuilt with the updated dependency. + +## Speech Dispatcher + +`speechdispatcher` owns the shared SSIP client used by both readers: endpoint +resolution, optional daemon startup, speaking and independent cancellation +connections, settings, bounded reply parsing, discovery queries, and read-all +notifications. It has no service-manager dependency. Each reader supplies its +client identity and keeps its own admission, interruption, presentation, and +hardware-synthesizer behavior. Fenrir enables automatic system-socket fallback; +explicit socket/address choices never fall back to another server. + +After a connection fails, the failed utterance is not replayed. The next fresh +speech request rebuilds both channels and restores settings, priority, and the +new cancellation target. Failed reconnection remains retryable on subsequent +requests. Context cancellation bounds connection work; Close and Abort prevent +reconnection. Fenrir additionally retains its worker's bounded background retry +and outage-queue discard policy. An already accepted utterance whose reply was +lost may have spoken before the failure; automatically replaying it is unsafe. + +`Speak` normalizes desktop text; `SpeakText` preserves console-prepared whitespace +and line boundaries. `SpeakCharacter` sends character feedback. Query connections +are separate from speaking connections, and ordinary discovery never autostarts +a daemon. Startup can honor the invoking sudo user's credentials without +changing the reader process's credentials. + +Run `go test -race ./speechdispatcher` for protocol and recovery fixtures. +`CTHULHU_NATIVE_SPEECH_STARTUP=1 go test -race ./speechdispatcher` additionally +starts and restarts private dummy-output daemons; it does not restart the user's +Speech Dispatcher. The environment variable retains the migrated test's name. + +The shared client is available starting with v0.3.0. Both readers pin this +version for standalone builds; the sibling workspace remains useful for local +development. Verify released dependencies with `GOWORK=off`. Existing installed +binaries do not gain fixes until rebuilt. Live audible-speech, keyboard, and +braille acceptance is tracked separately from automated protocol tests. diff --git a/speechdispatcher/address.go b/speechdispatcher/address.go new file mode 100644 index 0000000..6afd5c0 --- /dev/null +++ b/speechdispatcher/address.go @@ -0,0 +1,105 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "fmt" + "net" + "os" + "os/user" + "path/filepath" + "strconv" + "strings" +) + +type Endpoint struct { + Network string + Address string +} + +// DefaultSocketAddress follows Python speechd, retaining Fenrir's sudo-user +// runtime directory selection for console sessions. +func DefaultSocketAddress() string { + if uid := os.Getenv("SUDO_UID"); uid != "" { + if parsed, err := strconv.ParseUint(uid, 10, 32); err == nil { + runtimeDirectory := os.Getenv("XDG_RUNTIME_DIR") + if !owned_directory(runtimeDirectory, uint32(parsed)) { + runtimeDirectory = filepath.Join("/run/user", uid) + } + if !owned_directory(runtimeDirectory, uint32(parsed)) { + if account, err := user.LookupId(uid); err == nil { + runtimeDirectory = filepath.Join(account.HomeDir, ".cache") + } + } + return filepath.Join(runtimeDirectory, "speech-dispatcher/speechd.sock") + } + } + runtimeDirectory := os.Getenv("XDG_RUNTIME_DIR") + if runtimeDirectory == "" { + runtimeDirectory = os.Getenv("XDG_CACHE_HOME") + } + if runtimeDirectory == "" { + cacheDirectory, err := os.UserCacheDir() + if err == nil { + runtimeDirectory = cacheDirectory + } + } + return filepath.Join(runtimeDirectory, "speech-dispatcher", "speechd.sock") +} + +// ResolveAddress gives an internal socket override priority over speechd's +// standard address variables. SPEECHD_SOCKET is the older Unix-only setting. +func ResolveAddress(socket string) (Endpoint, error) { + if socket != "" { + return Endpoint{Network: "unix", Address: socket}, nil + } + if address := os.Getenv("SPEECHD_ADDRESS"); address != "" { + return ParseAddress(address) + } + if socket := os.Getenv("SPEECHD_SOCKET"); socket != "" { + return Endpoint{Network: "unix", Address: socket}, nil + } + return Endpoint{Network: "unix", Address: DefaultSocketAddress()}, nil +} + +func ParseAddress(address string) (Endpoint, error) { + method, value, _ := strings.Cut(address, ":") + switch method { + case "unix_socket": + if value == "" { + value = DefaultSocketAddress() + } + if !filepath.IsAbs(value) { + return Endpoint{}, fmt.Errorf("Speech Dispatcher Unix socket must be an absolute path: %q", value) + } + return Endpoint{Network: "unix", Address: value}, nil + case "inet_socket": + host, port := "127.0.0.1", 6560 + if value != "" { + parts := strings.Split(value, ":") + if len(parts) > 2 { + return Endpoint{}, fmt.Errorf("invalid Speech Dispatcher address %q", address) + } + if parts[0] != "" { + host = parts[0] + } + if len(parts) == 2 { + parsed, err := strconv.Atoi(parts[1]) + if err != nil || parsed < 1 || parsed > 65535 { + return Endpoint{}, fmt.Errorf("invalid Speech Dispatcher port in %q", address) + } + port = parsed + } + } + return Endpoint{Network: "tcp4", Address: net.JoinHostPort(host, strconv.Itoa(port))}, nil + default: + return Endpoint{}, fmt.Errorf("unsupported Speech Dispatcher address %q", address) + } +} + +// Explicit settings select exactly one server; only defaults use fallback. +func AutomaticAddress(socket string) bool { + return socket == "" && os.Getenv("SPEECHD_ADDRESS") == "" && os.Getenv("SPEECHD_SOCKET") == "" +} diff --git a/speechdispatcher/address_test.go b/speechdispatcher/address_test.go new file mode 100644 index 0000000..abc1ea4 --- /dev/null +++ b/speechdispatcher/address_test.go @@ -0,0 +1,100 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "net" + "path/filepath" + "strconv" + "testing" +) + +func TestResolveServerAddressPrecedence(t *testing.T) { + runtimeDirectory := t.TempDir() + cacheDirectory := t.TempDir() + t.Setenv("XDG_RUNTIME_DIR", runtimeDirectory) + t.Setenv("XDG_CACHE_HOME", cacheDirectory) + t.Setenv("SPEECHD_SOCKET", "/tmp/legacy-speech.sock") + t.Setenv("SPEECHD_ADDRESS", "unix_socket:/tmp/address-speech.sock") + + for _, test := range []struct { + name, override, speechAddress, legacySocket, runtimeDir, want string + }{ + {"explicit", "/tmp/explicit-speech.sock", "unix_socket:/tmp/address-speech.sock", "/tmp/legacy-speech.sock", runtimeDirectory, "/tmp/explicit-speech.sock"}, + {"address", "", "unix_socket:/tmp/address-speech.sock", "/tmp/legacy-speech.sock", runtimeDirectory, "/tmp/address-speech.sock"}, + {"legacy", "", "", "/tmp/legacy-speech.sock", runtimeDirectory, "/tmp/legacy-speech.sock"}, + {"runtime", "", "", "", runtimeDirectory, filepath.Join(runtimeDirectory, "speech-dispatcher", "speechd.sock")}, + {"cache", "", "", "", "", filepath.Join(cacheDirectory, "speech-dispatcher", "speechd.sock")}, + } { + t.Run(test.name, func(t *testing.T) { + t.Setenv("SPEECHD_ADDRESS", test.speechAddress) + t.Setenv("SPEECHD_SOCKET", test.legacySocket) + t.Setenv("XDG_RUNTIME_DIR", test.runtimeDir) + got, err := ResolveAddress(test.override) + if err != nil || got.Network != "unix" || got.Address != test.want { + t.Fatalf("address = %+v, error = %v; want %q", got, err, test.want) + } + }) + } +} + +func TestParseServerAddress(t *testing.T) { + for _, test := range []struct { + input, network, address string + }{ + {"unix_socket:/tmp/speech.sock", "unix", "/tmp/speech.sock"}, + {"inet_socket", "tcp4", "127.0.0.1:6560"}, + {"inet_socket:localhost:6561", "tcp4", "localhost:6561"}, + } { + got, err := ParseAddress(test.input) + if err != nil || got.Network != test.network || got.Address != test.address { + t.Fatalf("parse %q = %+v, %v", test.input, got, err) + } + } + for _, address := range []string{"invalid:/tmp/speech.sock", "unix_socket:relative.sock", "inet_socket:localhost:0", "inet_socket:localhost:bad"} { + if _, err := ParseAddress(address); err == nil { + t.Fatalf("accepted invalid address %q", address) + } + } +} + +func TestClientAndDiscoveryHonorSpeechdAddress(t *testing.T) { + path, _ := newSettingsServer(t, func(command string) string { + if command == "LIST OUTPUT_MODULES" { + return "200-test\r\n200 OK\r\n" + } + return "" + }) + t.Setenv("SPEECHD_ADDRESS", "unix_socket:"+path) + t.Setenv("SPEECHD_SOCKET", "/tmp/absent-speech.sock") + client := New("") + defer client.Close(context.Background()) + if err := client.Connect(context.Background()); err != nil { + t.Fatal(err) + } + if _, err := Discover(context.Background(), ""); err != nil { + t.Fatal(err) + } +} + +func TestTCPAddressConnects(t *testing.T) { + listener, err := net.Listen("tcp4", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer listener.Close() + server := newSettingsServerListener(t, listener, nil) + port := listener.Addr().(*net.TCPAddr).Port + t.Setenv("SPEECHD_ADDRESS", "inet_socket:127.0.0.1:"+strconv.Itoa(port)) + client := New("") + defer client.Close(context.Background()) + if err := client.Connect(context.Background()); err != nil { + t.Fatal(err) + } + if !server.saw(1, "HISTORY GET CLIENT_ID") { + t.Fatal("speech client did not use the TCP server") + } +} diff --git a/speechdispatcher/autospawn.go b/speechdispatcher/autospawn.go new file mode 100644 index 0000000..e4f7083 --- /dev/null +++ b/speechdispatcher/autospawn.go @@ -0,0 +1,187 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "fmt" + "net" + "os" + "os/exec" + "os/user" + "path/filepath" + "strconv" + "strings" + "syscall" + "time" +) + +type Dialer func(context.Context, string, string) (net.Conn, error) + +// Automatic connections prefer the user's server, then the system service. +// Preserve the user's endpoint error if neither server is available so that +// autospawn still targets the user's socket, never the system socket. +func WithSystemFallback(dial Dialer) Dialer { + return func(ctx context.Context, network, address string) (net.Conn, error) { + conn, err := dial(ctx, network, address) + if ctx.Err() != nil || network != "unix" || (!errors.Is(err, syscall.ENOENT) && !errors.Is(err, syscall.ECONNREFUSED)) { + return conn, err + } + systemConn, systemErr := dial(ctx, "unix", "/run/speech-dispatcher/speechd.sock") + if systemErr == nil { + return systemConn, nil + } + if ctx.Err() != nil { + return nil, ctx.Err() + } + return nil, err + } +} + +// Like Python speechd, try the existing server first, then ask the daemon to +// spawn according to its own configuration. Never start a local daemon for a +// remote TCP endpoint, and never stop a daemon owned by the session. +func ConnectWithAutospawn(ctx context.Context, endpoint Endpoint, dial Dialer, spawn func(context.Context, Endpoint) error) (net.Conn, error) { + conn, err := dial(ctx, endpoint.Network, endpoint.Address) + if ctx.Err() != nil { + if conn != nil { + _ = conn.Close() + } + return nil, ctx.Err() + } + if err == nil { + return conn, err + } + // Only an absent or stale endpoint warrants starting a daemon. + if !errors.Is(err, syscall.ENOENT) && !errors.Is(err, syscall.ECONNREFUSED) { + return nil, err + } + if spawnErr := spawn(ctx, endpoint); spawnErr != nil { + return nil, fmt.Errorf("%w; autostart Speech Dispatcher: %v", err, spawnErr) + } + retryContext, cancel := context.WithTimeout(ctx, ioTimeout) + defer cancel() + for { + conn, err = dial(retryContext, endpoint.Network, endpoint.Address) + if err == nil { + return conn, nil + } + timer := time.NewTimer(50 * time.Millisecond) + select { + case <-retryContext.Done(): + timer.Stop() + return nil, fmt.Errorf("after Speech Dispatcher autostart: %w", err) + case <-timer.C: + } + } +} + +func SpawnArguments(ctx context.Context, endpoint Endpoint) ([]string, error) { + args := []string{"--spawn"} + if endpoint.Network == "unix" { + return append(args, "--communication-method", "unix_socket", "--socket-path", endpoint.Address), nil + } + host, port, err := net.SplitHostPort(endpoint.Address) + if err != nil { + return nil, err + } + addresses, err := net.DefaultResolver.LookupIPAddr(ctx, host) + if err != nil { + return nil, err + } + if len(addresses) == 0 { + return nil, fmt.Errorf("no addresses for %s", host) + } + for _, address := range addresses { + if !address.IP.IsLoopback() { + return nil, fmt.Errorf("cannot autostart a remote Speech Dispatcher at %s", host) + } + } + return append(args, "--communication-method", "inet_socket", "--port", port), nil +} + +func SpawnServer(ctx context.Context, endpoint Endpoint) error { + spawnContext, cancel := context.WithTimeout(ctx, ioTimeout) + defer cancel() + args, err := SpawnArguments(spawnContext, endpoint) + if err != nil { + return err + } + command := os.Getenv("SPEECHD_CMD") + if command == "" { + command = "speech-dispatcher" + } + process := exec.CommandContext(spawnContext, command, args...) + if uid := os.Getenv("SUDO_UID"); uid != "" && uid != strconv.Itoa(os.Geteuid()) { + // Drop credentials only in the child. Never run a root-owned daemon in + // another user's session or change the reader's device privileges. + if os.Geteuid() != 0 { + return fmt.Errorf("cannot start Speech Dispatcher as the invoking user without root privileges") + } + account, err := user.LookupId(uid) + if err != nil { + return fmt.Errorf("look up invoking user for Speech Dispatcher: %w", err) + } + groups, err := account.GroupIds() + if err != nil { + return fmt.Errorf("look up invoking user's groups: %w", err) + } + if err := ConfigureSudoSpawn(process, account, groups); err != nil { + return err + } + } + process.WaitDelay = 100 * time.Millisecond + output, err := process.CombinedOutput() + if err != nil { + return fmt.Errorf("%s --spawn: %w: %s", command, err, strings.TrimSpace(string(output))) + } + return nil +} + +func ConfigureSudoSpawn(process *exec.Cmd, account *user.User, groups []string) error { + uid, uidErr := strconv.ParseUint(account.Uid, 10, 32) + gid, gidErr := strconv.ParseUint(account.Gid, 10, 32) + if uidErr != nil || gidErr != nil || uid == 0 || !filepath.IsAbs(account.HomeDir) { + return fmt.Errorf("invalid invoking user for Speech Dispatcher") + } + credentials := &syscall.Credential{Uid: uint32(uid), Gid: uint32(gid)} + for _, group := range groups { + id, err := strconv.ParseUint(group, 10, 32) + if err != nil { + return fmt.Errorf("invalid invoking user's group: %w", err) + } + credentials.Groups = append(credentials.Groups, uint32(id)) + } + process.SysProcAttr = &syscall.SysProcAttr{Credential: credentials} + process.Dir = account.HomeDir + // Do not pass root's HOME, XDG paths, D-Bus address, or unrelated secrets + // into a user-owned daemon. Preserve explicit audio choices and locale. + process.Env = []string{"HOME=" + account.HomeDir, "USER=" + account.Username, + "LOGNAME=" + account.Username, "PATH=/usr/local/bin:/usr/bin:/bin"} + for _, entry := range os.Environ() { + key, _, _ := strings.Cut(entry, "=") + if key == "LANG" || strings.HasPrefix(key, "LC_") || key == "PULSE_SERVER" || key == "PULSE_COOKIE" { + process.Env = append(process.Env, entry) + } + } + runtimeDir := filepath.Join("/run/user", account.Uid) + if candidate := os.Getenv("XDG_RUNTIME_DIR"); owned_directory(candidate, uint32(uid)) { + runtimeDir = candidate + } + if owned_directory(runtimeDir, uint32(uid)) { + process.Env = append(process.Env, "XDG_RUNTIME_DIR="+runtimeDir) + } + return nil +} + +func owned_directory(path string, uid uint32) bool { + info, err := os.Stat(path) + if err != nil || !info.IsDir() { + return false + } + stat, ok := info.Sys().(*syscall.Stat_t) + return ok && stat.Uid == uid +} diff --git a/speechdispatcher/autospawn_test.go b/speechdispatcher/autospawn_test.go new file mode 100644 index 0000000..212106f --- /dev/null +++ b/speechdispatcher/autospawn_test.go @@ -0,0 +1,215 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "fmt" + "net" + "os" + "os/exec" + "path/filepath" + "reflect" + "strconv" + "strings" + "syscall" + "testing" + "time" +) + +func TestColdSpeechConnectionAutostartsAndRetriesSelectedEndpoint(t *testing.T) { + for _, connectError := range []error{syscall.ENOENT, syscall.ECONNREFUSED} { + t.Run(connectError.Error(), func(t *testing.T) { + endpoint := Endpoint{Network: "unix", Address: "/tmp/selected-speech.sock"} + client, server := net.Pipe() + defer client.Close() + defer server.Close() + attempts, starts := 0, 0 + got, err := ConnectWithAutospawn(context.Background(), endpoint, func(_ context.Context, network, address string) (net.Conn, error) { + if network != endpoint.Network || address != endpoint.Address { + t.Fatal("connection address changed during autostart") + } + attempts++ + if attempts == 1 { + return nil, connectError + } + return client, nil + }, func(_ context.Context, selected Endpoint) error { + if selected != endpoint { + t.Fatal("spawn address differs from selected server") + } + starts++ + return nil + }) + if err != nil || got != client || attempts != 2 || starts != 1 { + t.Fatalf("connection = %v, %v; attempts %d, starts %d", got, err, attempts, starts) + } + }) + } +} + +func TestAutospawnKeepsRefusalAndCancellationErrors(t *testing.T) { + dial := func(context.Context, string, string) (net.Conn, error) { return nil, syscall.ECONNREFUSED } + starts := 0 + spawn := func(context.Context, Endpoint) error { starts++; return errors.New("autospawn disabled") } + _, err := ConnectWithAutospawn(context.Background(), Endpoint{}, dial, spawn) + if !errors.Is(err, syscall.ECONNREFUSED) || !strings.Contains(err.Error(), "autospawn disabled") || starts != 1 { + t.Fatalf("error = %v, starts = %d", err, starts) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + _, _ = ConnectWithAutospawn(ctx, Endpoint{}, dial, spawn) + if starts != 1 { + t.Fatal("canceled connection started a daemon") + } + ctx, cancel = context.WithCancel(context.Background()) + _, err = ConnectWithAutospawn(ctx, Endpoint{}, func(ctx context.Context, _, _ string) (net.Conn, error) { + if ctx.Err() != nil { + return nil, ctx.Err() + } + return nil, syscall.ECONNREFUSED + }, func(context.Context, Endpoint) error { cancel(); return nil }) + if !errors.Is(err, context.Canceled) { + t.Fatalf("retry error = %v", err) + } +} + +func TestSpeechSpawnArgumentsPreserveEndpointAndRejectRemote(t *testing.T) { + for _, test := range []struct { + endpoint Endpoint + want []string + }{ + {Endpoint{"unix", "/tmp/custom.sock"}, []string{"--spawn", "--communication-method", "unix_socket", "--socket-path", "/tmp/custom.sock"}}, + {Endpoint{"tcp4", "127.0.0.1:6561"}, []string{"--spawn", "--communication-method", "inet_socket", "--port", "6561"}}, + } { + args, err := SpawnArguments(context.Background(), test.endpoint) + if err != nil || !reflect.DeepEqual(args, test.want) { + t.Fatalf("arguments = %v, %v", args, err) + } + } + if _, err := SpawnArguments(context.Background(), Endpoint{"tcp4", "192.0.2.1:6560"}); err == nil { + t.Fatal("remote server allowed local autospawn") + } +} + +func TestSpeechSpawnUsesConfiguredExecutableAndReportsRefusal(t *testing.T) { + path := filepath.Join(t.TempDir(), "fake-speech-dispatcher") + if err := os.WriteFile(path, []byte("#!/bin/sh\necho 'autospawn disabled by daemon' >&2\nexit 1\n"), 0700); err != nil { + t.Fatal(err) + } + t.Setenv("SPEECHD_CMD", path) + err := SpawnServer(context.Background(), Endpoint{"unix", "/tmp/custom.sock"}) + if err == nil || !strings.Contains(err.Error(), "autospawn disabled by daemon") { + t.Fatalf("error = %v", err) + } +} + +func TestExistingSpeechServerDoesNotInvokeSpawn(t *testing.T) { + t.Setenv("SPEECHD_CMD", "/nonexistent/speech-dispatcher") + path, _ := newSettingsServer(t, func(string) string { return "" }) + client := New(path) + if err := client.Connect(context.Background()); err != nil { + t.Fatal(err) + } + defer client.Close(context.Background()) +} + +// Run against a separate dummy-output daemon, never the user's speech server. +func TestNativeSpeechDispatcherColdStart(t *testing.T) { + if os.Getenv("CTHULHU_NATIVE_SPEECH_STARTUP") != "1" { + t.Skip("requires isolated Speech Dispatcher startup") + } + if _, err := exec.LookPath("speech-dispatcher"); err != nil { + t.Fatal(err) + } + for _, staleSocket := range []bool{false, true} { + t.Run(fmt.Sprintf("stale-socket-%v", staleSocket), func(t *testing.T) { + directory, err := os.MkdirTemp("", "speech-start-") + if err != nil { + t.Fatal(err) + } + defer os.RemoveAll(directory) + configPath := filepath.Join(directory, "speechd.conf") + config := "LogLevel 0\nLogDir \"" + directory + "\"\nAddModule \"dummy\" \"sd_dummy\" \"\"\nDefaultModule dummy\nTimeout 1\n" + if err := os.WriteFile(configPath, []byte(config), 0600); err != nil { + t.Fatal(err) + } + pidPath := filepath.Join(directory, "speechd.pid") + wrapper := filepath.Join(directory, "spawn") + script := "#!/bin/sh\nexec speech-dispatcher --config-dir \"$CTHULHU_TEST_SPEECH_CONFIG\" --pid-file \"$CTHULHU_TEST_SPEECH_PID\" \"$@\"\n" + if err := os.WriteFile(wrapper, []byte(script), 0700); err != nil { + t.Fatal(err) + } + t.Setenv("CTHULHU_TEST_SPEECH_CONFIG", directory) + t.Setenv("CTHULHU_TEST_SPEECH_PID", pidPath) + t.Setenv("SPEECHD_CMD", wrapper) + t.Setenv("XDG_RUNTIME_DIR", directory) + t.Setenv("SPEECHD_ADDRESS", "") + t.Setenv("SPEECHD_SOCKET", "") + defer func() { + if data, err := os.ReadFile(pidPath); err == nil { + if pid, err := strconv.Atoi(strings.TrimSpace(string(data))); err == nil { + _ = syscall.Kill(pid, syscall.SIGTERM) + } + } + }() + socket := DefaultSocketAddress() + if staleSocket { + if err := os.MkdirAll(filepath.Dir(socket), 0700); err != nil { + t.Fatal(err) + } + listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: socket, Net: "unix"}) + if err != nil { + t.Fatal(err) + } + listener.SetUnlinkOnClose(false) + listener.Close() + } + client := New("") + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + defer client.Close(context.Background()) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + if client.clientID <= 0 || client.cancelConn == nil { + t.Fatal("cold-start client did not initialize both channels") + } + // Restart this private dummy-output daemon, never the session's server. + data, err := os.ReadFile(pidPath) + if err != nil { + t.Fatal(err) + } + pid, err := strconv.Atoi(strings.TrimSpace(string(data))) + if err != nil || pid <= 0 { + t.Fatalf("invalid private daemon PID: %q", data) + } + if err := syscall.Kill(pid, syscall.SIGTERM); err != nil { + t.Fatal(err) + } + deadline := time.Now().Add(5 * time.Second) + for { + if _, err := os.Stat(pidPath); os.IsNotExist(err) { + break + } + if time.Now().After(deadline) { + t.Fatal("private daemon did not exit") + } + time.Sleep(10 * time.Millisecond) + } + if err := client.Speak(ctx, "outage"); err == nil { + t.Fatal("expected old connection to fail") + } + if err := client.Speak(ctx, "recovered"); err != nil { + t.Fatalf("restart recovery: %v", err) + } + if err := client.Cancel(ctx); err != nil { + t.Fatalf("cancel after restart: %v", err) + } + + }) + } +} diff --git a/speechdispatcher/bounds_test.go b/speechdispatcher/bounds_test.go new file mode 100644 index 0000000..bed9e4f --- /dev/null +++ b/speechdispatcher/bounds_test.go @@ -0,0 +1,20 @@ +package speechdispatcher + +import ( + "bufio" + "strings" + "testing" +) + +func TestBoundedReplies(t *testing.T) { + for _, reply := range []string{ + "249-" + strings.Repeat("a", 5000) + "\n249 OK\n", + strings.Repeat("249-"+strings.Repeat("a", 3000)+"\n", 3000) + "249 OK\n", + "249-one\n250 OK\n", + } { + reader := bufio.NewReaderSize(strings.NewReader(reply), 4096) + if _, err := readReply(reader); err == nil { + t.Fatal("accepted unbounded or malformed reply") + } + } +} diff --git a/speechdispatcher/catalog.go b/speechdispatcher/catalog.go new file mode 100644 index 0000000..1449330 --- /dev/null +++ b/speechdispatcher/catalog.go @@ -0,0 +1,62 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "strings" +) + +type Voice struct{ Name, Language, Variant string } +type Catalog map[string][]Voice + +// Discover uses its own connection, so slow modules never hold up speech. +// The empty module selects the server default. +func Discover(ctx context.Context, socket string) (Catalog, error) { + query, err := OpenQuery(ctx, socket, false, false) + if err != nil { + return nil, err + } + defer query.Close() + modules, err := query.Command(ctx, "LIST OUTPUT_MODULES") + if err != nil { + return nil, err + } + catalog := Catalog{} + for _, module := range append([]string{""}, modules...) { + if strings.ContainsAny(module, "\r\n\x00") { + continue + } + var rows []string + if module != "" { + _, err = query.Command(ctx, "SET SELF OUTPUT_MODULE "+module) + } + if err == nil { + rows, err = query.Command(ctx, "LIST SYNTHESIS_VOICES") + } + if err != nil { + var rejected *Rejection + if errors.As(err, &rejected) { + err = nil + continue + } + return catalog, err + } + catalog[module] = nil + for _, row := range rows { + fields := strings.Split(row, "\t") + if len(fields) < 2 { + continue + } + voice := Voice{Name: fields[0], Language: fields[1]} + if len(fields) > 2 { + voice.Variant = fields[2] + } + catalog[module] = append(catalog[module], voice) + } + } + return catalog, nil +} diff --git a/speechdispatcher/catalog_test.go b/speechdispatcher/catalog_test.go new file mode 100644 index 0000000..d3d38bd --- /dev/null +++ b/speechdispatcher/catalog_test.go @@ -0,0 +1,43 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "testing" +) + +func TestDiscoverVoicesAndOutputModule(t *testing.T) { + path, server := newSettingsServer(t, func(command string) string { + switch command { + case "LIST OUTPUT_MODULES": + return "200-test\r\n200 OK\r\n" + case "LIST SYNTHESIS_VOICES": + return "200-Test Voice\ten-US\tnone\r\n200 OK\r\n" + } + return "" + }) + catalog, err := Discover(context.Background(), path) + if err != nil { + t.Fatal(err) + } + for _, module := range []string{"", "test"} { + voices := catalog[module] + if len(voices) != 1 || voices[0].Name != "Test Voice" || voices[0].Language != "en-US" { + t.Fatalf("catalog=%+v", catalog) + } + } + if !server.saw(1, "SET SELF OUTPUT_MODULE test") { + t.Fatal("did not select module for discovery") + } + client := NewWithSettings(path, Settings{OutputModule: "test", SynthesisVoice: "Test Voice"}) + defer client.Close(context.Background()) + if err := client.Connect(context.Background()); err != nil { + t.Fatal(err) + } + if !server.saw(2, "SET SELF OUTPUT_MODULE test") || !server.saw(2, "SET SELF SYNTHESIS_VOICE Test Voice") { + t.Fatal("echo voice/module not configured") + } +} diff --git a/speechdispatcher/defaults.go b/speechdispatcher/defaults.go new file mode 100644 index 0000000..0856cba --- /dev/null +++ b/speechdispatcher/defaults.go @@ -0,0 +1,57 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "bufio" + "context" + "fmt" + "net" + "strconv" +) + +// ReadDefaults queries a fresh client, leaving the speaking client's settings +// alone. Unsupported or invalid fields stay nil so preferences can use sensible +// display values. The caller bounds the entire optional query with a deadline. +func ReadDefaults(ctx context.Context, socket string) (Settings, error) { + var defaults Settings + endpoint, err := ResolveAddress(socket) + if err != nil { + return defaults, err + } + conn, err := (&net.Dialer{Timeout: connectTimeout}).DialContext(ctx, endpoint.Network, endpoint.Address) + if err != nil { + return defaults, err + } + defer conn.Close() + finish, err := prepareIO(ctx, conn, ioTimeout) + if err != nil { + return defaults, err + } + defer finish() + client := &Client{conn: conn, reader: bufio.NewReader(conn)} + for _, field := range []struct { + name string + target **int + }{ + {"RATE", &defaults.Rate}, {"PITCH", &defaults.Pitch}, {"VOLUME", &defaults.Volume}, + } { + if _, err := fmt.Fprintf(conn, "GET %s\r\n", field.name); err != nil { + return defaults, err + } + response, err := client.readReply() + if err != nil { + return defaults, err + } + if response.code < 200 || response.code >= 300 || len(response.data) != 1 { + continue + } + value, err := strconv.Atoi(response.data[0]) + if err == nil && value >= -100 && value <= 100 { + *field.target = &value + } + } + return defaults, nil +} diff --git a/speechdispatcher/defaults_test.go b/speechdispatcher/defaults_test.go new file mode 100644 index 0000000..f4fcb1b --- /dev/null +++ b/speechdispatcher/defaults_test.go @@ -0,0 +1,66 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "testing" + "time" +) + +func TestReadDefaults(t *testing.T) { + path, server := newSettingsServer(t, func(command string) string { + switch command { + case "GET RATE": + return "200-20\r\n200 OK\r\n" + case "GET PITCH": + return "200--10\r\n200 OK\r\n" + case "GET VOLUME": + return "200-100\r\n200 OK\r\n" + } + return "" + }) + defaults, err := ReadDefaults(t.Context(), path) + if err != nil || defaults.Rate == nil || *defaults.Rate != 20 || + defaults.Pitch == nil || *defaults.Pitch != -10 || defaults.Volume == nil || *defaults.Volume != 100 { + t.Fatalf("defaults=%+v, err=%v", defaults, err) + } + for _, command := range []string{"SET SELF RATE 20", "SET SELF PITCH -10", "SET SELF VOLUME 100", "SPEAK"} { + if server.saw(1, command) { + t.Fatalf("query changed speech: %s", command) + } + } +} + +func TestReadDefaultsRejectsUnsupportedAndInvalidValues(t *testing.T) { + for _, response := range []string{"500 UNSUPPORTED\r\n", "200 OK\r\n", "200-invalid\r\n200 OK\r\n", + "200-101\r\n200 OK\r\n", "200-0\r\n200-1\r\n200 OK\r\n"} { + t.Run(response, func(t *testing.T) { + path, _ := newSettingsServer(t, func(string) string { return response }) + defaults, err := ReadDefaults(t.Context(), path) + if err != nil || defaults.Rate != nil || defaults.Pitch != nil || defaults.Volume != nil { + t.Fatalf("invalid defaults=%+v, err=%v", defaults, err) + } + }) + } +} + +func TestReadDefaultsRetainsPartialValuesAndHonorsDeadline(t *testing.T) { + path, _ := newSettingsServer(t, func(command string) string { + if command == "GET RATE" { + return "200-0\r\n200 OK\r\n" + } + if command == "GET PITCH" { + return "200-unfinished\r\n" + } + return "" + }) + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + defaults, err := ReadDefaults(ctx, path) + if err == nil || defaults.Rate == nil || *defaults.Rate != 0 || defaults.Pitch != nil || defaults.Volume != nil { + t.Fatalf("partial defaults=%+v, err=%v", defaults, err) + } +} diff --git a/speechdispatcher/fragments.go b/speechdispatcher/fragments.go new file mode 100644 index 0000000..8221628 --- /dev/null +++ b/speechdispatcher/fragments.go @@ -0,0 +1,176 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "fmt" + "strings" + "unicode/utf8" +) + +// Fragment is literal text with resolved spelling/language state. A fragment +// boundary is a synthesis boundary; callers coalesce transport fragments first. +// Empty language selects this client's effective configured default language. +type Fragment struct { + Text string + Characters bool + Language string +} + +// SpeakFragmentsAndWait is for an isolated output owner. Unlike ordinary local +// speech, it preserves spaces/tabs and line boundaries (canonicalized to CRLF). +// Plain-text mode prevents network text being interpreted as synthesis markup. +// It validates the entire sequence before any backend operation, then retains +// the speaking lock through every END/CANCEL. Cancel still uses its own channel. +// This method implements no priority, lease, pause or local-focus policy. +func (client *Client) SpeakFragmentsAndWait(ctx context.Context, fragments []Fragment) (result error) { + if len(fragments) == 0 || len(fragments) > 8192 { + return errors.New("invalid speech fragment count") + } + bytes := 0 + for _, part := range fragments { + bytes += len(part.Text) + if bytes > 256*1024 || !valid_fragment(part) { + return errors.New("invalid speech fragment") + } + } + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + if client.conn == nil { + return errors.New("speech client is not connected") + } + defer func() { + if result != nil { + result = errors.Join(ctx.Err(), result) + } + if result != nil && client.conn != nil { + _ = client.conn.Close() + client.conn, client.reader = nil, nil + } + }() + // Query the effective default after initialization: a selected synthesis + // voice may override SET LANGUAGE, and the server default may be unsaved. + defaultLanguage, err := client.fragment_parameter(ctx, "LANGUAGE") + if err != nil || !valid_fragment_language(defaultLanguage, false) { + return errors.Join(ctx.Err(), errors.New("speech default language unavailable")) + } + module, err := client.fragment_parameter(ctx, "OUTPUT_MODULE") + if err != nil || !valid_fragment_language(module, false) { + return errors.Join(ctx.Err(), errors.New("speech default module unavailable")) + } + voiceType, err := client.fragment_parameter(ctx, "VOICE_TYPE") + if err != nil { + return errors.Join(ctx.Err(), errors.New("speech default voice unavailable")) + } + switch voiceType { + case "MALE1", "MALE2", "MALE3", "FEMALE1", "FEMALE2", "FEMALE3", "CHILD_MALE", "CHILD_FEMALE": + case "NO_VOICE": + if client.settings.SynthesisVoice == "" { + return errors.New("speech default voice unavailable") + } + // A named voice has no portable gender/category. Explicit remote + // languages use the SSIP baseline category instead of that voice name. + voiceType = "MALE1" + default: + return errors.New("speech default voice unavailable") + } + setVoice := func(language, named string) error { + // SET LANGUAGE can select a different output module via server config. + // Restore the reader's actual module, then clear any previous named + // voice through VOICE_TYPE. A default-language part regains its name. + for _, fields := range [][]string{ + {"SET", "SELF", "LANGUAGE", language}, + {"SET", "SELF", "OUTPUT_MODULE", module}, + {"SET", "SELF", "VOICE_TYPE", voiceType}, + } { + if err := client.sendCommand(ctx, fields); err != nil { + return err + } + } + if named != "" { + return client.sendCommand(ctx, []string{"SET", "SELF", "SYNTHESIS_VOICE", named}) + } + return nil + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", "SSML_MODE", "off"}); err != nil { + return err + } + for _, part := range fragments { + language, spelling, named := part.Language, "off", "" + if language == "" { + language, named = defaultLanguage, client.settings.SynthesisVoice + } + if err := setVoice(language, named); err != nil { + return err + } + if part.Characters { + spelling = "on" + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", "SPELLING", spelling}); err != nil { + return err + } + text := strings.ReplaceAll(part.Text, "\r\n", "\n") + text = strings.ReplaceAll(text, "\r", "\n") + text = strings.ReplaceAll(text, "\n", "\r\n") + if err := client.speak_and_wait_locked(ctx, func() error { return client.speak_block(ctx, text) }, nil); err != nil { + return err + } + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", "SPELLING", "off"}); err != nil { + return err + } + return setVoice(defaultLanguage, client.settings.SynthesisVoice) +} + +// These names are fixed by the caller; response values never become commands +// until their bounded token/enum validators have accepted them. +func (client *Client) fragment_parameter(ctx context.Context, name string) (string, error) { + finish, err := prepareIO(ctx, client.conn, client.ioTimeout) + if err != nil { + return "", err + } + defer finish() + _, err = fmt.Fprint(client.conn, "GET "+name+"\r\n") + var response reply + if err == nil { + response, err = client.readReply() + } + if err != nil || response.code != 251 || len(response.data) != 1 { + return "", errors.New("speech default unavailable") + } + return response.data[0], nil +} + +func valid_fragment(part Fragment) bool { + if part.Text == "" || !utf8.ValidString(part.Text) || !valid_fragment_language(part.Language, true) { + return false + } + for _, character := range part.Text { + if character < 32 && character != '\r' && character != '\n' && character != '\t' || character == 127 { + return false + } + } + return true +} + +func valid_fragment_language(language string, empty bool) bool { + if language == "" { + return empty + } + if len(language) > 64 { + return false + } + for _, character := range language { + if !(character >= 'a' && character <= 'z' || character >= 'A' && character <= 'Z' || character >= '0' && character <= '9' || character == '-' || character == '_') { + return false + } + } + return true +} diff --git a/speechdispatcher/query.go b/speechdispatcher/query.go new file mode 100644 index 0000000..e76121f --- /dev/null +++ b/speechdispatcher/query.go @@ -0,0 +1,67 @@ +// Copyright (c) 2026 Storm Dragon +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "bufio" + "context" + "fmt" + "net" + "strings" +) + +type Rejection struct{ Code string } + +func (r *Rejection) Error() string { return "Speech Dispatcher rejected a command: " + r.Code } + +// Query owns a separate discovery connection. Its caller serializes commands. +// Discovery never starts a daemon unless preparation explicitly requests it. +type Query struct { + conn net.Conn + reader *bufio.Reader +} + +func OpenQuery(ctx context.Context, socket string, autospawn, systemFallback bool) (*Query, error) { + endpoint, err := ResolveAddress(socket) + if err != nil { + return nil, err + } + dial := Dialer((&net.Dialer{Timeout: connectTimeout}).DialContext) + if systemFallback && AutomaticAddress(socket) { + dial = WithSystemFallback(dial) + } + var conn net.Conn + if autospawn { + conn, err = ConnectWithAutospawn(ctx, endpoint, dial, SpawnServer) + } else { + conn, err = dial(ctx, endpoint.Network, endpoint.Address) + } + if err != nil { + return nil, err + } + return &Query{conn: conn, reader: bufio.NewReader(conn)}, nil +} +func (q *Query) Close() { q.conn.Close() } +func (q *Query) Command(ctx context.Context, command string) ([]string, error) { + if strings.ContainsAny(command, "\r\n\x00") { + return nil, fmt.Errorf("invalid SSIP command") + } + finish, err := prepareIO(ctx, q.conn, ioTimeout) + if err != nil { + return nil, err + } + defer finish() + if _, err = fmt.Fprint(q.conn, command+"\r\n"); err != nil { + return nil, err + } + response, err := readReply(q.reader) + if err != nil { + q.Close() + return nil, err + } + if response.code < 200 || response.code >= 300 { + return nil, &Rejection{Code: fmt.Sprint(response.code)} + } + return response.data, nil +} diff --git a/speechdispatcher/read_all.go b/speechdispatcher/read_all.go new file mode 100644 index 0000000..0c0a86a --- /dev/null +++ b/speechdispatcher/read_all.go @@ -0,0 +1,98 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "time" +) + +// SpeakAndWait uses SSIP BEGIN/END/CANCEL events, not the SPEAK queue +// acknowledgement, to pace continuous reading and report its current position. +// Protocol: https://github.com/brailcom/speechd/blob/master/doc/ssip.texi +func (client *Client) SpeakAndWait(ctx context.Context, text string, began func()) (result error) { + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + return client.speak_and_wait_locked(ctx, func() error { return client.speak(ctx, text) }, began) +} + +// The caller owns the speaking connection until the terminal notification. +func (client *Client) speak_and_wait_locked(ctx context.Context, speak func() error, began func()) (result error) { + if client.conn == nil { + return errors.New("speech client is not connected") + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", "NOTIFICATION", "ALL", "on"}); err != nil { + return err + } + defer func() { + if client.conn != nil { + cleanup, cancel := context.WithTimeout(context.Background(), client.ioTimeout) + defer cancel() + if err := client.sendCommand(cleanup, []string{"SET", "SELF", "NOTIFICATION", "ALL", "off"}); err != nil { + result = errors.Join(result, err) + } + } + }() + // Notifications can precede the SPEAK queue acknowledgement. Handle them + // while reading command replies too, or an early END/CANCEL is lost and + // this owner waits forever while later remote utterances queue behind it. + started, completed := false, false + var completion error + handle := func(event reply) { + if completed { + return + } + switch event.code { + case 701: + if !started && ctx.Err() == nil && began != nil { + began() + } + started = true + case 702: + completed, completion = true, ctx.Err() + case 703: + completed, completion = true, context.Canceled + } + } + client.notification = handle + defer func() { client.notification = nil }() + if err := speak(); err != nil { + return err + } + conn := client.conn + // A spoken line may take much longer than the command I/O timeout. + if err := conn.SetDeadline(time.Time{}); err != nil { + return err + } + done := make(chan struct{}) + stop := context.AfterFunc(ctx, func() { + defer close(done) + cleanup, cancel := context.WithTimeout(context.Background(), client.ioTimeout) + defer cancel() + _ = client.Cancel(cleanup) + // Allow the final cancellation notification to be drained, preserving + // the speaking connection for subsequent focus announcements. + _ = conn.SetReadDeadline(time.Now().Add(client.ioTimeout)) + }) + defer func() { + if !stop() { + <-done + } + }() + for !completed { + event, err := readReply(client.reader) + if err != nil { + _ = conn.Close() + client.conn, client.reader = nil, nil + return errors.Join(ctx.Err(), err) + } + handle(event) + } + return errors.Join(ctx.Err(), completion) +} diff --git a/speechdispatcher/read_all_test.go b/speechdispatcher/read_all_test.go new file mode 100644 index 0000000..44b9b5c --- /dev/null +++ b/speechdispatcher/read_all_test.go @@ -0,0 +1,123 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "bufio" + "context" + "errors" + "fmt" + "net" + "testing" + "time" +) + +func TestContinuousSpeechWaitsForEndAndSurvivesCancellation(t *testing.T) { + for _, interrupted := range []bool{false, true} { + t.Run(fmt.Sprint(interrupted), func(t *testing.T) { + conn, server := net.Pipe() + control, controlServer := net.Pipe() + client := connectedClient(conn) + client.cancelConn, client.cancelReader, client.clientID = control, bufio.NewReader(control), 42 + t.Cleanup(func() { server.Close(); controlServer.Close(); client.Close(context.Background()) }) + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + began := make(chan struct{}, 1) + finished := make(chan error, 1) + go func() { finished <- client.SpeakAndWait(ctx, "First line", func() { began <- struct{}{} }) }() + server.SetDeadline(time.Now().Add(2 * time.Second)) + reader := bufio.NewReader(server) + if err := exchangeSSIP(reader, server, "SET SELF NOTIFICATION ALL on\r\n", "200 OK\r\n"); err != nil { + t.Fatal(err) + } + for _, want := range []string{"SPEAK\r\n", "First line\r\n", ".\r\n"} { + got, err := reader.ReadString('\n') + if err != nil || got != want { + t.Fatalf("speech block %q, %v; want %q", got, err, want) + } + } + fmt.Fprint(server, "230 OK\r\n225-1\r\n225 QUEUED\r\n") + select { + case <-began: + t.Fatal("queue acknowledgement advanced reading position") + case <-finished: + t.Fatal("queue acknowledgement completed speech") + default: + } + fmt.Fprint(server, "701-1\r\n701-42\r\n701 BEGIN\r\n") + select { + case <-began: + case <-time.After(time.Second): + t.Fatal("BEGIN did not update reading position") + } + if interrupted { + cancel() + controlServer.SetDeadline(time.Now().Add(time.Second)) + if err := exchangeSSIP(bufio.NewReader(controlServer), controlServer, "CANCEL 42\r\n", "200 OK\r\n"); err != nil { + t.Fatal(err) + } + fmt.Fprint(server, "703-1\r\n703-42\r\n703 CANCELED\r\n") + } else { + fmt.Fprint(server, "702-1\r\n702-42\r\n702 END\r\n") + } + if err := exchangeSSIP(reader, server, "SET SELF NOTIFICATION ALL off\r\n", "200 OK\r\n"); err != nil { + t.Fatal(err) + } + if err := <-finished; interrupted && !errors.Is(err, context.Canceled) || !interrupted && err != nil { + t.Fatalf("completion = %v", err) + } + // The cancellation notification must not become the next SPEAK reply. + go func() { finished <- client.Speak(context.Background(), "After") }() + for range 3 { + if _, err := reader.ReadString('\n'); err != nil { + t.Fatal(err) + } + } + fmt.Fprint(server, "230 OK\r\n225-2\r\n225 QUEUED\r\n") + if err := <-finished; err != nil { + t.Fatalf("speech after read all: %v", err) + } + }) + } +} + +func TestContinuousSpeechCompletionBeforeQueueReply(t *testing.T) { + for _, terminal := range []int{702, 703} { + t.Run(fmt.Sprint(terminal), func(t *testing.T) { + conn, server := net.Pipe() + client := connectedClient(conn) + t.Cleanup(func() { server.Close(); client.Close(context.Background()) }) + began := make(chan struct{}, 1) + finished := make(chan error, 1) + go func() { + finished <- client.SpeakAndWait(t.Context(), "Short remote response", func() { began <- struct{}{} }) + }() + server.SetDeadline(time.Now().Add(2 * time.Second)) + reader := bufio.NewReader(server) + if err := exchangeSSIP(reader, server, "SET SELF NOTIFICATION ALL on\r\n", "200 OK\r\n"); err != nil { + t.Fatal(err) + } + for range 3 { + if _, err := reader.ReadString('\n'); err != nil { + t.Fatal(err) + } + } + // Speech Dispatcher queues work before returning the SPEAK reply. + // A short or preempted utterance can finish before that reply arrives. + fmt.Fprintf(server, "230 OK\r\n701-1\r\n701-42\r\n701 BEGIN\r\n%d-1\r\n%d-42\r\n%d DONE\r\n225-1\r\n225 QUEUED\r\n", terminal, terminal, terminal) + if err := exchangeSSIP(reader, server, "SET SELF NOTIFICATION ALL off\r\n", "200 OK\r\n"); err != nil { + t.Fatal("completion before queue reply was lost:", err) + } + if err := <-finished; terminal == 703 && !errors.Is(err, context.Canceled) || terminal == 702 && err != nil { + t.Fatalf("completion = %v", err) + } + select { + case <-began: + default: + t.Fatal("early BEGIN was lost") + } + }) + } +} diff --git a/speechdispatcher/recovery.go b/speechdispatcher/recovery.go new file mode 100644 index 0000000..f72d79d --- /dev/null +++ b/speechdispatcher/recovery.go @@ -0,0 +1,108 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "strconv" + "strings" +) + +// Abort interrupts blocked I/O and permanently prevents reconnection. Close +// subsequently releases state. It may run concurrently with any operation. +func (client *Client) Abort() { + client.aborted.Store(true) + if pair := client.sockets.Load(); pair != nil { + pair.data.Close() + pair.control.Close() + } +} + +// ensureConnected runs under the speaking lock. Never replay a failed request: +// its acknowledgement may have been lost after the daemon accepted it. +func (client *Client) ensureConnected(ctx context.Context) error { + if err := ctx.Err(); err != nil { + return err + } + if client.closed || client.aborted.Load() { + return errors.New("speech client is closed") + } + client.cancelMutex.Lock() + defer client.cancelMutex.Unlock() + if client.conn != nil && (client.cancelConn != nil || !client.initialized) { + return nil + } + if !client.initialized { + return errors.New("speech client is not connected") + } + if client.conn != nil { + client.conn.Close() + } + if client.cancelConn != nil { + client.cancelConn.Close() + } + client.conn, client.reader = nil, nil + client.cancelConn, client.cancelReader = nil, nil + client.clientID = 0 + return client.connectLocked(ctx) +} + +// SpeakText preserves line breaks and whitespace for readers that prepare their +// own text. Speak provides the desktop reader's whitespace normalization. +func (client *Client) SpeakText(ctx context.Context, text string) error { + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + text = strings.ToValidUTF8(strings.ReplaceAll(text, "\x00", ""), "�") + text = strings.ReplaceAll(text, "\r\n", "\n") + text = strings.ReplaceAll(text, "\r", "\n") + return client.speak_block(ctx, strings.ReplaceAll(text, "\n", "\r\n")) +} + +// Configure applies numeric settings on the current speaking connection and +// remembers successful changes for recovery. Nil leaves a parameter unchanged. +func (client *Client) Configure(ctx context.Context, rate, pitch, volume *int) error { + for _, value := range []*int{rate, pitch, volume} { + if value != nil && (*value < -100 || *value > 100) { + return errors.New("speech parameters must be between -100 and 100") + } + } + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + for _, item := range []struct { + name string + value *int + target **int + }{ + {"RATE", rate, &client.settings.Rate}, {"PITCH", pitch, &client.settings.Pitch}, {"VOLUME", volume, &client.settings.Volume}, + } { + if item.value == nil { + continue + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", item.name, strconv.Itoa(*item.value)}); err != nil { + return err + } + value := *item.value + *item.target = &value + } + return nil +} + +// Shutdown interrupts pending sends, cancels only this client's queued output, +// and closes both sockets. Readers that already cancel at shutdown can use Close. +func (client *Client) Shutdown(ctx context.Context) error { + client.aborted.Store(true) + if pair := client.sockets.Load(); pair != nil { + pair.data.Close() + } + err := client.Cancel(ctx) + return errors.Join(err, client.Close(ctx)) +} diff --git a/speechdispatcher/recovery_test.go b/speechdispatcher/recovery_test.go new file mode 100644 index 0000000..e8b78f8 --- /dev/null +++ b/speechdispatcher/recovery_test.go @@ -0,0 +1,175 @@ +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "context" + "errors" + "net" + "path/filepath" + "testing" +) + +func TestRecoveryRestoresBothChannelsSettingsAndPriority(t *testing.T) { + for _, name := range []string{"cthulhu", "fenrir"} { + t.Run(name, func(t *testing.T) { + ctx := context.Background() + path, server := newSettingsServer(t, nil) + rate, pitch, volume := 30, 10, 70 + client := NewWithSettings(path, Settings{ClientName: name, Rate: &rate, Pitch: &pitch, Volume: &volume, OutputModule: "fixture", Language: "en", SynthesisVoice: "Test Voice", Punctuation: "none", Capitalization: "none"}) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + defer client.Close(ctx) + if err := client.SetBackgroundPriority(ctx); err != nil { + t.Fatal(err) + } + rate = 45 + if err := client.Configure(ctx, &rate, nil, nil); err != nil { + t.Fatal(err) + } + server.mu.Lock() + for _, conn := range server.connections { + conn.Close() + } + server.mu.Unlock() + if err := client.Speak(ctx, "lost acknowledgement"); err == nil { + t.Fatal("broken connection was accepted") + } + if err := client.Speak(ctx, "fresh speech"); err != nil { + t.Fatal(err) + } + if err := client.Cancel(ctx); err != nil { + t.Fatal(err) + } + for _, command := range []string{"SET SELF CLIENT_NAME " + name + ":" + name + ":main", "SET SELF RATE 45", "SET SELF PITCH 10", "SET SELF VOLUME 70", "SET SELF OUTPUT_MODULE fixture", "SET SELF LANGUAGE en", "SET SELF SYNTHESIS_VOICE Test Voice", "SET SELF PUNCTUATION none", "SET SELF CAP_LET_RECOGN none", "SET SELF PRIORITY TEXT", "SPEAK"} { + if !server.saw(3, command) { + t.Errorf("new connection missing %q", command) + } + } + if !server.saw(4, "CANCEL 3") || server.saw(4, "CANCEL 1") { + t.Fatal("cancellation did not follow the new speaking ID") + } + server.mu.Lock() + speaks := 0 + for _, command := range server.commands[3] { + if command == "SPEAK" { + speaks++ + } + } + server.mu.Unlock() + if speaks != 1 { + t.Fatalf("failed utterance replayed: %d speech commands", speaks) + } + }) + } +} + +func TestControlFailureRecoversOnNextCharacterAndClosePreventsReopen(t *testing.T) { + ctx := context.Background() + path, server := newSettingsServer(t, nil) + client := New(path) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + server.mu.Lock() + server.connections[1].Close() + server.mu.Unlock() + if err := client.Cancel(ctx); err == nil { + t.Fatal("broken control channel accepted") + } + if err := client.SpeakCharacter(ctx, "a"); err != nil { + t.Fatal(err) + } + if !server.saw(3, "CHAR a") { + t.Fatal("character did not recover the pair") + } + if err := client.Close(ctx); err != nil { + t.Fatal(err) + } + if err := client.Speak(ctx, "closed"); err == nil { + t.Fatal("closed client revived") + } + if err := client.Connect(ctx); err == nil { + t.Fatal("closed client reconnected") + } +} + +func TestCanceledRecoveryDoesNotConnect(t *testing.T) { + ctx := context.Background() + path, server := newSettingsServer(t, nil) + client := New(path) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + defer client.Close(ctx) + server.mu.Lock() + for _, conn := range server.connections { + conn.Close() + } + server.mu.Unlock() + if err := client.Speak(ctx, "lost"); err == nil { + t.Fatal("expected disconnect") + } + canceled, cancel := context.WithCancel(ctx) + cancel() + if err := client.Speak(canceled, "stale"); !errors.Is(err, context.Canceled) { + t.Fatal(err) + } + server.mu.Lock() + count := len(server.connections) + server.mu.Unlock() + if count != 2 { + t.Fatal("canceled request opened connections") + } + if err := client.Speak(ctx, "fresh"); err != nil { + t.Fatal(err) + } +} + +func TestRecoveryRemainsAvailableAfterAnUnsuccessfulReconnect(t *testing.T) { + t.Setenv("SPEECHD_CMD", "/nonexistent-shared-speech-fixture") + ctx := context.Background() + path := filepath.Join(t.TempDir(), "speech.sock") + listener, err := net.Listen("unix", path) + if err != nil { + t.Fatal(err) + } + server := newSettingsServerListener(t, listener, nil) + client := New(path) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + defer client.Close(ctx) + listener.Close() + server.mu.Lock() + for _, conn := range server.connections { + conn.Close() + } + server.mu.Unlock() + if err := client.Speak(ctx, "lost"); err == nil { + t.Fatal("expected disconnect") + } + if err := client.Speak(ctx, "unavailable"); err == nil { + t.Fatal("expected unavailable server") + } + replacement, err := net.Listen("unix", path) + if err != nil { + t.Fatal(err) + } + restored := newSettingsServerListener(t, replacement, func(command string) string { + if command == "SPEAK" { + return "230 OK\r\n225 QUEUED\r\n701 BEGIN\r\n702 END\r\n" + } + return "" + }) + began := false + if err := client.SpeakAndWait(ctx, "fresh", func() { began = true }); err != nil { + t.Fatal(err) + } + if !began || !restored.saw(1, "SET SELF NOTIFICATION ALL off") { + t.Fatal("continuous reading did not recover its notifications") + } +} diff --git a/speechdispatcher/settings_test.go b/speechdispatcher/settings_test.go new file mode 100644 index 0000000..4cf97ac --- /dev/null +++ b/speechdispatcher/settings_test.go @@ -0,0 +1,258 @@ +// Cthulhu screen reader. +// Copyright (c) 2026 Storm Dragon +// Authors: Storm Dragon, Angus Kola +// SPDX-License-Identifier: GPL-3.0-or-later + +package speechdispatcher + +import ( + "bufio" + "context" + "fmt" + "net" + "path/filepath" + "strings" + "sync" + "testing" + "time" +) + +// Each connection gets its own client ID and command history, allowing tests +// to detect settings sent to the old connection or cancellation of the wrong ID. +type settingsServer struct { + mu sync.Mutex + commands map[int][]string + connections []net.Conn + hook func(string) string +} + +func newSettingsServer(t *testing.T, hook func(string) string) (string, *settingsServer) { + t.Helper() + path := filepath.Join(t.TempDir(), "speech.sock") + listener, err := net.Listen("unix", path) + if err != nil { + t.Fatal(err) + } + return path, newSettingsServerListener(t, listener, hook) +} + +func newSettingsServerListener(t *testing.T, listener net.Listener, hook func(string) string) *settingsServer { + t.Helper() + server := &settingsServer{commands: make(map[int][]string), hook: hook} + var handlers sync.WaitGroup + accepted := make(chan struct{}) + go func() { + defer close(accepted) + for id := 1; ; id++ { + conn, err := listener.Accept() + if err != nil { + return + } + server.mu.Lock() + server.connections = append(server.connections, conn) + server.mu.Unlock() + handlers.Add(1) + go func(id int) { + defer handlers.Done() + defer conn.Close() + reader := bufio.NewReader(conn) + for { + line, err := reader.ReadString('\n') + if err != nil { + return + } + command := strings.TrimSpace(line) + server.mu.Lock() + server.commands[id] = append(server.commands[id], command) + server.mu.Unlock() + response := "200 OK\r\n" + if command == "HISTORY GET CLIENT_ID" { + response = fmt.Sprintf("245-%d\r\n245 OK\r\n", id) + } + if command == "SPEAK" { + for { + text, err := reader.ReadString('\n') + if err != nil { + return + } + if text == ".\r\n" { + break + } + } + response = "230 OK\r\n200 QUEUED\r\n" + } + if server.hook != nil { + if override := server.hook(command); override != "" { + response = override + } + } + if _, err := conn.Write([]byte(response)); err != nil { + return + } + } + }(id) + } + }() + t.Cleanup(func() { + listener.Close() + <-accepted + server.mu.Lock() + for _, conn := range server.connections { + conn.Close() + } + server.mu.Unlock() + handlers.Wait() + }) + return server +} + +func (server *settingsServer) saw(id int, command string) bool { + server.mu.Lock() + defer server.mu.Unlock() + for _, got := range server.commands[id] { + if got == command { + return true + } + } + return false +} + +func TestUpdateSettingsSwitchesSpeechAndCancellation(t *testing.T) { + path, server := newSettingsServer(t, nil) + rate := 20 + client := NewWithSettings(path, Settings{Rate: &rate}) + rate = 80 // The constructor must own its settings. + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + defer client.Close(ctx) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + if !server.saw(1, "SET SELF RATE 20") { + t.Fatal("constructor retained caller's rate pointer") + } + if err := client.UpdateSettings(ctx, Settings{Punctuation: "all"}); err != nil { + t.Fatal(err) + } + if err := client.Speak(ctx, "new settings"); err != nil { + t.Fatal(err) + } + if err := client.Cancel(ctx); err != nil { + t.Fatal(err) + } + if !server.saw(3, "SET SELF PUNCTUATION all") || !server.saw(3, "SPEAK") { + t.Fatal("new settings and speech did not use replacement connection") + } + if server.saw(3, "SET SELF RATE 20") || client.settings.Rate != nil { + t.Fatal("omitted rate did not return to fresh-connection defaults") + } + if !server.saw(2, "CANCEL 1") || !server.saw(4, "CANCEL 3") { + t.Fatal("cancellation did not follow the speaking connection") + } +} + +func TestUpdateSettingsRejectionPreservesActiveClient(t *testing.T) { + path, server := newSettingsServer(t, func(command string) string { + if command == "SET SELF PITCH 40" { + return "500 REJECTED\r\n" + } + return "" + }) + client := New(path) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + defer client.Close(ctx) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + rate, pitch := 25, 40 + if err := client.UpdateSettings(ctx, Settings{Rate: &rate, Pitch: &pitch}); err == nil { + t.Fatal("rejected update succeeded") + } + if err := client.Speak(ctx, "still speaking"); err != nil { + t.Fatal(err) + } + if server.saw(2, "CANCEL 1") || server.saw(1, "SET SELF RATE 25") || !server.saw(1, "SPEAK") { + t.Fatal("rejected candidate affected active speech") + } + if client.settings.Rate != nil { + t.Fatal("rejected settings were committed") + } + if err := client.Cancel(ctx); err != nil { + t.Fatal(err) + } +} + +func TestUpdateSettingsPreparationDoesNotBlockSpeechOrReviveClosedClient(t *testing.T) { + preparing, release := make(chan struct{}), make(chan struct{}) + var once sync.Once + unblock := func() { once.Do(func() { close(release) }) } + path, _ := newSettingsServer(t, func(command string) string { + if command == "SET SELF RATE 30" { + close(preparing) + <-release + } + return "" + }) + defer unblock() + client := New(path) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + defer client.Close(ctx) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + done := make(chan error, 1) + go func() { rate := 30; done <- client.UpdateSettings(ctx, Settings{Rate: &rate}) }() + select { + case <-preparing: + case <-ctx.Done(): + t.Fatal(ctx.Err()) + } + if err := client.UpdateSettings(ctx, Settings{}); err == nil || !strings.Contains(err.Error(), "already in progress") { + t.Fatalf("overlapping update = %v, want busy error", err) + } + if err := client.Speak(ctx, "while preparing"); err != nil { + t.Fatal(err) + } + if err := client.Cancel(ctx); err != nil { + t.Fatal(err) + } + if err := client.Close(ctx); err != nil { + t.Fatal(err) + } + unblock() + select { + case err := <-done: + if err == nil { + t.Fatal("update revived closed client") + } + case <-ctx.Done(): + t.Fatal(ctx.Err()) + } + if client.conn != nil || client.cancelConn != nil { + t.Fatal("closed client regained connections") + } +} + +func TestUpdateSettingsCanceledContext(t *testing.T) { + path, server := newSettingsServer(t, nil) + client := New(path) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + defer client.Close(ctx) + if err := client.Connect(ctx); err != nil { + t.Fatal(err) + } + canceled, stop := context.WithCancel(ctx) + stop() + if err := client.UpdateSettings(canceled, Settings{}); err == nil { + t.Fatal("canceled update succeeded") + } + if err := client.Speak(ctx, "unchanged"); err != nil { + t.Fatal(err) + } + if server.saw(2, "CANCEL 1") { + t.Fatal("canceled update interrupted speech") + } +} diff --git a/speechdispatcher/speech.go b/speechdispatcher/speech.go new file mode 100644 index 0000000..abc4268 --- /dev/null +++ b/speechdispatcher/speech.go @@ -0,0 +1,585 @@ +// 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 . + +package speechdispatcher + +import ( + "bufio" + "context" + "errors" + "fmt" + "net" + "strconv" + "strings" + "sync" + "sync/atomic" + "time" + "unicode/utf8" +) + +const ( + connectTimeout = 2 * time.Second + ioTimeout = 5 * time.Second +) + +type Client struct { + socketAddress string + settings Settings + initialized bool + closed bool + background bool + aborted atomic.Bool + sockets atomic.Pointer[connectionPair] + conn net.Conn + reader *bufio.Reader + cancelConn net.Conn + cancelReader *bufio.Reader + clientID int + ioTimeout time.Duration + mutex sync.Mutex + cancelMutex sync.Mutex + settingsMutex sync.Mutex + notification func(reply) // Speaking mutex owns the active completion handler. +} + +type connectionPair struct{ data, control net.Conn } + +type Settings struct { + ClientName string + SystemFallback bool + OutputModule string + Rate *int + Pitch *int + Volume *int + Language string + SynthesisVoice string + Punctuation string + Capitalization string +} + +type reply struct { + code int + text string + data []string +} + +func New(socketAddress string) *Client { + return NewWithSettings(socketAddress, Settings{}) +} + +func NewWithSettings(socketAddress string, settings Settings) *Client { + if settings.ClientName == "" { + settings.ClientName = "screenreader" + } + return &Client{socketAddress: socketAddress, settings: cloneSettings(settings), ioTimeout: ioTimeout} +} + +func cloneSettings(settings Settings) Settings { + for _, value := range []**int{&settings.Rate, &settings.Pitch, &settings.Volume} { + if *value != nil { + copy := **value + *value = © + } + } + return settings +} + +// UpdateSettings replaces the complete speech configuration. A fresh pair of +// connections lets omitted settings regain server defaults and prevents a +// rejected SET command from leaving the active client partially configured. +// Preparation leaves Speak and Cancel available. Commit serializes with Speak, +// cancels the old client's queued speech, and switches the cancellation target. +// Only one update may prepare connections at a time; overlapping calls fail. +// Call this from a settings worker, never from the focus or input event path. +func (client *Client) UpdateSettings(ctx context.Context, settings Settings) error { + if !client.settingsMutex.TryLock() { + return errors.New("speech settings update already in progress") + } + defer client.settingsMutex.Unlock() + ctx, cancel := context.WithTimeout(ctx, ioTimeout) + defer cancel() + client.mutex.Lock() + original := client.conn + identity, fallback, background := client.settings.ClientName, client.settings.SystemFallback, client.background + client.mutex.Unlock() + if original == nil { + return errors.New("speech client is not connected") + } + + if settings.ClientName == "" { + settings.ClientName = identity + } + settings.SystemFallback = fallback + candidate := NewWithSettings(client.socketAddress, settings) + candidate.background = background + defer candidate.Close(context.Background()) + if err := candidate.Connect(ctx); err != nil { + return fmt.Errorf("prepare speech settings: %w", err) + } + + client.mutex.Lock() + defer client.mutex.Unlock() + client.cancelMutex.Lock() + defer client.cancelMutex.Unlock() + if client.conn != original || client.aborted.Load() { + return errors.New("speech connection changed while preparing settings") + } + if err := ctx.Err(); err != nil { + return err + } + if err := client.sendCancelCommand(ctx, "CANCEL "+strconv.Itoa(client.clientID)); err != nil { + return fmt.Errorf("cancel speech before applying settings: %w", err) + } + + // Swap ownership so the deferred close releases only the retired pair. + client.conn, candidate.conn = candidate.conn, client.conn + client.reader, candidate.reader = candidate.reader, client.reader + client.cancelConn, candidate.cancelConn = candidate.cancelConn, client.cancelConn + client.cancelReader, candidate.cancelReader = candidate.cancelReader, client.cancelReader + client.clientID, candidate.clientID = candidate.clientID, client.clientID + client.settings = candidate.settings + client.sockets.Store(&connectionPair{client.conn, client.cancelConn}) + candidate.sockets.Store(&connectionPair{candidate.conn, candidate.cancelConn}) + if client.aborted.Load() { + client.Abort() + return errors.New("speech client is closed") + } + return nil +} + +func (client *Client) Connect(ctx context.Context) error { + client.mutex.Lock() + defer client.mutex.Unlock() + client.cancelMutex.Lock() + defer client.cancelMutex.Unlock() + if client.conn != nil || client.cancelConn != nil { + return errors.New("speech client already connected") + } + + if client.closed || client.aborted.Load() { + return errors.New("speech client is closed") + } + if err := client.connectLocked(ctx); err != nil { + return err + } + client.initialized = true + return nil +} + +// connectLocked replaces both channels as one session; both locks are held. +func (client *Client) connectLocked(ctx context.Context) error { + ctx, cancel := context.WithTimeout(ctx, ioTimeout) + defer cancel() + + endpoint, err := ResolveAddress(client.socketAddress) + if err != nil { + return err + } + dialer := net.Dialer{Timeout: connectTimeout} + dial := Dialer(dialer.DialContext) + if client.settings.SystemFallback && AutomaticAddress(client.socketAddress) { + dial = WithSystemFallback(dial) + } + conn, err := ConnectWithAutospawn(ctx, endpoint, dial, SpawnServer) + if err != nil { + return fmt.Errorf("connect to Speech Dispatcher at %s: %w", endpoint.Address, err) + } + if endpoint.Network == "unix" { + endpoint.Address = conn.RemoteAddr().String() + } + cancelConn, err := dialer.DialContext(ctx, endpoint.Network, endpoint.Address) + if err != nil { + _ = conn.Close() + return fmt.Errorf("connect cancellation channel to Speech Dispatcher at %s: %w", endpoint.Address, err) + } + client.sockets.Store(&connectionPair{conn, cancelConn}) + if client.aborted.Load() { + conn.Close() + cancelConn.Close() + return errors.New("speech client is closed") + } + client.conn = conn + client.reader = bufio.NewReader(conn) + client.cancelConn = cancelConn + client.cancelReader = bufio.NewReader(cancelConn) + if err := client.initialize(ctx); err != nil { + _ = conn.Close() + _ = cancelConn.Close() + client.conn, client.reader = nil, nil + client.cancelConn, client.cancelReader = nil, nil + client.clientID = 0 + return err + } + return nil +} + +// initialize runs with both connection locks held. Cancellation always targets +// the speaking connection's ID, never the separate control connection or ALL. +func (client *Client) initialize(ctx context.Context) error { + if err := client.applySettings(ctx); err != nil { + return err + } + finish, err := prepareIO(ctx, client.conn, client.ioTimeout) + if err != nil { + return err + } + defer finish() + if _, err := client.conn.Write([]byte("HISTORY GET CLIENT_ID\r\n")); err != nil { + return fmt.Errorf("request speech client ID: %w", err) + } + response, err := client.readReply() + if err != nil { + return err + } + if response.code != 245 || len(response.data) != 1 { + return fmt.Errorf("invalid Speech Dispatcher client ID reply: %d %s (expected code 245 and one ID)", response.code, response.text) + } + clientID, err := strconv.Atoi(response.data[0]) + if err != nil || clientID <= 0 { + return errors.New("invalid Speech Dispatcher client ID") + } + client.clientID = clientID + return client.sendCancelCommand(ctx, "SET SELF CLIENT_NAME "+client.settings.ClientName+":"+client.settings.ClientName+":cancel") +} + +func (client *Client) applySettings(ctx context.Context) error { + if client.settings.ClientName == "" { + client.settings.ClientName = "screenreader" + } + commands := [][]string{ + {"SET", "SELF", "CLIENT_NAME", client.settings.ClientName + ":" + client.settings.ClientName + ":main"}, + {"SET", "SELF", "PRIORITY", "MESSAGE"}, + } + if client.settings.OutputModule != "" { + commands = append(commands, []string{"SET", "SELF", "OUTPUT_MODULE", client.settings.OutputModule}) + } + if client.settings.Punctuation != "" { + commands = append(commands, []string{"SET", "SELF", "PUNCTUATION", client.settings.Punctuation}) + } + if client.settings.Capitalization != "" { + commands = append(commands, []string{"SET", "SELF", "CAP_LET_RECOGN", client.settings.Capitalization}) + } + for _, setting := range []struct { + name string + value *int + }{ + {name: "RATE", value: client.settings.Rate}, + {name: "PITCH", value: client.settings.Pitch}, + {name: "VOLUME", value: client.settings.Volume}, + } { + if setting.value != nil { + commands = append(commands, []string{"SET", "SELF", setting.name, strconv.Itoa(*setting.value)}) + } + } + if client.settings.Language != "" { + commands = append(commands, []string{"SET", "SELF", "LANGUAGE", client.settings.Language}) + } + if client.settings.SynthesisVoice != "" { + commands = append(commands, []string{"SET", "SELF", "SYNTHESIS_VOICE", client.settings.SynthesisVoice}) + } + + if client.background { + commands = append(commands, []string{"SET", "SELF", "PRIORITY", "TEXT"}) + } + for _, command := range commands { + if err := client.sendCommand(ctx, command); err != nil { + return fmt.Errorf("configure Speech Dispatcher %s: %w", command[2], err) + } + } + return nil +} + +func (client *Client) sendCommand(ctx context.Context, fields []string) (result error) { + defer func() { + if result != nil && client.conn != nil { + client.conn.Close() + client.conn, client.reader = nil, nil + } + }() + for _, field := range fields { + if strings.ContainsAny(field, "\r\n\x00") { + return errors.New("SSIP command contains a control character") + } + } + finish, err := prepareIO(ctx, client.conn, client.ioTimeout) + if err != nil { + return err + } + defer finish() + if _, err := client.conn.Write([]byte(strings.Join(fields, " ") + "\r\n")); err != nil { + return fmt.Errorf("send SSIP command: %w", err) + } + commandReply, err := client.readReply() + if err != nil { + return err + } + if commandReply.code < 200 || commandReply.code >= 300 { + return fmt.Errorf("SSIP command rejected with %d %s", commandReply.code, commandReply.text) + } + return nil +} + +func (client *Client) Speak(ctx context.Context, text string) (result error) { + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + return client.speak(ctx, text) +} + +// SetBackgroundPriority makes this isolated client yield to ordinary MESSAGE +// output. Call before speaking; relay priorities must never select SSIP priority. +// TEXT waits behind MESSAGE and is cancelled when new MESSAGE output arrives. +// Protocol: https://github.com/brailcom/speechd/blob/master/doc/ssip.texi +func (client *Client) SetBackgroundPriority(ctx context.Context) error { + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + if client.conn == nil { + return errors.New("speech client is not connected") + } + if err := client.sendCommand(ctx, []string{"SET", "SELF", "PRIORITY", "TEXT"}); err != nil { + return err + } + client.background = true + return nil +} + +// SpeakCharacter gives the synthesizer a single character as a character, +// preserving repeated adjacent letters during caret and flat review. Spoken +// names such as "space" still use normal speech. +func (client *Client) SpeakCharacter(ctx context.Context, text string) error { + client.mutex.Lock() + defer client.mutex.Unlock() + if err := client.ensureConnected(ctx); err != nil { + return err + } + if utf8.RuneCountInString(text) != 1 || strings.ContainsAny(text, "\r\n\x00") { + return client.speak(ctx, text) + } + if client.conn == nil { + return errors.New("speech client is not connected") + } + return client.sendCommand(ctx, []string{"CHAR", text}) +} + +func (client *Client) speak(ctx context.Context, text string) (result error) { + text, err := normalizeSpeakText(text) + if err != nil { + return err + } + return client.speak_block(ctx, text) +} + +// text is validated by the caller. Dot escaping applies to every data line, +// including lines containing what would otherwise be the SSIP terminator. +func (client *Client) speak_block(ctx context.Context, text string) (result error) { + + if client.conn == nil { + return errors.New("speech client is not connected") + } + finish, err := prepareIO(ctx, client.conn, client.ioTimeout) + if err != nil { + return err + } + defer finish() + + defer func() { + if result != nil { + // A partial exchange cannot safely be reused: a late reply could + // otherwise be mistaken for the next command's acknowledgment. + _ = client.conn.Close() + client.conn, client.reader = nil, nil + } + }() + // SSIP doubles a leading dot so it cannot terminate the speech block. + if strings.HasPrefix(text, ".") { + text = "." + text + } + text = strings.ReplaceAll(text, "\r\n.", "\r\n..") + request := "SPEAK\r\n" + text + "\r\n.\r\n" + if _, err := client.conn.Write([]byte(request)); err != nil { + return fmt.Errorf("send speech block: %w", err) + } + accepted, err := client.readReply() + if err != nil { + return err + } + if accepted.code != 230 { + return fmt.Errorf("speech block rejected with %d %s", accepted.code, accepted.text) + } + + queued, err := client.readReply() + if err != nil { + return err + } + if queued.code < 200 || queued.code >= 300 { + return fmt.Errorf("speech queue rejected with %d %s", queued.code, queued.text) + } + return nil +} + +func (client *Client) Cancel(ctx context.Context) error { + client.cancelMutex.Lock() + defer client.cancelMutex.Unlock() + return client.sendCancelCommand(ctx, "CANCEL "+strconv.Itoa(client.clientID)) +} + +func (client *Client) Close(context.Context) error { + client.Abort() + client.mutex.Lock() + defer client.mutex.Unlock() + client.cancelMutex.Lock() + defer client.cancelMutex.Unlock() + client.closed = true + conn := client.conn + client.conn = nil + client.reader = nil + cancelConn := client.cancelConn + client.cancelConn = nil + client.cancelReader = nil + client.clientID = 0 + + if conn == nil && cancelConn == nil { + return nil + } + + closeError := error(nil) + if conn != nil { + if err := conn.Close(); err != nil && !errors.Is(err, net.ErrClosed) { + closeError = fmt.Errorf("close Speech Dispatcher connection: %w", err) + } + } + if cancelConn != nil { + if err := cancelConn.Close(); err != nil && !errors.Is(err, net.ErrClosed) { + cancelError := fmt.Errorf("close Speech Dispatcher cancellation connection: %w", err) + closeError = errors.Join(closeError, cancelError) + } + } + return closeError +} + +// prepareIO makes cancellation interrupt blocked socket I/O. The cleanup waits +// for a started callback before the next operation can install its deadline. +func prepareIO(ctx context.Context, conn net.Conn, timeout time.Duration) (func(), error) { + if err := ctx.Err(); err != nil { + return nil, err + } + deadline := time.Now().Add(timeout) + if contextDeadline, ok := ctx.Deadline(); ok && contextDeadline.Before(deadline) { + deadline = contextDeadline + } + if err := conn.SetDeadline(deadline); err != nil { + return nil, fmt.Errorf("set Speech Dispatcher deadline: %w", err) + } + done := make(chan struct{}) + stop := context.AfterFunc(ctx, func() { + _ = conn.SetDeadline(time.Now()) + close(done) + }) + return func() { + if !stop() { + <-done + } + }, nil +} + +func (client *Client) readReply() (reply, error) { + for { + response, err := readReply(client.reader) + if err != nil || response.code < 700 || response.code >= 800 { + return response, err + } + if client.notification != nil { + client.notification(response) + } + } +} + +func (client *Client) sendCancelCommand(ctx context.Context, command string) (result error) { + if client.cancelConn == nil { + return errors.New("speech cancellation channel is not connected") + } + finish, err := prepareIO(ctx, client.cancelConn, client.ioTimeout) + if err != nil { + return err + } + defer finish() + defer func() { + if result != nil { + _ = client.cancelConn.Close() + client.cancelConn, client.cancelReader = nil, nil + } + }() + if _, err := client.cancelConn.Write([]byte(command + "\r\n")); err != nil { + return fmt.Errorf("send Speech Dispatcher cancellation command: %w", err) + } + cancelReply, err := readReply(client.cancelReader) + if err != nil { + return err + } + if cancelReply.code < 200 || cancelReply.code >= 300 { + return fmt.Errorf("Speech Dispatcher cancellation rejected with %d %s", cancelReply.code, cancelReply.text) + } + return nil +} + +func readReply(reader *bufio.Reader) (reply, error) { + var final reply + total := 0 + for count := 0; count < 65536; count++ { + part, err := reader.ReadSlice('\n') + line := string(part) + total += len(line) + if total > 8<<20 { + return final, errors.New("SSIP reply exceeds byte limit") + } + if err != nil { + return final, fmt.Errorf("read Speech Dispatcher reply: %w", err) + } + line = strings.TrimRight(line, "\r\n") + if len(line) < 4 || line[3] != '-' && line[3] != ' ' { + return final, fmt.Errorf("invalid Speech Dispatcher reply %q", line) + } + code, err := strconv.Atoi(line[:3]) + if err != nil { + return final, fmt.Errorf("parse Speech Dispatcher reply %q: %w", line, err) + } + if final.code != 0 && final.code != code { + return final, errors.New("inconsistent SSIP reply codes") + } + final.code = code + final.text = strings.TrimSpace(line[4:]) + if line[3] == ' ' { + return final, nil + } + final.data = append(final.data, final.text) + } + return final, errors.New("SSIP reply exceeds line limit") +} + +func normalizeSpeakText(text string) (string, error) { + text = strings.ToValidUTF8(text, "�") + text = strings.Join(strings.Fields(text), " ") + if text == "" { + return "", errors.New("speech text is empty") + } + return text, nil +} diff --git a/speechdispatcher/speech_test.go b/speechdispatcher/speech_test.go new file mode 100644 index 0000000..8151934 --- /dev/null +++ b/speechdispatcher/speech_test.go @@ -0,0 +1,471 @@ +// 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 . + +package speechdispatcher + +import ( + "bufio" + "context" + "errors" + "fmt" + "net" + "strings" + "testing" + "time" +) + +func TestSpeakSendsSSIPAndAcceptsQueuedReply(t *testing.T) { + connection, done := startSSIPServer(t, func(reader *bufio.Reader) error { + request, err := reader.ReadString('\n') + if err != nil { + return err + } + if request != "SPEAK\r\n" { + return errors.New("missing SPEAK command") + } + text, err := reader.ReadString('\n') + if err != nil { + return err + } + if text != "Generic focus text\r\n" { + return fmt.Errorf("speech text = %q", text) + } + if terminator, err := reader.ReadString('\n'); err != nil || terminator != ".\r\n" { + if err != nil { + return err + } + return errors.New("invalid speech block terminator") + } + return nil + }, "230 OK RECEIVING DATA\r\n225-1\r\n225 OK MESSAGE QUEUED\r\n") + client := connectedClient(connection) + if err := client.Speak(context.Background(), "Generic focus text"); err != nil { + t.Fatalf("Speak: %v", err) + } + if err := client.Close(context.Background()); err != nil { + t.Fatalf("Close: %v", err) + } + select { + case err := <-done: + if err != nil { + t.Fatalf("SSIP server error: %v", err) + } + case <-time.After(time.Second): + t.Fatal("timed out waiting for fake SSIP server") + } +} + +func TestSpeakCharacterSendsEachRepeatedCharacter(t *testing.T) { + connection, server := net.Pipe() + client := connectedClient(connection) + defer client.Close(context.Background()) + defer server.Close() + done := make(chan error, 1) + characters := []string{"o", "o", "1", "1", "1", "l", "l"} + go func() { + reader := bufio.NewReader(server) + for _, character := range characters { + if err := exchangeSSIP(reader, server, "CHAR "+character+"\r\n", "225 OK MESSAGE QUEUED\r\n"); err != nil { + done <- err + return + } + } + done <- nil + }() + for _, character := range characters { + if err := client.SpeakCharacter(context.Background(), character); err != nil { + t.Fatal(err) + } + } + if err := <-done; err != nil { + t.Fatal(err) + } +} + +func TestCancelSendsSSIPCommand(t *testing.T) { + connection, done := startSSIPServer(t, func(reader *bufio.Reader) error { + request, err := reader.ReadString('\n') + if err != nil { + return err + } + if request != "CANCEL 42\r\n" { + return errors.New("unexpected cancel command") + } + return nil + }, "200 OK CANCELLED\r\n") + client := New("") + client.cancelConn = connection + client.cancelReader = bufio.NewReader(connection) + client.clientID = 42 + if err := client.Cancel(context.Background()); err != nil { + t.Fatalf("Cancel: %v", err) + } + if err := client.Close(context.Background()); err != nil { + t.Fatalf("Close: %v", err) + } + select { + case err := <-done: + if err != nil { + t.Fatalf("SSIP server error: %v", err) + } + case <-time.After(time.Second): + t.Fatal("timed out waiting for fake SSIP server") + } +} + +func TestApplySettingsSendsConfiguredSSIPCommands(t *testing.T) { + rate, pitch, volume := 52, 0, 40 + connection, serverConnection := net.Pipe() + client := connectedClient(connection) + client.settings = Settings{ + Rate: &rate, + Pitch: &pitch, + Volume: &volume, + Language: "en-US", + SynthesisVoice: "Generic Voice", + Punctuation: "some", + Capitalization: "spell", + } + expected := []string{ + "SET SELF CLIENT_NAME screenreader:screenreader:main\r\n", + "SET SELF PRIORITY MESSAGE\r\n", + "SET SELF PUNCTUATION some\r\n", + "SET SELF CAP_LET_RECOGN spell\r\n", + "SET SELF RATE 52\r\n", + "SET SELF PITCH 0\r\n", + "SET SELF VOLUME 40\r\n", + "SET SELF LANGUAGE en-US\r\n", + "SET SELF SYNTHESIS_VOICE Generic Voice\r\n", + } + done := make(chan error, 1) + go func() { + reader := bufio.NewReader(serverConnection) + for _, want := range expected { + got, err := reader.ReadString('\n') + if err != nil { + done <- err + return + } + if got != want { + done <- fmt.Errorf("SSIP command = %q, want %q", got, want) + return + } + if _, err := serverConnection.Write([]byte("200 OK\r\n")); err != nil { + done <- err + return + } + } + done <- nil + }() + t.Cleanup(func() { serverConnection.Close() }) + + if err := client.applySettings(context.Background()); err != nil { + t.Fatalf("applySettings: %v", err) + } + select { + case err := <-done: + if err != nil { + t.Fatal(err) + } + case <-time.After(time.Second): + t.Fatal("timed out waiting for configured SSIP commands") + } +} + +func TestNormalizeSpeakText(t *testing.T) { + for _, test := range []struct { + name, input, want string + }{ + {"line breaks", " Generic\r\nlabel ", "Generic label"}, + {"punctuation", ".", "."}, + {"tabs and spacing", "\tRoom 123\tA12\n", "Room 123 A12"}, + {"Unicode whitespace", "\u00a0Café\u2003猫\u2028text\u3000", "Café 猫 text"}, + {"combining characters", "\te\u0301 saveFile!\n", "e\u0301 saveFile!"}, + {"invalid UTF-8", "\x80bad\xfftext", "�bad�text"}, + {"empty", "", ""}, + {"whitespace only", " \r\n\t\u00a0\u2003", ""}, + } { + t.Run(test.name, func(t *testing.T) { + text, err := normalizeSpeakText(test.input) + if text != test.want || (err != nil) != (test.want == "") { + t.Fatalf("normalizeSpeakText(%q) = %q, %v; want %q", test.input, text, err, test.want) + } + if err != nil && err.Error() != "speech text is empty" { + t.Fatalf("empty speech error = %v", err) + } + }) + } +} + +func FuzzNormalizeSpeakTextPreservesOutput(f *testing.F) { + for _, text := range []string{"", " Generic\r\nlabel ", ".", "\tRoom 123 A12", "Café\u00a0猫\u2003text", "e\u0301 saveFile!", "\x80bad\xfftext", " \r\n\t\u00a0\u2003", "text\x00with\vcontrols"} { + f.Add(text) + } + f.Fuzz(func(t *testing.T, text string) { + // Retain the previous normalization pipeline as a behavior oracle. + expected := strings.ToValidUTF8(text, "�") + expected = strings.NewReplacer("\r", " ", "\n", " ").Replace(expected) + expected = strings.TrimSpace(strings.Join(strings.Fields(expected), " ")) + actual, err := normalizeSpeakText(text) + if actual != expected || (err != nil) != (expected == "") { + t.Fatalf("normalization changed for %q: got %q, %v; want %q", text, actual, err, expected) + } + }) +} + +func BenchmarkNormalizeSpeakText(b *testing.B) { + for _, sample := range []struct{ name, text string }{ + {"short", "Save button"}, + {"whitespace", " Example\r\nline\twith multiple spaces. "}, + } { + b.Run(sample.name, func(b *testing.B) { + b.ReportAllocs() + for b.Loop() { + if _, err := normalizeSpeakText(sample.text); err != nil { + b.Fatal(err) + } + } + }) + } +} + +func startSSIPServer( + t *testing.T, + readRequest func(*bufio.Reader) error, + reply string, +) (net.Conn, chan error) { + t.Helper() + clientConnection, serverConnection := net.Pipe() + done := make(chan error, 1) + + go func() { + defer serverConnection.Close() + reader := bufio.NewReader(serverConnection) + if err := readRequest(reader); err != nil { + done <- err + return + } + if _, err := serverConnection.Write([]byte(reply)); err != nil { + done <- err + return + } + done <- nil + }() + t.Cleanup(func() { + clientConnection.Close() + serverConnection.Close() + }) + return clientConnection, done +} + +func connectedClient(connection net.Conn) *Client { + client := New("") + client.conn = connection + client.reader = bufio.NewReader(connection) + return client +} + +func TestInitializeTargetsSpeakingConnection(t *testing.T) { + for _, test := range []struct { + name string + reply string + valid bool + }{ + {"valid", "245-42\r\n245 OK CLIENT ID SENT\r\n", true}, + {"missing", "245 OK\r\n", false}, + {"not numeric", "245-SELF\r\n245 OK\r\n", false}, + {"zero", "245-0\r\n245 OK\r\n", false}, + {"negative", "245--1\r\n245 OK\r\n", false}, + {"wrong code", "200-42\r\n200 OK\r\n", false}, + {"rejected", "500 UNKNOWN COMMAND\r\n", false}, + {"multiple", "245-42\r\n245-43\r\n245 OK\r\n", false}, + } { + t.Run(test.name, func(t *testing.T) { + mainConn, mainServer := net.Pipe() + controlConn, controlServer := net.Pipe() + client := connectedClient(mainConn) + client.cancelConn, client.cancelReader = controlConn, bufio.NewReader(controlConn) + t.Cleanup(func() { + mainServer.Close() + controlServer.Close() + client.Close(context.Background()) + }) + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + done := make(chan error, 1) + go func() { + reader := bufio.NewReader(mainServer) + for _, exchange := range []struct{ command, reply string }{ + {"SET SELF CLIENT_NAME screenreader:screenreader:main\r\n", "200 OK\r\n"}, + {"SET SELF PRIORITY MESSAGE\r\n", "200 OK\r\n"}, + {"HISTORY GET CLIENT_ID\r\n", test.reply}, + } { + if err := exchangeSSIP(reader, mainServer, exchange.command, exchange.reply); err != nil { + done <- err + return + } + } + if test.valid { + reader = bufio.NewReader(controlServer) + for _, command := range []string{ + "SET SELF CLIENT_NAME screenreader:screenreader:cancel\r\n", + "CANCEL 42\r\n", + } { + if err := exchangeSSIP(reader, controlServer, command, "200 OK\r\n"); err != nil { + done <- err + return + } + } + } + done <- nil + }() + err := client.initialize(ctx) + if (err == nil) != test.valid { + t.Fatalf("initialize error = %v, valid = %v", err, test.valid) + } + if test.valid { + if err := client.Cancel(ctx); err != nil { + t.Fatal(err) + } + } + select { + case err := <-done: + if err != nil { + t.Fatal(err) + } + case <-ctx.Done(): + t.Fatal(ctx.Err()) + } + }) + } +} + +func exchangeSSIP(reader *bufio.Reader, conn net.Conn, command, reply string) error { + got, err := reader.ReadString('\n') + if err != nil { + return err + } + if got != command { + return fmt.Errorf("command = %q, want %q", got, command) + } + _, err = conn.Write([]byte(reply)) + return err +} + +func TestCancelWhileSpeakWaitsForReply(t *testing.T) { + mainConn, mainServer := net.Pipe() + controlConn, controlDone := startSSIPServer(t, func(reader *bufio.Reader) error { + got, err := reader.ReadString('\n') + if err == nil && got != "CANCEL 42\r\n" { + return fmt.Errorf("cancel = %q", got) + } + return err + }, "200 OK\r\n") + client := connectedClient(mainConn) + client.cancelConn, client.cancelReader, client.clientID = controlConn, bufio.NewReader(controlConn), 42 + t.Cleanup(func() { mainServer.Close(); client.Close(context.Background()) }) + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + speakDone := make(chan error, 1) + go func() { speakDone <- client.Speak(ctx, "Generic text") }() + reader := bufio.NewReader(mainServer) + for range 3 { + if _, err := reader.ReadString('\n'); err != nil { + t.Fatal(err) + } + } + if err := client.Cancel(ctx); err != nil { + t.Fatalf("Cancel during SPEAK: %v", err) + } + if err := <-controlDone; err != nil { + t.Fatal(err) + } + cancel() + select { + case err := <-speakDone: + if err == nil { + t.Fatal("blocked Speak succeeded") + } + case <-time.After(time.Second): + t.Fatal("Speak ignored context cancellation") + } + if err := client.Speak(context.Background(), "Next"); err == nil { + t.Fatal("reused interrupted protocol exchange") + } +} + +func TestCancelContextAndFailedChannel(t *testing.T) { + conn, server := net.Pipe() + client := New("") + client.cancelConn, client.cancelReader, client.clientID = conn, bufio.NewReader(conn), 42 + t.Cleanup(func() { server.Close(); client.Close(context.Background()) }) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if err := client.Cancel(ctx); !errors.Is(err, context.Canceled) { + t.Fatalf("Cancel = %v", err) + } + ctx, cancel = context.WithCancel(context.Background()) + defer cancel() + done := make(chan error, 1) + go func() { done <- client.Cancel(ctx) }() + if _, err := bufio.NewReader(server).ReadString('\n'); err != nil { + t.Fatal(err) + } + cancel() + select { + case err := <-done: + if err == nil { + t.Fatal("Cancel succeeded without reply") + } + case <-time.After(time.Second): + t.Fatal("Cancel ignored context cancellation") + } + if err := client.Cancel(context.Background()); err == nil { + t.Fatal("reused failed control channel") + } +} + +func TestSpeakEscapesLeadingDots(t *testing.T) { + for _, text := range []string{".", "..", ".hidden", "ordinary"} { + t.Run(text, func(t *testing.T) { + wireText := text + if text[0] == '.' { + wireText = "." + text + } + conn, done := startSSIPServer(t, func(reader *bufio.Reader) error { + for _, want := range []string{"SPEAK\r\n", wireText + "\r\n", ".\r\n"} { + got, err := reader.ReadString('\n') + if err != nil { + return err + } + if got != want { + return fmt.Errorf("wire text = %q, want %q", got, want) + } + } + return nil + }, "230 OK RECEIVING DATA\r\n225-1\r\n225 OK MESSAGE QUEUED\r\n") + client := connectedClient(conn) + if err := client.Speak(context.Background(), text); err != nil { + t.Fatal(err) + } + if err := <-done; err != nil { + t.Fatal(err) + } + client.Close(context.Background()) + }) + } +}