Description

This PR provides three QOL improvements for the runtime side of the binding/service system and fixes a major bug:

• it adds a method App.RegisterService for registering services after app creation (but before App.Run);
• it adds rich error handling for binding calls inspired by the v2 approach, with json marshaling as default behaviour and global + per-service MarshalError functions for custom handling (see the updated docs);
• it standardises and documents the order in which services are started and shut down (registration order and reverse registration order, respectively);
• it fixes a macOS bug whereby service shutdown methods would not be called on quit (due to the fact that on macOS the app event loop never returns control back to App.Run).

Additionally, it adds a test harness for end-to-end tests of the application object and uses it to test service startup/shutdown sequences and error handling. Note that the go test framework spawns one process per package, hence – against go conventions – I had to split tests over many packages because at most one application run per process is supported.

🚨 Breaking changes 🚨

There are a few minor breaking changes necessitated by the restructuring described above (should not affect users in practice):

• ServiceStartup hooks are now invoked when App.Run is called, not in application.New
• ServiceStartup errors are now returned from App.Run instead of terminating the process
• Binding and dialog calls from JS now reject with rich error objects instead of simple strings

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Ran the test suite including new and updated tests, verified that everything is passing; tested examples manually.

• Windows
• macOS
• Linux

Test Configuration

 Wails (v3.0.0-dev)  Wails Doctor

# System

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
| Name          | MacOS                                                                                                          |
| Version       | 12.6.6                                                                                                         |
| ID            | 21G646                                                                                                         |
| Branding      | Monterey                                                                                                       |
| Platform      | darwin                                                                                                         |
| Architecture  | amd64                                                                                                          |
| Apple Silicon | unknown                                                                                                        |
| CPU           | Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz                                                                       |
| CPU           | Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz                                                                       |
| GPU           |  cores, Metal Family: Supported, Metal GPUFamily macOS 2                                                       |
|       Metal Family: Supported, Metal GPUFamily macOS 2                                                                         |
| Memory        | 32 GB                                                                                                          |
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

# Build Environment

┌─────────────────────────────────────────────────────────┐
| Wails CLI    | v3.0.0-dev                               |
| Go Version   | go1.23.5                                 |
| Revision     | 7f6b911e15fccadd140077b809d244a9878bf2c6 |
| Modified     | true                                     |
| -buildmode   | exe                                      |
| -compiler    | gc                                       |
| CGO_CFLAGS   |                                          |
| CGO_CPPFLAGS |                                          |
| CGO_CXXFLAGS |                                          |
| CGO_ENABLED  | 1                                        |
| CGO_LDFLAGS  |                                          |
| GOAMD64      | v1                                       |
| GOARCH       | amd64                                    |
| GOOS         | darwin                                   |
| vcs          | git                                      |
| vcs.modified | true                                     |
| vcs.revision | 7f6b911e15fccadd140077b809d244a9878bf2c6 |
| vcs.time     | 2025-02-12T08:35:30Z                     |
└─────────────────────────────────────────────────────────┘

# Dependencies

┌───────────────────────────┐
| npm             | 10.8.2  |
| *NSIS           | v3.10   |
| Xcode cli tools | 2395    |
└─ * - Optional Dependency ─┘

# Checking for issues

 SUCCESS  No issues found

# Diagnosis

 SUCCESS  Your system is ready for Wails development!

Checklist:

• I have updated docs/src/content/docs/changelog.mdx with details of this PR
• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features

  • Introduced a post-shutdown hook to allow custom code execution after shutdown.
  • Added a new error type for improved fatal error detection, along with a streamlined service registration approach.

• Improvements

  • Upgraded error handling in JavaScript bindings and dialogs so that errors now return standardized error objects.
  • Enhanced the reliability of service startup and shutdown order for better lifecycle management.
  • Improved error handling and logging consistency across various components.
  • Updated error handling in multiple methods to use structured error messages and improved formatting.
  • Standardized documentation for service lifecycle management and error handling.

• Documentation

  • Expanded and clarified content on error handling and service lifecycle procedures.

• Tests

  • Added a test harness to validate application startup and shutdown sequences.
  • Introduced comprehensive tests for service startup and shutdown behaviors, including error handling scenarios.