[v3] Late service registration and error handling overhaul (#4066)

* Add service registration method

* Fix error handling and formatting in messageprocessor

* Add configurable error handling

* Improve error strings

* Fix service shutdown on macOS

* Add post shutdown hook

* Better fatal errors

* Add startup/shutdown sequence tests

* Improve debug messages

* Update JS runtime

* Update docs

* Update changelog

* Fix log message in clipboard message processor

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Remove panic in RegisterService

* Fix linux tests (hopefully)

* Fix error formatting everywhere

* Fix typo in windows webview

* Tidy example mods

* Set application name in tests

* Fix ubuntu test workflow

* Cleanup template test pipeline

* Fix dev build detection on Go 1.24

* Update template go.mod/sum to Go 1.24

* Remove redundant caching in template tests

* Final format string cleanup

* Fix wails3 tool references

* Fix legacy log calls

* Remove formatJS and simplify format strings

* Fix indirect import

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: fbbdev

.github/workflows/build-and-test-v3.yml

@@ -30,7 +30,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [windows-latest, macos-latest, ubuntu-latest]
-        go-version: [1.23]
+        go-version: [1.24]
 
     steps:
       - name: Checkout code
@@ -40,7 +40,7 @@ jobs:
         uses: awalsh128/cache-apt-pkgs-action@latest
         if: matrix.os == 'ubuntu-latest'
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config xvfb x11-xserver-utils at-spi2-core xdg-desktop-portal-gtk
           version: 1.0
 
       - name: Setup Go
@@ -66,11 +66,25 @@ jobs:
         working-directory: ./v3
         run: go test -v ./...
 
-      - name: Run tests (!mac)
-        if: matrix.os != 'macos-latest'
+      - name: Run tests (windows)
+        if: matrix.os == 'windows-latest'
         working-directory: ./v3
         run: go test -v ./...
 
+      - name: Run tests (ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: ./v3
+        run: >
+          xvfb-run --auto-servernum
+          sh -c '
+          dbus-update-activation-environment --systemd --all &&
+          go test -v ./...
+          '
+
+      - name: Typecheck binding generator output
+        working-directory: ./v3
+        run: task generator:test:check
+
   test_js:
     name: Run JS Tests
     needs: check_approval
@@ -105,59 +119,52 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
         template:
-          [
-            svelte,
-            svelte-ts,
-            vue,
-            vue-ts,
-            react,
-            react-ts,
-            preact,
-            preact-ts,
-            lit,
-            lit-ts,
-            vanilla,
-            vanilla-ts,
-          ]
-        go-version: [1.23]
+          - svelte
+          - svelte-ts
+          - vue
+          - vue-ts
+          - react
+          - react-ts
+          - preact
+          - preact-ts
+          - lit
+          - lit-ts
+          - vanilla
+          - vanilla-ts
+        go-version: [1.24]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install linux dependencies
+        uses: awalsh128/cache-apt-pkgs-action@latest
+        if: matrix.os == 'ubuntu-latest'
+        with:
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
+          version: 1.0
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.go-version }}
           cache-dependency-path: "v3/go.sum"
 
-      - name: Setup Golang caches
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache/go-build
-            ~/go/pkg/mod
-          key: ${{ runner.os }}-golang-${{ hashFiles('**/go.sum') }}
-          restore-keys: |
-            ${{ runner.os }}-golang-
-
-      - name: Install linux dependencies
-        uses: awalsh128/cache-apt-pkgs-action@latest
-        if: matrix.os == 'ubuntu-latest'
+      - name: Install Task
+        uses: arduino/setup-task@v2
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
-          version: 1.0
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build Wails3 CLI
+        working-directory: ./v3
         run: |
-          cd ./v3/cmd/wails3
-          go install
-          wails3 -help
+          task install
+          wails3 doctor
 
       - name: Generate template '${{ matrix.template }}'
         run: |
-          go install github.com/go-task/task/v3/cmd/task@latest 
           mkdir -p ./test-${{ matrix.template }}
           cd ./test-${{ matrix.template }}
           wails3 init -n ${{ matrix.template }} -t ${{ matrix.template }}
           cd ${{ matrix.template }}
-          wails3 build
+          wails3 build

docs/src/content/docs/changelog.mdx

@@ -54,6 +54,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `//wails:internal` directive on services and models to allow for types that are exported in Go but not in JS/TS by [@fbbdev](https://github.com/fbbdev) in [#4045](https://github.com/wailsapp/wails/pull/4045)
 - Add binding generator support for constants of alias type to allow for weakly typed enums by [@fbbdev](https://github.com/fbbdev) in [#4045](https://github.com/wailsapp/wails/pull/4045)
 - Add support for macOS 15 "Sequoia" to `OSInfo.Branding` for improved OS version detection in [#4065](https://github.com/wailsapp/wails/pull/4065)
+- Add `PostShutdown` hook for running custom code after the shutdown process completes by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Add `FatalError` struct to support detection of fatal errors in custom error handlers by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Standardise and document service startup and shutdown order by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Add test harness for application startup/shutdown sequence and service startup/shutdown tests by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Add `RegisterService` method for registering services after the application has been created by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Add `MarshalError` field in application and service options for custom error handling in binding calls by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
 
 ### Fixed
 
@@ -81,6 +87,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Suppressed warnings for services that define lifecycle or http methods but no other bound methods by [@fbbdev](https://github.com/fbbdev) in [#4045](https://github.com/wailsapp/wails/pull/4045)
 - Fixed non-React templates failing to display Hello World footer when using light system colour scheme by [@marcus-crane](https://github.com/marcus-crane) in [#4056](https://github.com/wailsapp/wails/pull/4056)
 - Fixed hidden menu items on macOS by [@leaanthony](https://github.com/leaanthony)
+- Fixed handling and formatting of errors in message processors by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+-  Fixed skipped service shutdown when quitting application by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
 
 ### Changed
 
@@ -98,6 +106,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update copyright date to 2025 by [@IanVS](https://github.com/IanVS) in [#4037](https://github.com/wailsapp/wails/pull/4037)
 - Add docs for event.Sender by [@IanVS](https://github.com/IanVS) in [#4075](https://github.com/wailsapp/wails/pull/4075)
 - Go 1.24 support by [@leaanthony](https://github.com/leaanthony)
+- `ServiceStartup` hooks are now invoked when `App.Run` is called, not in `application.New` by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- `ServiceStartup` errors are now returned from `App.Run` instead of terminating the process by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
+- Binding and dialog calls from JS now reject with error objects instead of strings by [@fbbdev](https://github.com/fbbdev) in [#4066](https://github.com/wailsapp/wails/pull/4066)
 
 ## v3.0.0-alpha.9 - 2025-01-13
 

docs/src/content/docs/learn/bindings.mdx

@@ -448,3 +448,149 @@ const promise = MyService.LongRunningTask("input");
 // This will cause the context to be cancelled in the Go method
 promise.cancel();
 ```
+
+### Handling errors
+
+As you may have noticed above, bound methods can return errors, which are handled specially.
+When a result field has type `error`, it is omitted by default from the values returned to JS.
+When such a field is _non-nil_, the promise rejects with a `RuntimeError` exception
+that wraps the Go error message:
+
+```go
+func (*MyService) FailingMethod(name string) error {
+    return fmt.Errorf("Welcome to an imperfect world, %s", name)
+}
+```
+
+```js
+import { MyService } from './bindings/changeme';
+
+try {
+    await MyService.FailingMethod("CLU")
+} catch (err) {
+    if (err.name === 'RuntimeError') {
+        console.log(err.message); // Prints 'Welcome to an imperfect world, CLU'
+    }
+}
+```
+
+The exception will be an instance of the `Call.RuntimeError` class from the wails runtime,
+hence you can also test its type like this:
+
+```js
+import { Call } from '@wailsio/runtime';
+
+try {
+    // ...
+} catch (err) {
+    if (err instanceof Call.RuntimeError) {
+        // ...
+    }
+}
+```
+
+If the Go error value supports JSON marshaling, the exception's `cause` property
+will hold the marshaled version of the error:
+
+```go
+type ImperfectWorldError struct {
+    Name string `json:"name"`
+}
+
+func (err *ImperfectWorldError) Error() {
+    return fmt.Sprintf("Welcome to an imperfect world, %s", err.Name)
+}
+
+func (*MyService) FailingMethod(name string) error {
+    return &ImperfectWorldError{
+        Name: name,
+    }
+}
+```
+
+```js
+import { MyService } from './bindings/changeme';
+
+try {
+    await MyService.FailingMethod("CLU")
+} catch (err) {
+    if (err.name === 'RuntimeError') {
+        console.log(err.cause.name); // Prints 'CLU'
+    }
+}
+```
+
+Generally, many Go error values will only have limited or no support for marshaling to JSON.
+If you so wish, you can customise the value provided as cause
+by specifying either a global or per-service error marshaling function:
+
+```go
+app := application.New(application.Options{
+    MarshalError: func(err error) []byte {
+        // ...
+    },
+    Services: []application.Service{
+        application.NewServiceWithOptions(&MyService{}, application.ServiceOptions{
+            MarshalError: func(err error) []byte {
+                // ...
+            },
+        }),
+    },
+})
+```
+
+Per-service functions override the global function,
+which in turn overrides the default behaviour of using `json.Marshal`.
+If a marshaling function returns `nil`, it falls back to the outer function:
+per-service functions fall back to the global function,
+which in turn falls back to the default behaviour.
+
+:::tip
+If you wish to omit the `cause` property on the resulting exception,
+let the marshaling function return a falsy JSON value like `[]byte("null")`.
+:::
+
+Here's an example marshaling function that unwraps path errors and reports the file path:
+
+```go
+app := application.New(application.Options{
+    MarshalError: func(err error) []byte {
+        var perr *fs.PathError
+        if !errors.As(err, &perr) {
+            // Not a path error, fall back to default handling.
+            return nil
+        }
+
+        // Marshal path string
+        path, err := json.Marshal(&perr.Path)
+        if err != nil {
+            // String marshaling failed, fall back to default handling.
+            return nil
+        }
+
+        return []byte(fmt.Sprintf(`{"path":%s}`, path))
+    },
+})
+```
+
+:::note
+Error marshaling functions are not allowed to fail.
+If they are not able to process a given error and return valid JSON,
+they should return `nil` and fall back to a more generic handler.
+If no strategy succeeds, the exception will not have a `cause` property.
+:::
+
+Binding call promises may also reject with a `TypeError`
+when the method has been passed the wrong number of arguments,
+when the conversion of arguments from JSON to their Go types fails,
+or when the conversion of results to JSON fails.
+These problems will usually be caught early by the type system.
+If your code typechecks but you still get type errors,
+it might be that some of your Go types are not supported by the `encoding/json` package:
+look for warnings from the binding generator to catch these.
+
+:::caution
+If you see a `ReferenceError` complaining about unknown methods,
+it could mean that your JS bindings have gotten out of sync with Go code
+and must be regenerated.
+:::

docs/src/content/docs/learn/services.mdx

@@ -40,9 +40,9 @@ greeting.
 ## Registering a Service
 
 To register a service with the application, you need to provide an instance of
-the service to the `Services` field of the `application.Options` struct (All
-services need to be wrapped by an `application.NewService` call. Here's an
-example:
+the service to the `Services` field of the `application.Options` struct.
+All services need to be wrapped by an `application.NewService` call.
+Here's an example:
 
 ```go
 app := application.New(application.Options{
@@ -70,6 +70,25 @@ ServiceOptions has the following fields:
 	- Name - Specify a custom name for the Service
     - Route - A route to bind the Service to the frontend (more on this below)
 
+After the application has been created but not yet started,
+you can register more services using the `RegisterService` method.
+This is useful when you need to feed a service some value
+that is only available after the application has been created.
+For example, let's wire application's logger into your own service:
+
+```go
+app := application.New(application.Options{})
+
+app.RegisterService(application.NewService(NewMyService(app.Logger)))
+
+// ...
+
+err := app.Run()
+```
+
+Services may only be registered before running the application:
+`RegisterService` will panic if called after the `Run` method.
+
 ## Optional Methods
 
 Services can implement optional methods to hook into the application lifecycle.
@@ -98,8 +117,12 @@ func (s *Service) ServiceStartup(ctx context.Context, options application.Servic
 
 This method is called when the application is starting up. You can use it to
 initialize resources, set up connections, or perform any necessary setup tasks.
-The context is the application context, and the `options` parameter provides
-additional information about the service.
+The context is the application context that will be canceled upon shutdown,
+and the `options` parameter provides additional information about the service.
+
+Services are initialised in the exact order of registration:
+first those listed in the `Services` field of the `application.Options` struct,
+then those added through the `RegisterService` method.
 
 ### ServiceShutdown
 
@@ -110,6 +133,9 @@ func (s *Service) ServiceShutdown() error
 This method is called when the application is shutting down. Use it to clean up
 resources, close connections, or perform any necessary cleanup tasks.
 
+Services are shut down in reverse registration order.
+The application context will be canceled before `ServiceShutdown` is called.
+
 ### ServeHTTP
 
 ```go